@solidjs/signals 2.0.0-rc.2 → 2.0.0-rc.20

package/dist/types/signals.d.ts

@@ -26,6 +26,12 @@ import type { Disposable, Refreshable } from "./core/index.js";
  * Cannot be used inside `createTrackedEffect` or `onSettled` — return a
  * cleanup function from the callback body instead.
  *
+ * Cleanups run in unwind order: an owner's children are disposed before its
+ * own cleanups, and within one owner later registrations run before earlier
+ * ones. In production a component body shares its enclosing owner, so
+ * register cleanup before creating children when the order between them
+ * matters.
+ *
  * @example
  * ```ts
  * // Library shape: thread a resource's disposal into a *captured* owner
@@ -86,6 +92,13 @@ export type EffectBundle<Prev, Next extends Prev = Prev> = {
 interface BaseEffectOptions {
     /** Debug name (dev mode only) */
     name?: string;
+    /**
+     * Source location (`file:line:col`, root-relative) written by the
+     * compiler's `sourceNames` `locations` kind beside `name`; dev and observe
+     * builds keep it for console reports and diagnostic events, production
+     * ignores it. Not meant to be written by hand.
+     */
+    loc?: string;
 }
 /** Options for effect primitives that support deferring/scheduling their initial run (`createEffect`, `createRenderEffect`, `createReaction`). */
 export interface EffectOptions extends BaseEffectOptions {
@@ -138,6 +151,13 @@ export interface EffectOptions extends BaseEffectOptions {
 export interface SignalOptions<T> {
     /** Debug name (dev mode only) */
     name?: string;
+    /**
+     * Source location (`file:line:col`, root-relative) written by the
+     * compiler's `sourceNames` `locations` kind beside `name`; dev and observe
+     * builds keep it for console reports and diagnostic events, production
+     * ignores it. Not meant to be written by hand.
+     */
+    loc?: string;
     /**
      * Custom equality function, or `false` to always notify subscribers.
      * Defaults to reference equality (`isEqual`). Pass a comparator (e.g.
@@ -160,6 +180,13 @@ export interface MemoOptions<T> {
     id?: string;
     /** Debug name (dev mode only) */
     name?: string;
+    /**
+     * Source location (`file:line:col`, root-relative) written by the
+     * compiler's `sourceNames` `locations` kind beside `name`; dev and observe
+     * builds keep it for console reports and diagnostic events, production
+     * ignores it. Not meant to be written by hand.
+     */
+    loc?: string;
     /**
      * Advanced (integration tier). When true, the memo is invisible to the
      * hydration id scheme: it inherits its parent's id instead of consuming a
@@ -169,6 +196,13 @@ export interface MemoOptions<T> {
      * the full semantics. No-op outside hydration.
      */
     transparent?: boolean;
+    /**
+     * @internal Framework plumbing (the `solid-js/refresh` HMR memo): in the
+     * observe tiers the memo has no name, is no owner-path segment, and the
+     * attribution engine records nothing about it, while what it owns stays
+     * observed. Not part of the public API.
+     */
+    _plumbing?: boolean;
     /**
      * Custom equality function, or `false` to always notify subscribers.
      * Defaults to reference equality (`isEqual`). Pass a comparator (e.g.
@@ -251,17 +285,43 @@ export type NoInfer<T extends any> = [T][T extends any ? 0 : never];
  *
  * @example
  * ```ts
- * // Writable memo: starts as `fn()`, can be locally overwritten by setter.
+ * // Writable memo: derives from `fn()` and can be written like a signal.
  * const [user, setUser] = createSignal(() => fetchUser(userId()));
  *
- * setUser({ ...user(), name: "Alice" }); // optimistic local edit
+ * // A write lands at once and never re-runs `fn` on its own; when `userId`
+ * // changes, in the same update or later, `fn` re-runs and receives the
+ * // written value as `prev`. While a transaction holds a re-derived value, a
+ * // write from outside it does not replace that derivation — it becomes its
+ * // `prev`.
+ * setUser({ ...user(), name: "Alice" });
  * ```
  *
- * @description https://docs.solidjs.com/reference/basic-reactivity/create-signal
+ * @description https://v2.solidjs.com/reference/solid-js/reactivity/create-signal
  */
 export declare function createSignal<T>(): Signal<T | undefined>;
 export declare function createSignal<T>(value: Exclude<T, Function>, options?: SignalOptions<T>): Signal<T>;
 export declare function createSignal<T>(fn: ComputeFunction<T>, options?: SignalOptions<T> & MemoOptions<T>): Signal<T>;
+/**
+ * Creates an optimistic signal: a value that can be set optimistically inside
+ * a transition and reverts to the value it covered when the transition ends.
+ *
+ * The write is a guess over the transition of the frame it is made in — the
+ * frame's held writes are its base, and it shows at once while they wait.
+ * Outside such a frame (nothing is held) the write is as if it never
+ * happened. With a function, the memo form: its own recompute is the truth
+ * — equal to the guess it confirms silently, different it corrects at the
+ * transition's commit.
+ *
+ * ```typescript
+ * const [state, setState] = createOptimistic<T>(value, options?: SignalOptions<T>);
+ * const [state, setState] = createOptimistic<T>(fn, options?: SignalOptions<T> & MemoOptions<T>);
+ * ```
+ *
+ * @description https://v2.solidjs.com/reference/solid-js/reactivity/create-optimistic
+ */
+export declare function createOptimistic<T>(): Signal<T | undefined>;
+export declare function createOptimistic<T>(value: Exclude<T, Function>, options?: SignalOptions<T>): Signal<T>;
+export declare function createOptimistic<T>(fn: ComputeFunction<T>, options?: SignalOptions<T> & MemoOptions<T>): Signal<T>;
 /**
  * Creates a readonly derived reactive memoized signal.
  *
@@ -290,7 +350,7 @@ export declare function createSignal<T>(fn: ComputeFunction<T>, options?: Signal
  * });
  * ```
  *
- * @description https://docs.solidjs.com/reference/basic-reactivity/create-memo
+ * @description https://v2.solidjs.com/reference/solid-js/reactivity/create-memo
  */
 export declare function createMemo<T>(compute: ComputeFunction<NoInfer<T>, T>, options: MemoOptions<T> & {
     loadingValue: T;
@@ -362,20 +422,9 @@ export declare function createMemo<T>(compute: ComputeFunction<undefined | NoInf
  * );
  * ```
  *
- * @description https://docs.solidjs.com/reference/basic-reactivity/create-effect
- */
-export declare function createEffect<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, effectFn: EffectFunction<NoInfer<T>, T> | EffectBundle<NoInfer<T>, T>, options?: EffectOptions): void;
-/**
- * @deprecated `createEffect(compute)` (single argument) is no longer supported.
- * Pass a separate effect function as the second argument:
- * `createEffect(compute, effect)`. See [MISSING_EFFECT_FN].
- *
- * - For a side effect that reacts to changes, split the work:
- *   `createEffect(() => signal(), value => doWork(value))`.
- * - For a derived value, use `createMemo(() => signal())`.
- * - For a one-shot side effect at construction time, just call the function.
+ * @description https://v2.solidjs.com/reference/solid-js/reactivity/create-effect
  */
-export declare function createEffect<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>): never;
+export declare function createEffect<const T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, effectFn: EffectFunction<NoInfer<T>, T> | EffectBundle<NoInfer<T>, T>, options?: EffectOptions): void;
 /**
  * Creates a reactive computation that runs during the render phase as DOM elements
  * are created and updated but not necessarily connected.
@@ -403,13 +452,23 @@ export declare function createEffect<T>(compute: ComputeFunction<undefined | NoI
  * }
  * ```
  *
- * @description https://docs.solidjs.com/reference/secondary-primitives/create-render-effect
+ * @description https://v2.solidjs.com/reference/solid-js/advanced/specialized-reactivity/create-render-effect
  */
-export declare function createRenderEffect<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, effectFn: EffectFunction<NoInfer<T>, T>, options?: EffectOptions): void;
+export declare function createRenderEffect<const T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, effectFn: EffectFunction<NoInfer<T>, T>, options?: EffectOptions): void;
 /**
  * Creates a tracked reactive effect where dependency tracking and side effects happen
  * in the same scope.
  *
+ * @deprecated Do not use in new code. For a side effect that follows reactive
+ * state, use `createEffect(compute, effect)` — it separates tracking from the
+ * side effect, knows its dependencies before it runs, and participates in
+ * async and transitions. For one-time DOM work after render (measuring,
+ * attaching third-party widgets to a ref), use `onSettled`. Tracking from
+ * inside the effect phase — the only thing this primitive adds — is retained
+ * solely to ease 1.x migration: it runs beside user-effect callbacks after
+ * values commit, never holds a transition, and cannot observe a write staged
+ * earlier in the same flush by a signal it has not read yet.
+ *
  * WARNING: Because tracking and effects happen in the same scope, this primitive
  * may run multiple times for a single change or show tearing (reading inconsistent
  * state). Use only when dynamic subscription patterns require same-scope tracking.
@@ -439,7 +498,7 @@ export declare function createRenderEffect<T>(compute: ComputeFunction<undefined
  * });
  * ```
  *
- * @description https://docs.solidjs.com/reference/secondary-primitives/create-tracked-effect
+ * @description https://v2.solidjs.com/reference/solid-js/advanced/specialized-reactivity/create-tracked-effect
  */
 export declare function createTrackedEffect(compute: () => void | (() => void), options?: BaseEffectOptions): void;
 /**
@@ -466,7 +525,7 @@ export declare function createTrackedEffect(compute: () => void | (() => void),
  * setCount(1); // logs once, reaction re-armed for next change
  * ```
  *
- * @description https://docs.solidjs.com/reference/secondary-primitives/create-reaction
+ * @description https://v2.solidjs.com/reference/solid-js/advanced/specialized-reactivity/create-reaction
  */
 export declare function createReaction(effectFn: EffectFunction<undefined> | EffectBundle<undefined>, options?: EffectOptions): (tracking: () => void) => void;
 /**
@@ -492,40 +551,95 @@ export declare function createReaction(effectFn: EffectFunction<undefined> | Eff
  */
 export declare function resolve<T>(fn: () => T): Promise<T>;
 /**
- * Creates an optimistic signal that can be used to optimistically update a value
- * and then revert it back to the previous value at end of transition.
+ * Invalidates one reactive source, forcing it to re-execute even if its inputs
+ * haven't changed, and returns a promise for the target's NEXT QUIESCENT
+ * STATE — the re-ask (and anything that supersedes it) has settled.
+ *
+ * Pass either a Solid-created accessor or a projected store created from
+ * `createStore(fn, ...)` / `createProjection(...)`. `refresh()` is a
+ * write-like invalidation operation: it does not read the target's value, and
+ * refreshing a plain signal accessor is a no-op that resolves immediately.
+ *
+ * The returned promise is safe to ignore (fire-and-forget refresh is
+ * unchanged, and a failed refetch will not surface an unhandled rejection).
+ * Awaiting it gives imperative flows the settle point without a reactive
+ * read:
+ * - Accessor targets resolve with the settled value; store targets resolve
+ *   with the store node passed (reads through it are fresh after the await).
+ * - A failed re-ask rejects with the error.
+ * - Semantics are quiescence, not flight identity: if another refresh (or
+ *   any invalidation) supersedes this one mid-flight, the promise waits for
+ *   — and delivers — whatever finally lands.
+ *
+ * @example
+ * ```ts
+ * const user = createMemo(async () => fetch(`/users/${id()}`).then(r => r.json()));
  *
- * When called with a plain value, creates an optimistic signal with `SignalOptions` (name, equals, ownedWrite, unobserved).
- * When called with a function, creates a writable optimistic memo with `SignalOptions & MemoOptions` (adds id, lazy).
+ * // Fire-and-forget re-fetch
+ * <button onClick={() => refresh(user)}>Reload</button>;
  *
- * ```typescript
- * // Plain optimistic signal
- * const [state, setState] = createOptimistic<T>(value, options?: SignalOptions<T>);
- * // Writable optimistic memo (function overload)
- * const [state, setState] = createOptimistic<T>(fn, options?: SignalOptions<T> & MemoOptions<T>);
+ * // Imperative settle point
+ * const fresh = await refresh(user);
  * ```
- * @param value initial value of the signal; if empty, the signal's type will automatically extended with undefined
- * @param options optional object with a name for debugging purposes and equals, a comparator function for the previous and next value to allow fine-grained control over the reactivity
+ */
+export declare function refresh<T>(target: Refreshable<T>): Promise<T extends (...args: any) => infer V ? V : T>;
+/** Falsy values a truthy predicate result is narrowed against. */
+export type Truthy<T> = Exclude<T, false | 0 | 0n | "" | null | undefined>;
+/**
+ * The global `AbortSignal` when the consumer's libs declare one (DOM,
+ * WebWorker, `@types/node`), else the surface `until` uses — so these
+ * declarations check under neither lib without widening the global type.
+ */
+type GlobalAbortSignal = typeof globalThis extends {
+    AbortSignal: {
+        prototype: infer S;
+    };
+} ? S : {
+    readonly aborted: boolean;
+    readonly reason: any;
+    addEventListener(type: "abort", listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: "abort", listener: () => void): void;
+};
+export interface UntilOptions {
+    /** Reject with `TimeoutError` if the predicate has not turned truthy within
+     * this many milliseconds. Strongly recommended when the confirming truth
+     * arrives over a transport that can drop (sockets, subscriptions). */
+    timeout?: number;
+    /** Reject with `signal.reason` on abort. */
+    signal?: GlobalAbortSignal;
+}
+/**
+ * Awaits a reactive predicate and resolves the first time it settles *truthy*,
+ * with that (narrowed) value. Falsy results and pending async reads both mean
+ * "not yet": the subscription stays live and re-evaluates as sources change.
+ * If the predicate settles with an error — a throw, or an async source that
+ * rejects — the promise rejects with it, as do timeout and abort.
  *
- * @returns `[state: Accessor<T>, setState: Setter<T>]`
+ * Where {@link resolve} answers "what is this value" (first settled value,
+ * whatever it is), `until` answers "when does the world confirm this
+ * condition".
+ *
+ * This is the acknowledgment mechanism for mutations confirmed on a live data
+ * channel (sockets, subscriptions, live queries) rather than by the mutation's
+ * own response: correlate by a client-generated id or version in the predicate,
+ * and let truth arrive however it arrives — push, refetch, or another tab.
+ *
+ * Must be called *outside* a tracking scope.
  *
  * @example
  * ```ts
- * const [todos, setTodos] = createOptimistic(initialTodos);
- *
- * const addTodo = action(function* (text: string) {
- *   const tempId = crypto.randomUUID();
- *   setTodos(t => [...t, { id: tempId, text, pending: true }]); // optimistic
- *   const saved = yield api.createTodo(text);
- *   setTodos(t => t.map(x => (x.id === tempId ? saved : x)));   // reconcile
- * });
+ * const clientId = crypto.randomUUID();
+ * await socket.send({ clientId, text }); // fire-and-forget transport
+ * // Wait until the live source echoes the write:
+ * await until(() => messages.some(m => m.clientId === clientId), { timeout: 10_000 });
  * ```
  *
- * @description https://docs.solidjs.com/reference/basic-reactivity/create-optimistic-signal
+ * @param fn a reactive predicate
+ * @param options optional `timeout` (ms) and abort `signal`
  */
-export declare function createOptimistic<T>(): Signal<T | undefined>;
-export declare function createOptimistic<T>(value: Exclude<T, Function>, options?: SignalOptions<T>): Signal<T>;
-export declare function createOptimistic<T>(fn: ComputeFunction<T>, options?: SignalOptions<T> & MemoOptions<T>): Signal<T>;
+export declare function until<T>(fn: () => T, options?: UntilOptions): Promise<Truthy<T>>;
 /**
  * Schedules `callback` to run **once** after the reactive graph has fully
  * settled — i.e. once every pending async read inside the current owner has
@@ -621,4 +735,41 @@ export declare function createOptimistic<T>(fn: ComputeFunction<T>, options?: Si
  *   on owner disposal
  */
 export declare function onSettled(callback: () => void | (() => void)): void;
+/**
+ * Schedules `callback` to run **once**, right after the pending flush
+ * finishes, in the same microtask checkpoint (before the browser paints).
+ * Unlike `onSettled`, it never waits on async work: if that flush is held by
+ * a pending transition, the callback still runs.
+ *
+ * Its main use is keeping a write out of another update's hold. Writes made
+ * in the same synchronous frame are applied together, so when one of them
+ * starts async work (a route change, a fetch), the others are held with it
+ * until it resolves. A write made in `onFlush` happens after that flush, so
+ * it is its own update: it commits on its own unless something it changes
+ * also derives from the held work (a memo or `createEffect` reading both),
+ * in which case it joins that hold as any later write would.
+ *
+ * Call it from event handlers and effect callbacks (including
+ * `createTrackedEffect` and `onSettled` bodies). In an owned scope such as a
+ * component body or a computation it warns in dev: use `onSettled` there.
+ *
+ * - A write in the callback lands after any write made inline in the same
+ *   frame. Don't write the same signal both inside and outside it; use a
+ *   functional setter if the order matters.
+ * - Several `onFlush` callbacks run in call order and batch into one flush.
+ * - `queueMicrotask` is not a substitute: called before the frame's first
+ *   write, it runs before that flush and its write joins it.
+ *
+ * @example
+ * ```tsx
+ * // A menu closes now even when the consumer's onSelect starts async work.
+ * const select = (id: string) => {
+ *   onFlush(() => setOpen(false));
+ *   props.onSelect?.(id);
+ * };
+ * ```
+ *
+ * @param callback Function to run once after the pending flush
+ */
+export declare function onFlush(callback: () => void): void;
 export {};

package/dist/types/store/affects.d.ts

@@ -0,0 +1,12 @@
+import type { Computed, Signal } from "../core/types.js";
+import { type StoreTarget } from "./target.js";
+type Marked = Signal<any> | Computed<any>;
+/** The nodes an `affects(store[, key])` declaration marks (affects.ts
+ * registers each). */
+export declare function storeMarks(t: StoreTarget, key: PropertyKey | undefined): Marked[];
+/** `affects()` calls it before a store-targeted declaration (idempotent). */
+export declare function installStoreAffects(): void;
+/** The carrier's last mark released (affects.ts): its scope dies, and the
+ * nodes that inherited the mark release theirs. */
+export declare function releaseMarkScope(carrier: Marked): void;
+export {};

package/dist/types/store/edges.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @internal The name of the store `x` belongs to — `x` a store proxy (a
+ * setter's entry) or one of its property nodes (the setter notifying it) —
+ * or undefined when it has none or it cannot be placed: a projection or
+ * optimistic family, a store chained over another store's proxy, a root
+ * named twice, or a proxy reached through a store other than the one it
+ * was named as the root of.
+ */
+export declare function storeName(x: object | undefined): string | undefined;

package/dist/types/store/hooks.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Store — the engine's optional-machinery slots, in a module of their own so
+ * an installer reaches them without importing store.ts (whose top level
+ * installs the engine): the store half of `affects()` installs through here
+ * from `affects()`, and an app without stores carries none of the engine.
+ * A slot no installer reaches stays `null`, and a bundler folds its sites.
+ */
+import type { Transaction } from "../core/scheduler.js";
+import type { Signal } from "../core/types.js";
+import type { StoreFamily, StoreTarget } from "./target.js";
+/** The optimistic machinery (optimistic.ts, S4), installed when it loads
+ * — a plain store pays nothing for it (#2883): the plain paths reach it
+ * only through a family with `opt` set, which only `createOptimisticStore`
+ * sets. */
+export interface OptHooks {
+    /** A user setter's draft on an optimistic family: a clone of the
+     * writer's view (a staging already on the target is set aside). */
+    draft(t: StoreTarget): Record<PropertyKey, any>;
+    /** The setter's exit: the draft becomes guesses; returns the staging the
+     * draft set aside (`null`: none). */
+    writes(t: StoreTarget, pb: Record<PropertyKey, any>): Record<PropertyKey, any> | null;
+    /** `src` with the lanes' values over it (`writer`: the next write's base
+     * — the unflushed guesses too). */
+    view(t: StoreTarget, src: Record<PropertyKey, any>, writer?: boolean): Record<PropertyKey, any>;
+    /** An untracked `key in store`: the presence guess, or `undefined`. */
+    has(t: StoreTarget, key: PropertyKey): boolean | undefined;
+    /** A guessed key's descriptor (`null`: removed; `undefined`: no guess). */
+    descriptor(t: StoreTarget, key: PropertyKey): PropertyDescriptor | null | undefined;
+    /** The flush's commit: targets no lane holds leave `overlaid`. */
+    sweep(): void;
+    /** The container comparator's lane arm: an arrangement guess against a
+     * landing (or another arrangement), by row identity. */
+    arrangement(t: StoreTarget, a: any, b: any): boolean;
+    /** A user's `reconcile` on an optimistic family: the keyed diff written
+     * into the draft. */
+    reconcile(draft: any, incoming: any, keyFn: ((item: any) => any) | null): void;
+    /** The derive's draft wrote `pb` on `t`: the new object at a guessed
+     * row's slot (by key in a keyed list) is adopted by that row's target. */
+    pair(t: StoreTarget, pb: Record<PropertyKey, any>): void;
+    /** The derive of `fam` went in flight (#4336): a new question asked over
+     * the family's guesses is judged by its reads (`stands`) and at the seam
+     * (`park`). */
+    ask(fam: StoreFamily): void;
+    /** The flush parks with `t`: a guess a frame still reads, over a family
+     * asked a new question this flush, holds `t` with its action (D-34). */
+    park(t: Transaction): void;
+    /** A read of `t` while its family's derive is in flight: the family's
+     * guesses stand in for the flight (no suspension). */
+    stands(t: StoreTarget): boolean;
+}
+export declare let optHooks: OptHooks | null;
+export declare function installOptHooks(hooks: OptHooks): void;
+/** The store half of `affects()` (store/affects.ts), installed by the first
+ * store-targeted declaration: a node born on a covered record inherits the
+ * live mark; an untracked verdict probe through a record with no node is
+ * witnessed. */
+export interface AffectsHooks {
+    _born(t: StoreTarget, node: Signal<any>, key: PropertyKey): void;
+    _witness(t: StoreTarget, key: PropertyKey | undefined): void;
+}
+export declare let affectsHooks: AffectsHooks | null;
+export declare function installAffectsHooks(hooks: AffectsHooks): void;

package/dist/types/store/index.d.ts

@@ -1,19 +1,46 @@
-export type { Store, StoreReturn, ProjectionStoreReturn, StoreSetter, StoreNode, StoreOptions, ProjectionOptions, NotWrappable, SolidStore } from "./store.js";
+/**
+ * Store — public surface. Plain stores (S1) are live; the derived form
+ * (`createStore(fn, seed)`), projections, optimistic stores and reconcile
+ * return on later steps (plan sec. 31.5).
+ */
+export type { NoArray, NoFn, NotWrappable, ProjectionOptions, ProjectionStoreReturn, SolidStore, Store, StoreOptions, StoreReturn, StoreSetter } from "./types.js";
+export { $PROXY, $RECORD, $TARGET, $TRACK, isWrappable, markRaw } from "./types.js";
+export { storeIsShallow, storeHasFamily, storeHasOptimisticFamily } from "./store.js";
+export { storePath } from "./storePath.js";
+export type { StorePathRange, PathSetter, Part, CustomPartial, ArrayFilterFn } from "./storePath.js";
+import { createOptimisticStore } from "./optimistic.js";
+import { createProjection } from "./projection.js";
+import type { NoArray, NoFn, ProjectionOptions, ProjectionStoreReturn, Store, StoreOptions, StoreReturn } from "./types.js";
+export { createOptimisticStore, createProjection };
+/** The store's internal record behind a proxy (`store[$TARGET]`). Kept
+ * under `next`'s public name; its shape is the L2 target's (plan plan sec. 31–32:
+ * the symbol-keyed legacy record is gone with the representation). */
+export type { StoreTarget as StoreNode } from "./target.js";
 export type { Merge, Omit } from "./utils.js";
-export { isWrappable, $TRACK, $PROXY, $TARGET } from "./store.js";
-import type { NoFn, ProjectionOptions, Store, StoreOptions, StoreSetter } from "./store.js";
-import type { Refreshable } from "../core/index.js";
-export { createProjectionNext as createProjection } from "./next/projection.js";
-export { createOptimisticStoreNext as createOptimisticStore } from "./next/optimistic.js";
-/** Public createStore: plain form `(init, options?)` and derived writable
- * form `(fn, seed, options?)`. */
-export declare function createStore<T extends object = {}>(store: NoFn<T> | Store<NoFn<T>>, options?: StoreOptions & {
-    shallow?: boolean;
-}): [get: Store<T>, set: StoreSetter<T>];
-export declare function createStore<T extends object = {}>(fn: (store: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, store: Partial<T> | Store<NoFn<T>>, options?: ProjectionOptions): [get: Refreshable<Store<T>>, set: StoreSetter<T>];
+export { mergeSources, mergeView, viewOf, omitView, sourceKeys, sourceHas, sourceGet, hasStaticKeys, isStatic, resolvedTable, OmitView, MergeView, SOURCE_PLAIN, SOURCE_OMIT, SOURCE_PROXY, SOURCE_MEMO, SOURCE_MERGE, sourceOwners, merge, omit } from "./utils.js";
+export type { SourceKind } from "./utils.js";
+/**
+ * Create a reactive store: a proxy over plain data with fine-grained
+ * subscriptions per read path, written through its setter's draft — or, in
+ * the derived form, a projection with a setter.
+ *
+ * The derived form comes in two shapes. Seedless, `createStore(fn)`: `fn`
+ * takes no draft and every answer is a complete `T` (plain-object roots only;
+ * pass `undefined` for the seed to reach the options). Seeded,
+ * `createStore(fn, seed)`: the seed is a complete `T` the derive drafts
+ * against — `[]` for an array.
+ */
+export declare function createStore<T extends object = {}>(initialValue: NoFn<T>, options?: StoreOptions): StoreReturn<T>;
+export declare function createStore<T extends object = {}>(fn: (() => T | Promise<T> | AsyncIterable<T>) & NoArray<T>, seed?: null, options?: Omit<ProjectionOptions, "seedLoadingValue">): ProjectionStoreReturn<T>;
+export declare function createStore<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: NoFn<T> | Store<NoFn<T>>, options?: ProjectionOptions): ProjectionStoreReturn<T>;
+/**
+ * A setter transform that reconciles `value` into the store by key
+ * (`"id"` by default; `null` positional), preserving store identity for
+ * surviving rows.
+ */
 export declare function reconcile<T extends U, U>(value: T, key?: string | ((item: NonNullable<any>) => any) | null): (state: U) => T;
+/** Non-tracking snapshot of a store's current value (source identity for
+ * unmodified subtrees). */
 export declare function snapshot<T>(value: T): T;
+/** Tracking snapshot: subscribes to every reachable record. */
 export declare function deep<T>(value: T): T;
-export { storePath } from "./storePath.js";
-export type { PathSetter, Part, StorePathRange, ArrayFilterFn, CustomPartial } from "./storePath.js";
-export { merge, omit } from "./utils.js";

package/dist/types/store/optimistic.d.ts

@@ -1,45 +1,24 @@
-import { type Refreshable } from "../core/index.js";
-import { type NoFn, type ProjectionOptions, type Store, type StoreSetter } from "./store.js";
-/**
- * The store equivalent of `createOptimistic`. Writes inside an `action`
- * transition are tentative — they show up immediately but auto-revert (or
- * reconcile to the action's resolved value) once the transition finishes.
- *
- * Use this for optimistic UI on collection-shaped data. For single-value
- * optimistic state, prefer `createOptimistic`.
- *
- * - Plain form: `createOptimisticStore(initialValue)`.
- * - Derived form: `createOptimisticStore(fn, seed, options?)` — a projection
- *   store whose authoritative value is recomputed by `fn` and whose
- *   optimistic overlay reverts after each transition.
- *
- * `options.key` defaults to `"id"`; specify it only when your data uses a
- * different identity field (e.g. `{ key: "uuid" }` or `{ key: t => t.slug }`),
- * or `null` to merge positionally. Restating the default just adds noise.
- *
- * @example
- * ```ts
- * const [todos, setTodos] = createOptimisticStore<Todo[]>([]);
- *
- * // Mutation: optimistic add, then in-place reconcile to the saved row.
- * const addTodo = action(function* (text: string) {
- *   const tempId = crypto.randomUUID();
- *   setTodos(t => { t.push({ id: tempId, text, pending: true }); });
- *   const saved = yield api.createTodo(text);
- *   setTodos(t => {
- *     const i = t.findIndex(x => x.id === tempId);
- *     if (i >= 0) t[i] = saved;
- *   });
- * });
- *
- * // Return form: filter is the natural shape for removal.
- * const removeTodo = action(function* (id: string) {
- *   setTodos(t => t.filter(x => x.id !== id));
- *   yield api.removeTodo(id);
- * });
- * ```
- *
- * @returns `[store: Store<T>, setStore: StoreSetter<T>]`
- */
-export declare function createOptimisticStore<T extends object = {}>(store: NoFn<T> | Store<NoFn<T>>, options?: ProjectionOptions): [get: Store<T>, set: StoreSetter<T>];
-export declare function createOptimisticStore<T extends object = {}>(fn: (store: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, store: Partial<T> | Store<NoFn<T>>, options?: ProjectionOptions): [get: Refreshable<Store<T>>, set: StoreSetter<T>];
+import type { Refreshable } from "../core/index.js";
+import { type StoreTarget } from "./target.js";
+import { type NoArray, type NoFn, type ProjectionOptions, type Store, type StoreOptions, type StoreSetter } from "./types.js";
+export declare function notifyOptimisticWrites(t: StoreTarget, pb: Record<PropertyKey, any>): Record<PropertyKey, any> | null;
+export declare function sweepOverlaid(): void;
+/** An untracked `key in store` on an optimistic family: the presence guess
+ * (what its lane shows) when the key carries one; `undefined` when not —
+ * the backing answers. */
+export declare function optimisticHas(t: StoreTarget, key: PropertyKey): boolean | undefined;
+/** A descriptor read of a guessed key: synthesized from the lane's value
+ * (`null`: the guess removed the key; `undefined`: no guess — the backing
+ * describes it). */
+export declare function optimisticOwnDescriptor(t: StoreTarget, key: PropertyKey): PropertyDescriptor | null | undefined;
+/** The truth `src` with the target's lane values over it: each overlaid
+ * leaf's value (`pick`: what the lane shows, or — for `latest` — the lane's
+ * latest), each presence guess as a key added or removed, the array
+ * length. Returns `src` itself when nothing is overlaid. */
+export declare function optimisticView(t: StoreTarget, src: Record<PropertyKey, any>, pick?: (n: any) => unknown, writer?: boolean): Record<PropertyKey, any>;
+/** `latest()`'s view: the lanes' latest values (a landing staged beneath a
+ * guess is what lands). */
+export declare function latestView(t: StoreTarget, src: Record<PropertyKey, any>): Record<PropertyKey, any>;
+export declare function createOptimisticStore<T extends object = {}>(initialValue: NoFn<T> | Store<NoFn<T>>, options?: StoreOptions): [get: Store<T>, set: StoreSetter<T>];
+export declare function createOptimisticStore<T extends object = {}>(fn: (() => T | Promise<T> | AsyncIterable<T>) & NoArray<T>, seed?: null, options?: Omit<ProjectionOptions, "seedLoadingValue">): [get: Refreshable<Store<T>>, set: StoreSetter<T>];
+export declare function createOptimisticStore<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: NoFn<T> | Store<NoFn<T>>, options?: ProjectionOptions): [get: Refreshable<Store<T>>, set: StoreSetter<T>];