solid-deps 0.0.0-stage → 0.0.1

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,193 @@
-# 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.1 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.
+
+Pending resources, transitions, reentrant reactive updates, 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,45 @@
 {
   "name": "solid-deps",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "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:dev": "node --conditions=browser --conditions=development --test test/test.mjs test/test-async.mjs test/test-tuple.mjs",
+    "test:observe": "node --conditions=browser --conditions=observe --test test/test.mjs test/test-async.mjs test/test-tuple.mjs",
+    "test:all": "node scripts/run-tests.mjs",
+    "test:package": "node scripts/smoke-package.mjs"
+  }
+}

package/src/attach-read.mjs

@@ -0,0 +1,150 @@
+/**
+ * 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' },
+  prod: { deps: 'C', tail: '_', gen: 'Ne', flags: 'R', dep: 'S', sub: 'u', next: 'G', linkGen: 'Te' }
+};
+function layoutOf(node) {
+  const shape = node && (('_deps' in node) ? layouts.dev : ('C' in node) ? 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;
+}
+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);
+    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[];