solid-deps 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 solid-deps contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,203 @@
-# Temporary Holding Version
+# solid-deps
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Attach additional reactive dependencies to an existing **Solid 2 effect**—even after an `await`—without re-running the effect at the moment of attachment.
+
+`solid-deps` is an experimental, browser-oriented utility for Solid 2. It lets a synchronous callback read signals, memos, or store properties and registers those reads as dependencies of an existing tracked computation. When an attached dependency changes, Solid can rerun that computation normally.
+
+## Installation
+
+```sh
+npm install solid-deps@0.0.2 solid-js@2.0.0-rc.17 @solidjs/signals@2.0.0-rc.17
+```
+
+With Bun:
+
+```sh
+bun add solid-deps@0.0.2 solid-js@2.0.0-rc.17 @solidjs/signals@2.0.0-rc.17
+```
+
+**Compatibility:** This release targets **Solid 2.0.0-rc.17** (`solid-js` and `@solidjs/signals`). Both the app and `solid-deps` must resolve to the **same instance** of `@solidjs/signals`. Server-side rendering is not supported. See [Limitations](#limitations).
+
+## Quick start
+
+Capture the computation before `await`, then attach the reads after the asynchronous work finishes.
+
+```tsx
+import { createEffect, createSignal, getOwner } from "solid-js";
+import { attachRead, captureObserverPass } from "solid-deps";
+
+export default function Counter() {
+  const [count, setCount] = createSignal(0);
+
+  createEffect(
+    async () => {
+      // Capture the current effect pass while it is still tracking.
+      const pass = captureObserverPass(getOwner());
+
+      await Promise.resolve();
+
+      // count() becomes a dependency of this effect.
+      const [value, result] = attachRead(pass, () => count());
+
+      // An older async run may finish after a newer one, or after disposal.
+      if (result.stale || result.disposed) return;
+
+      console.log("Count:", value);
+    },
+    () => {}
+  );
+
+  return (
+    <button type="button" onClick={() => setCount(value => value + 1)}>
+      Increment: {count()}
+    </button>
+  );
+}
+```
+
+The first late read adds `count` as a dependency. Later changes to `count` can rerun the effect; each new pass captures its own token and reattaches the read after `await`.
+
+## API
+
+The package exports `attachRead`, `captureObserverPass`, and `inspectDeps` from its main entry point.
+
+### `attachRead(observerOrPass, read)`
+
+Runs a **synchronous** reader and attaches the reactive sources it accesses to the specified existing computation.
+
+```ts
+const [retValue, result] = attachRead(pass, () => {
+  const countValue = count();
+  const nameValue = name();
+  return { countValue, nameValue };
+});
+```
+
+The return value is always a tuple:
+
+- **`retValue`** — the exact value returned by `read()`, or `undefined` if the read was skipped.
+- **`result`** — an `AttachReadResult` object describing the attachment.
+
+| Result field | Type | Meaning |
+| --- | --- | --- |
+| `added` | `number` | Newly attached or revalidated dependencies, including promoted ones. |
+| `duplicate` | `number` | Dependencies already valid for the current effect pass. |
+| `promoted` | `number` | Previously attached dependencies reused for this pass; included in `added`. |
+| `disposed` | `boolean` | Target computation was disposed; `read()` was not called. |
+| `stale` | `boolean` | Captured pass has been superseded; `read()` was not called. |
+
+A disposed or stale pass returns `[undefined, result]` without executing `read()`. Errors thrown by the reader propagate to the caller. A reader returning a Promise or thenable is rejected with a `TypeError`; awaiting work **before** calling `attachRead()` is supported, but passing an `async` reader is not.
+
+You may also pass a captured computation directly:
+
+```ts
+import { getOwner } from "solid-js";
+
+// `owner` must have been captured inside a tracked computation.
+const [value, result] = attachRead(owner, () => count());
+```
+
+For async effects, prefer a pass token so an older continuation cannot attach dependencies to a newer execution.
+
+### `captureObserverPass(observer)`
+
+Captures a token identifying the current execution of a tracked computation. Call it **during the computation's tracked phase, before an `await`**.
+
+```ts
+const pass = captureObserverPass(getOwner());
+```
+
+Pass the token to `attachRead()`. If a newer execution has started, the older token produces `result.stale === true` and the reader is skipped.
+
+`getOwner()` must refer to an actual tracking computation. An ordinary component/root owner is not a suitable attachment target.
+
+### `inspectDeps(observer)`
+
+Returns an array of the current dependency **source objects** for the supplied computation:
+
+```ts
+const sources = inspectDeps(owner);
+console.log(sources.length);
+```
+
+This is a diagnostic helper, not an accessor-value API. Treat returned source objects as read-only.
+
+## TypeScript
+
+Type declarations are included. No separate `@types` package is needed.
+
+The package exports the following types and typed function signatures:
+
+```ts
+import type { Owner } from "@solidjs/signals";
+
+export interface ObserverPass {
+  readonly __solidDepsObserverPass: unique symbol;
+}
+
+export interface AttachReadResult {
+  readonly added: number;
+  readonly duplicate: number;
+  readonly promoted: number;
+  readonly disposed: boolean;
+  readonly stale: boolean;
+}
+
+export declare function captureObserverPass(observer: Owner | null): ObserverPass;
+
+export declare function attachRead<T>(
+  observerOrPass: Owner | ObserverPass | null,
+  read: () => T
+): [retValue: T | undefined, result: AttachReadResult];
+
+export declare function inspectDeps(observer: Owner): unknown[];
+```
+
+For example, TypeScript preserves the reader's return type:
+
+```ts
+import { createEffect, createSignal, getOwner } from "solid-js";
+import { attachRead, captureObserverPass } from "solid-deps";
+import type { AttachReadResult, ObserverPass } from "solid-deps";
+
+const [count] = createSignal(0);
+
+createEffect(async () => {
+  const pass: ObserverPass = captureObserverPass(getOwner());
+  await Promise.resolve();
+
+  const [value, result] = attachRead(pass, () => count());
+  // value: number | undefined
+  // result: AttachReadResult
+
+  if (!result.stale && !result.disposed && value !== undefined) {
+    console.log(value.toFixed(0));
+  }
+}, () => {});
+```
+
+`ObserverPass` is an opaque type. Obtain one from `captureObserverPass()` rather than constructing it yourself.
+
+## Dependency lifetime
+
+- Reads are attached **without immediately re-running** the target computation.
+- Source changes that occurred **before** attachment are not replayed.
+- The attached dependencies participate in subsequent normal updates. On the next computation pass, Solid may remove dependencies that are not read or reattached for that pass.
+- Use `captureObserverPass()` for async work that may overlap with newer effect executions.
+- Disposed computations cannot receive new dependencies.
+
+## Limitations
+
+`solid-deps` is experimental and restricted to Solid **2.0.0-rc.17** in browser-oriented applications. Dependency registration requires an existing **tracked computation**, not simply any owner.
+
+Keep `read()` synchronous and limited to settled reactive reads, such as signals, memos, or store properties. Do not use it to create computations, install cleanups, write signals, or perform side effects. It does not run in the target's original reactive context. The library rejects reader callbacks that create owned children or register cleanups, and rejects sources owned by its temporary observer, to prevent subscriptions to disposed computations.
+
+Pending async memo reads can throw `NotReadyError`; a failed read does not attach dependencies. A memo with a `loadingValue` can return that fallback while pending, but `attachRead` does not restore the target observer's original suspension or transition context. Treat resources, loading boundaries, held transactions, and optimistic state as **unsupported beyond ordinary settled reads**.
+
+An `attachRead()` subscription is prospective: signal updates that happen before attachment are not replayed. Grafted dependencies can be removed by the target's next normal recomputation. For async effects, reattach on each pass using `captureObserverPass()`.
+
+Reads that create computations/cleanups, write signals, or depend on `getOwner()`/`getObserver()` seeing the original effect are unsupported, because the callback executes under a temporary observer. Server rendering and independently bundled copies of the signals runtime are not supported. Do not assume compatibility with other Solid versions.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "solid-deps",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "Experimental direct dependency attachment for Solid 2 reactive observers after async boundaries",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.mts",
+      "default": "./src/index.mjs"
+    }
+  },
+  "types": "./types/index.d.mts",
+  "files": [
+    "src/attach-read.mjs",
+    "src/index.mjs",
+    "types/index.d.mts",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@solidjs/signals": "2.0.0-rc.17"
+  },
+  "keywords": [
+    "solid",
+    "solidjs",
+    "signals",
+    "reactivity",
+    "async",
+    "observer",
+    "dependency-tracking"
+  ],
+  "scripts": {
+    "setup": "node scripts/setup.mjs",
+    "test": "node --conditions=browser --test test/test.mjs test/test-async.mjs test/test-tuple.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs",
+    "test:dev": "node --conditions=browser --conditions=development --test test/test.mjs test/test-async.mjs test/test-tuple.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs",
+    "test:observe": "node --conditions=browser --conditions=observe --test test/test.mjs test/test-async.mjs test/test-tuple.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs",
+    "test:all": "node scripts/run-tests.mjs",
+    "test:package": "node scripts/smoke-package.mjs"
+  },
+  "devDependencies": {
+    "@solidjs/signals": "2.0.0-rc.17",
+    "solid-js": "2.0.0-rc.17"
+  }
+}

package/src/attach-read.mjs

@@ -0,0 +1,175 @@
+/**
+ * Experimental RC.17 graph surgery. No changes/forks of Solid.
+ * Target must be captured using getObserver() while its tracking function runs.
+ * Scope: synchronous, settled signal and memo reads, outside a target recompute.
+ * Maintenance/compatibility: see HANDOFF.md and docs/INTERNALS.md.
+ * This is link transfer, NOT restoration of the original observer context.
+ */
+import { createRoot, createReaction, getObserver, isDisposed } from '@solidjs/signals';
+
+const layouts = {
+  dev: { deps: '_deps', tail: '_depsTail', gen: '_depGen', flags: '_flags', dep: '_dep', sub: '_sub', next: '_nextDep', linkGen: '_gen', child: '_firstChild', disposal: '_disposal' },
+  prod: { deps: 'C', tail: '_', gen: 'Ne', flags: 'R', dep: 'S', sub: 'u', next: 'G', linkGen: 'Te', child: 'De', disposal: 'He' },
+  observe: { deps: 'C', tail: '_', gen: 'Ne', flags: 'R', dep: 'S', sub: 'u', next: 'G', linkGen: 'Te', child: 'ze', disposal: 'rt' }
+};
+function layoutOf(node) {
+  const shape = node && (('_deps' in node) ? layouts.dev : ('C' in node) ? ('ze' in node ? layouts.observe : layouts.prod) : null);
+  if (!shape || typeof node[shape.gen] !== 'number' || !(shape.tail in node))
+    throw new TypeError('Expected a tracking Computed from @solidjs/signals rc.17, not a plain Owner');
+  return shape;
+}
+// Probe-owned sources disappear when the temporary tracking root is disposed.
+// Their dependency edges must never be transferred to a longer-lived target.
+function ownedBy(node, ancestor) {
+  const seen = new Set();
+  for (let owner = node; owner != null; owner = owner._parent) {
+    if (owner === ancestor) return true;
+    if (seen.has(owner)) throw new Error('Cyclic owner ancestry');
+    seen.add(owner);
+  }
+  return false;
+}
+function links(owner, layout) {
+  const out = [];
+  let cur = owner[layout.deps];
+  const visited = new Set();
+  while (cur != null) {
+    if (visited.has(cur)) throw new Error('Cyclic dependency list');
+    visited.add(cur);
+    out.push(cur);
+    cur = cur[layout.next];
+  }
+  return out;
+}
+// Capture a generation before an await, so a superseded async invocation
+// cannot attach subscriptions to a more recent pass of the same effect.
+const observerPasses = new WeakMap();
+export function captureObserverPass(observer) {
+  const shape = layoutOf(observer);
+  const token = Object.freeze({});
+  observerPasses.set(token, { observer, generation: observer[shape.gen] });
+  return token;
+}
+
+/**
+ * Attach dependencies read by `read` onto `target` without re-running target.
+ * Returns [retValue, result] where result describes the graft.
+ * They remain until target recomputes and performs normal dependency reconciliation.
+ */
+export function attachRead(observerOrPass, read) {
+  const pass = observerOrPass && observerPasses.get(observerOrPass);
+  const target = pass ? pass.observer : observerOrPass;
+  const s = layoutOf(target);
+  if (typeof read !== 'function') throw new TypeError('read must be a function');
+  if (isDisposed(target)) return [undefined, { added: 0, duplicate: 0, promoted: 0, disposed: true, stale: false }];
+  if (pass && target[s.gen] !== pass.generation)
+    return [undefined, { added: 0, duplicate: 0, promoted: 0, disposed: false, stale: true }];
+  if (target[s.flags] & 4) throw new Error('Target observer is currently recomputing');
+  const existing = links(target, s);
+  const beforeTail = target[s.tail];
+  const beforeGen = target[s.gen];
+  // Solid can retain an uncommitted stale suffix from a previous pass.
+  // The tail identifies the validated *prefix*, not necessarily the list end.
+  const prefixEnd = beforeTail == null ? -1 : existing.indexOf(beforeTail);
+  if (beforeTail !== null && prefixEnd < 0)
+    throw new Error('Target tail is not reachable from its dependency head');
+  const valid = existing.slice(0, prefixEnd + 1);
+  const stale = existing.slice(prefixEnd + 1);
+  let disposeRoot;
+  let probe;
+  let caught;
+  let retValue;
+  try {
+    createRoot(dispose => {
+      disposeRoot = dispose;
+      const track = createReaction(() => {});
+      track(() => {
+        probe = getObserver();
+        try { retValue = read(); } catch (err) { caught = [err]; }
+      });
+    });
+    if (caught) throw caught[0];
+    if (retValue != null && typeof retValue.then === 'function')
+      throw new TypeError('attachRead requires synchronous reads, not an async callback');
+    if (!probe) throw new Error('No temporary observer was captured');
+    const p = layoutOf(probe);
+    if (p !== s) throw new Error('Temporary observer and target use different Solid builds');
+    if (isDisposed(target)) return [undefined, { added: 0, duplicate: 0, promoted: 0, disposed: true, stale: false }];
+    if ((target[s.flags] & 4) || target[s.tail] !== beforeTail || target[s.gen] !== beforeGen ||
+      (target[s.deps] ?? null) !== (existing[0] ?? null))
+      throw new Error('Target changed during capture; refusing unsafe graft');
+    const after = links(target, s);
+    if (after.length !== existing.length || after.some((edge, i) => edge !== existing[i]))
+      throw new Error('Target dependency chain changed during capture');
+
+    const captured = links(probe, s);
+    // `read()` must not allocate owned children or register cleanups. A child
+    // can disappear when the probe is disposed, and a cleanup can throw AFTER
+    // a successful graft, leaving the target changed despite a failed call.
+    if (probe[s.child] != null || probe[s.disposal] != null)
+      throw new Error('attachRead read() cannot create owned children or register cleanups');
+    // Guard before touching either graph. A memo or signal created inside
+    // `read()` may be owned by the disposable probe, and disposing that probe
+    // would otherwise leave the target subscribed to a disposed source.
+    for (const edge of captured) {
+      const source = edge[s.dep];
+      if (isDisposed(source) || ownedBy(source, probe))
+        throw new Error('Cannot attach a disposed or temporary-observer-owned source');
+    }
+    const seen = new Set(valid.map(edge => edge[s.dep]));
+    const staleBySource = new Map(stale.map(edge => [edge[s.dep], edge]));
+    const moved = [];
+    const promoted = [];
+    const kept = [];
+
+    for (const edge of captured) {
+      const source = edge[s.dep];
+      if (seen.has(source)) {
+        kept.push(edge);
+      } else {
+        seen.add(source);
+        const old = staleBySource.get(source);
+        if (old) {
+          promoted.push(old);
+          kept.push(edge);
+        } else {
+          moved.push(edge);
+        }
+      }
+    }
+    // Fix the temporary observer's list before its disposer walks it.
+    probe[s.deps] = kept[0] ?? null;
+    probe[s.tail] = kept.at(-1) ?? null;
+    for (let i = 0; i < kept.length; i++) kept[i][s.next] = kept[i+1] ?? null;
+
+    // Rebuild the target's list as:
+    //   validated prefix -> newly validated links -> stale suffix.
+    // Trimming the suffix remains Solid's responsibility at commit/settle.
+    const promotedSet = new Set(promoted);
+    const staleRemainder = stale.filter(edge => !promotedSet.has(edge));
+    const additions = [...promoted, ...moved];
+    const validated = [...valid, ...additions];
+    const nextList = [...validated, ...staleRemainder];
+    for (const edge of additions) {
+      edge[s.sub] = target;
+      edge[s.linkGen] = beforeGen;
+    }
+    for (let i = 0; i < nextList.length; i++)
+      nextList[i][s.next] = nextList[i + 1] ?? null;
+    target[s.deps] = nextList[0] ?? null;
+    target[s.tail] = validated.at(-1) ?? null;
+    return [retValue, {
+      added: additions.length,
+      duplicate: kept.length - promoted.length,
+      promoted: promoted.length,
+      disposed: false,
+      stale: false
+    }];
+  } finally {
+    disposeRoot?.();
+  }
+}
+export function inspectDeps(owner) {
+  const s = layoutOf(owner);
+  return links(owner, s).map(link => link[s.dep]);
+}

package/src/index.mjs

@@ -0,0 +1 @@
+export { attachRead, captureObserverPass, inspectDeps } from './attach-read.mjs';

package/types/index.d.mts

@@ -0,0 +1,37 @@
+import type { Owner } from '@solidjs/signals';
+
+/** Opaque identity of a specific observer recomputation, captured before await. */
+export interface ObserverPass {
+  readonly __solidDepsObserverPass: unique symbol;
+}
+
+/** Metadata about a synchronous dependency graft. */
+export interface AttachReadResult {
+  /** Newly attached/validated sources, INCLUDING promotions. */
+  readonly added: number;
+  /** Sources already attached as current validated dependencies. */
+  readonly duplicate: number;
+  /** Prior-generation links reused; a subset of added. */
+  readonly promoted: number;
+  /** Observer already disposed; callback was not invoked. */
+  readonly disposed: boolean;
+  /** A newer recomputation superseded the pass; callback was not invoked. */
+  readonly stale: boolean;
+}
+
+/**
+ * Add dependencies read by a synchronous callback to an existing tracking observer.
+ * Returns `[retValue, result]` (not `[result, retValue]`).
+ * If skipped for stale/disposed target, retValue is undefined.
+ * EXPERIMENTAL: accesses private Solid 2.0.0-rc.17 dependency graph layouts.
+ */
+export declare function attachRead<T>(
+  observerOrPass: Owner | ObserverPass | null,
+  read: () => T
+): [retValue: T | undefined, result: AttachReadResult];
+
+/** Capture a specific recomputation inside a tracking callback (before await). */
+export declare function captureObserverPass(observer: Owner | null): ObserverPass;
+
+/** Return source node objects in an observer's dependency chain. Diagnostic only. */
+export declare function inspectDeps(observer: Owner): unknown[];