solid-deps 0.0.3 → 0.0.5

package/README.md

@@ -16,7 +16,7 @@ Or with Bun:
 bun add solid-deps solid-js@2.0.0-rc.17 @solidjs/signals@2.0.0-rc.17
 ```
 
-**Compatibility:** Tested with Solid 2.0.0-rc.17 production, development and observe builds. `solid-deps` now discovers observer graph fields at runtime, rather than using fixed field-name mappings. Other Solid 2 versions may work if they retain compatible internal graph semantics, but are not yet verified. Your app and `solid-deps` must share one `@solidjs/signals` runtime instance. SSR is not supported.
+**Compatibility:** Tested with Solid 2.0.0-rc.17 production, development and observe builds. `solid-deps` recognizes validated descriptive development fields directly and discovers unknown or minified graph fields at runtime. Other Solid 2 versions may work if they retain compatible internal graph semantics, but are not yet verified. Your app and `solid-deps` must share one `@solidjs/signals` runtime instance. SSR is not supported.
 
 ## Quick start: `createScope()`
 
@@ -67,6 +67,86 @@ const summary = scope(() => ({ count: count(), enabled: enabled() }));
 
 The callback must be synchronous. Await asynchronous work **before** calling `scope()`, not inside it.
 
+## Pending async memos and `NotReadyError`
+
+A synchronous callback may read an **existing async memo that is not ready yet**. In that case, Solid 2 throws `NotReadyError` as part of its pending-value protocol. `solid-deps` preserves the dependencies read up to that point **before rethrowing** the same error:
+
+```ts
+import { createMemo, createEffect, NotReadyError } from 'solid-js';
+import { createOwnerScope } from 'solid-deps';
+
+const memo = createMemo(async () => {
+  return await loadData();
+});
+
+createEffect(() => {
+  const scope = createOwnerScope();
+
+  // Example: an externally scheduled callback after the effect starts.
+  queueMicrotask(() => {
+    try {
+      console.log(scope(() => memo()));
+    } catch (error) {
+      if (error instanceof NotReadyError) {
+        // memo() has been subscribed to the original effect.
+        // Its successful settlement can invalidate that effect.
+        return;
+      }
+      throw error;
+    }
+  });
+
+  return 0;
+}, () => {});
+```
+
+**What this means:** the pending memo becomes a direct dependency of the original computation, even when `scope()` cannot return a value. If the memo later fulfills, Solid can schedule the original effect; its next normal recomputation may remove the late subscription if the effect no longer reads it. Only sources actually read **before** `NotReadyError` are attached. Other thrown errors still leave the original dependency graph unchanged.
+
+`NotReadyError` is **re-thrown**, not converted to `undefined` or an `AttachReadResult`. `createScope()` and `createOwnerScope()` share this behavior. When using a delayed callback outside Solid's tracked execution, catch or handle the error; simply propagating it does not automatically restore the original `<Loading>` boundary context. Fulfillment-based wakeup and basic suspended-effect behavior have been tested on rc.17; complex Loading/transition semantics and error-state recovery are not guaranteed.
+
+## Alternative: `createOwnerScope()`
+
+`createScope()` is **cycle-bound**: when the effect recomputes, an earlier scope becomes stale. Use `createOwnerScope()` when an older asynchronous callback deliberately needs to attach reads to the **same still-live effect**, even after that effect has rerun.
+
+```tsx
+import { createEffect, createSignal } from 'solid-js';
+import { createOwnerScope, DisposedScopeError } from 'solid-deps';
+
+const [key, setKey] = createSignal(0);
+const [late, setLate] = createSignal(0);
+
+createEffect(() => {
+  const ownerScope = createOwnerScope();
+  const current = key(); // Native dependency
+
+  setTimeout(() => {
+    try {
+      console.log(ownerScope(() => late()));
+    } catch (error) {
+      if (!(error instanceof DisposedScopeError)) throw error;
+    }
+  }, 2000);
+
+  return current;
+}, () => {});
+
+setKey(1); // The old ownerScope still targets the same live computation.
+```
+
+This example deliberately leaves the timeout running to demonstrate owner-bound behavior. **For async work that belongs only to a particular effect execution, prefer `createScope()` and cancel obsolete work using the effect's cleanup mechanism.**
+
+Comparison:
+
+| | `createScope()` | `createOwnerScope()` |
+| --- | --- | --- |
+| Captures | Computation and dependency generation | Computation identity only |
+| Reusable after a normal effect rerun | No — throws `StaleScopeError` | Yes, while the effect is alive |
+| After final disposal | Throws `DisposedScopeError` | Throws `DisposedScopeError` |
+| Callback return | Direct value | Direct value |
+| Extra dependencies survive every rerun | No | No |
+
+Owner-bound callbacks do **not** restore Solid ownership context, transfer to a replacement effect, or make attached dependencies permanent. An older callback may alter the currently running effect's dependency graph; use this behavior intentionally.
+
 ## API
 
 ### `createScope(owner?)`
@@ -89,6 +169,21 @@ A scope call:
 - Throws `DisposedScopeError` if the computation has been disposed. The callback is not executed.
 - Propagates errors thrown by the callback or the graph-validation mechanism.
 
+### `createOwnerScope(owner?)`
+
+Create a callable function bound to the lifetime of the current tracked computation, rather than its current execution cycle.
+
+```ts
+const scope = createOwnerScope();      // While an observer is tracking
+const other = createOwnerScope(owner); // Explicit existing computation owner
+await loadData();
+const value = scope(() => signal());   // Exact callback value
+```
+
+The implicit form requires an active observer at creation time. An explicit owner must be a tracking computation rather than a plain Solid owner/root. The handle keeps a reference to that **same** computation across normal reruns; it does not discover or switch to any newly created effect. Final disposal causes `DisposedScopeError`, and the callback is skipped. Other reader/graph errors propagate normally.
+
+Do not call it to perform tracked reads *inside an effect cleanup callback*: the temporary tracking computation required for grafting can be rejected by Solid in development mode. Use cleanup to cancel external timers or requests instead.
+
 ### `captureOwnerCycle(owner?)`
 
 Capture an opaque owner-cycle token with the same implicit-or-explicit owner behavior as `createScope`:
@@ -165,6 +260,7 @@ export interface AttachReadResult<T> {
 }
 
 export declare function createScope(owner?: Owner | null): Scope;
+export declare function createOwnerScope(owner?: Owner | null): Scope;
 export declare function captureOwnerCycle(owner?: Owner | null): OwnerCycle;
 export declare function attachRead<T>(
   target: Owner | OwnerCycle | null,
@@ -181,18 +277,19 @@ With `createScope()`, a callback returning `number` gives a `number` directly. W
 
 - An attached read affects **future** invalidations. Writes that occurred before registration are not replayed.
 - Extra dependencies can be removed on the target's next normal recomputation. Reattach them on each async effect execution when needed.
-- `scope()` / `attachRead()` callbacks must only make synchronous, settled reactive reads. Creating owned computations, registering cleanups, or mutating signals from inside them is not supported.
+- `scope()` / `attachRead()` callbacks must be synchronous. They may read existing pending memos: `NotReadyError` is propagated **after** transferring previously read dependencies. Ordinary thrown errors leave the target unchanged. Creating owned computations, registering cleanups, or mutating signals from inside callbacks is not supported.
 - A callback that allocates owned children/cleanups, or reads a newly allocated probe-owned memo, is rejected. Access existing independently owned memos instead.
 - Reads happen under a temporary observer; `getOwner()`, `getObserver()`, pending resource behavior, transitions, Loading boundaries, and ownership-sensitive operations are **not equivalent** to running under the original effect.
-- Pending reads can throw (such as `NotReadyError`). Advanced suspense/transition and held-transaction behavior is not broadly supported.
-- A scope invalidated by a newer run throws rather than silently executing a stale callback. This doesn't cancel async work or its other side effects.
+- A pending memo can throw `NotReadyError`, and the attached observer will keep the dependency for successful settlement. This does not recreate the original Loading boundary or guarantee retry after rejection. Advanced suspense/transition and held-transaction behavior is not broadly supported.
+- Cycle-bound `createScope()` rejects an older execution after rerun; `createOwnerScope()` stays valid for the same live observer, but old callbacks can change the new execution's dependencies. Neither automatically cancels work.
+- Do not graft reads from inside effect-phase cleanup; use cleanup to cancel obsolete external work. Final disposal invalidates both scope types.
 - Uses private observer graph internals discovered by inspecting disposable runtime probes. This supports field renaming when graph relationships remain compatible, but cannot guarantee future graph algorithms, scheduler semantics, or minifier property restructuring. Discovery fails with an error if required fields are ambiguous or missing.
 - Calibrates only once per loaded package instance. In an ambiguous numeric-generation case, a field-position clue is used after checking link-generation equality; reordered internal fields may therefore cause calibration to fail or be misidentified. Test on new versions before shipping.
 - Other Solid versions, SSR, and multiple separately instantiated signal runtimes are not guaranteed.
 
 ## Online Solid playground check
 
-A copy-pasteable `main.tsx` is available in the source ZIP at `examples/online-playground/main.tsx`. Install `solid-deps@0.0.3`, ensure the playground runs a Solid 2 browser build with a shared signals runtime, and use **Run runtime checks**. It reports successful automatic layout discovery, async dependency attachment, deduplication, future updates, stale cycles, and disposal.
+A copy-pasteable `main.tsx` is available in the source ZIP at `examples/online-playground/main.tsx`. Install `solid-deps@0.0.5`, ensure the playground runs a Solid 2 browser build with a shared signals runtime, and use **Run runtime checks**. It reports successful automatic layout discovery, async dependency attachment, deduplication, future updates, stale cycles, and disposal.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-deps",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Experimental direct dependency attachment for Solid 2 reactive observers after async boundaries",
   "type": "module",
   "license": "MIT",
@@ -37,9 +37,9 @@
   ],
   "scripts": {
     "setup": "node scripts/setup.mjs",
-    "test": "node --conditions=browser --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.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/test-discovery.mjs",
-    "test:dev": "node --conditions=browser --conditions=development --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.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/test-discovery.mjs",
-    "test:observe": "node --conditions=browser --conditions=observe --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.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/test-discovery.mjs",
+    "test": "node --conditions=browser --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.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/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs",
+    "test:dev": "node --conditions=browser --conditions=development --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.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/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs",
+    "test:observe": "node --conditions=browser --conditions=observe --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.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/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs",
     "test:all": "node scripts/run-tests.mjs",
     "test:package": "node scripts/smoke-package.mjs",
     "test:browser": "node --test test/browser/playwright.test.mjs",

package/src/attach-read.mjs

@@ -1,11 +1,13 @@
 /**
  * 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.
+ * Scope: synchronous reactive reads, including pending memo reads that throw NotReadyError.
+ * Reads execute in a temporary observer; pending dependencies can be transferred,
+ * but this does not restore the target effect's Suspense/Loading context.
  * 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';
+import { createRoot, createReaction, getObserver, isDisposed, NotReadyError } from '@solidjs/signals';
 
 import { layoutOf } from './discover.mjs';
 
@@ -45,7 +47,9 @@ export function captureOwnerCycle(owner = getObserver()) {
 
 /**
  * Attach dependencies read by `read` onto `target` without re-running target.
- * Returns an object { value, added, duplicate, promoted, stale, disposed }.
+ * Returns an object { value, added, duplicate, promoted, stale, disposed }
+ * on successful reads. A NotReadyError preserves tracked dependencies before
+ * rethrowing so pending memos can wake the target; other exceptions roll back.
  * They remain until target recomputes and performs normal dependency reconciliation.
  */
 export function attachRead(observerOrCycle, read) {
@@ -80,7 +84,13 @@ export function attachRead(observerOrCycle, read) {
         try { retValue = read(); } catch (err) { caught = [err]; }
       });
     });
-    if (caught) throw caught[0];
+    // Solid's normal tracking pass keeps dependencies read before NotReadyError,
+    // so pending sources can wake the computation after settling. Preserve the
+    // same dependency semantics for a late read, while still propagating the
+    // suspension signal to the caller. Other exceptions remain transactional:
+    // they must not mutate the target observer's graph.
+    const pendingError = caught?.[0] instanceof NotReadyError ? caught[0] : null;
+    if (caught && !pendingError) 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');
@@ -150,6 +160,9 @@ export function attachRead(observerOrCycle, read) {
       nextList[i][s.next] = nextList[i + 1] ?? null;
     target[s.deps] = nextList[0] ?? null;
     target[s.tail] = validated.at(-1) ?? null;
+    // Re-throw only AFTER the graph transfer has succeeded. The temporary
+    // probe is disposed in finally; its moved edges now belong to the target.
+    if (pendingError) throw pendingError;
     return { value: retValue,
       added: additions.length,
       duplicate: kept.length - promoted.length,
@@ -182,17 +195,34 @@ export class DisposedScopeError extends Error {
   }
 }
 
-/**
- * Capture the current observer cycle and return a callable dependency scope.
- * The callback must be synchronous. Its return value is returned directly.
- * Throws instead of returning an ambiguous undefined when the cycle has ended.
- */
-export function createScope(owner) {
-  const cycle = arguments.length === 0 ? captureOwnerCycle() : captureOwnerCycle(owner);
+/** Shared callable facade for owner-bound and cycle-bound dependency scopes. */
+function makeScope(target) {
   return function scope(read) {
-    const result = attachRead(cycle, read);
+    const result = attachRead(target, read);
     if (result.disposed) throw new DisposedScopeError();
     if (result.stale) throw new StaleScopeError();
     return result.value;
   };
 }
+
+/**
+ * Capture the current observer cycle and return a callable dependency scope.
+ * The callback must be synchronous; it may throw NotReadyError after grafting
+ * its pending dependencies. An earlier cycle becomes stale after rerun.
+ */
+export function createScope(owner) {
+  return makeScope(arguments.length === 0 ? captureOwnerCycle() : captureOwnerCycle(owner));
+}
+
+/**
+ * Capture a live computation owner, without binding to its dependency generation.
+ * The returned callback remains usable across that computation's normal reruns,
+ * but rejects reads after its final disposal. An old callback can therefore
+ * attach dependencies to the newest execution of the same computation.
+ */
+export function createOwnerScope(owner) {
+  const observer = arguments.length === 0 ? getObserver() : owner;
+  // Validate at capture time, including the initial empty dependency list.
+  layoutOf(observer);
+  return makeScope(observer);
+}

package/src/discover.mjs

@@ -1,6 +1,7 @@
 /**
  * Discover the private linked dependency graph from controlled, disposable
- * Solid computations. No minified or development property names are encoded.
+ * Solid computations. Only recognizable descriptive development property names
+ * are encoded; all unknown layouts use the name-independent inference.
  *
  * This is topology inference, not a guarantee of compatibility with a new
  * algorithm or a property-mangling transform that changes graph semantics.
@@ -11,6 +12,111 @@ import {
 } from '@solidjs/signals';
 
 let inferred;
+const diagnostics = { knownDev: 0, inferred: 0 };
+
+/** Internal test-only counters. Not exported from the package entry point. */
+export function _discoveryDiagnostics() {
+  return { ...diagnostics, origin: inferred?.origin ?? null };
+}
+
+// Development field names are a candidate, never evidence of graph compatibility.
+// Minified field names are deliberately not recorded here.
+const knownDev = Object.freeze({
+  deps: '_deps', tail: '_depsTail', gen: '_depGen', flags: '_flags',
+  dep: '_dep', sub: '_sub', next: '_nextDep', linkGen: '_gen',
+  parent: '_parent', child: '_firstChild', disposal: '_disposal',
+  recomputingBit: 4
+});
+const devFields = ['deps', 'tail', 'gen', 'flags', 'parent', 'child', 'disposal'];
+
+// Only inspect own *data* properties to avoid executing an arbitrary getter
+// during compatibility detection. A missing data field is not silently read.
+function data(node, key) {
+  if (!obj(node)) return { exists: false };
+  const descriptor = Object.getOwnPropertyDescriptor(node, key);
+  return descriptor && 'value' in descriptor
+    ? { exists: true, value: descriptor.value }
+    : { exists: false };
+}
+
+/**
+ * Pure, non-mutating candidate check; the initial observer may have zero deps,
+ * or a validated prefix followed by an older-generation stale suffix.
+ * `null` means unknown or partially renamed; corrupted complete layouts throw.
+ * Kept as an internal module export for the source-tree regression suite.
+ */
+export function tryKnownDevLayout(node) {
+  if (!obj(node)) return null;
+  const present = devFields.filter(role => Object.hasOwn(node, knownDev[role]));
+  if (present.length !== devFields.length) return null;
+
+  const read = (object, key, role) => {
+    const slot = data(object, key);
+    if (!slot.exists) throw new Error(`solid-deps: invalid known development ${role}; refusing graph mutation`);
+    return slot.value;
+  };
+  const fail = why => { throw new Error(`solid-deps: invalid known development graph (${why}); refusing graph mutation`); };
+  const gen = read(node, knownDev.gen, 'generation');
+  const flags = read(node, knownDev.flags, 'flags');
+  const head = read(node, knownDev.deps, 'head');
+  const tail = read(node, knownDev.tail, 'tail');
+  const parent = read(node, knownDev.parent, 'parent');
+  const child = read(node, knownDev.child, 'child');
+  const disposal = read(node, knownDev.disposal, 'disposal');
+
+  if (!Number.isSafeInteger(gen) || gen < 0 || !Number.isSafeInteger(flags) || flags < 0)
+    fail('generation or flags is not a nonnegative integer');
+  // Multiple onCleanup() calls create an array of disposal callbacks.
+  // Check their data slots without invoking a potentially shadowed .every().
+  let validDisposal = disposal == null || typeof disposal === 'function';
+  if (Array.isArray(disposal)) {
+    validDisposal = disposal.length > 0;
+    for (let i = 0; i < disposal.length; i++) {
+      const callback = data(disposal, String(i));
+      if (!callback.exists || typeof callback.value !== 'function') validDisposal = false;
+    }
+  }
+  if (head != null && !obj(head) || tail != null && !obj(tail) ||
+      parent != null && !obj(parent) || child != null && !obj(child) ||
+      !validDisposal)
+    fail('invalid dependency or lifecycle value');
+  if (head == null && tail != null) fail('tail exists without a head');
+
+  let edge = head;
+  let tailReached = tail == null;
+  const visited = new Set();
+  while (edge != null) {
+    if (!obj(edge) || visited.has(edge)) fail('non-link or cyclic dependency chain');
+    visited.add(edge);
+    const source = read(edge, knownDev.dep, 'link source');
+    const subscriber = read(edge, knownDev.sub, 'link subscriber');
+    const linkGen = read(edge, knownDev.linkGen, 'link generation');
+    const next = read(edge, knownDev.next, 'next link');
+    if (!obj(source) || subscriber !== node || !Number.isSafeInteger(linkGen) ||
+        linkGen < 0 || linkGen > gen || next != null && !obj(next))
+      fail('inconsistent dependency link');
+
+    // Check both sides of the source subscription list. In rc.17 dev builds,
+    // source._subs and edge._nextSub connect each signal back to its readers.
+    // This is a read-only check, never an attempt to repair graph structure.
+    let sub = read(source, '_subs', 'source subscriber head');
+    const subscribers = new Set();
+    let found = false;
+    while (sub != null) {
+      if (!obj(sub) || subscribers.has(sub)) fail('invalid source subscriber list');
+      subscribers.add(sub);
+      if (sub === edge) found = true;
+      sub = read(sub, '_nextSub', 'subscriber next');
+    }
+    if (!found) fail('source is not subscribed back to dependency link');
+
+    if (edge === tail) tailReached = true;
+    edge = next;
+  }
+  if (!tailReached) fail('tail not reachable from dependency head');
+  return knownDev;
+}
+
 const own = (obj) => obj && typeof obj === 'object'
   ? Reflect.ownKeys(obj).filter(key => Object.prototype.propertyIsEnumerable.call(obj, key)) : [];
 const entries = obj => own(obj).map(key => [key, obj[key]]);
@@ -157,12 +263,24 @@ function discover() {
   }
 }
 
-export function internalLayout() {
-  return inferred ??= discover();
+export function internalLayout(node) {
+  if (inferred) return inferred.layout;
+  // Called with the real target by layoutOf; keep the optional no-argument
+  // form for internal source-tree tests and unknown-layout calibration.
+  const dev = node == null ? null : tryKnownDevLayout(node);
+  if (dev) {
+    diagnostics.knownDev++;
+    inferred = { layout: dev, origin: 'known-dev' };
+  } else {
+    const layout = discover();
+    diagnostics.inferred++;
+    inferred = { layout, origin: 'inferred' };
+  }
+  return inferred.layout;
 }
 
 export function layoutOf(node) {
-  const shape = internalLayout();
+  const shape = internalLayout(node);
   if (!obj(node) || typeof node[shape.gen] !== 'number' ||
       !(shape.deps in node) || !(shape.tail in node) ||
       typeof node[shape.flags] !== 'number' || !(shape.child in node) ||

package/src/index.mjs

@@ -1 +1 @@
-export { attachRead, captureOwnerCycle, createScope, inspectDeps, StaleScopeError, DisposedScopeError } from './attach-read.mjs';
+export { attachRead, captureOwnerCycle, createScope, createOwnerScope, inspectDeps, StaleScopeError, DisposedScopeError } from './attach-read.mjs';

package/types/index.d.mts

@@ -47,6 +47,13 @@ export declare function captureOwnerCycle(owner?: Owner | null): OwnerCycle;
  */
 export declare function createScope(owner?: Owner | null): Scope;
 
+/**
+ * Create an owner-bound callable scope. Unlike createScope(), it stays valid
+ * across normal reruns of the same computation and rejects final disposal.
+ * Captured work from an older execution may attach to the current execution.
+ */
+export declare function createOwnerScope(owner?: Owner | null): Scope;
+
 /**
  * Graft dependencies read synchronously by `read` onto an existing observer.
  * The callback is skipped when the target is stale or disposed.