gorsee 0.2.4 → 0.2.6

package/dist-pkg/reactive/diagnostics.d.ts

@@ -0,0 +1,100 @@
+export declare const REACTIVE_TRACE_SCHEMA_VERSION = 1;
+type ReactiveNodeKind = "signal" | "computed" | "effect" | "resource" | "mutation";
+type ReactiveInvalidationReason = "write" | "resource.invalidate" | "resource.invalidateAll";
+export interface ReactiveDiagnosticsSnapshot {
+    signalsCreated: number;
+    signalReads: number;
+    signalWrites: number;
+    computedCreated: number;
+    computedReads: number;
+    computedRuns: number;
+    effectCreated: number;
+    effectRuns: number;
+    resourcesCreated: number;
+    resourceLoadsStarted: number;
+    resourceLoadsSucceeded: number;
+    resourceLoadsFailed: number;
+    resourceInvalidations: number;
+    resourceMutations: number;
+    mutationsCreated: number;
+    mutationRuns: number;
+    mutationSuccesses: number;
+    mutationFailures: number;
+    mutationRollbacks: number;
+    mutationResets: number;
+}
+export interface ReactiveDiagnosticsConfig {
+    enabled?: boolean;
+    captureEvents?: boolean;
+    maxEvents?: number;
+}
+export interface ReactiveDiagnosticOptions {
+    label?: string;
+}
+export interface ReactiveGraphNode {
+    id: number;
+    kind: ReactiveNodeKind;
+    label?: string;
+    reads: number;
+    writes: number;
+    runs: number;
+    invalidations: number;
+}
+export interface ReactiveDependencyEdge {
+    sourceNodeId: number;
+    targetNodeId: number;
+    sourceKind: ReactiveNodeKind;
+    targetKind: ReactiveNodeKind;
+    sourceLabel?: string;
+    targetLabel?: string;
+    reads: number;
+}
+export interface ReactiveDiagnosticEvent {
+    seq: number;
+    kind: "signal:create" | "signal:read" | "signal:write" | "computed:create" | "computed:read" | "computed:run" | "effect:create" | "effect:run" | "resource:create" | "resource:load.start" | "resource:load.success" | "resource:load.error" | "resource:refetch" | "resource:mutate" | "resource:invalidate" | "mutation:create" | "mutation:start" | "mutation:success" | "mutation:error" | "mutation:settled" | "mutation:rollback" | "mutation:reset" | "invalidation";
+    nodeId: number;
+    label?: string;
+    relatedNodeId?: number;
+    relatedLabel?: string;
+    reason?: ReactiveInvalidationReason;
+    causeNodeIds?: number[];
+    causeLabels?: string[];
+    cacheKey?: string;
+    detail?: string;
+}
+export interface ReactiveTraceArtifact {
+    schemaVersion: typeof REACTIVE_TRACE_SCHEMA_VERSION;
+    snapshot: ReactiveDiagnosticsSnapshot;
+    nodes: ReactiveGraphNode[];
+    edges: ReactiveDependencyEdge[];
+    events: ReactiveDiagnosticEvent[];
+}
+export declare function configureReactiveDiagnostics(config?: ReactiveDiagnosticsConfig): void;
+export declare function resetReactiveDiagnostics(): void;
+export declare function getReactiveDiagnosticsSnapshot(): ReactiveDiagnosticsSnapshot;
+export declare function getReactiveGraphNodes(): ReactiveGraphNode[];
+export declare function getReactiveDependencyEdges(): ReactiveDependencyEdge[];
+export declare function getReactiveDiagnosticsEvents(): ReactiveDiagnosticEvent[];
+export declare function getReactiveTraceArtifact(): ReactiveTraceArtifact;
+export declare function trackSignalCreated(label?: string): number | null;
+export declare function trackSignalRead(nodeId?: number | null, label?: string): void;
+export declare function trackSignalWrite(nodeId?: number | null, label?: string): void;
+export declare function trackComputedCreated(label?: string): number | null;
+export declare function trackComputedRead(nodeId?: number | null, label?: string): void;
+export declare function trackEffectCreated(label?: string): number | null;
+export declare function trackResourceCreated(label?: string, cacheKey?: string): number | null;
+export declare function trackResourceLoadStart(nodeId?: number | null, label?: string, cacheKey?: string, detail?: string): void;
+export declare function trackResourceLoadSuccess(nodeId?: number | null, label?: string, cacheKey?: string): void;
+export declare function trackResourceLoadError(nodeId?: number | null, label?: string, cacheKey?: string, detail?: string): void;
+export declare function trackResourceRefetch(nodeId?: number | null, label?: string, cacheKey?: string): void;
+export declare function trackResourceMutate(nodeId?: number | null, label?: string, cacheKey?: string): void;
+export declare function trackResourceInvalidation(cacheKey: string, reason: ReactiveInvalidationReason): void;
+export declare function trackMutationCreated(label?: string): number | null;
+export declare function trackMutationStart(nodeId?: number | null, label?: string): void;
+export declare function trackMutationSuccess(nodeId?: number | null, label?: string): void;
+export declare function trackMutationError(nodeId?: number | null, label?: string, detail?: string): void;
+export declare function trackMutationSettled(nodeId?: number | null, label?: string): void;
+export declare function trackMutationRollback(nodeId?: number | null, label?: string): void;
+export declare function trackMutationReset(nodeId?: number | null, label?: string): void;
+export declare function runTrackedComputation<T>(nodeId: number | null | undefined, kind: "computed" | "effect", label: string | undefined, fn: () => T): T;
+export {};

package/dist-pkg/reactive/diagnostics.js

@@ -0,0 +1,363 @@
+export const REACTIVE_TRACE_SCHEMA_VERSION = 1;
+let diagnosticsEnabled = !1, captureEvents = !1, maxEvents = 200, nextNodeId = 1, nextEventSeq = 1;
+const snapshot = {
+  signalsCreated: 0,
+  signalReads: 0,
+  signalWrites: 0,
+  computedCreated: 0,
+  computedReads: 0,
+  computedRuns: 0,
+  effectCreated: 0,
+  effectRuns: 0,
+  resourcesCreated: 0,
+  resourceLoadsStarted: 0,
+  resourceLoadsSucceeded: 0,
+  resourceLoadsFailed: 0,
+  resourceInvalidations: 0,
+  resourceMutations: 0,
+  mutationsCreated: 0,
+  mutationRuns: 0,
+  mutationSuccesses: 0,
+  mutationFailures: 0,
+  mutationRollbacks: 0,
+  mutationResets: 0
+}, nodes = new Map, edges = new Map, events = [], activeComputations = [], pendingInvalidations = new Map, resourceNodeIdsByKey = new Map;
+export function configureReactiveDiagnostics(config = {}) {
+  diagnosticsEnabled = config.enabled === !0;
+  captureEvents = config.captureEvents === !0;
+  maxEvents = Math.max(1, config.maxEvents ?? 200);
+}
+export function resetReactiveDiagnostics() {
+  snapshot.signalsCreated = 0;
+  snapshot.signalReads = 0;
+  snapshot.signalWrites = 0;
+  snapshot.computedCreated = 0;
+  snapshot.computedReads = 0;
+  snapshot.computedRuns = 0;
+  snapshot.effectCreated = 0;
+  snapshot.effectRuns = 0;
+  snapshot.resourcesCreated = 0;
+  snapshot.resourceLoadsStarted = 0;
+  snapshot.resourceLoadsSucceeded = 0;
+  snapshot.resourceLoadsFailed = 0;
+  snapshot.resourceInvalidations = 0;
+  snapshot.resourceMutations = 0;
+  snapshot.mutationsCreated = 0;
+  snapshot.mutationRuns = 0;
+  snapshot.mutationSuccesses = 0;
+  snapshot.mutationFailures = 0;
+  snapshot.mutationRollbacks = 0;
+  snapshot.mutationResets = 0;
+  nextNodeId = 1;
+  nextEventSeq = 1;
+  nodes.clear();
+  edges.clear();
+  events.length = 0;
+  activeComputations.length = 0;
+  pendingInvalidations.clear();
+  resourceNodeIdsByKey.clear();
+}
+export function getReactiveDiagnosticsSnapshot() {
+  return { ...snapshot };
+}
+export function getReactiveGraphNodes() {
+  return Array.from(nodes.values()).map((node) => ({ ...node }));
+}
+export function getReactiveDependencyEdges() {
+  return Array.from(edges.values()).map((edge) => ({ ...edge }));
+}
+export function getReactiveDiagnosticsEvents() {
+  return events.map((event) => ({
+    ...event,
+    causeNodeIds: event.causeNodeIds ? [...event.causeNodeIds] : void 0,
+    causeLabels: event.causeLabels ? [...event.causeLabels] : void 0
+  }));
+}
+export function getReactiveTraceArtifact() {
+  return {
+    schemaVersion: REACTIVE_TRACE_SCHEMA_VERSION,
+    snapshot: getReactiveDiagnosticsSnapshot(),
+    nodes: getReactiveGraphNodes(),
+    edges: getReactiveDependencyEdges(),
+    events: getReactiveDiagnosticsEvents()
+  };
+}
+export function trackSignalCreated(label) {
+  if (!diagnosticsEnabled)
+    return null;
+  snapshot.signalsCreated++;
+  const nodeId = registerNode("signal", label);
+  pushEvent({ kind: "signal:create", nodeId, label });
+  return nodeId;
+}
+export function trackSignalRead(nodeId, label) {
+  if (!diagnosticsEnabled)
+    return;
+  snapshot.signalReads++;
+  updateNode(nodeId, (node) => {
+    node.reads++;
+  });
+  if (nodeId != null) {
+    registerDependency(nodeId, label);
+    pushEvent({ kind: "signal:read", nodeId, label });
+  }
+}
+export function trackSignalWrite(nodeId, label) {
+  if (!diagnosticsEnabled)
+    return;
+  snapshot.signalWrites++;
+  updateNode(nodeId, (node) => {
+    node.writes++;
+  });
+  if (nodeId != null) {
+    pushEvent({ kind: "signal:write", nodeId, label });
+    propagateInvalidation(nodeId, label, "write");
+  }
+}
+export function trackComputedCreated(label) {
+  if (!diagnosticsEnabled)
+    return null;
+  snapshot.computedCreated++;
+  const nodeId = registerNode("computed", label);
+  pushEvent({ kind: "computed:create", nodeId, label });
+  return nodeId;
+}
+export function trackComputedRead(nodeId, label) {
+  if (!diagnosticsEnabled)
+    return;
+  snapshot.computedReads++;
+  updateNode(nodeId, (node) => {
+    node.reads++;
+  });
+  if (nodeId != null) {
+    registerDependency(nodeId, label);
+    pushEvent({ kind: "computed:read", nodeId, label });
+  }
+}
+export function trackEffectCreated(label) {
+  if (!diagnosticsEnabled)
+    return null;
+  snapshot.effectCreated++;
+  const nodeId = registerNode("effect", label);
+  pushEvent({ kind: "effect:create", nodeId, label });
+  return nodeId;
+}
+export function trackResourceCreated(label, cacheKey) {
+  if (!diagnosticsEnabled)
+    return null;
+  snapshot.resourcesCreated++;
+  const nodeId = registerNode("resource", label);
+  if (cacheKey) {
+    const existing = resourceNodeIdsByKey.get(cacheKey) ?? new Set;
+    existing.add(nodeId);
+    resourceNodeIdsByKey.set(cacheKey, existing);
+  }
+  pushEvent({ kind: "resource:create", nodeId, label, cacheKey });
+  return nodeId;
+}
+export function trackResourceLoadStart(nodeId, label, cacheKey, detail) {
+  if (!diagnosticsEnabled || nodeId == null)
+    return;
+  snapshot.resourceLoadsStarted++;
+  updateNode(nodeId, (node) => {
+    node.runs++;
+  });
+  pushEvent({ kind: "resource:load.start", nodeId, label, cacheKey, detail });
+}
+export function trackResourceLoadSuccess(nodeId, label, cacheKey) {
+  if (!diagnosticsEnabled || nodeId == null)
+    return;
+  snapshot.resourceLoadsSucceeded++;
+  pushEvent({ kind: "resource:load.success", nodeId, label, cacheKey });
+}
+export function trackResourceLoadError(nodeId, label, cacheKey, detail) {
+  if (!diagnosticsEnabled || nodeId == null)
+    return;
+  snapshot.resourceLoadsFailed++;
+  pushEvent({ kind: "resource:load.error", nodeId, label, cacheKey, detail });
+}
+export function trackResourceRefetch(nodeId, label, cacheKey) {
+  if (!diagnosticsEnabled || nodeId == null)
+    return;
+  pushEvent({ kind: "resource:refetch", nodeId, label, cacheKey });
+}
+export function trackResourceMutate(nodeId, label, cacheKey) {
+  if (!diagnosticsEnabled || nodeId == null)
+    return;
+  snapshot.resourceMutations++;
+  updateNode(nodeId, (node) => {
+    node.writes++;
+  });
+  pushEvent({ kind: "resource:mutate", nodeId, label, cacheKey });
+}
+export function trackResourceInvalidation(cacheKey, reason) {
+  if (!diagnosticsEnabled)
+    return;
+  const nodeIds = resourceNodeIdsByKey.get(cacheKey);
+  if (!nodeIds || nodeIds.size === 0)
+    return;
+  for (const nodeId of nodeIds) {
+    snapshot.resourceInvalidations++;
+    updateNode(nodeId, (node) => {
+      node.invalidations++;
+    });
+    const label = nodes.get(nodeId)?.label;
+    pushEvent({ kind: "resource:invalidate", nodeId, label, cacheKey, reason });
+    propagateInvalidation(nodeId, label, reason);
+  }
+}
+export function trackMutationCreated(label) {
+  if (!diagnosticsEnabled)
+    return null;
+  snapshot.mutationsCreated++;
+  const nodeId = registerNode("mutation", label);
+  pushEvent({ kind: "mutation:create", nodeId, label });
+  return nodeId;
+}
+export function trackMutationStart(nodeId, label) {
+  if (!diagnosticsEnabled || nodeId == null)
+    return;
+  snapshot.mutationRuns++;
+  updateNode(nodeId, (node) => {
+    node.runs++;
+  });
+  pushEvent({ kind: "mutation:start", nodeId, label });
+}
+export function trackMutationSuccess(nodeId, label) {
+  if (!diagnosticsEnabled || nodeId == null)
+    return;
+  snapshot.mutationSuccesses++;
+  pushEvent({ kind: "mutation:success", nodeId, label });
+}
+export function trackMutationError(nodeId, label, detail) {
+  if (!diagnosticsEnabled || nodeId == null)
+    return;
+  snapshot.mutationFailures++;
+  pushEvent({ kind: "mutation:error", nodeId, label, detail });
+}
+export function trackMutationSettled(nodeId, label) {
+  if (!diagnosticsEnabled || nodeId == null)
+    return;
+  pushEvent({ kind: "mutation:settled", nodeId, label });
+}
+export function trackMutationRollback(nodeId, label) {
+  if (!diagnosticsEnabled || nodeId == null)
+    return;
+  snapshot.mutationRollbacks++;
+  pushEvent({ kind: "mutation:rollback", nodeId, label });
+}
+export function trackMutationReset(nodeId, label) {
+  if (!diagnosticsEnabled || nodeId == null)
+    return;
+  snapshot.mutationResets++;
+  pushEvent({ kind: "mutation:reset", nodeId, label });
+}
+export function runTrackedComputation(nodeId, kind, label, fn) {
+  if (!diagnosticsEnabled || nodeId == null)
+    return fn();
+  const causes = consumeInvalidationCauses(nodeId);
+  if (kind === "computed")
+    snapshot.computedRuns++;
+  if (kind === "effect")
+    snapshot.effectRuns++;
+  updateNode(nodeId, (node) => {
+    node.runs++;
+  });
+  pushEvent({
+    kind: kind === "computed" ? "computed:run" : "effect:run",
+    nodeId,
+    label,
+    causeNodeIds: causes.map((cause) => cause.sourceNodeId),
+    causeLabels: causes.map((cause) => cause.sourceLabel).filter((value) => Boolean(value))
+  });
+  activeComputations.push({ nodeId, kind, label });
+  try {
+    return fn();
+  } finally {
+    activeComputations.pop();
+  }
+}
+function registerNode(kind, label) {
+  const id = nextNodeId++;
+  nodes.set(id, {
+    id,
+    kind,
+    label,
+    reads: 0,
+    writes: 0,
+    runs: 0,
+    invalidations: 0
+  });
+  return id;
+}
+function updateNode(nodeId, update) {
+  if (nodeId == null)
+    return;
+  const node = nodes.get(nodeId);
+  if (!node)
+    return;
+  update(node);
+}
+function registerDependency(sourceNodeId, sourceLabel) {
+  const active = activeComputations[activeComputations.length - 1];
+  if (!active)
+    return;
+  if (active.nodeId === sourceNodeId)
+    return;
+  const sourceNode = nodes.get(sourceNodeId), targetNode = nodes.get(active.nodeId);
+  if (!sourceNode || !targetNode)
+    return;
+  const key = `${sourceNodeId}->${active.nodeId}`, existing = edges.get(key);
+  if (existing) {
+    existing.reads++;
+    return;
+  }
+  edges.set(key, {
+    sourceNodeId,
+    targetNodeId: active.nodeId,
+    sourceKind: sourceNode.kind,
+    targetKind: targetNode.kind,
+    sourceLabel: sourceNode.label ?? sourceLabel,
+    targetLabel: targetNode.label ?? active.label,
+    reads: 1
+  });
+}
+function propagateInvalidation(sourceNodeId, sourceLabel, reason) {
+  for (const edge of edges.values()) {
+    if (edge.sourceNodeId !== sourceNodeId)
+      continue;
+    updateNode(edge.targetNodeId, (node) => {
+      node.invalidations++;
+    });
+    const pending = pendingInvalidations.get(edge.targetNodeId) ?? [];
+    if (!pending.some((cause) => cause.sourceNodeId === sourceNodeId && cause.reason === reason)) {
+      pending.push({ sourceNodeId, sourceLabel, reason });
+      pendingInvalidations.set(edge.targetNodeId, pending);
+    }
+    pushEvent({
+      kind: "invalidation",
+      nodeId: edge.targetNodeId,
+      label: edge.targetLabel,
+      relatedNodeId: sourceNodeId,
+      relatedLabel: sourceLabel,
+      reason,
+      causeNodeIds: [sourceNodeId],
+      causeLabels: sourceLabel ? [sourceLabel] : void 0
+    });
+  }
+}
+function consumeInvalidationCauses(nodeId) {
+  const causes = pendingInvalidations.get(nodeId) ?? [];
+  pendingInvalidations.delete(nodeId);
+  return causes;
+}
+function pushEvent(event) {
+  if (!captureEvents)
+    return;
+  events.push({
+    ...event,
+    seq: nextEventSeq++
+  });
+  if (events.length > maxEvents)
+    events.splice(0, events.length - maxEvents);
+}

package/dist-pkg/reactive/effect.d.ts

@@ -0,0 +1,3 @@
+import { type ReactiveDiagnosticOptions } from "./diagnostics.js";
+export type CleanupFn = () => void;
+export declare function createEffect(fn: () => void, options?: ReactiveDiagnosticOptions): CleanupFn;

package/dist-pkg/reactive/effect.js

@@ -0,0 +1,6 @@
+import { effect as alienEffect } from "alien-signals";
+import { runTrackedComputation, trackEffectCreated } from "./diagnostics.js";
+export function createEffect(fn, options = {}) {
+  const nodeId = trackEffectCreated(options.label);
+  return alienEffect(() => runTrackedComputation(nodeId, "effect", options.label, fn));
+}

package/dist-pkg/reactive/index.d.ts

@@ -0,0 +1,9 @@
+export { createSignal } from "./signal.js";
+export { createComputed } from "./computed.js";
+export { createEffect } from "./effect.js";
+export { configureReactiveDiagnostics, getReactiveDependencyEdges, getReactiveDiagnosticsEvents, getReactiveDiagnosticsSnapshot, getReactiveGraphNodes, getReactiveTraceArtifact, REACTIVE_TRACE_SCHEMA_VERSION, resetReactiveDiagnostics, type ReactiveDiagnosticsConfig, type ReactiveDiagnosticEvent, type ReactiveDiagnosticOptions, type ReactiveDependencyEdge, type ReactiveDiagnosticsSnapshot, type ReactiveGraphNode, type ReactiveTraceArtifact, } from "./diagnostics.js";
+export { createResource, invalidateResource, invalidateAll } from "./resource.js";
+export { createDataQuery, createDataMutation, type DataQuery, type DataQueryOptions, type DataMutation, type DataMutationOptions } from "./data.js";
+export { createStore } from "./store.js";
+export { createLive, type LiveOptions, type LiveSignal } from "./live.js";
+export { createMutation, type Mutation, type MutationState, type MutationOptions } from "./optimistic.js";

package/dist-pkg/reactive/index.js

@@ -0,0 +1,18 @@
+export { createSignal } from "./signal.js";
+export { createComputed } from "./computed.js";
+export { createEffect } from "./effect.js";
+export {
+  configureReactiveDiagnostics,
+  getReactiveDependencyEdges,
+  getReactiveDiagnosticsEvents,
+  getReactiveDiagnosticsSnapshot,
+  getReactiveGraphNodes,
+  getReactiveTraceArtifact,
+  REACTIVE_TRACE_SCHEMA_VERSION,
+  resetReactiveDiagnostics
+} from "./diagnostics.js";
+export { createResource, invalidateResource, invalidateAll } from "./resource.js";
+export { createDataQuery, createDataMutation } from "./data.js";
+export { createStore } from "./store.js";
+export { createLive } from "./live.js";
+export { createMutation } from "./optimistic.js";

package/dist-pkg/reactive/live.d.ts

@@ -0,0 +1,15 @@
+import { type SignalGetter } from "./signal.js";
+export interface LiveOptions<T> {
+    url: string;
+    initialValue: T;
+    transform?: (data: unknown) => T;
+    reconnect?: boolean;
+    reconnectDelay?: number;
+}
+export interface LiveSignal<T> {
+    readonly value: SignalGetter<T>;
+    readonly connected: SignalGetter<boolean>;
+    send: (data: unknown) => void;
+    close: () => void;
+}
+export declare function createLive<T>(options: LiveOptions<T>): LiveSignal<T>;

package/dist-pkg/reactive/live.js

@@ -0,0 +1,70 @@
+import { createSignal } from "./signal.js";
+export function createLive(options) {
+  const {
+    url,
+    initialValue,
+    transform,
+    reconnect = !0,
+    reconnectDelay = 1000
+  } = options, [value, setValue] = createSignal(initialValue), [connected, setConnected] = createSignal(!1);
+  let ws = null, closed = !1, retryCount = 0, reconnectScheduled = !1, reconnectToken = 0;
+  function handleMessage(event) {
+    try {
+      const parsed = JSON.parse(String(event.data)), result = transform ? transform(parsed) : parsed;
+      setValue(result);
+    } catch {}
+  }
+  function handleOpen() {
+    retryCount = 0;
+    reconnectScheduled = !1;
+    reconnectToken++;
+    setConnected(!0);
+  }
+  function handleClose() {
+    setConnected(!1);
+    ws = null;
+    if (!closed && reconnect)
+      scheduleReconnect();
+  }
+  function scheduleReconnect() {
+    if (reconnectScheduled || closed)
+      return;
+    reconnectScheduled = !0;
+    const token = ++reconnectToken, delay = Math.min(reconnectDelay * 2 ** retryCount, 30000);
+    retryCount++;
+    setTimeout(() => {
+      if (closed || !reconnectScheduled || token !== reconnectToken)
+        return;
+      reconnectScheduled = !1;
+      connect();
+    }, delay);
+  }
+  function connect() {
+    if (closed)
+      return;
+    if (typeof globalThis.WebSocket > "u")
+      return;
+    ws = new WebSocket(url);
+    ws.addEventListener("open", handleOpen);
+    ws.addEventListener("message", handleMessage);
+    ws.addEventListener("close", handleClose);
+    ws.addEventListener("error", () => {});
+  }
+  function send(data) {
+    if (ws && ws.readyState === WebSocket.OPEN)
+      ws.send(JSON.stringify(data));
+  }
+  function close() {
+    closed = !0;
+    reconnectScheduled = !1;
+    reconnectToken++;
+    if (ws) {
+      ws.close();
+      ws = null;
+    }
+    setConnected(!1);
+  }
+  if (typeof globalThis.WebSocket < "u")
+    connect();
+  return { value, connected, send, close };
+}

package/dist-pkg/reactive/optimistic.d.ts

@@ -0,0 +1,20 @@
+import { type SignalGetter } from "./signal.js";
+export interface MutationOptions<T, V> {
+    mutationFn: (variables: V) => Promise<T>;
+    onSuccess?: (data: T, variables: V) => void;
+    onError?: (error: Error, variables: V) => void;
+    onSettled?: (data: T | undefined, error: Error | undefined) => void;
+    label?: string;
+}
+export interface MutationState<T> {
+    readonly data: SignalGetter<T | undefined>;
+    readonly error: SignalGetter<Error | undefined>;
+    readonly isPending: SignalGetter<boolean>;
+}
+export interface Mutation<T, V> extends MutationState<T> {
+    mutate: (variables: V) => Promise<T>;
+    /** Optimistic: update signal immediately, rollback if server fails */
+    optimistic: <S>(signal: SignalGetter<S>, setter: (current: S) => void, update: (current: S, variables: V) => S, variables: V) => Promise<T>;
+    reset: () => void;
+}
+export declare function createMutation<T, V = void>(options: MutationOptions<T, V>): Mutation<T, V>;

package/dist-pkg/reactive/optimistic.js

@@ -0,0 +1,67 @@
+import { createSignal } from "./signal.js";
+import {
+  trackMutationCreated,
+  trackMutationError,
+  trackMutationReset,
+  trackMutationRollback,
+  trackMutationSettled,
+  trackMutationStart,
+  trackMutationSuccess
+} from "./diagnostics.js";
+export function createMutation(options) {
+  const mutationNodeId = trackMutationCreated(options.label), [data, setData] = createSignal(void 0), [error, setError] = createSignal(void 0), [isPending, setIsPending] = createSignal(!1);
+  let pendingCount = 0, mutationEpoch = 0;
+  async function mutate(variables) {
+    const epoch = mutationEpoch;
+    trackMutationStart(mutationNodeId, options.label);
+    pendingCount++;
+    setIsPending(!0);
+    setError(void 0);
+    try {
+      const result = await options.mutationFn(variables);
+      if (epoch !== mutationEpoch)
+        return result;
+      setData(result);
+      trackMutationSuccess(mutationNodeId, options.label);
+      options.onSuccess?.(result, variables);
+      options.onSettled?.(result, void 0);
+      return result;
+    } catch (err) {
+      const e = err instanceof Error ? err : Error(String(err));
+      if (epoch !== mutationEpoch)
+        throw e;
+      setError(e);
+      trackMutationError(mutationNodeId, options.label, e.message);
+      options.onError?.(e, variables);
+      options.onSettled?.(void 0, e);
+      throw e;
+    } finally {
+      trackMutationSettled(mutationNodeId, options.label);
+      if (epoch === mutationEpoch) {
+        pendingCount = Math.max(0, pendingCount - 1);
+        setIsPending(pendingCount > 0);
+      }
+    }
+  }
+  async function optimistic(signal, setter, update, variables) {
+    const previous = signal(), optimisticValue = update(previous, variables);
+    setter(optimisticValue);
+    try {
+      return await mutate(variables);
+    } catch (err) {
+      if (Object.is(signal(), optimisticValue))
+        setter(previous);
+      trackMutationRollback(mutationNodeId, options.label);
+      throw err;
+    }
+  }
+  function reset() {
+    trackMutationReset(mutationNodeId, options.label);
+    mutationEpoch++;
+    pendingCount = 0;
+    setData(void 0);
+    setError(void 0);
+    setIsPending(!1);
+  }
+  return { data, error, isPending, mutate, optimistic, reset };
+}