thefrontside · jbolda · Dec 12, 2025 · Dec 30, 2025 · Dec 31, 2025 · Jan 5, 2026
diff --git a/.github/workflows/preview.yaml b/.github/workflows/preview.yaml
@@ -36,4 +36,5 @@ jobs:
           for workspace in ${{ steps.changed.outputs.workspaces }}; do
             dirs="$dirs ./$workspace"
           done
-          npx pkg-pr-new publish $dirs
+          echo $dirs
+          npx pkg-pr-new publish --pnpm $dirs
diff --git a/.gitignore b/.gitignore
@@ -36,4 +36,4 @@ dist/
 
 # pnpm config (created by test-matrix runner)
 .npmrc
-
+.turbo
diff --git a/biome.json b/biome.json
@@ -9,7 +9,8 @@
       "recommended": true,
       "style": {
         "noParameterAssign": "off",
-        "useConst": "off"
+        "useConst": "off",
+        "noUselessElse": "off"
       },
       "correctness": {
         "useYield": "off"

diff --git a/inspector/README.md b/inspector/README.md
@@ -0,0 +1,3 @@
+# inspector
+
+Helpers to inspect an effection tree.
diff --git a/inspector/examples/example.ts b/inspector/examples/example.ts
@@ -0,0 +1,23 @@
+import { main, sleep, spawn, type Task } from "effection";
+
+import { useLabels } from ".././lib/labels.ts";
+
+await main(function* () {
+  let tasks: Task<string>[] = [];
+  for (let i = 1; i <= 10; i++) {
+    let task = yield* spawn(function* () {
+      yield* useLabels({ name: "child", number: i });
+      let delay = Math.random() * 1000;
+      yield* sleep(delay);
+      return `${i} is done`;
+    });
+    tasks.push(task);
+  }
+
+  for (let task of tasks) {
+    yield* sleep(Math.random() * 200);
+    yield* task.halt();
+  }
+
+  console.log("done");
+});
diff --git a/inspector/index.html b/inspector/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>vite + react + starfx</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/ui/main.tsx"></script>
+  </body>
+</html>
diff --git a/inspector/lib/attach.ts b/inspector/lib/attach.ts
@@ -0,0 +1,25 @@
+import { type Operation, type Scope, suspend, withResolvers } from "effection";
+import type { Methods, Inspector, Handle } from "./types.ts";
+import { useLabels } from "./labels.ts";
+
+export function* attach<M extends Methods>(
+  scope: Scope,
+  inspector: Inspector<M>,
+  init: (handle: Handle<M>) => Operation<void>,
+): Operation<void> {
+  let attached = withResolvers<void>();
+
+  scope.run(function* () {
+    yield* useLabels({ name: "Inspector" });
+    try {
+      let handle = yield* inspector.attach(scope);
+      yield* init(handle);
+      attached.resolve();
+      yield* suspend();
+    } catch (error) {
+      attached.reject(error as Error);
+    }
+  });
+
+  return yield* attached.operation;
+}
diff --git a/inspector/lib/box.ts b/inspector/lib/box.ts
@@ -0,0 +1,8 @@
+import type { Result } from "effection";
+
+export function unbox<T>(result: Result<T>): T {
+  if (result.ok) {
+    return result.value;
+  }
+  throw result.error;
+}
diff --git a/inspector/lib/combine.ts b/inspector/lib/combine.ts
@@ -0,0 +1,66 @@
+import type { Operation, Scope } from "effection";
+import type { Handle, Inspector, Methods, Protocol } from "./types.ts";
+
+export interface Combine {
+  protocols<A extends Methods>(...protocols: [Protocol<A>]): Protocol<A>;
+  protocols<A extends Methods, B extends Methods>(
+    ...protocols: [Protocol<A>, Protocol<B>]
+  ): Protocol<A & B>;
+  protocols<A extends Methods, B extends Methods, C extends Methods>(
+    ...protocols: [Protocol<A>, Protocol<B>, Protocol<C>]
+  ): Protocol<A & B & C>;
+  protocols<
+    A extends Methods,
+    B extends Methods,
+    C extends Methods,
+    D extends Methods,
+  >(
+    ...protocols: [Protocol<A>, Protocol<B>, Protocol<C>, Protocol<D>]
+  ): Protocol<A & B & C & D>;
+
+  inspectors<A extends Methods>(...inspectors: [Inspector<A>]): Inspector<A>;
+  inspectors<A extends Methods, B extends Methods>(
+    ...inspectors: [Inspector<A>, Inspector<B>]
+  ): Inspector<A & B>;
+  inspectors<A extends Methods, B extends Methods, C extends Methods>(
+    ...inspectors: [Inspector<A>, Inspector<B>, Inspector<C>]
+  ): Inspector<A & B & C>;
+  inspectors<
+    A extends Methods,
+    B extends Methods,
+    C extends Methods,
+    D extends Methods,
+  >(
+    ...inspectors: [Inspector<A>, Inspector<B>, Inspector<C>, Inspector<D>]
+  ): Inspector<A & B & C & D>;
+}
+
+export const combine: Combine = {
+  protocols: (...protocols: Protocol<Methods>[]) => {
+    return protocols.reduce(
+      (acc, protocol) => {
+        Object.assign(acc.methods, protocol.methods);
+        return acc;
+      },
+      { methods: {} } as Protocol<Methods>,
+    );
+  },
+  inspectors: (...inspectors: Inspector<Methods>[]) => {
+    return inspectors.reduce(
+      (acc: Inspector<Methods>, inspector: Inspector<Methods>) => {
+        let protocol = combine.protocols(acc.protocol, inspector.protocol);
+        let attach = function* (scope: Scope): Operation<Handle<Methods>> {
+          let a = yield* acc.attach(scope);
+          let b = yield* inspector.attach(scope);
+          let methods = Object.assign({}, a.methods, b.methods);
+          return {
+            protocol,
+            methods,
+            invoke: ({ name, args }) => methods[name](...args),
+          };
+        };
+        return { protocol, attach };
+      },
+    );
+  },
+};
diff --git a/inspector/lib/impl.ts b/inspector/lib/impl.ts
@@ -0,0 +1,26 @@
+import { lift, type Operation, type Stream } from "effection";
+
+export function fn<TArgs extends unknown[], TReturn>(
+  fn: (...args: TArgs) => TReturn,
+): (...args: TArgs) => Stream<never, TReturn> {
+  return lift((...args) => ({
+    *next() {
+      return { done: true, value: fn(...args) };
+    },
+  }));
+}
+
+export function op<TArgs extends unknown[], TReturn>(
+  fn: (...args: TArgs) => Operation<TReturn>,
+): (
+  ...args: TArgs
+) => Stream<never, TReturn extends void ? undefined : TReturn> {
+  return lift((...args) => ({
+    *next() {
+      return {
+        done: true,
+        value: yield* fn(...args),
+      } as IteratorReturnResult<TReturn extends void ? undefined : TReturn>;
+    },
+  }));
+}
diff --git a/inspector/lib/implementation.ts b/inspector/lib/implementation.ts
@@ -0,0 +1,25 @@
+import type { Operation, Scope } from "effection";
+import type {
+  Handle,
+  Implementation,
+  Inspector,
+  Methods,
+  Protocol,
+} from "./types.ts";
+
+export function createImplementation<M extends Methods>(
+  protocol: Protocol<M>,
+  create: Implementation<M>,
+): Inspector<M> {
+  return {
+    protocol,
+    *attach(scope: Scope): Operation<Handle<M>> {
+      let methods = yield* create(scope);
+      return {
+        protocol,
+        methods,
+        invoke: ({ name, args }) => methods[name](...args),
+      };
+    },
+  };
+}
diff --git a/inspector/lib/labels.ts b/inspector/lib/labels.ts
@@ -0,0 +1,28 @@
+import { createContext, type Scope, useScope, type Operation } from "effection";
+
+export type Labels = Record<string, string | number | boolean>;
+
+export const LabelsContext = createContext<Labels>(
+  "@effectionx/inspector.labels",
+  { name: "anonymous" },
+);
+
+export function* useLabels(labels: Labels): Operation<Labels> {
+  let scope = yield* useScope();
+
+  if (!scope.hasOwn(LabelsContext)) {
+    return yield* LabelsContext.set({
+      ...LabelsContext.defaultValue,
+      ...labels,
+    });
+  }
+  let current = yield* LabelsContext.expect();
+  return yield* LabelsContext.set({ ...current, ...labels });
+}
+
+export function getLabels(scope: Scope) {
+  if (scope.hasOwn(LabelsContext)) {
+    return scope.expect(LabelsContext);
+  }
+  return LabelsContext.defaultValue as Labels;
+}
diff --git a/inspector/lib/mod.ts b/inspector/lib/mod.ts
@@ -0,0 +1,5 @@
+export * from "./types.ts";
+export * from "./protocol.ts";
+export * from "./implementation.ts";
+export * from "./combine.ts";
+export * from "./reader.ts";
diff --git a/inspector/lib/protocol.ts b/inspector/lib/protocol.ts
@@ -0,0 +1,9 @@
+import type { Method, Protocol } from "./types.ts";
+
+export function createProtocol<
+  M extends Record<string, Method<unknown[], unknown, unknown>>,
+>(methods: M): Protocol<M> {
+  return {
+    methods,
+  };
+}
diff --git a/inspector/lib/reader.ts b/inspector/lib/reader.ts
@@ -0,0 +1,7 @@
+export function toJson(value: unknown) {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch (_error) {
+    return String(value);
+  }
+}
diff --git a/inspector/lib/reduce.ts b/inspector/lib/reduce.ts
@@ -0,0 +1,47 @@
+import type { Operation, Stream } from "effection";
+
+/**
+ * Transforms a stream by taking each item and applying it to an
+ * accumulated value to produce a new accumulated value which is then
+ *  passed downstream.
+ *
+ * @example
+ * ```ts
+ * import { reduce, streamOf } from "@effectionx/stream-helpers";
+ *
+ * const sum = reduce(function*(total: number, item: number) {
+ *   return sum + number;
+ * }, 0);
+ *
+ * sum(streamOf([1,2,3])) //=> yields 1, 3, 6
+ * ```
+ *
+ * @param fn - The operation to apply a single item to the accumulated value
+ * @param initial - The first accumulated value from which all others will descend
+ * @returns A stream transformer that applies the reduction over the lifetime of the stream
+ */
+export function reduce<T, TSum>(
+  fn: (current: TSum, item: T) => Operation<TSum>,
+  initial: TSum,
+): <TClose>(stream: Stream<T, TClose>) => Stream<TSum, TClose> {
+  return (upstream) => ({
+    *[Symbol.iterator]() {
+      let current = initial;
+      let subscription = yield* upstream;
+
+      return {
+        *next() {
+          let next = yield* subscription.next();
+          if (next.done) {
+            return next;
+          }
+          let reduction = yield* fn(current, next.value);
+
+          current = reduction;
+
+          return { done: false, value: current } as const;
+        },
+      };
+    },
+  });
+}
Original file line number	Diff line number	Diff line change
Expand Up		@@ -36,4 +36,4 @@ dist/

		# pnpm config (created by test-matrix runner)
		.npmrc

		.turbo
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# inspector

		Helpers to inspect an effection tree.