preact-sigma 2.1.2 → 2.1.3

package/README.md

@@ -164,6 +164,6 @@ In Preact, the same constructor can be used with `useSigma(() => new TodoList(),
 - Use `computed(...)` for argument-free derived state, and use queries for reactive reads that need parameters.
 - Put writes in actions. A draft boundary is any point where sigma cannot keep reusing the current draft. `emit()`, `await`, and any action call other than a same-instance sync nested action call are draft boundaries, so call `this.commit()` before those boundaries when pending writes should become public.
 - Use `snapshot(instance)` and `replaceState(instance, snapshot)` for committed-state replay. They work on top-level state keys and stay outside action semantics.
-- Use `ref(value)` when a value should stay by reference in sigma's `Draft` and `Immutable` types. It only changes typing and does not change Immer's runtime drafting or freezing behavior.
+- Use `SigmaRef<T>` when a value should stay by reference in sigma's `Draft` and `Immutable` types. A normal assignment to a `SigmaRef<T>`-typed value only changes typing and does not change Immer's runtime drafting or freezing behavior.
 - Use `immerable` on custom classes only when they should participate in Immer drafting. `setAutoFreeze(false)` disables sigma's runtime deep-freezing when you need published state to stay unfrozen.
 - Use `setup(...)` for owned side effects, and always return cleanup resources for anything the instance starts.

package/dist/index.d.mts

@@ -50,7 +50,7 @@ type Disposable = {
 interface SigmaRefBrand {
   [sigmaRefBrand]?: true;
 }
-/** A type brand added by `ref(...)`. */
+/** A type brand that keeps a value by reference in sigma's `Draft` and `Immutable` helpers. */
 type SigmaRef<T = unknown> = T & SigmaRefBrand;
 /** The event map shape used by sigma types. */
 type AnyEvents = Record<string, object | void>;
@@ -150,11 +150,6 @@ declare function replaceState<T extends AnySigmaState>(publicInstance: T, nextSt
 //#region src/framework.d.ts
 /** Checks whether a value is a sigma-state instance. */
 declare function isSigmaState(value: unknown): value is AnySigmaState;
-/**
- * Returns `value` unchanged and marks its type so sigma's Draft and Immutable
- * helpers keep it by reference instead of recursively immerizing it.
- */
-declare function ref<T extends object>(value: T): SigmaRef<T>;
 /** Creates a standalone tracked query function with the same signature as `fn`. */
 declare function query<TArgs extends any[], TResult>(fn: (this: void, ...args: TArgs) => TResult): typeof fn;
 /**
@@ -238,4 +233,4 @@ declare function useSigma<T extends AnySigmaState>(create: () => T, setupArgs?:
 /** Attaches an event listener in a component and cleans it up when dependencies change. */
 declare function useListener<TTarget extends EventTarget | AnySigmaState, TEvent extends InferEventType<TTarget>>(target: TTarget | null, name: TEvent, listener: InferListener<TTarget, TEvent>): void;
 //#endregion
-export { type AnyDefaultState, type AnyEvents, type AnyResource, type AnySigmaState, type AnySigmaStateWithEvents, type AnyState, InferEventType, InferListener, type InferSetupArgs, type SigmaObserveChange, type SigmaObserveOptions, type SigmaRef, type SigmaState, SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, ref, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };
+export { type AnyDefaultState, type AnyEvents, type AnyResource, type AnySigmaState, type AnySigmaStateWithEvents, type AnyState, InferEventType, InferListener, type InferSetupArgs, type SigmaObserveChange, type SigmaObserveOptions, type SigmaRef, type SigmaState, SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };

package/dist/index.mjs

@@ -520,13 +520,6 @@ Object.defineProperty(Sigma.prototype, sigmaStateBrand, { value: true });
 function isSigmaState(value) {
 	return Boolean(value && typeof value === "object" && value[sigmaStateBrand]);
 }
-/**
-* Returns `value` unchanged and marks its type so sigma's Draft and Immutable
-* helpers keep it by reference instead of recursively immerizing it.
-*/
-function ref(value) {
-	return value;
-}
 /** Creates a standalone tracked query function with the same signature as `fn`. */
 function query(fn) {
 	return ((...args) => computed$1(() => fn(...args)).value);
@@ -633,4 +626,4 @@ function useListener(target, name, listener) {
 	}, [target, name]);
 }
 //#endregion
-export { SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, ref, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };
+export { SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };

package/llms.txt

@@ -7,7 +7,6 @@
 - `state property`: A top-level property from `TState`, such as `draft` in `{ draft: string }`.
 - `computed`: A tracked getter declared with `.computed({ ... })`.
 - `query`: A tracked method declared with `.queries({ ... })` or created with `query(fn)`.
-- `ref`: A helper that keeps a value by reference in sigma's `Draft` and `Immutable` types without changing runtime behavior.
 - `action`: A method declared with `.actions({ ... })` that reads and writes through one Immer draft for one synchronous call.
 - `draft boundary`: Any point where sigma cannot keep reusing the current draft.
 - `setup handler`: A function declared with `.setup(fn)` that returns an array of cleanup resources.
@@ -18,7 +17,7 @@
 
 - For state shape, inference, and instance shape, read `Start Here`, `Inference`, `SigmaType`, and `Public Instance Shape`.
 - For mutation semantics, read `Critical Rules`, `actions`, `immerable`, and `setAutoFreeze`.
-- For type-level by-reference values, read `ref`.
+- For type-level by-reference values, see `SigmaRef<T>`.
 - For side effects and events, read `setup`, `Events`, `listen`, `useListener`, and `useSigma`.
 - For committed-state utilities, read `observe`, `snapshot`, and `replaceState`.
 
@@ -62,7 +61,7 @@ import {
   isSigmaState,
   listen,
   query,
-  ref,
+  type SigmaRef,
   replaceState,
   setAutoFreeze,
   snapshot,
@@ -328,13 +327,13 @@ Behavior:
 - custom class instances without a true `[immerable]` property stay outside that freeze path
 - plain objects, arrays, `Map`, and `Set` already participate in normal Immer drafting without extra markers
 
-## `ref(value)`
+## `SigmaRef<T>`
 
-`ref(value)` returns `value` unchanged and marks its type so sigma's `Draft` and `Immutable` helpers keep that value by reference.
+`SigmaRef<T>` marks a value's type so sigma's `Draft` and `Immutable` helpers keep that value by reference.
 
 Behavior:
 
-- it has no runtime effect
+- assigning to a `SigmaRef<T>`-typed value has no runtime effect
 - it only changes sigma's local `Draft` and `Immutable` typing
 - it prevents type-level recursive immerization for that value
 - it does not change whether Immer drafts or freezes the value at runtime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preact-sigma",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "keywords": [],
   "license": "MIT",
   "author": "Alec Larson",