octane 0.2.11 → 0.2.13

package/dist/signals/requests.js

@@ -1,10 +1,15 @@
 import { decodeSignalValue, encodeSignalValue } from "./encoding.js";
+import { createResourceCellWith } from "./engine.js";
+import { SignalStreamError } from "./errors.js";
 import {
   ScopedNode,
+  CandidateUnsupportedError,
   assertAlive,
   assertWritable,
   errorState,
+  idleState,
   invalidateNode,
+  isThenable,
   pendingState,
   publishNode,
   pure,
@@ -12,8 +17,18 @@ import {
   refreshNode,
   releaseRetention,
   signalBatch,
-  untrack
+  untrack,
+  untrackCommitted
 } from "./graph.js";
+import {
+  QUERY_REQUEST,
+  skip
+} from "./types.js";
+import {
+  captureCurrentServerSignalQueryAttemptObserver,
+  hasServerSignalQueryAttemptObserver,
+  serverSignalQueryAttemptObserver
+} from "./query-attempt-observer.js";
 class Request {
   constructor(definition, argument) {
     this.definition = definition;
@@ -24,6 +39,9 @@ class Request {
     Object.freeze(this);
   }
   definition;
+  get [QUERY_REQUEST]() {
+    return void 0;
+  }
   queryKey;
   identity;
   argument;
@@ -42,16 +60,24 @@ function query(key, load, options) {
   });
   return Object.freeze(describe);
 }
-function makeAttempt(entry) {
+function createResource(owner, key, describe) {
+  return createResourceCellWith(owner, key, describe, initializeResource, true);
+}
+function makeAttempt(entry, generation, streamed = false) {
   let resolve;
   const settled = new Promise((done) => {
     resolve = done;
   });
   return {
     entry,
-    controller: new AbortController(),
+    controller: streamed ? void 0 : new AbortController(),
     iterator: void 0,
     settled,
+    generation,
+    streamed,
+    result: void 0,
+    observations: void 0,
+    sequence: 0,
     resolve,
     hasYielded: false
   };
@@ -75,13 +101,33 @@ class RequestEntry {
   get active() {
     return this.attempt !== void 0;
   }
+  get attemptGeneration() {
+    return this.generation;
+  }
+  observe(nodeKey) {
+    const attempt = this.attempt;
+    if (!attempt || attempt.streamed) return;
+    const context = serverSignalQueryAttemptObserver(this.owner.scopeKey);
+    if (context === void 0) return;
+    const observations = attempt.observations ??= context.createObservations();
+    observations.observe(context, {
+      nodeKey,
+      selectionKey: this.request.identity,
+      attempt: attempt.generation,
+      kind: this.request.definition.kind,
+      result: attempt.result,
+      isCurrent: () => currentEntry(attempt) === this
+    });
+    return attempt;
+  }
   start(pending) {
+    if (this.owner.readBarrier !== void 0) return;
     const generation = ++this.generation;
     this.stopAttempt();
-    if (generation !== this.generation || this.owner.retired || this.owner.requests.get(this.request.identity) !== this || !this.consumers.size)
+    if (generation !== this.generation || this.owner.readBarrier !== void 0 || this.owner.retired || this.owner.requests.get(this.request.identity) !== this || !this.consumers.size)
       return;
     const previous = this.state.snapshot;
-    const attempt = this.attempt = makeAttempt(this);
+    const attempt = this.attempt = makeAttempt(this, generation);
     const connection = this.request.definition.kind === "stream" ? "connecting" : "none";
     this.state = !pending && previous.status === "ready" ? readyState(previous.value, {
       refreshing: true,
@@ -95,7 +141,8 @@ class RequestEntry {
       result = untrack(
         () => signalBatch(
           () => this.request.definition.load(this.request.argument, {
-            signal: attempt.controller.signal
+            signal: attempt.controller.signal,
+            ...previous.status === "ready" ? { previous: previous.value } : {}
           })
         )
       );
@@ -104,7 +151,73 @@ class RequestEntry {
       return;
     }
     if (this.request.definition.kind === "stream") observeStream(attempt, result);
-    else observePromise(attempt, result);
+    else {
+      if (currentEntry(attempt)) attempt.result = result;
+      observePromise(attempt, result);
+    }
+  }
+  startStreamed(identity) {
+    if (this.owner.readBarrier !== void 0 || identity.selectionKey !== this.request.identity || identity.attempt < this.generation || this.attempt === void 0 && identity.attempt === this.generation && this.state.snapshot.status !== "pending" || this.owner.retired || !this.consumers.size) {
+      return false;
+    }
+    if (this.attempt?.streamed && this.attempt.generation === identity.attempt) {
+      return true;
+    }
+    this.generation = identity.attempt;
+    this.stopAttempt();
+    if (this.generation !== identity.attempt || this.owner.readBarrier !== void 0 || this.owner.retired || this.owner.requests.get(this.request.identity) !== this || !this.consumers.size) {
+      return false;
+    }
+    this.attempt = makeAttempt(this, identity.attempt, true);
+    return true;
+  }
+  acceptStreamed(frame) {
+    const attempt = this.attempt;
+    if (!attempt?.streamed || attempt.generation !== frame.identity.attempt || frame.sequence !== attempt.sequence || currentEntry(attempt) !== this) {
+      return false;
+    }
+    attempt.sequence++;
+    signalBatch(() => {
+      if (frame.kind === "open") return;
+      if (frame.kind === "value") {
+        attempt.hasYielded = true;
+        this.state = readyState(decodeSignalValue(frame.value), {
+          requestKey: this.request.identity,
+          connection: this.request.definition.kind === "stream" ? "open" : "none",
+          complete: false
+        });
+        this.deliver();
+        return;
+      }
+      if (frame.kind === "error") {
+        this.state = errorState(
+          new SignalStreamError(frame.code),
+          this.request.definition.kind === "stream" ? "closed" : "none",
+          this.request.identity
+        );
+        completeAttempt(attempt);
+        this.deliver();
+        return;
+      }
+      if (!attempt.hasYielded || this.state.snapshot.status !== "ready") {
+        this.state = errorState(
+          new Error("The streamed signal completed without yielding a value."),
+          this.request.definition.kind === "stream" ? "closed" : "none",
+          this.request.identity
+        );
+        completeAttempt(attempt);
+        this.deliver();
+        return;
+      }
+      this.state = readyState(this.state.snapshot.value, {
+        requestKey: this.request.identity,
+        connection: this.request.definition.kind === "stream" ? "closed" : "none",
+        complete: true
+      });
+      completeAttempt(attempt);
+      this.deliver();
+    });
+    return true;
   }
   deliver() {
     for (const consumer of this.consumers) consumer.deliver();
@@ -118,8 +231,10 @@ class RequestEntry {
     const iterator = attempt.iterator;
     attempt.controller = void 0;
     attempt.iterator = void 0;
+    attempt.result = void 0;
+    attempt.observations?.retire();
     attempt.resolve();
-    if (controller) untrack(() => signalBatch(() => controller.abort()));
+    if (controller) untrackCommitted(() => signalBatch(() => controller.abort()));
     if (iterator) closeIterator(iterator);
   }
   remove(consumer) {
@@ -136,11 +251,13 @@ function currentEntry(attempt) {
   return entry && !entry.owner.retired && entry.attempt === attempt ? entry : void 0;
 }
 function completeAttempt(attempt) {
+  attempt.observations?.complete();
   const entry = attempt.entry;
   if (entry?.attempt === attempt) entry.attempt = void 0;
   attempt.entry = void 0;
   attempt.controller = void 0;
   attempt.iterator = void 0;
+  attempt.result = void 0;
   attempt.resolve();
 }
 function observePromise(attempt, result) {
@@ -160,6 +277,7 @@ function observePromise(attempt, result) {
 function failAttempt(attempt, error) {
   const entry = currentEntry(attempt);
   if (!entry) return;
+  attempt.observations?.fail(error);
   signalBatch(() => {
     const iterator = attempt.iterator;
     entry.state = errorState(
@@ -176,7 +294,7 @@ function ignoreRetiredCloseFailure() {
 }
 function closeIterator(iterator) {
   try {
-    const result = untrack(() => signalBatch(() => iterator.return?.()));
+    const result = untrackCommitted(() => signalBatch(() => iterator.return?.()));
     Promise.resolve(result).catch(ignoreRetiredCloseFailure);
   } catch {
   }
@@ -272,7 +390,9 @@ function receiveStreamStep(attempt, result) {
     });
     accepted.deliver();
   });
-  nextStreamStep(attempt);
+  const observed = attempt.observations?.publish(value);
+  if (observed === void 0) nextStreamStep(attempt);
+  else observed.then(() => nextStreamStep(attempt));
 }
 class ResourceBinding {
   constructor(owner, node, describe, seed, retained = seed) {
@@ -286,7 +406,11 @@ class ResourceBinding {
       kind: identity.kind,
       argument: decodeSignalValue(identity.argument)
     } : void 0;
-    node.compute = () => this.compute();
+    node.compute = () => {
+      const pending = this.pendingObserver;
+      this.pendingObserver = void 0;
+      return pending === void 0 || hasServerSignalQueryAttemptObserver(this.owner.scopeKey) ? this.compute() : pending(() => this.compute());
+    };
     node.retry = (options) => this.retry(options);
   }
   owner;
@@ -297,18 +421,92 @@ class ResourceBinding {
   retainedRequest;
   seeded;
   describedAttempt;
+  observedAttempt;
+  pendingObserver;
   pendingPromise;
   resolvePending;
+  streamedSelection;
+  selectionAuthority = {};
   request() {
     const request = pure(() => this.describe());
+    if (request === skip) return request;
     if (!(request instanceof Request))
-      throw new TypeError("asyncSignal$ must describe a query request.");
+      throw new TypeError("A resource must describe a query request.");
     return request;
   }
+  forkCandidate(target) {
+    if (this.streamedSelection || this.owner.streamedSelections?.has(this.node.key)) {
+      throw new CandidateUnsupportedError(
+        "Streamed candidates are not supported by this prototype."
+      );
+    }
+    const fork = new ResourceBinding(this.owner, target, this.describe);
+    fork.candidate = true;
+    fork.retainedRequest = this.retainedRequest;
+    return {
+      dispose: () => fork.dispose(),
+      prepare: () => {
+        if (this.streamedSelection || this.owner.streamedSelections?.has(this.node.key))
+          return { status: "invalid" };
+        const entry = fork.selected;
+        const attempt = entry?.attempt;
+        if (entry) {
+          if (attempt?.streamed) return { status: "invalid" };
+          const snapshot = entry.state.snapshot;
+          if (attempt && (entry.request.definition.kind !== "stream" || snapshot.status !== "ready"))
+            return { status: "pending", waiting: target.state?.waiting ?? attempt.settled };
+          if (!(snapshot.status === "ready" && (snapshot.complete || entry.request.definition.kind === "stream") || snapshot.status === "error"))
+            return { status: "invalid" };
+        } else if (target.state?.snapshot.status !== "idle") {
+          const state2 = target.state;
+          if (state2?.snapshot.status === "error")
+            return { status: "error", error: state2.snapshot.error };
+          if (state2?.waiting) return { status: "pending", waiting: state2.waiting };
+          return { status: "invalid" };
+        }
+        const state = entry?.state;
+        const authority = this.selectionAuthority;
+        const forkAuthority = fork.selectionAuthority;
+        return {
+          status: "ready",
+          receipt: {
+            validate: () => !this.streamedSelection && !this.owner.streamedSelections?.has(this.node.key) && this.selectionAuthority === authority && fork.selectionAuthority === forkAuthority && fork.selected === entry && (entry ? entry.state === state && entry.attempt === attempt && entry.consumers.has(fork) : target.state?.snapshot.status === "idle"),
+            publish: () => {
+              const previous = this.selected;
+              const resolve = this.resolvePending;
+              entry?.consumers.add(this);
+              entry?.consumers.delete(fork);
+              this.selected = entry;
+              this.selectedIdentity = fork.selectedIdentity;
+              this.retainedRequest = fork.retainedRequest;
+              this.describedAttempt = fork.describedAttempt;
+              this.observedAttempt = fork.observedAttempt;
+              this.selectionAuthority = fork.selectionAuthority;
+              this.pendingObserver = void 0;
+              this.pendingPromise = void 0;
+              this.resolvePending = void 0;
+              this.seeded = void 0;
+              fork.selected = void 0;
+              return () => {
+                resolve?.();
+                if (previous !== entry && previous !== this.selected) previous?.remove(this);
+              };
+            }
+          }
+        };
+      }
+    };
+  }
   compute() {
     let request;
     try {
-      request = this.request();
+      const described = this.request();
+      if (described === skip) {
+        this.detach();
+        this.seeded = void 0;
+        return idleState();
+      }
+      request = described;
       const previousDefinition = this.owner.queryDefinitions.get(request.queryKey);
       if (previousDefinition && (previousDefinition.load !== request.definition.load || previousDefinition.kind !== request.definition.kind)) {
         throw new TypeError(
@@ -317,12 +515,18 @@ class ResourceBinding {
       }
       this.owner.queryDefinitions.set(request.queryKey, request.definition);
     } catch (error) {
+      if (isThenable(error)) {
+        this.pendingObserver = captureCurrentServerSignalQueryAttemptObserver(this.owner.scopeKey);
+      }
       this.detach();
       throw error;
     }
     if (this.selected?.request.identity !== request.identity) {
       this.detach();
       assertAlive(this.owner);
+      if (this.candidate && this.describe === void 0) {
+        throw new TypeError("The signal candidate has retired.");
+      }
       this.selectedIdentity = {
         queryKey: request.queryKey,
         kind: request.definition.kind,
@@ -344,8 +548,19 @@ class ResourceBinding {
       this.selected = entry;
       entry.consumers.add(this);
       this.owner.trace("select", this.node);
-      if (start) entry.start(entry.state.snapshot.status !== "ready");
+      const streamed = this.candidate ? void 0 : this.owner.streamedSelections?.get(this.node.key);
+      if (streamed && streamed.selectionKey !== request.identity) {
+        this.owner.discardCompletedStreamedSelection?.(streamed);
+      }
+      if (streamed?.selectionKey === request.identity && entry.startStreamed(streamed)) {
+        this.streamedSelection = streamed;
+        this.owner.streamedSelectionReady?.(this);
+        entry.deliver();
+      } else if (start) {
+        entry.start(entry.state.snapshot.status !== "ready");
+      }
     }
+    this.observeSelectedAttempt();
     assertAlive(this.owner);
     return this.state();
   }
@@ -383,17 +598,65 @@ class ResourceBinding {
   }
   detach() {
     const entry = this.selected;
+    if (!this.candidate && this.streamedSelection === this.owner.streamedSelections?.get(this.node.key)) {
+      this.owner.streamedSelections?.delete(this.node.key);
+    }
     this.selected = void 0;
     this.selectedIdentity = void 0;
     this.describedAttempt = void 0;
+    this.observedAttempt = void 0;
     this.resolvePending?.();
     this.resolvePending = void 0;
     this.pendingPromise = void 0;
+    this.streamedSelection = void 0;
+    this.selectionAuthority = {};
     entry?.remove(this);
   }
+  observeSelectedAttempt() {
+    const attempt = this.selected?.attempt;
+    if (!attempt || attempt === this.observedAttempt) return;
+    if (this.selected.observe(this.node.key) === attempt) this.observedAttempt = attempt;
+  }
+  get authority() {
+    return this.selected ? this.selectionAuthority : void 0;
+  }
+  isStreamedSelectionReady(identity) {
+    return this.streamedSelection === identity && this.selected?.request.identity === identity.selectionKey;
+  }
+  bindStreamedSelection(identity) {
+    assertAlive(this.owner);
+    const entry = this.selected;
+    if (identity.nodeKey !== this.node.key) return false;
+    if (!entry || entry.request.identity !== identity.selectionKey) {
+      this.streamedSelection = void 0;
+      return true;
+    }
+    if (!entry.startStreamed(identity)) return false;
+    this.streamedSelection = identity;
+    entry.deliver();
+    return true;
+  }
+  acceptStreamed(frame) {
+    const identity = this.streamedSelection;
+    const entry = this.selected;
+    if (!identity || !entry || identity.nodeKey !== frame.identity.nodeKey || identity.selectionKey !== frame.identity.selectionKey || identity.selectionGeneration !== frame.identity.selectionGeneration || identity.attempt !== frame.identity.attempt || frame.kind === "open" && frame.resource !== entry.request.definition.kind) {
+      return false;
+    }
+    return entry.acceptStreamed(frame);
+  }
+  failStreamed(identity, error) {
+    const streamed = this.streamedSelection;
+    const entry = this.selected;
+    if (!streamed || !entry || streamed.nodeKey !== identity.nodeKey || streamed.selectionKey !== identity.selectionKey || streamed.selectionGeneration !== identity.selectionGeneration || streamed.attempt !== identity.attempt || entry.attempt?.generation !== identity.attempt || !entry.attempt.streamed) {
+      return false;
+    }
+    failAttempt(entry.attempt, error);
+    return true;
+  }
   retry(options) {
     assertAlive(this.owner);
     assertWritable();
+    if (!this.selected && this.node.state?.snapshot.status === "idle") return;
     signalBatch(() => {
       const previous = this.selected;
       if (!previous) invalidateNode(this.node);
@@ -403,7 +666,23 @@ class ResourceBinding {
       }
       this.owner.trace("retry", this.node);
       if (this.selected === previous) this.selected.start(options?.pending === true);
+      this.observeSelectedAttempt();
+    });
+  }
+  adopt(requestKey, value) {
+    assertAlive(this.owner);
+    assertWritable();
+    const entry = this.selected;
+    if (!entry || entry.request.identity !== requestKey) return false;
+    const streaming = entry.request.definition.kind === "stream";
+    if (!streaming) entry.stopAttempt();
+    entry.state = readyState(value, {
+      requestKey: entry.request.identity,
+      connection: streaming ? entry.state.snapshot.connection : "none",
+      complete: streaming ? entry.state.snapshot.complete : true
     });
+    entry.deliver();
+    return true;
   }
   seedRequest(retained = false) {
     const request = retained ? this.retainedRequest : this.selectedIdentity;
@@ -415,13 +694,16 @@ class ResourceBinding {
     };
   }
   acceptsSeed(seed) {
-    return matchesSeed(this.request(), seed);
+    const request = this.request();
+    return request !== skip && matchesSeed(request, seed);
   }
   dispose() {
     this.detach();
+    this.pendingObserver = void 0;
     this.describe = void 0;
     this.seeded = void 0;
     this.retainedRequest = void 0;
+    this.streamedSelection = void 0;
   }
 }
 function matchesSeed(request, seed) {
@@ -433,6 +715,7 @@ function initializeResource(owner, node, describe, seed, retained = seed) {
 export {
   RequestEntry,
   ResourceBinding,
+  createResource,
   initializeResource,
   query
 };

package/dist/signals/scalar-computations.d.ts

@@ -0,0 +1,2 @@
+import type { DerivedCompute, DerivedSignal, Scope } from './types.js';
+export declare function createDeclaredScalarCell<T>(owner: Scope, key: string, compute: DerivedCompute<T>): DerivedSignal<T>;

package/dist/signals/scalar-computations.js

@@ -0,0 +1,60 @@
+import { createDerivedCellWith } from "./engine.js";
+import {
+  CandidateUnsupportedError,
+  derivedValueState,
+  errorState,
+  invalidateNode,
+  isThenable,
+  pendingState,
+  refreshNode
+} from "./graph.js";
+class ScalarBinding {
+  constructor(owner, node, compute) {
+    this.owner = owner;
+    this.node = node;
+    this.compute = compute;
+    node.compute = (target) => {
+      if (owner.readBarrier !== void 0) {
+        this.frozen = true;
+        return target.state?.snapshot.status === "ready" ? target.state : pendingState(owner.readBarrier);
+      }
+      let result;
+      try {
+        result = this.compute();
+      } catch (error) {
+        if (isThenable(error)) throw error;
+        return errorState(error);
+      }
+      return derivedValueState(target, result);
+    };
+  }
+  owner;
+  node;
+  frozen = false;
+  compute;
+  forkCandidate(target) {
+    if (this.frozen || this.owner.readBarrier || !this.compute) {
+      throw new CandidateUnsupportedError("Frozen scalar candidates are not supported.");
+    }
+    target.compute = this.node.compute;
+  }
+  suspend() {
+    return false;
+  }
+  resume() {
+    if (!this.frozen || this.owner.retired || this.owner.readBarrier !== void 0 || !this.compute)
+      return;
+    this.frozen = false;
+    invalidateNode(this.node);
+    refreshNode(this.node);
+  }
+  dispose() {
+    this.compute = void 0;
+  }
+}
+function createDeclaredScalarCell(owner, key, compute) {
+  return createDerivedCellWith(owner, key, compute, void 0, ScalarBinding);
+}
+export {
+  createDeclaredScalarCell
+};

package/dist/signals/server.d.ts

@@ -1,3 +1,5 @@
+/** Server twin selected by the native-read compiler for octane/signals/client. */
+export * from './index.js';
 import type { WritableSignal } from './types.js';
 /** Local server state is recreated on a new pass and never enters shared seeds. */
 export declare function useSignal$<T>(initial: T | (() => T), slot?: symbol): WritableSignal<T>;

package/dist/signals/server.js

@@ -1,3 +1,4 @@
+export * from "./index.js";
 import { nativeLocalHook } from "../runtime.server.js";
 import { createLocalScope } from "./engine.js";
 function disposeLocalSignal(cell) {

package/dist/signals/transition-candidate.d.ts

@@ -0,0 +1,71 @@
+import type { ScopedNode, SignalReadMode } from './graph.js';
+import { type NativeReadSource, type NativeTransitionConsumer } from './read-protocol.js';
+export type CandidatePreparation = {
+    status: 'ready';
+    token: object;
+    receipt: {
+        publish(accepted?: () => void): boolean;
+    };
+} | {
+    status: 'pending';
+    token: object;
+    wakeables: readonly PromiseLike<unknown>[];
+} | {
+    status: 'error';
+    token: object;
+    error: unknown;
+} | {
+    status: 'invalid';
+    token: object;
+    reason: 'stale' | 'unsupported';
+};
+interface PreparationWake {
+    notify?: (event: {
+        kind: 'retry' | 'invalid';
+        token: object;
+    }) => void;
+    validate?: () => boolean;
+    token?: object;
+    queued: boolean;
+    invalid: boolean;
+}
+/**
+ * Private transition graph. The renderer supplies admission through existing
+ * presentation transactions; ordinary signal consumers do not retain this class.
+ */
+export declare class SignalCandidateFrame {
+    private entries;
+    private originals;
+    private generation;
+    private active;
+    private preparationToken;
+    private preparationWatch;
+    private demand;
+    run<T>(callback: () => T): T;
+    resolve<T>(node: ScopedNode<T>): ScopedNode<T>;
+    write<T>(node: ScopedNode<T>, value: T | ((previous: T) => T)): void;
+    /** Only observed candidates allocate forwarding sources; ordinary reads keep their identity. */
+    nativeSource(target: ScopedNode, read: SignalReadMode, source: NativeReadSource): NativeReadSource;
+    validate(): boolean;
+    hasWrites(): boolean;
+    /** Follow existing graph edges, never the document or a global consumer registry. */
+    consumers(): readonly NativeTransitionConsumer[];
+    /** Canonical memo witnesses cannot justify skipping a private forward read. */
+    observes(node: ScopedNode): boolean;
+    canonical<T>(node: ScopedNode<T>): ScopedNode<T>;
+    /** Record intent without evaluating the forward graph in an urgent setter. */
+    recordUrgentWrite(node: ScopedNode, value: unknown): (() => void) | undefined;
+    private replaceWrite;
+    private forgetWrite;
+    /** Urgent writes win their own cells without restarting unaffected producer leases. */
+    rebase(): void;
+    prepare(reads?: readonly (() => unknown)[]): CandidatePreparation;
+    watchPreparation(outcome: CandidatePreparation, notify: NonNullable<PreparationWake['notify']>): () => void;
+    private invalidatePreparation;
+    private pruneDemand;
+    discard(): void;
+    private release;
+    private releaseEntry;
+    private committed;
+}
+export {};