preact-sigma 6.1.3 → 6.2.0

package/README.md

@@ -48,5 +48,8 @@ console.log(counter.doubled); // 2
 - Concepts, lifecycle, invariants, and API selection live in [`docs/context.md`](./docs/context.md).
 - Persistence-specific guidance lives in [`docs/persist.md`](./docs/persist.md).
 - Migration guidance from v5 lives in [`docs/migrations/v5-to-v6.md`](./docs/migrations/v5-to-v6.md).
-- Runnable usage patterns live in [`examples/`](./examples/), starting with [`examples/basic-counter.ts`](./examples/basic-counter.ts) and [`examples/command-palette.tsx`](./examples/command-palette.tsx).
+- Runnable usage patterns live in [`examples/`](./examples/).
+  - [`examples/basic-counter.ts`](./examples/basic-counter.ts)
+  - [`examples/command-palette.tsx`](./examples/command-palette.tsx)
+  - [`examples/external-query-sync.tsx`](./examples/external-query-sync.tsx)
 - Exact exported signatures and public API comments live in `dist/index.d.mts` and `dist/persist.d.mts` after `pnpm build`.

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as SigmaState, c as query, d as Draft, f as Immutable, i as SigmaRef, l as setAutoFreeze, m as Cleanup, n as Sigma, o as SigmaTarget, p as typeSymbol, r as SigmaDefinition, s as castProtected, t as Protected, u as sigma } from "./sigma-Dki3T7re.mjs";
+import { a as SigmaRef, c as castProtected, d as sigma, f as Draft, h as Cleanup, i as SigmaDefinition, l as query, m as typeSymbol, n as ReadableSigma, o as SigmaState, p as Immutable, r as Sigma, s as SigmaTarget, t as Protected, u as setAutoFreeze } from "./sigma-BfaJUPWw.mjs";
 
 //#region src/defaults.d.ts
 /**
@@ -58,4 +58,18 @@ type UseSigmaArgs<T extends Sigma<any>> = T extends {
  */
 declare function useSigma<T extends Sigma<any>>(...args: UseSigmaArgs<T>): Protected<T>;
 //#endregion
-export { type Draft, type Immutable, InferEventType, InferListener, Listenable, Protected, Sigma, SigmaDefinition, SigmaListenable, SigmaRef, SigmaState, SigmaTarget, UseSigmaArgs, UseSigmaOptions, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSigma };
+//#region src/hooks/useSigmaSync.d.ts
+type PlainObject = Record<string, unknown>;
+/**
+ * Synchronizes changed external data into a sigma instance after the initial render.
+ *
+ * `input` must be a plain object with stable keys. Its values are shallow-compared with
+ * `Object.is(...)`, and `sync(...)` runs only after at least one value changes.
+ *
+ * A changed `instance` resets the baseline input, so newly created component-owned sigma
+ * instances can receive their initial external data through construction or setup before
+ * later renders synchronize changes through this hook.
+ */
+declare function useSigmaSync<TInstance extends Sigma<any>, TInput extends PlainObject>(instance: TInstance | Protected<TInstance>, input: TInput, sync: (input: Readonly<TInput>) => void): void;
+//#endregion
+export { type Draft, type Immutable, InferEventType, InferListener, Listenable, Protected, ReadableSigma, Sigma, SigmaDefinition, SigmaListenable, SigmaRef, SigmaState, SigmaTarget, UseSigmaArgs, UseSigmaOptions, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSigma, useSigmaSync };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as setAutoFreeze, c as listenersSymbol, i as query, n as SigmaTarget, o as sigma, r as castProtected, t as Sigma } from "./sigma-Oviv0rzP.mjs";
+import { a as setAutoFreeze, c as listenersSymbol, i as query, n as SigmaTarget, o as sigma, r as castProtected, s as isPlainObject, t as Sigma } from "./sigma-DEKK3bHd.mjs";
 import { useEffect, useRef } from "preact/hooks";
 //#region src/defaults.ts
 /**
@@ -77,4 +77,42 @@ function useSigma(create, optionsOrDeps) {
 	return castProtected(instance);
 }
 //#endregion
-export { Sigma, SigmaTarget, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSigma };
+//#region src/hooks/useSigmaSync.ts
+function assertStableKeys(cachedKeys, nextKeys) {
+	if (cachedKeys.length !== nextKeys.length || nextKeys.some((key) => !cachedKeys.includes(key))) throw new Error("[preact-sigma] useSigmaSync() input keys must stay stable between renders.");
+}
+function hasChanged(previous, next, keys) {
+	return keys.some((key) => !Object.is(previous[key], next[key]));
+}
+/**
+* Synchronizes changed external data into a sigma instance after the initial render.
+*
+* `input` must be a plain object with stable keys. Its values are shallow-compared with
+* `Object.is(...)`, and `sync(...)` runs only after at least one value changes.
+*
+* A changed `instance` resets the baseline input, so newly created component-owned sigma
+* instances can receive their initial external data through construction or setup before
+* later renders synchronize changes through this hook.
+*/
+function useSigmaSync(instance, input, sync) {
+	if (!isPlainObject(input)) throw new Error("[preact-sigma] useSigmaSync() input must be a plain object.");
+	const previousInput = useRef(void 0);
+	const previousKeys = useRef(void 0);
+	const previousInstance = useRef(void 0);
+	useEffect(() => {
+		const nextKeys = Object.keys(input);
+		if (previousInstance.current !== instance) {
+			previousInstance.current = instance;
+			previousInput.current = input;
+			previousKeys.current = nextKeys;
+			return;
+		}
+		assertStableKeys(previousKeys.current, nextKeys);
+		if (hasChanged(previousInput.current, input, nextKeys)) {
+			previousInput.current = input;
+			sync(input);
+		}
+	});
+}
+//#endregion
+export { Sigma, SigmaTarget, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSigma, useSigmaSync };

package/dist/persist.d.mts

@@ -1,13 +1,7 @@
-import { f as Immutable, n as Sigma, t as Protected } from "./sigma-Dki3T7re.mjs";
+import { n as ReadableSigma, p as Immutable, r as Sigma } from "./sigma-BfaJUPWw.mjs";
 
 //#region src/persist.d.ts
 type MaybePromise<T> = T | Promise<T>;
-/**
- * Sigma instance or protected consumer view accepted by persistence helpers.
- *
- * Restore and hydrate helpers may replace committed state through this trusted owner boundary.
- */
-type PersistInstance<TState extends object> = Sigma<TState> | Protected<Sigma<TState>>;
 /** Decode-time context passed to persistence codecs. */
 interface PersistDecodeContext<TState extends object> {
   /** Storage key used to read the record being decoded. */
@@ -114,19 +108,19 @@ interface SyncHydrationHandle extends PersistenceHandle {
   readonly restored: RestoreResult;
 }
 /** Restores committed state from a persisted record through an async store. */
-declare function restore<TState extends object, TKey extends keyof TState>(instance: PersistInstance<TState>, options: PickPersistOptions<TState, TKey>): Promise<RestoreResult>;
-declare function restore<TState extends object, TStored = Immutable<TState>>(instance: PersistInstance<TState>, options: PersistOptions<TState, TStored>): Promise<RestoreResult>;
+declare function restore<TState extends object, TKey extends keyof TState>(instance: ReadableSigma<TState>, options: PickPersistOptions<TState, TKey>): Promise<RestoreResult>;
+declare function restore<TState extends object, TStored = Immutable<TState>>(instance: ReadableSigma<TState>, options: PersistOptions<TState, TStored>): Promise<RestoreResult>;
 /** Restores committed state from a persisted record through a sync store. */
-declare function restoreSync<TState extends object, TKey extends keyof TState>(instance: PersistInstance<TState>, options: SyncPickPersistOptions<TState, TKey>): RestoreResult;
-declare function restoreSync<TState extends object, TStored = Immutable<TState>>(instance: PersistInstance<TState>, options: SyncPersistOptions<TState, TStored>): RestoreResult;
+declare function restoreSync<TState extends object, TKey extends keyof TState>(instance: ReadableSigma<TState>, options: SyncPickPersistOptions<TState, TKey>): RestoreResult;
+declare function restoreSync<TState extends object, TStored = Immutable<TState>>(instance: ReadableSigma<TState>, options: SyncPersistOptions<TState, TStored>): RestoreResult;
 /** Persists future committed state changes for one sigma instance. */
-declare function persist<TState extends object, TKey extends keyof TState>(instance: PersistInstance<TState>, options: PickPersistOptions<TState, TKey>): PersistenceHandle;
-declare function persist<TState extends object, TStored = Immutable<TState>>(instance: PersistInstance<TState>, options: PersistOptions<TState, TStored>): PersistenceHandle;
+declare function persist<TState extends object, TKey extends keyof TState>(instance: ReadableSigma<TState>, options: PickPersistOptions<TState, TKey>): PersistenceHandle;
+declare function persist<TState extends object, TStored = Immutable<TState>>(instance: ReadableSigma<TState>, options: PersistOptions<TState, TStored>): PersistenceHandle;
 /** Restores state, then begins persisting future committed changes. */
-declare function hydrate<TState extends object, TKey extends keyof TState>(instance: PersistInstance<TState>, options: PickPersistOptions<TState, TKey>): HydrationHandle;
-declare function hydrate<TState extends object, TStored = Immutable<TState>>(instance: PersistInstance<TState>, options: PersistOptions<TState, TStored>): HydrationHandle;
+declare function hydrate<TState extends object, TKey extends keyof TState>(instance: ReadableSigma<TState>, options: PickPersistOptions<TState, TKey>): HydrationHandle;
+declare function hydrate<TState extends object, TStored = Immutable<TState>>(instance: ReadableSigma<TState>, options: PersistOptions<TState, TStored>): HydrationHandle;
 /** Restores state synchronously, then begins persisting future committed changes. */
-declare function hydrateSync<TState extends object, TKey extends keyof TState>(instance: PersistInstance<TState>, options: SyncPickPersistOptions<TState, TKey>): SyncHydrationHandle;
-declare function hydrateSync<TState extends object, TStored = Immutable<TState>>(instance: PersistInstance<TState>, options: SyncPersistOptions<TState, TStored>): SyncHydrationHandle;
+declare function hydrateSync<TState extends object, TKey extends keyof TState>(instance: ReadableSigma<TState>, options: SyncPickPersistOptions<TState, TKey>): SyncHydrationHandle;
+declare function hydrateSync<TState extends object, TStored = Immutable<TState>>(instance: ReadableSigma<TState>, options: SyncPersistOptions<TState, TStored>): SyncHydrationHandle;
 //#endregion
 export { HydrationHandle, PersistCodec, PersistDecodeContext, PersistErrorContext, PersistOptions, PersistRecord, PersistSchedule, PersistStore, PersistenceHandle, PickPersistOptions, RestoreResult, SyncHydrationHandle, SyncPersistOptions, SyncPersistStore, SyncPickPersistOptions, hydrate, hydrateSync, persist, restore, restoreSync };

package/dist/persist.mjs

@@ -1,4 +1,4 @@
-import { o as sigma, s as isPlainObject } from "./sigma-Oviv0rzP.mjs";
+import { o as sigma, s as isPlainObject } from "./sigma-DEKK3bHd.mjs";
 //#region src/persist.ts
 function createIdentityCodec() {
 	return {

package/dist/{sigma-Dki3T7re.d.mts → sigma-BfaJUPWw.d.mts}

@@ -75,6 +75,7 @@ declare function setAutoFreeze(autoFreeze: boolean): void;
 type SigmaRef<T extends object = {}> = T & {
   [refSymbol]?: true;
 };
+type ReadableSigma<TState extends object> = Sigma<TState> | Protected<Sigma<TState>>;
 /** Definition shape used by helper types that need both state and event maps. */
 type SigmaDefinition = {
   state: object;
@@ -150,7 +151,7 @@ declare const sigma: Readonly<{
     <TState extends object, TKey extends Extract<keyof TState, string>>(instance: Sigma<TState>, key: TKey, listener: (value: Immutable<TState[TKey]>) => void): Cleanup;
   }; /** Returns the readonly signal backing one top-level state key. */
   getSignal<TState extends object, TKey extends Extract<keyof TState, string>>(instance: Sigma<TState>, key: TKey): ReadonlySignal<Immutable<TState[TKey]>>; /** Captures the current committed top-level state snapshot. */
-  captureState<TState extends object>(instance: Sigma<TState>): Immutable<TState>; /** Publishes a plain-object snapshot, including readonly captured snapshots, as committed state. */
+  captureState<TState extends object>(instance: ReadableSigma<TState>): Immutable<TState>; /** Publishes a plain-object snapshot, including readonly captured snapshots, as committed state. */
   replaceState<TState extends object>(target: Sigma<TState>, nextState: TState | Immutable<TState>): void;
 }>;
 /**
@@ -171,4 +172,4 @@ type Protected<T extends Sigma<any>> = BrandProtected<T extends {
   };
 } ? { readonly [K in keyof T as K extends ProtectedKey ? never : K]: K extends typeof typeSymbol ? T[K] : K extends keyof TState ? Immutable<T[K]> : T[K] extends AnyFunction ? (...params: Parameters<T[K]>) => Immutable<ReturnType<T[K]>> : Immutable<T[K]> } : never>;
 //#endregion
-export { SigmaState as a, query as c, Draft as d, Immutable as f, SigmaRef as i, setAutoFreeze as l, Cleanup as m, Sigma as n, SigmaTarget as o, typeSymbol as p, SigmaDefinition as r, castProtected as s, Protected as t, sigma as u };
+export { SigmaRef as a, castProtected as c, sigma as d, Draft as f, Cleanup as h, SigmaDefinition as i, query as l, typeSymbol as m, ReadableSigma as n, SigmaState as o, Immutable as p, Sigma as r, SigmaTarget as s, Protected as t, setAutoFreeze as u };

package/dist/{sigma-Oviv0rzP.mjs → sigma-DEKK3bHd.mjs}

@@ -114,9 +114,11 @@ function getStateSignal(instance, key) {
 	return instance[key + signalSuffix];
 }
 function createSnapshot(instance) {
-	if (instance[snapshotSymbol]) return instance[snapshotSymbol];
+	const source = instance;
+	if (source[snapshotSymbol]) return source[snapshotSymbol];
 	const state = {};
-	for (const key in instance) if (isStateKey(instance, key)) state[key] = getStateSignal(instance, key).value;
+	for (const key in source) if (isStateKey(source, key)) state[key] = getStateSignal(source, key).value;
+	source[snapshotSymbol] = state;
 	return state;
 }
 function createDraft(instance) {

package/docs/context.md

@@ -55,6 +55,7 @@
 - Read one top-level state property as a `ReadonlySignal`: `sigma.getSignal(instance, key)`.
 - Own timers, listeners, subscriptions, or nested setup: `onSetup(...)` plus `setup(...)`.
 - Use a sigma instance inside a component: `useSigma(...)`.
+- Synchronize changed component data into a sigma instance after the initial render: `useSigmaSync(instance, input, sync)`.
 - Cast an instance to its readonly consumer view outside a component: `castProtected(instance)`.
 - Subscribe to sigma or DOM events in a component: `useListener(...)`.
 - Subscribe outside components: `listen(instance, ...)`.
@@ -72,6 +73,7 @@
 - Emit directly from standalone `SigmaTarget` instances. In subclasses, emit from actions that have no unpublished draft changes. After mutating state, publish first with `this.commit(); this.emit(...)`.
 - Prefer `listen(...)` for external event subscriptions. It works with sigma targets and DOM targets.
 - Put owned side effects in `onSetup(...)`.
+- Use `useSigmaSync(...)` when a component-owned sigma instance is initialized from external props or hook data and needs to receive later changes through an action. Pass a plain object with stable keys; values are compared with `Object.is(...)`, and a recreated instance treats the current input as its new baseline.
 - Use `sigma.subscribe(this, ...)` inside `onSetup(...)` when a setup-owned side effect should react to future committed publishes. Return that cleanup so the subscription stops with setup.
   ```ts
   onSetup() {
@@ -115,6 +117,7 @@
 - Calling `emit(...)` outside an action on a subclass, or before committing the active draft, throws.
 - Calling an action from a computed or query throws.
 - Returning an active draft from an action throws.
+- `useSigmaSync(...)` throws when its input is not a plain object or when the input keys change between renders for the same instance.
 - `sigma.replaceState(...)` throws when the replacement value is not a plain object or when an action still owns unpublished changes.
 - Starting an action on another sigma instance while the current instance has an active action context throws.
 

package/examples/external-query-sync.tsx

@@ -0,0 +1,51 @@
+import type { FunctionComponent } from "preact";
+
+import { Sigma, useSigma, useSigmaSync } from "preact-sigma";
+
+type SearchResult = {
+  id: string;
+  title: string;
+};
+
+type SearchResultsState = {
+  query: string;
+  results: readonly SearchResult[];
+};
+
+class SearchResults extends Sigma<SearchResultsState> {
+  constructor(query: string, results: readonly SearchResult[]) {
+    super({
+      query,
+      results,
+    });
+  }
+
+  syncExternalQuery(query: string, results: readonly SearchResult[]) {
+    this.query = query;
+    this.results = results;
+  }
+}
+
+interface SearchResults extends SearchResultsState {}
+
+export const ExternalQuerySyncExample: FunctionComponent<{
+  query: string;
+  results: readonly SearchResult[];
+}> = ({ query, results }) => {
+  const search = useSigma(() => new SearchResults(query, results));
+
+  useSigmaSync(search, { query, results }, ({ query, results }) => {
+    search.syncExternalQuery(query, results);
+  });
+
+  return (
+    <section>
+      <h2>Results for {search.query || "everything"}</h2>
+      <ul>
+        {search.results.map((result) => (
+          <li key={result.id}>{result.title}</li>
+        ))}
+      </ul>
+    </section>
+  );
+};

package/package.json

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