@solidjs/signals 0.9.10 → 0.10.0

package/dist/types/signals.d.ts

@@ -1,4 +1,3 @@
-import type { SignalOptions } from "./core/index.js";
 export type Accessor<T> = () => T;
 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;
@@ -13,92 +12,104 @@ export type EffectBundle<Prev, Next extends Prev = Prev> = {
     effect: EffectFunction<Prev, Next>;
     error: (err: unknown, cleanup: () => void) => void;
 };
+/** Options for effect primitives (`createEffect`, `createRenderEffect`, `createTrackedEffect`, `createReaction`). */
 export interface EffectOptions {
+    /** Debug name (dev mode only) */
     name?: string;
+    /** When true, defers the initial effect execution until the next change */
     defer?: boolean;
 }
+/** Options for plain signals created with `createSignal(value)` or `createOptimistic(value)`. */
+export interface SignalOptions<T> {
+    /** Debug name (dev mode only) */
+    name?: string;
+    /** Custom equality function, or `false` to always notify subscribers */
+    equals?: false | ((prev: T, next: T) => boolean);
+    /** Suppress dev-mode warnings when writing inside an owned scope */
+    pureWrite?: boolean;
+    /** Callback invoked when the signal loses all subscribers */
+    unobserved?: () => void;
+}
+/**
+ * Options for read-only memos created with `createMemo`.
+ * Also used in combination with `SignalOptions` for writable memos
+ * (`createSignal(fn)` / `createOptimistic(fn)`).
+ */
 export interface MemoOptions<T> {
+    /** Stable identifier for the owner hierarchy */
+    id?: string;
+    /** Debug name (dev mode only) */
     name?: string;
+    /** Custom equality function, or `false` to always notify subscribers */
     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 */
+    lazy?: boolean;
 }
 export type NoInfer<T extends any> = [T][T extends any ? 0 : never];
 /**
- * Creates a simple reactive state with a getter and setter
+ * Creates a simple reactive state with a getter and setter.
+ *
+ * When called with a plain value, creates a signal with `SignalOptions` (name, equals, pureWrite, unobserved).
+ * When called with a function, creates a writable memo with `SignalOptions & MemoOptions` (adds id, lazy).
+ *
  * ```typescript
- * const [state: Accessor<T>, setState: Setter<T>] = createSignal<T>(
- *  value: T,
- *  options?: { name?: string, equals?: false | ((prev: T, next: T) => boolean) }
- * )
+ * // Plain signal
+ * const [state, setState] = createSignal<T>(value, options?: SignalOptions<T>);
+ * // Writable memo (function overload)
+ * const [state, setState] = createSignal<T>(fn, initialValue?, options?: SignalOptions<T> & MemoOptions<T>);
  * ```
- * @param value initial value of the state; if empty, the state's type will automatically extended with undefined; otherwise you need to extend the type manually if you want setting to undefined not be an error
+ * @param value initial value of the state; if empty, the state'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
  *
- * @returns ```typescript
- * [state: Accessor<T>, setState: Setter<T>]
- * ```
- * * the Accessor is a function that returns the current value and registers each call to the reactive root
- * * the Setter is a function that allows directly setting or mutating the value:
- * ```typescript
- * const [count, setCount] = createSignal(0);
- * setCount(count => count + 1);
- * ```
+ * @returns `[state: Accessor<T>, setState: Setter<T>]`
  *
  * @description https://docs.solidjs.com/reference/basic-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>, initialValue?: T, options?: SignalOptions<T>): Signal<T>;
+export declare function createSignal<T>(fn: ComputeFunction<T>, initialValue?: T, options?: SignalOptions<T> & MemoOptions<T>): Signal<T>;
 /**
- * Creates a readonly derived reactive memoized signal
+ * Creates a readonly derived reactive memoized signal.
+ *
  * ```typescript
- * export function createMemo<T>(
- *   compute: (v: T) => T,
- *   value?: T,
- *   options?: { name?: string, equals?: false | ((prev: T, next: T) => boolean) }
- * ): () => T;
+ * const value = createMemo<T>(compute, initialValue?, options?: MemoOptions<T>);
  * ```
  * @param compute a function that receives its previous or the initial value, if set, and returns a new value used to react on a computation
  * @param value an optional initial value for the computation; if set, fn will never receive undefined as first argument
- * @param options allows to set a name in dev mode for debugging purposes and use a custom comparison function in equals
+ * @param options `MemoOptions` -- id, name, equals, unobserved, lazy
  *
  * @description https://docs.solidjs.com/reference/basic-reactivity/create-memo
  */
 export declare function createMemo<Next extends Prev, Prev = Next>(compute: ComputeFunction<undefined | NoInfer<Prev>, Next>): Accessor<Next>;
 export declare function createMemo<Next extends Prev, Init = Next, Prev = Next>(compute: ComputeFunction<Init | Prev, Next>, value: Init, options?: MemoOptions<Next>): Accessor<Next>;
 /**
- * Creates a reactive effect that runs after the render phase
+ * Creates a reactive effect that runs after the render phase.
+ *
  * ```typescript
- * export function createEffect<T>(
- *   compute: (prev: T) => T,
- *   effect: (v: T, prev: T) => (() => void) | void,
- *   value?: T,
- *   options?: { name?: string }
- * ): void;
+ * createEffect<T>(compute, effectFn | { effect, error }, initialValue?, options?: EffectOptions);
  * ```
  * @param compute a function that receives its previous or the initial value, if set, and returns a new value used to react on a computation
- * @param effect a function that receives the new value and is used to perform side effects, return a cleanup function to run on disposal
- * @param error an optional function that receives an error if thrown during the 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 value an optional initial value for the computation; if set, fn will never receive undefined as first argument
- * @param options allows to set a name in dev mode for debugging purposes
+ * @param options `EffectOptions` -- name, defer
  *
  * @description https://docs.solidjs.com/reference/basic-reactivity/create-effect
  */
 export declare function createEffect<Next>(compute: ComputeFunction<undefined | NoInfer<Next>, Next>, effectFn: EffectFunction<NoInfer<Next>, Next> | EffectBundle<NoInfer<Next>, Next>): void;
 export declare function createEffect<Next, Init = Next>(compute: ComputeFunction<Init | Next, Next>, effect: EffectFunction<Next, Next> | EffectBundle<Next, Next>, value: Init, options?: EffectOptions): void;
 /**
- * Creates a reactive computation that runs during the render phase as DOM elements are created and updated but not necessarily connected
+ * Creates a reactive computation that runs during the render phase as DOM elements
+ * are created and updated but not necessarily connected.
+ *
  * ```typescript
- * export function createRenderEffect<T>(
- *   compute: (prev: T) => T,
- *   effect: (v: T, prev: T) => (() => void) | void,
- *   value?: T,
- *   options?: { name?: string }
- * ): void;
+ * createRenderEffect<T>(compute, effectFn, initialValue?, options?: EffectOptions);
  * ```
  * @param compute a function that receives its previous or the initial value, if set, and returns a new value used to react on a computation
- * @param effect a function that receives the new value and is used to perform side effects
+ * @param effectFn a function that receives the new value and is used to perform side effects
  * @param value an optional initial value for the computation; if set, fn will never receive undefined as first argument
- * @param options allows to set a name in dev mode for debugging purposes
+ * @param options `EffectOptions` -- name, defer
  *
  * @description https://docs.solidjs.com/reference/secondary-primitives/create-render-effect
  */
@@ -113,27 +124,23 @@ export declare function createRenderEffect<Next, Init = Next>(compute: ComputeFu
  * state). Use only when dynamic subscription patterns require same-scope tracking.
  *
  * ```typescript
- * export function createTrackedEffect(
- *   compute: () => (() => void) | void,
- *   options?: { name?: string }
- * ): void;
+ * createTrackedEffect(compute, options?: EffectOptions);
  * ```
  * @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 allows to set a name in dev mode for debugging purposes
+ * @param options `EffectOptions` -- name, defer
  *
  * @description https://docs.solidjs.com/reference/secondary-primitives/create-tracked-effect
  */
 export declare function createTrackedEffect(compute: () => void | (() => void), options?: EffectOptions): void;
 /**
- * Creates a reactive computation that runs after the render phase with flexible tracking
+ * Creates a reactive computation that runs after the render phase with flexible tracking.
+ *
  * ```typescript
- * export function createReaction(
- *   onInvalidate: () => void,
- *   options?: { name?: string }
- * ): (fn: () => void) => void;
+ * const track = createReaction(effectFn, options?: EffectOptions);
+ * track(() => { // reactive reads });
  * ```
- * @param invalidated a function that is called when tracked function is invalidated.
- * @param options allows to set a name in dev mode for debugging purposes
+ * @param effectFn a function (or `EffectBundle`) that is called when tracked function is invalidated
+ * @param options `EffectOptions` -- name, defer
  *
  * @description https://docs.solidjs.com/reference/secondary-primitives/create-reaction
  */
@@ -146,36 +153,26 @@ 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.
+ *
+ * When called with a plain value, creates an optimistic signal with `SignalOptions` (name, equals, pureWrite, unobserved).
+ * When called with a function, creates a writable optimistic memo with `SignalOptions & MemoOptions` (adds id, lazy).
+ *
  * ```typescript
- * export function createOptimistic<T>(): Signal<T | undefined>;
- * export function createOptimistic<T>(
- *   value: Exclude<T, Function>,
- *   options?: SignalOptions<T>
- * ): Signal<T>;
- * export function createOptimistic<T>(
- *   fn: ComputeFunction<T>,
- *   initialValue?: T,
- *   options?: SignalOptions<T>
- * ): Signal<T>;
+ * // Plain optimistic signal
+ * const [state, setState] = createOptimistic<T>(value, options?: SignalOptions<T>);
+ * // Writable optimistic memo (function overload)
+ * const [state, setState] = createOptimistic<T>(fn, initialValue?, options?: SignalOptions<T> & MemoOptions<T>);
  * ```
- * @param value initial value of the signal; if empty, the signal's type will automatically extended with undefined; otherwise you need to extend the type manually if you want setting to undefined not be an error
+ * @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
  *
- * @returns ```typescript
- * [state: Accessor<T>, setState: Setter<T>]
- * ```
- * * the Accessor is a function that returns the current value and registers each call to the reactive root
- * * the Setter is a function that allows directly setting or mutating the value:
- * ```typescript
- * const [count, setCount] = createOptimistic(0);
- * setCount(count => count + 1);
- * ```
+ * @returns `[state: Accessor<T>, setState: Setter<T>]`
  *
  * @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>, initialValue?: T, options?: SignalOptions<T>): Signal<T>;
+export declare function createOptimistic<T>(fn: ComputeFunction<T>, initialValue?: T, options?: SignalOptions<T> & MemoOptions<T>): Signal<T>;
 /**
  * Runs a callback after the current flush cycle completes.
  *

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

@@ -1,4 +1,4 @@
-export type { Store, StoreSetter, StoreNode, NotWrappable, SolidStore } from "./store.js";
+export type { Store, StoreSetter, StoreNode, StoreOptions, ProjectionOptions, NotWrappable, SolidStore } from "./store.js";
 export type { Merge, Omit } from "./utils.js";
 export { isWrappable, createStore, deep, $TRACK, $PROXY, $TARGET } from "./store.js";
 export { createProjection } from "./projection.js";

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

@@ -1,22 +1,19 @@
 import { $REFRESH } from "../core/index.js";
-import { type NoFn, type Store, type StoreOptions, type StoreSetter } from "./store.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.
- * ```typescript
- * export function createOptimisticStore<T>(
- *   fn: (store: T) => void,
- *   initial: T,
- *   options?: { key?: string | ((item: NonNullable<any>) => any); all?: boolean }
- * ): [get: Store<T>, set: StoreSetter<T>];
- * ```
+ *
+ * When called with a plain value, creates an optimistic store.
+ * When called with a function, creates a derived optimistic store with `ProjectionOptions` (name, key, all).
+ *
  * @param fn a function that receives the current store and can be used to mutate it directly inside a transition
- * @param initial The initial value of the signal.
- * @param options Optional signal options.
+ * @param initial The initial value of the store.
+ * @param options Optional projection options for reconciliation.
  *
- * @returns A tuple containing an accessor for the current value and a setter function to apply changes.
+ * @returns A tuple containing a store accessor and a setter function to apply changes.
  */
 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?: NoFn<T> | Store<NoFn<T>>, options?: StoreOptions): [get: Store<T> & {
+export declare function createOptimisticStore<T extends object = {}>(fn: (store: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, store?: NoFn<T> | Store<NoFn<T>>, options?: ProjectionOptions): [get: Store<T> & {
     [$REFRESH]: any;
 }, set: StoreSetter<T>];

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

@@ -1,17 +1,25 @@
 import { $REFRESH, type Computed } from "../core/index.js";
-import { type Store, type StoreOptions } from "./store.js";
-export declare function createProjectionInternal<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, initialValue?: T, options?: StoreOptions): {
+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>, initialValue?: T, options?: ProjectionOptions): {
     store: Store<T> & {
         [$REFRESH]: any;
     };
     node: Computed<void | T>;
 };
 /**
- * Creates a mutable derived value
+ * 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.
+ *
+ * ```typescript
+ * const store = createProjection<T>(fn, initialValue?, options?: ProjectionOptions);
+ * ```
+ * @param fn a function that receives the current draft and mutates it or returns new data
+ * @param initialValue the initial store value (defaults to `{}`)
+ * @param options `ProjectionOptions` -- name, key, all
  *
  * @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>, initialValue?: T, options?: StoreOptions): Store<T> & {
+export declare function createProjection<T extends object = {}>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, initialValue?: T, options?: ProjectionOptions): Store<T> & {
     [$REFRESH]: any;
 };
 export declare const writeTraps: ProxyHandler<any>;

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

@@ -1,8 +1,16 @@
 import { $REFRESH, type Computed, type Signal } from "../core/index.js";
 export type Store<T> = Readonly<T>;
 export type StoreSetter<T> = (fn: (state: T) => T | void) => void;
+/** Base options for store primitives. */
 export type StoreOptions = {
+    /** Debug name (dev mode only) */
+    name?: string;
+};
+/** Options for derived/projected stores created with `createStore(fn)`, `createProjection`, or `createOptimisticStore(fn)`. */
+export type ProjectionOptions = StoreOptions & {
+    /** Key property name or function for reconciliation identity */
     key?: string | ((item: NonNullable<any>) => any);
+    /** When true, reconciles all properties (not just tracked ones) */
     all?: boolean;
 };
 export type NoFn<T> = T extends Function ? never : T;
@@ -36,8 +44,25 @@ export declare function getKeys(source: Record<PropertyKey, any>, override: Reco
 export declare function getPropertyDescriptor(source: Record<PropertyKey, any>, override: Record<PropertyKey, any> | undefined, property: PropertyKey): PropertyDescriptor | undefined;
 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.
+ *
+ * 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).
+ *
+ * ```typescript
+ * // Plain store
+ * const [store, setStore] = createStore<T>(initialValue);
+ * // Derived store (projection)
+ * const [store, setStore] = createStore<T>(fn, initialValue?, options?: ProjectionOptions);
+ * ```
+ * @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?: NoFn<T> | Store<NoFn<T>>, options?: StoreOptions): [get: Store<T> & {
+export declare function createStore<T extends object = {}>(fn: (store: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, store?: NoFn<T> | Store<NoFn<T>>, options?: ProjectionOptions): [get: Store<T> & {
     [$REFRESH]: any;
 }, set: StoreSetter<T>];
 export declare function deep<T extends object>(store: Store<T>): Store<T>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@solidjs/signals",
-  "version": "0.9.10",
-  "description": "",
+  "version": "0.10.0",
+  "description": "SolidJS' standalone reactive implementation",
   "author": "Ryan Carniato",
   "license": "MIT",
   "repository": {