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

package/dist/types-cjs/store/store.d.cts

@@ -1,5 +1,21 @@
-import { $REFRESH, STORE_SNAPSHOT_PROPS, type Computed, type Signal } from "../core/index.cjs";
+import { STORE_SNAPSHOT_PROPS, type Computed, type Refreshable, type Signal } from "../core/index.cjs";
+/** 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, all).
+ * 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, all (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-cjs/store/storePath.d.cts

@@ -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 {};

package/dist/types-cjs/store/utils.d.cts

@@ -1,15 +1,41 @@
 /**
- * Returns a non reactive copy of the store object.
- * It will attempt to preserver the original reference unless the value has been modified.
- * @param item store proxy object
+ * Returns a plain (non-proxy, non-reactive) deep copy of a store value.
+ * Reading via `snapshot` does **not** subscribe to changes — use this when you
+ * need to hand a stable plain object to non-reactive code (logging,
+ * serialization, structured-clone, network payloads, etc.).
+ *
+ * Returns the original object identity for any sub-tree that wasn't modified
+ * relative to the proxy's underlying source.
+ *
+ * @example
+ * ```ts
+ * const [state] = createStore({ user: { name: "Ada" }, todos: [] });
+ *
+ * console.log(JSON.stringify(snapshot(state))); // safe, non-reactive copy
+ * ```
  */
 export declare function snapshot<T>(item: T): T;
 export declare function snapshot<T>(item: T, map?: Map<unknown, unknown>, lookup?: WeakMap<any, any>): T;
 /**
- * Returns a non-reactive snapshot of the store while subscribing to all nested changes.
- * Subscribes to `$TRACK` at every level so that any deep change triggers recomputation,
- * and returns plain (non-proxy) data. Works correctly with `reconcile()`.
- * @param store store proxy object
+ * Returns a plain (non-proxy) deep copy **and** subscribes the current
+ * tracking scope to every nested change in the source store. Any write
+ * anywhere in the subtree invalidates the consumer.
+ *
+ * Use this when you need plain data inside a reactive scope and want to
+ * react to deep mutations (e.g. passing a snapshot to `reconcile()` or to a
+ * memo that should rerun on any nested change). For most read paths, prefer
+ * direct property access — Solid stores already track per-property reads
+ * with no `deep()` wrapper needed.
+ *
+ * @example
+ * ```ts
+ * const [state] = createStore({ a: { b: { c: 1 } } });
+ *
+ * createEffect(
+ *   () => deep(state),                  // reruns on any nested change
+ *   plain => sendToWorker(plain)        // worker gets a non-proxy copy
+ * );
+ * ```
  */
 export declare function deep<T extends object>(store: T): T;
 type DistributeOverride<T, F> = T extends undefined ? F : T;
@@ -35,9 +61,54 @@ type _Merge<T extends unknown[], Curr = {}> = T extends [
     ...infer Rest
 ] ? _Merge<Rest, Override<Curr, Next>> : T extends [...infer Rest, infer Next | (() => infer Next)] ? Override<_Merge<Rest, Curr>, Next> : T extends [] ? Curr : T extends (infer I | (() => infer I))[] ? OverrideSpread<Curr, I> : Curr;
 export type Merge<T extends unknown[]> = Simplify<_Merge<T>>;
+/**
+ * Merges multiple props-like objects into a single proxy that *preserves
+ * reactivity*. Reads are forwarded to the right-most source that defines the
+ * property, so later sources override earlier ones (like `Object.assign`).
+ *
+ * Function arguments are treated as memo-backed sources — useful for passing
+ * derived defaults whose computation should track reactively.
+ *
+ * Use this in component bodies to merge defaults / overrides without losing
+ * Solid's per-property tracking.
+ *
+ * @example
+ * ```tsx
+ * function Button(_props: { label: string; type?: string; disabled?: boolean }) {
+ *   const props = merge({ type: "button", disabled: false }, _props);
+ *
+ *   return <button type={props.type} disabled={props.disabled}>{props.label}</button>;
+ * }
+ * ```
+ */
 export declare function merge<T extends unknown[]>(...sources: T): Merge<T>;
 export type Omit<T, K extends readonly (keyof T)[]> = {
     [P in keyof T as Exclude<P, K[number]>]: T[P];
 };
+/**
+ * Returns a reactive proxy of `props` with the listed keys hidden. Tracking
+ * on the remaining keys is preserved.
+ *
+ * Use it to forward "rest" props to a child element while pulling out the
+ * keys your component handles itself — the equivalent of `splitProps(p, ["a","b"])[1]`.
+ *
+ * @example
+ * ```tsx
+ * function Input(props: { label: string; value: string; onInput: (v: string) => void } & JSX.HTMLAttributes<HTMLInputElement>) {
+ *   const rest = omit(props, "label", "value", "onInput");
+ *
+ *   return (
+ *     <label>
+ *       {props.label}
+ *       <input
+ *         {...rest}
+ *         value={props.value}
+ *         onInput={e => props.onInput(e.currentTarget.value)}
+ *       />
+ *     </label>
+ *   );
+ * }
+ * ```
+ */
 export declare function omit<T extends Record<any, any>, K extends readonly (keyof T)[]>(props: T, ...keys: K): Omit<T, K>;
 export {};

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@solidjs/signals",
-  "version": "2.0.0-beta.7",
-  "description": "SolidJS' reactive core implementation",
+  "version": "2.0.0-beta.9",
+  "description": "Solid's reactive primitives: signals, memos, effects, stores, and async-aware computations.",
   "author": "Ryan Carniato",
   "license": "MIT",
   "homepage": "https://solidjs.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/solidjs/solid"
+    "url": "git+https://github.com/solidjs/solid.git",
+    "directory": "packages/solid-signals"
   },
   "publishConfig": {
     "access": "public"