@solidjs/signals 2.0.0-beta.8 → 2.0.0-beta.9

package/dist/types/signals.d.ts

@@ -1,13 +1,56 @@
 import type { Disposable } from "./core/index.js";
+/**
+ * Low-level reactive-cleanup primitive. Registers a callback that runs when
+ * the surrounding owner is disposed.
+ *
+ * **In 2.0 user code this is rare.** The two cases where you might reach for
+ * it have better-shaped tools:
+ *
+ * - **Component lifecycle (mount/unmount, listeners, intervals):** use
+ *   {@link onSettled} and **return** a cleanup function. Setup and teardown
+ *   stay paired in one block. This replaces the 1.x `onMount` + `onCleanup`
+ *   pairing.
+ * - **Cleanup tied to an effect run:** `onCleanup` does not belong in
+ *   `createEffect`'s apply phase. If a compute phase genuinely needs per-run
+ *   teardown, that's usually a sign the work should be a memo/projection
+ *   instead, or moved to `onSettled` if it's lifecycle-shaped.
+ *
+ * Where `onCleanup` is the right tool is **library / custom-primitive
+ * internals** — coordinating disposal inside a `createRoot` body, or wiring
+ * cleanup to a captured owner via `runWithOwner` from a custom factory.
+ * Application code rarely needs to write any of those shapes directly.
+ *
+ * Must be called inside an owner. Calling outside an owner is a no-op (with a
+ * dev-mode warning).
+ *
+ * Cannot be used inside `createTrackedEffect` or `onSettled` — return a
+ * cleanup function from the callback body instead.
+ */
 export declare function onCleanup(fn: Disposable): Disposable;
+/**
+ * A zero-arg getter for a reactive value. Calling it inside a tracking scope
+ * (memo, effect compute, JSX expression) subscribes the scope to changes.
+ *
+ * Reading outside any tracking scope simply returns the current value without
+ * creating a subscription.
+ */
 export type Accessor<T> = () => T;
 export declare function accessor<T>(node: any): Accessor<T>;
+/**
+ * A signal setter. Accepts either a new value or an updater `(prev) => next`.
+ *
+ * If the type permits `undefined`, `setState()` (no args) clears to `undefined`.
+ *
+ * To store a function as the value itself (rather than as an updater), wrap it
+ * with an updater: `setHandler(() => myHandler)`.
+ */
 export type Setter<in out T> = {
     <U extends T>(...args: undefined extends T ? [] : [value: Exclude<U, Function> | ((prev: T) => U)]): undefined extends T ? undefined : U;
     <U extends T>(value: (prev: T) => U): U;
     <U extends T>(value: Exclude<U, Function>): U;
     <U extends T>(value: Exclude<U, Function> | ((prev: T) => U)): U;
 };
+/** A `[get, set]` pair returned from `createSignal` / `createOptimistic`. */
 export type Signal<T> = [get: Accessor<T>, set: Setter<T>];
 export type ComputeFunction<Prev, Next extends Prev = Prev> = (v: Prev) => PromiseLike<Next> | AsyncIterable<Next> | Next;
 export type EffectFunction<Prev, Next extends Prev = Prev> = (v: Next, p?: Prev) => (() => void) | void;
@@ -62,7 +105,14 @@ export interface MemoOptions<T> {
     equals?: false | ((prev: T, next: T) => boolean);
     /** Callback invoked when the computed loses all subscribers */
     unobserved?: () => void;
-    /** When true, defers the initial computation until the value is first read */
+    /**
+     * When true, defers the initial computation until the value is first read,
+     * **and** opts the memo into autodisposal — once it has no remaining
+     * subscribers it is torn down and recomputed from scratch on the next read.
+     * Use it for compute-on-demand values that should not retain state across
+     * idle periods. Non-lazy owned memos live for their owner's lifetime and
+     * never autodispose.
+     */
     lazy?: boolean;
 }
 export type NoInfer<T extends any> = [T][T extends any ? 0 : never];
@@ -83,6 +133,23 @@ export type NoInfer<T extends any> = [T][T extends any ? 0 : never];
  *
  * @returns `[state: Accessor<T>, setState: Setter<T>]`
  *
+ * @example
+ * ```ts
+ * const [count, setCount] = createSignal(0);
+ *
+ * count();              // 0
+ * setCount(1);          // explicit value
+ * setCount(c => c + 1); // updater
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Writable memo: starts as `fn()`, can be locally overwritten by setter.
+ * const [user, setUser] = createSignal(() => fetchUser(userId()));
+ *
+ * setUser({ ...user(), name: "Alice" }); // optimistic local edit
+ * ```
+ *
  * @description https://docs.solidjs.com/reference/basic-reactivity/create-signal
  */
 export declare function createSignal<T>(): Signal<T | undefined>;
@@ -97,22 +164,91 @@ export declare function createSignal<T>(fn: ComputeFunction<T>, options?: Signal
  * @param compute a function that receives its previous value and returns a new value used to react on a computation
  * @param options `MemoOptions` -- id, name, equals, unobserved, lazy
  *
+ * @example
+ * ```ts
+ * const [first, setFirst] = createSignal("Ada");
+ * const [last, setLast] = createSignal("Lovelace");
+ *
+ * const fullName = createMemo(() => `${first()} ${last()}`);
+ *
+ * fullName(); // "Ada Lovelace"
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Async memo — reads surface as pending inside <Loading>
+ * const user = createMemo(async () => {
+ *   const res = await fetch(`/users/${id()}`);
+ *   return res.json();
+ * });
+ * ```
+ *
  * @description https://docs.solidjs.com/reference/basic-reactivity/create-memo
  */
 export declare function createMemo<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, options?: MemoOptions<T>): Accessor<T>;
 /**
- * Creates a reactive effect that runs after the render phase.
+ * Creates a reactive effect with **separate compute and effect phases**.
+ *
+ * - `compute(prev)` runs reactively — *put all reactive reads here*. The
+ *   returned value is passed to `effect` and is also the new "previous" value
+ *   for the next run.
+ * - `effect(next, prev?)` runs imperatively (untracked) after the queue
+ *   flushes. *Put DOM writes / fetch / logging / subscriptions here.* It may
+ *   return a cleanup function which runs before the next effect or on
+ *   disposal.
+ *
+ * Reactive reads inside `effect` will *not* re-trigger this effect — that's
+ * intentional. If you need a single-phase tracked effect, use
+ * `createTrackedEffect` (with the tradeoffs noted there).
+ *
+ * Pass an `EffectBundle` (`{ effect, error }`) instead of a plain function to
+ * intercept errors thrown from the compute or effect phases.
  *
  * ```typescript
  * createEffect<T>(compute, effectFn | { effect, error }, options?: EffectOptions);
  * ```
  * @param compute a function that receives its previous value and returns a new value used to react on a computation
  * @param effectFn a function that receives the new value and is used to perform side effects (return a cleanup function), or an `EffectBundle` with `effect` and `error` handlers
- * @param options `EffectOptions` -- name, defer
+ * @param options `EffectOptions` -- name, defer, schedule
+ *
+ * @example
+ * ```ts
+ * const [count, setCount] = createSignal(0);
+ *
+ * createEffect(
+ *   () => count(),                  // compute: tracks `count`
+ *   value => console.log(value)     // effect: side effect
+ * );
+ *
+ * setCount(1); // logs 1 after the next flush
+ * ```
+ *
+ * @example
+ * ```ts
+ * createEffect(
+ *   () => userId(),
+ *   id => {
+ *     const ctrl = new AbortController();
+ *     fetch(`/users/${id}`, { signal: ctrl.signal });
+ *     return () => ctrl.abort(); // cleanup before next run / disposal
+ *   }
+ * );
+ * ```
  *
  * @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.
+ */
+export declare function createEffect<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>): never;
 /**
  * Creates a reactive computation that runs during the render phase as DOM elements
  * are created and updated but not necessarily connected.
@@ -122,7 +258,7 @@ export declare function createEffect<T>(compute: ComputeFunction<undefined | NoI
  * ```
  * @param compute a function that receives its previous value and returns a new value used to react on a computation
  * @param effectFn a function that receives the new value and is used to perform side effects
- * @param options `EffectOptions` -- name, defer
+ * @param options `EffectOptions` -- name, defer, schedule
  *
  * @description https://docs.solidjs.com/reference/secondary-primitives/create-render-effect
  */
@@ -141,6 +277,19 @@ export declare function createRenderEffect<T>(compute: ComputeFunction<undefined
  * @param compute a function that contains reactive reads to track and returns an optional cleanup function to run on disposal or before next execution
  * @param options -- name
  *
+ * @example
+ * ```ts
+ * createTrackedEffect(() => {
+ *   const target = focusedNode();
+ *   if (!target) return;
+ *
+ *   const handler = () => log(target.value());
+ *   target.on("change", handler);
+ *
+ *   return () => target.off("change", handler);
+ * });
+ * ```
+ *
  * @description https://docs.solidjs.com/reference/secondary-primitives/create-tracked-effect
  */
 export declare function createTrackedEffect(compute: () => void | (() => void), options?: BaseEffectOptions): void;
@@ -154,11 +303,40 @@ export declare function createTrackedEffect(compute: () => void | (() => void),
  * @param effectFn a function (or `EffectBundle`) that is called when tracked function is invalidated
  * @param options `EffectOptions` -- name, defer
  *
+ * @example
+ * ```ts
+ * const [count, setCount] = createSignal(0);
+ *
+ * const track = createReaction(() => {
+ *   console.log("count changed once, re-arm to listen again");
+ *   track(() => count()); // re-arm
+ * });
+ *
+ * track(() => count()); // initial arm
+ *
+ * setCount(1); // logs once, reaction re-armed for next change
+ * ```
+ *
  * @description https://docs.solidjs.com/reference/secondary-primitives/create-reaction
  */
 export declare function createReaction(effectFn: EffectFunction<undefined> | EffectBundle<undefined>, options?: EffectOptions): (tracking: () => void) => void;
 /**
- * Returns a promise of the resolved value of a reactive expression
+ * Awaits a reactive expression and returns its first fully-settled value as a
+ * `Promise`. Pending async reads (`createMemo` returning a promise, etc.) are
+ * waited on; once the expression returns synchronously without `NotReadyError`
+ * the promise resolves with that value.
+ *
+ * Must be called *outside* a tracking scope — it doesn't subscribe, it just
+ * resolves the current value once.
+ *
+ * @example
+ * ```ts
+ * const user = createMemo(() => fetch(`/users/${id()}`).then(r => r.json()));
+ *
+ * // outside any reactive scope
+ * const initial = await resolve(() => user());
+ * ```
+ *
  * @param fn a reactive expression to resolve
  */
 export declare function resolve<T>(fn: () => T): Promise<T>;
@@ -180,21 +358,96 @@ export declare function resolve<T>(fn: () => T): Promise<T>;
  *
  * @returns `[state: Accessor<T>, setState: Setter<T>]`
  *
+ * @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
+ * });
+ * ```
+ *
  * @description https://docs.solidjs.com/reference/basic-reactivity/create-optimistic-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>;
 /**
- * Runs a callback after the current flush cycle completes.
+ * Schedules `callback` to run **once** after the reactive graph has fully
+ * settled — i.e. once every pending async read inside the current owner has
+ * resolved and the queue has flushed. Each call registers a single fire; it
+ * does not create an ongoing subscription.
  *
- * When called within a reactive context (owner), uses a tracked effect with untracked
- * reads - this means normal signal reads won't create subscriptions, but uninitialized
- * async values will throw NotReadyError, causing the callback to re-run when they settle.
+ * The canonical lifecycle primitive in 2.0. Three main usages:
  *
- * When called without an owner, runs once and immediately calls any returned cleanup.
+ * - **Component-level setup-and-teardown** *(the most common shape)*: run
+ *   setup after the component's first stable render and **return a cleanup
+ *   function** to dispose it on owner disposal. This is the replacement for
+ *   the 1.x `onMount` + `onCleanup` pairing — setup and teardown live in one
+ *   block, and `onCleanup` is no longer the right tool for component
+ *   bodies. (`onMount` no longer exists in 2.0.)
+ * - **Post-settle "ready" hook:** run once after a component's first stable
+ *   render — analytics ping, focus, scroll-into-view, etc. No cleanup needed.
+ * - **Inside an event handler:** schedule work to run after the action /
+ *   transition triggered by the event has completed.
+ *
+ * Reactive reads inside the callback are *not* tracked — to react to
+ * subsequent settles, register a new `onSettled` each time.
+ *
+ * `onCleanup` is **not** allowed inside the callback — return a cleanup
+ * function instead. The returned cleanup runs on owner disposal.
+ *
+ * @example
+ * ```tsx
+ * // Component-level setup + teardown — replaces onMount + onCleanup.
+ * // Subscribe to an external source on mount, unsubscribe on dispose.
+ * function useViewportWidth() {
+ *   const [width, setWidth] = createSignal(window.innerWidth);
+ *   onSettled(() => {
+ *     const onResize = () => setWidth(window.innerWidth);
+ *     window.addEventListener("resize", onResize);
+ *     return () => window.removeEventListener("resize", onResize);
+ *   });
+ *   return width;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Post-settle "ready" hook — no cleanup needed.
+ * function Dashboard() {
+ *   const data = createMemo(async () => fetchData());
+ *
+ *   onSettled(() => {
+ *     analytics.track("dashboard.ready");
+ *   });
+ *
+ *   return <Loading fallback={<Spinner />}><pre>{data()}</pre></Loading>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Event-handler — runs after the action settles.
+ * function SaveButton() {
+ *   const save = action(function* () {
+ *     yield api.save();
+ *   });
+ *
+ *   const handleClick = () => {
+ *     save();
+ *     onSettled(() => toast("Saved!"));
+ *   };
+ *
+ *   return <button onClick={handleClick}>Save</button>;
+ * }
+ * ```
  *
- * @param callback Function to run, may return a cleanup function
+ * @param callback Function to run; may return a cleanup function that fires
+ *   on owner disposal
  */
 export declare function onSettled(callback: () => void | (() => void)): void;
 export {};

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

@@ -1,19 +1,45 @@
-import { $REFRESH } from "../core/index.js";
+import { type Refreshable } from "../core/index.js";
 import { type NoFn, type ProjectionOptions, type Store, type StoreSetter } from "./store.js";
 /**
- * Creates an optimistic store that can be used to optimistically update a value
- * and then revert it back to the previous value at end of transition.
+ * 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.
  *
- * When called with a plain value, creates an optimistic store.
- * When called with a function, creates a derived optimistic store with `ProjectionOptions` (name, key).
+ * Use this for optimistic UI on collection-shaped data. For single-value
+ * optimistic state, prefer `createOptimistic`.
  *
- * @param fn a function that receives the current store and can be used to mutate it directly inside a transition
- * @param store The plain store value, or the backing seed when using the derived-store form.
- * @param options Optional projection options for reconciliation.
+ * - 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.
  *
- * @returns A tuple containing a store accessor and a setter function to apply changes.
+ * `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 }`).
+ * 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>>): [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: Store<T> & {
-    [$REFRESH]: any;
-}, 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>];

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

@@ -1,27 +1,53 @@
-import { $REFRESH, type Computed } from "../core/index.js";
+import { type Computed, type Refreshable } from "../core/index.js";
 import { type ProjectionOptions, type Store } from "./store.js";
 export declare function createProjectionInternal<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: Partial<T>, options?: ProjectionOptions): {
-    store: Store<T> & {
-        [$REFRESH]: any;
-    };
+    store: Refreshable<Store<T>>;
     node: Computed<void | T>;
 };
 /**
- * Creates a mutable derived store (projection). The derive function receives a mutable
- * draft and can mutate it directly or return a new value for reconciliation.
+ * Creates a derived (projected) store. Like `createMemo` but for stores: the
+ * derive function receives a mutable draft and either mutates it in place
+ * (canonical) or returns a new value. Either way the result is reconciled
+ * against the previous draft by `options.key` (default `"id"`), so surviving
+ * items keep their proxy identity — only added/removed items are
+ * created/disposed.
  *
- * ```typescript
- * const store = createProjection<T>(fn, seed, options?: ProjectionOptions);
+ * Returns the projected store directly (no setter — reads only).
+ *
+ * Use this when you want the structural-sharing / per-property tracking
+ * behaviour of a store on top of a derived computation. For simple read-only
+ * derivations, `createMemo` is lighter.
+ *
+ * @param fn receives the current draft; mutate it in place or return new
+ *   data. Return is convenient for filter/derive shapes where mutation is
+ *   awkward.
+ * @param seed the backing store value to wrap and reconcile into
+ * @param options `ProjectionOptions` — `name`, `key`. `key` defaults to
+ *   `"id"`; specify it only when your data uses a different identity field
+ *   (e.g. `{ key: "uuid" }` or `{ key: u => u.slug }`).
+ *
+ * @example
+ * ```ts
+ * // Mutation form — update individual fields on the draft.
+ * const summary = createProjection<{ total: number; active: number }>(
+ *   draft => {
+ *     draft.total = users().length;
+ *     draft.active = users().filter(u => u.active).length;
+ *   },
+ *   { total: 0, active: 0 }
+ * );
+ *
+ * // Return form — produce a derived collection. Reconciled by `id` so each
+ * // surviving user keeps the same store identity across recomputes.
+ * const activeUsers = createProjection<User[]>(
+ *   () => allUsers().filter(u => u.active),
+ *   []
+ * );
  * ```
- * @param fn a function that receives the current draft and mutates it or returns new data
- * @param seed the backing store host value to wrap and reconcile into
- * @param options `ProjectionOptions` -- name, key
  *
  * @see {@link https://github.com/solidjs/x-reactivity#createprojection}
  */
-export declare function createProjection<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: Partial<T>, options?: ProjectionOptions): Store<T> & {
-    [$REFRESH]: any;
-};
+export declare function createProjection<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, seed: Partial<T>, options?: ProjectionOptions): Refreshable<Store<T>>;
 /**
  * Shared projection computed body used by both `createProjection` and the derived
  * form of `createOptimisticStore`. Encapsulates the write-trap draft, `storeSetter`

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

@@ -1 +1,23 @@
+/**
+ * Returns a draft-mutating function that smart-merges `value` into a store,
+ * preserving the identity of items whose `key` field matches between old and
+ * new states. Useful when applying server payloads or full-replacement data
+ * onto an existing store without losing fine-grained reactivity.
+ *
+ * Items with the same key are updated in place (only changed properties
+ * trigger updates). Items added or removed update the corresponding signals.
+ *
+ * @param value the next state to merge in
+ * @param key property name (string) or extractor function for stable identity
+ *
+ * @example
+ * ```ts
+ * const [todos, setTodos] = createStore<Todo[]>([]);
+ *
+ * async function refresh() {
+ *   const fresh = await api.getTodos();
+ *   setTodos(reconcile(fresh, "id")); // diff-merge by `id`
+ * }
+ * ```
+ */
 export declare function reconcile<T extends U, U>(value: T, key: string | ((item: NonNullable<any>) => any)): (state: U) => void;

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

@@ -1,5 +1,21 @@
-import { $REFRESH, STORE_SNAPSHOT_PROPS, type Computed, type Signal } from "../core/index.js";
+import { STORE_SNAPSHOT_PROPS, type Computed, type Refreshable, type Signal } from "../core/index.js";
+/** A read-only view of a store's value as seen by consumers. Mutate it via the paired `StoreSetter`. */
 export type Store<T> = Readonly<T>;
+/**
+ * A store setter. The callback receives a writable **draft** of the store.
+ *
+ * - **Mutate in place (canonical):** `s.foo = 1`, `s.list.push(x)`,
+ *   `s.list.splice(i, 1)`. This is the default form for most updates.
+ * - **Return a new value:** for shapes where mutation is awkward, most
+ *   commonly removing items (`s => s.list.filter(...)`). Arrays are replaced
+ *   by index (length adjusted); objects are shallow-diffed at the top level
+ *   (keys present in the returned value are written, missing keys deleted).
+ *
+ * The setter does **not** perform keyed reconciliation. If you need surviving
+ * items to keep their store identity across full-array replacement, use the
+ * projection form — `createStore(fn, seed, { key })` or `createProjection` —
+ * whose derive function reconciles its return by `options.key`.
+ */
 export type StoreSetter<T> = (fn: (state: T) => T | void) => void;
 /** Base options for store primitives. */
 export interface StoreOptions {
@@ -45,24 +61,58 @@ export declare function getPropertyDescriptor(source: Record<PropertyKey, any>,
 export declare const storeTraps: ProxyHandler<StoreNode>;
 export declare function storeSetter<T extends object>(store: Store<T>, fn: (draft: T) => T | void): void;
 /**
- * Creates a deeply reactive store with proxy-based tracking.
+ * Creates a deeply-reactive store backed by a Proxy. Reads track each property
+ * accessed; only the parts that change trigger updates.
+ *
+ * Store properties hold **plain values**, not accessors. The proxy already
+ * tracks reads per-property — wrapping a value in `() => state.foo` produces
+ * a getter that *won't* track when called, which looks like a reactivity bug
+ * but is just a category error. If you have a signal-shaped piece of state,
+ * make it a property of the store (`{ foo: 1 }`) rather than nesting an
+ * accessor inside (`{ foo: () => signal() }`).
  *
- * When called with a plain value, wraps it in a reactive proxy.
- * When called with a function, creates a derived projection store with `ProjectionOptions` (name, key).
+ * The setter takes a **draft-mutating** function — mutate the draft in place
+ * (canonical). The callback may also return a new value: arrays are replaced
+ * by index (length adjusted), objects are shallow-diffed at the top level
+ * (keys present in the returned value are written, missing keys deleted). Use
+ * the return form for shapes where mutation is awkward — most commonly
+ * removing items via `filter`. The setter does **not** do keyed reconciliation;
+ * for that, use the derived/projection form (or `createProjection`).
+ *
+ * - Plain form: `createStore(initialValue)` — wraps a value in a reactive
+ *   proxy.
+ * - Derived form: `createStore(fn, seed, options?)` — a *projection store*
+ *   whose contents are computed by `fn(draft)`. `fn` may be sync, async, or
+ *   an `AsyncIterable`; the projection's result reconciles against the
+ *   existing store by `options.key` (default `"id"`) for stable identity.
+ *
+ * @example
+ * ```ts
+ * const [state, setState] = createStore({
+ *   user: { name: "Ada", age: 36 },
+ *   todos: [] as { id: string; text: string; done: boolean }[]
+ * });
+ *
+ * // Canonical: mutate the draft in place.
+ * setState(s => { s.user.age = 37; });
+ * setState(s => { s.todos.push({ id: "1", text: "x", done: false }); });
+ *
+ * // Return form: reach for it when mutation is awkward.
+ * setState(s => s.todos.filter(t => !t.done));               // remove items
+ * setState(s => ({ ...s, user: { name: "Grace", age: 85 } })); // shallow replace
+ * ```
  *
- * ```typescript
- * // Plain store
- * const [store, setStore] = createStore<T>(initialValue);
- * // Derived store (projection)
- * const [store, setStore] = createStore<T>(fn, seed, options?: ProjectionOptions);
+ * @example
+ * ```ts
+ * // Derived store — auto-fetches & reconciles by `id`.
+ * const [users] = createStore(
+ *   async () => fetch("/users").then(r => r.json()),
+ *   [] as User[]
+ * );
  * ```
- * @param store initial value to wrap in a reactive proxy, or a derive function
- * @param options `ProjectionOptions` -- name, key (only for derived stores)
  *
  * @returns `[store: Store<T>, setStore: StoreSetter<T>]`
  */
 export declare function createStore<T extends object = {}>(store: NoFn<T> | Store<NoFn<T>>): [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: Store<T> & {
-    [$REFRESH]: any;
-}, 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 {};

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

@@ -26,5 +26,33 @@ export interface storePath {
     <T, K1 extends KeyOf<W<T>>>(k1: Part<W<T>, K1>, setter: PathSetter<W<T>[K1]>): (state: T) => void;
     <T>(setter: PathSetter<T>): (state: T) => void;
 }
+/**
+ * Path-based setter helper for `createStore`. Call `storePath(...path, value)`
+ * to produce a draft-mutating function suitable for passing to `setStore`.
+ *
+ * The canonical setter form in Solid 2.0 is the draft-mutating callback
+ * (`setStore(s => { s.user.name = "Ada"; })`). `storePath` is a backwards-
+ * compatibility helper for users porting from Solid 1.x's
+ * `setStore("user", "name", "Ada")` style — it's optional and you can mix the
+ * two styles freely.
+ *
+ * Path parts can be:
+ * - a single key — `"user"`, `0`
+ * - an array of keys — `[0, 1, 2]`
+ * - a range over an array — `{ from?, to?, by? }`
+ * - a filter `(item, index) => boolean` for arrays
+ *
+ * The final argument is the new value or an updater `(prev) => next`. Use
+ * `storePath.DELETE` to remove a property.
+ *
+ * @example
+ * ```ts
+ * const [state, setState] = createStore({ user: { name: "Ada" }, todos: [] });
+ *
+ * setState(storePath("user", "name", "Grace"));
+ * setState(storePath("todos", t => !t.done, "done", true)); // mark all undone as done
+ * setState(storePath("user", "nickname", storePath.DELETE));
+ * ```
+ */
 export declare const storePath: storePath;
 export {};