@lab206/core 0.1.0

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,MAAM,QAAQ,GAAG,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;AAEjD,mEAAmE;AACnE,MAAM,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC;AAEjC,8CAA8C;AAC9C,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;IACvC,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,+BAA+B;AAC/B,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,0EAA0E;IAC1E,IAAI,CAAC,CAAC;IACN,uDAAuD;IACvD,IAAI,IAAI,CAAC,CAAC;IACV,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,+BAA+B;AAC/B,MAAM,WAAW,MAAM,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC;IAClD,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACpB,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;CAClC;AAED,6CAA6C;AAC7C,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@lab206/core",
+  "version": "0.1.0",
+  "description": "Fine-grained reactivity primitives for Powers — signals, computed, effects, store, resource, ownership.",
+  "type": "module",
+  "license": "BUSL-1.1",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "src/**/*.css",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "devDependencies": {
+    "esbuild": "^0.25.1",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "author": "Scott Powers",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://lab206.com",
+  "bugs": {
+    "url": "https://github.com/spowers2/powers/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spowers2/powers.git",
+    "directory": "packages/core"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test src/*.test.ts",
+    "bench": "node --import tsx scripts/bench.ts",
+    "size": "node --import tsx scripts/size.ts"
+  }
+}

package/src/effect.ts

@@ -0,0 +1,101 @@
+import {
+  clearSources,
+  createNode,
+  disposeNode,
+  getActiveOwner,
+  setActiveNode,
+  type ReactiveNode,
+} from "./graph.js";
+import { reportError } from "./errors.js";
+import { enqueue } from "./scheduler.js";
+import type { Dispose, EffectFn } from "./types.js";
+
+export interface EffectOptions {
+  name?: string;
+  /** Local error handler (runs before owner `onError` handlers). */
+  onError?: (error: unknown) => void;
+}
+
+/**
+ * Run `fn` immediately, track reactive reads, and re-run when they change.
+ * Returns a dispose function. `fn` may return a cleanup called before the
+ * next run and on dispose.
+ *
+ * Errors are caught so one bad effect cannot tear down the whole graph.
+ * Handle them with `options.onError` or owner-level `onError()`.
+ *
+ * @example
+ * ```ts
+ * const stop = effect(() => {
+ *   console.log(count());
+ *   return () => console.log("cleanup");
+ * });
+ * stop();
+ * ```
+ */
+export function effect(fn: EffectFn, options?: EffectOptions): Dispose {
+  const node = createNode("effect", options?.name);
+  const owner = getActiveOwner();
+  const localOnError = options?.onError;
+
+  const run = () => {
+    if (node.disposed) return;
+
+    if (node.cleanup) {
+      const c = node.cleanup;
+      node.cleanup = undefined;
+      try {
+        c();
+      } catch (err) {
+        handle(err);
+      }
+    }
+
+    clearSources(node);
+
+    const prev = setActiveNode(node);
+    try {
+      const cleanup = fn();
+      if (typeof cleanup === "function") {
+        node.cleanup = cleanup;
+      }
+    } catch (err) {
+      handle(err);
+    } finally {
+      setActiveNode(prev);
+    }
+  };
+
+  function handle(err: unknown): void {
+    if (localOnError) {
+      try {
+        localOnError(err);
+        return;
+      } catch (handlerError) {
+        // Fall through to owner handlers with the handler error.
+        if (reportError(handlerError, owner)) return;
+        console.error("[powers] effect onError handler threw:", handlerError);
+        return;
+      }
+    }
+    if (reportError(err, owner)) return;
+    console.error("[powers] Unhandled effect error:", err);
+  }
+
+  node.run = run;
+
+  // Initial run is synchronous so first paint / first log is immediate.
+  run();
+
+  return () => {
+    disposeNode(node);
+  };
+}
+
+/**
+ * Schedule an effect run without running it now.
+ * Primarily for internal/testing use.
+ */
+export function scheduleEffect(node: ReactiveNode): void {
+  enqueue(node);
+}

package/src/errors.ts

@@ -0,0 +1,84 @@
+import { getActiveOwner, type Owner } from "./graph.js";
+import type { Dispose } from "./types.js";
+
+type ErrorHandler = (error: unknown) => void;
+
+/** Owner → handlers registered while that owner is active. */
+const ownerHandlers = new WeakMap<Owner, Set<ErrorHandler>>();
+
+/** Fallback when no owner handler claims the error. */
+let globalHandler: ErrorHandler | null = null;
+
+/**
+ * Register an error handler for the **current owner** (from `createRoot`).
+ * Effect errors bubble to these handlers instead of crashing the graph.
+ *
+ * @example
+ * ```ts
+ * createRoot(() => {
+ *   onError((err) => console.error("caught", err));
+ *   effect(() => { throw new Error("boom"); });
+ * });
+ * ```
+ */
+export function onError(fn: ErrorHandler): Dispose {
+  const owner = getActiveOwner();
+  if (!owner) {
+    // No owner — install as process-local global for this call site's lifetime.
+    const prev = globalHandler;
+    globalHandler = fn;
+    return () => {
+      if (globalHandler === fn) globalHandler = prev;
+    };
+  }
+
+  let set = ownerHandlers.get(owner);
+  if (!set) {
+    set = new Set();
+    ownerHandlers.set(owner, set);
+  }
+  set.add(fn);
+
+  return () => {
+    set!.delete(fn);
+  };
+}
+
+/**
+ * Report an error to the nearest owner handlers, then parent owners,
+ * then the global handler. Returns true if anyone handled it.
+ */
+export function reportError(error: unknown, owner: Owner | null): boolean {
+  let current: Owner | null = owner;
+  while (current) {
+    const set = ownerHandlers.get(current);
+    if (set && set.size > 0) {
+      for (const handler of set) {
+        try {
+          handler(error);
+        } catch (handlerError) {
+          // Handler bugs should not recurse forever.
+          console.error("[powers] onError handler threw:", handlerError);
+        }
+      }
+      return true;
+    }
+    current = current.parent;
+  }
+
+  if (globalHandler) {
+    try {
+      globalHandler(error);
+    } catch (handlerError) {
+      console.error("[powers] onError handler threw:", handlerError);
+    }
+    return true;
+  }
+
+  return false;
+}
+
+/** @internal */
+export function clearGlobalErrorHandler(): void {
+  globalHandler = null;
+}

package/src/graph.ts

@@ -0,0 +1,218 @@
+import type { Dispose, NodeKind } from "./types.js";
+import { enqueue } from "./scheduler.js";
+
+/** A node in the reactive dependency graph. */
+export interface ReactiveNode {
+  kind: NodeKind;
+  name?: string;
+  disposed: boolean;
+  pending: boolean;
+  /** Sources this node currently depends on. */
+  sources: Set<ReactiveNode>;
+  /** Nodes that depend on this node. */
+  observers: Set<ReactiveNode>;
+  /** For computed: dirty when a source may have changed. */
+  dirty: boolean;
+  /** Recompute value (computed) or re-run body (effect). */
+  run?: () => void;
+  /** Cleanup registered by the last effect run. */
+  cleanup?: (() => void) | undefined;
+  /** Owner that created this node (for disposal trees). */
+  owner: Owner | null;
+  /** Child nodes owned by this owner-like node (effects/roots). */
+  children?: Set<ReactiveNode>;
+}
+
+/** Ownership scope — disposing a root disposes all owned nodes. */
+export interface Owner {
+  parent: Owner | null;
+  nodes: Set<ReactiveNode>;
+  disposed: boolean;
+}
+
+let activeNode: ReactiveNode | null = null;
+let activeOwner: Owner | null = null;
+let tracking = true;
+
+export function getActiveNode(): ReactiveNode | null {
+  return activeNode;
+}
+
+export function setActiveNode(node: ReactiveNode | null): ReactiveNode | null {
+  const prev = activeNode;
+  activeNode = node;
+  return prev;
+}
+
+export function getActiveOwner(): Owner | null {
+  return activeOwner;
+}
+
+export function setActiveOwner(owner: Owner | null): Owner | null {
+  const prev = activeOwner;
+  activeOwner = owner;
+  return prev;
+}
+
+export function isTracking(): boolean {
+  return tracking;
+}
+
+/** Run `fn` without collecting dependencies. */
+export function untrack<T>(fn: () => T): T {
+  const prev = tracking;
+  tracking = false;
+  try {
+    return fn();
+  } finally {
+    tracking = prev;
+  }
+}
+
+export function createOwner(parent: Owner | null = activeOwner): Owner {
+  return {
+    parent,
+    nodes: new Set(),
+    disposed: false,
+  };
+}
+
+export function createNode(
+  kind: NodeKind,
+  name?: string,
+  owner: Owner | null = activeOwner,
+): ReactiveNode {
+  const node: ReactiveNode = {
+    kind,
+    disposed: false,
+    pending: false,
+    sources: new Set(),
+    observers: new Set(),
+    dirty: true,
+    owner,
+  };
+  if (name !== undefined) {
+    node.name = name;
+  }
+
+  if (owner && !owner.disposed) {
+    owner.nodes.add(node);
+  }
+
+  return node;
+}
+
+/** Register `source` as a dependency of the active consumer. */
+export function track(source: ReactiveNode): void {
+  if (!tracking || !activeNode || activeNode === source || source.disposed) {
+    return;
+  }
+  source.observers.add(activeNode);
+  activeNode.sources.add(source);
+}
+
+/** Drop all current source links for a node (before re-running). */
+export function clearSources(node: ReactiveNode): void {
+  for (const source of node.sources) {
+    source.observers.delete(node);
+  }
+  node.sources.clear();
+}
+
+/** Notify observers that `source` changed. */
+export function notify(source: ReactiveNode): void {
+  for (const observer of source.observers) {
+    if (observer.disposed) continue;
+
+    if (observer.kind === "computed") {
+      if (!observer.dirty) {
+        observer.dirty = true;
+        // Propagate dirty flags through computed chains.
+        notify(observer);
+      }
+    } else if (observer.kind === "effect") {
+      enqueue(observer);
+    }
+  }
+}
+
+/** Dispose a single node and unlink it from the graph. */
+export function disposeNode(node: ReactiveNode): void {
+  if (node.disposed) return;
+  node.disposed = true;
+
+  if (node.cleanup) {
+    const c = node.cleanup;
+    node.cleanup = undefined;
+    c();
+  }
+
+  clearSources(node);
+
+  for (const observer of node.observers) {
+    observer.sources.delete(node);
+  }
+  node.observers.clear();
+
+  if (node.children) {
+    for (const child of node.children) {
+      disposeNode(child);
+    }
+    node.children.clear();
+  }
+
+  if (node.owner) {
+    node.owner.nodes.delete(node);
+  }
+}
+
+/** Dispose an owner and every node it owns (depth-first). */
+export function disposeOwner(owner: Owner): void {
+  if (owner.disposed) return;
+  owner.disposed = true;
+
+  // Snapshot — disposal mutates the set.
+  const nodes = [...owner.nodes];
+  for (const node of nodes) {
+    disposeNode(node);
+  }
+  owner.nodes.clear();
+}
+
+/**
+ * Create a reactive root. All signals/effects created inside are owned by
+ * this root and disposed when the returned dispose function is called.
+ *
+ * Clears the active *tracking* node while `fn` runs so parent effects (e.g.
+ * a router outlet) do not accidentally subscribe to signals read during
+ * component setup — that would remount the whole page on first keystroke.
+ */
+export function createRoot<T>(fn: (dispose: Dispose) => T): T {
+  const owner = createOwner(activeOwner);
+  const prevOwner = setActiveOwner(owner);
+  const prevNode = setActiveNode(null);
+
+  const dispose: Dispose = () => {
+    disposeOwner(owner);
+  };
+
+  try {
+    return fn(dispose);
+  } finally {
+    setActiveOwner(prevOwner);
+    setActiveNode(prevNode);
+  }
+}
+
+/**
+ * Run `fn` under a fresh owner nested under the current owner.
+ * Useful for scoped components later.
+ */
+export function runWithOwner<T>(owner: Owner | null, fn: () => T): T {
+  const prev = setActiveOwner(owner);
+  try {
+    return fn();
+  } finally {
+    setActiveOwner(prev);
+  }
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @lab206/core
+ *
+ * Fine-grained reactivity primitives.
+ * No DOM. No framework. Just a correct reactive graph.
+ *
+ * Learning order (intentionally short):
+ *   1. signal  2. computed  3. effect  4. store  5. resource / createQuery
+ */
+
+export { signal, computed } from "./signal.js";
+export { effect } from "./effect.js";
+export type { EffectOptions } from "./effect.js";
+export { batch, flush, isBatching } from "./scheduler.js";
+export {
+  createRoot,
+  untrack,
+  getActiveOwner,
+  runWithOwner,
+  createOwner,
+  disposeOwner,
+} from "./graph.js";
+export { store, cell } from "./store.js";
+export type { Store, StoreFields, StoreOptions } from "./store.js";
+export { resource } from "./resource.js";
+export type {
+  Resource,
+  ResourceState,
+  ResourceOptions,
+  ResourceFetcher,
+  ResourceFetcherInfo,
+} from "./resource.js";
+export { createQuery } from "./query.js";
+export type { CreateQueryOptions, QueryKey } from "./query.js";
+export { onError } from "./errors.js";
+
+export type {
+  Signal,
+  ReadonlySignal,
+  SignalOptions,
+  EffectFn,
+  Dispose,
+} from "./types.js";
+
+export type { Owner } from "./graph.js";

package/src/query.ts

@@ -0,0 +1,58 @@
+import { resource } from "./resource.js";
+import type { Resource, ResourceOptions } from "./resource.js";
+
+export type QueryKey = string | number | false | null | undefined;
+
+export type CreateQueryOptions<T> = {
+  /**
+   * Reactive key. When `false` / `null` / `undefined`, the query is idle
+   * (no fetch). Change the key to re-run — same mental model as signals.
+   */
+  queryKey: () => QueryKey;
+  /** Async work for the current key. */
+  queryFn: (key: string) => Promise<T> | T;
+  /** Seed UI before the first success. */
+  initialData?: T;
+  /** Debug name for the underlying resource. */
+  name?: string;
+};
+
+/**
+ * Signal-native async query — thin, intentional ergonomics on `resource`.
+ *
+ * Why it feels great with Powers:
+ * - The key is a **function of signals** — no dependency arrays
+ * - `data()` / `loading()` / `error()` are fine-grained
+ * - `refetch()` re-runs without remounting the page
+ *
+ * @example
+ * ```ts
+ * const q = signal("design");
+ * const art = createQuery({
+ *   queryKey: () => q(),
+ *   queryFn: (key) => fetch(`/api/search?q=${key}`).then((r) => r.json()),
+ * });
+ * // art() · art.loading() · art.error() · art.refetch()
+ * ```
+ */
+export function createQuery<T>(
+  options: CreateQueryOptions<T>,
+): Resource<T> {
+  const opts: ResourceOptions<T> = {
+    name: options.name ?? "query",
+  };
+  if (options.initialData !== undefined) {
+    opts.initialValue = options.initialData;
+  }
+
+  // Source is `string | false` so resource can idle; fetcher only runs when key is string.
+  return resource(
+    (): string | false => {
+      const k = options.queryKey();
+      if (k === false || k === null || k === undefined) return false;
+      return String(k);
+    },
+    (key) => options.queryFn(key as string),
+    opts,
+  );
+}