@yoltra/core 0.3.0 → 0.4.0

package/README.es.md

@@ -1,4 +1,4 @@
-![yoltra logo](../../assets/yoltra-logo.png)
+![Yoltra logo](https://yoltra.dev/assets/yoltra-logo.png)
 
 # @yoltra/core
 

package/README.md

@@ -1,4 +1,4 @@
-![yoltra logo](../../assets/yoltra-logo.png)
+![Yoltra logo](https://yoltra.dev/assets/yoltra-logo.png)
 
 # @yoltra/core
 
@@ -426,14 +426,119 @@ store.registerEffect({
 
 ---
 
+## Saving and restoring state
+
+Two functions, because the halves happen on opposite sides of the store's existence.
+`hydrate` produces *initial slice state*, so the store is born with it:
+
+```ts
+import { createStore, createWebStorageAdapter, hydrate, persist, withHydration } from '@yoltra/core';
+
+const adapter = createWebStorageAdapter(localStorage);
+const hydration = await hydrate({ key: 'app', adapter, version: 3 });
+
+const store = createStore({
+  name: 'App',
+  reducer: withHydration({ todos: todosSpec, ui: uiSpec }, hydration),
+});
+
+const stop = persist(store, { key: 'app', adapter, version: 3, slices: ['todos'] });
+```
+
+Restoring *after* construction is the obvious alternative and the wrong one: applying a
+snapshot to a live store emits a change across every path, which on boot is a flash, a burst
+of instrumentation entries describing changes nobody made, and effects observing a transition
+that never happened.
+
+**Nothing throws on boot.** A missing, unparseable or unmigratable payload falls back to your
+declared defaults and reports through `onError`. A store that will not start because storage
+holds stale JSON is worse than one that starts fresh — and a full disk should not take down a
+page, so write failures are reported the same way rather than raised.
+
+**Version mismatches are refused, not trusted.** Reducers change, and a snapshot written
+against an older shape may not be valid state for this build at all. Supply `migrate` to
+upgrade it, or it is discarded.
+
+Writes are driven by instrumentation, so a change confined to a slice you are not persisting
+costs nothing, and a burst is coalesced into one write. `Map`, `Set`, `Date`, `BigInt`,
+`undefined` and circular references all survive the round trip: `JSON.stringify` does not fail
+on those, it silently destroys them.
+
+For a server render, `dehydrate(store, { version })` produces the payload and
+`hydrate({ source, version })` consumes it.
+
+## Lists that reorder
+
+Path notification is positional for arrays. `items.0.title` names a *slot*, not a thing, so
+`unshift`, `splice(0, 1)` and `sort` move nearly every element into a different slot — and the
+diff correctly reports that nearly every leaf changed. Inserting one row at the front of a
+thousand wakes a thousand subscribers.
+
+That is honest rather than noisy: with positional paths the value at almost every index really
+did change. The remedy is the shape of the state, not a diff that stays quiet.
+
+```ts
+import { createEntityAdapter } from '@yoltra/core';
+
+const todos = createEntityAdapter<Todo>();
+
+// state is { ids: [...], entities: { abc: {...} } }
+todos.updateOne(state, { id: 'abc', changes: { done: true } });
+
+// and the adapter hands out the paths, so they are never typed by hand
+todos.pathTo('abc', 'title');  // "entities.abc.title"
+todos.idsPath;                 // "ids"
+```
+
+`entities.abc.title` survives insert, remove and reorder. A list container subscribes to `ids`
+and reorders its children; rows subscribe to their own entity and stay asleep through a sort.
+
+`ids` is still an array, so a reorder still reports `ids.0`, `ids.1` and so on — that cost is
+confined, not removed. What you get is cost proportional to what actually changed.
+
+For a small list that only ever grows at the end, `items.0.title` is fine and simpler. The
+adapter is for collections that reorder, or that are large enough for the difference to show.
+
+### What it costs, measured
+
+At 1000 rows, diffing after an insert at the front costs 1200 µs for an array and 371 µs
+normalised, and the array reports roughly a thousand changed paths against two. That is the
+case the adapter is for.
+
+A single-field update runs the other way: 20 µs for the array against 470 µs normalised.
+`detectChangedProps` indexes an array but enumerates an object's keys — building two key
+arrays and a `Set` per comparison — so a wide entity map is more expensive to walk even when
+almost nothing in it moved. The numbers are in `benchmarks/`, and closing that gap is tracked
+work rather than a property of normalising as such.
+
+So: normalise collections that reorder or churn. A large collection that only ever has
+individual fields edited is better off as an array today.
+
 ## Performance
 
-| Metric             | Value                          |
-| ------------------ | ------------------------------ |
-| **Bundle size**    | ~8KB (minified + gzipped)      |
-| **Tree-shakeable** | Yes (ES modules)               |
-| **Dependencies**   | Zero                           |
-| **TypeScript**     | Full type definitions included |
+| Metric             | Value                                     |
+| ------------------ | ----------------------------------------- |
+| **Bundle size**    | 6.7 KB for the store (minified + gzipped) |
+| **Tree-shakeable** | Yes (ES modules)                          |
+| **Dependencies**   | Zero                                      |
+| **TypeScript**     | Full type definitions included            |
+
+Bundle size is checked, not asserted: `rush size` bundles the package the way a consumer
+would — tree-shaken, minified, gzipped — and fails when it exceeds the budget declared in
+`package.json`.
+
+The number that matters is what you import, not what the package exports:
+
+| Import                              | Size   |
+| ----------------------------------- | ------ |
+| `{ createStore }`                   | 6.7 KB |
+| `{ createStore, hydrate, persist }` | 8.2 KB |
+| everything                          | 9.5 KB |
+
+Persistence and the entity adapter cost nothing to anyone who does not import them — the
+first row has not moved as either was added, which is the tree-shaking claim being checked
+rather than repeated. The last row is a growth tripwire; `import * as all` is not something
+anybody writes.
 
 ---
 

package/dist/types/entity/entityAdapter.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Normalised collections, so a list stops paying O(N) for an O(1) change.
+ *
+ * @remarks
+ * Path notification is positional for arrays. `detectChangedProps` walks indices and reports
+ * `items.0.title`, which names a *slot*, not a thing. So `unshift`, `splice(0, 1)` and `sort`
+ * move nearly every element into a different slot, and the diff correctly reports that nearly
+ * every leaf changed. Inserting one row at the front of a thousand wakes a thousand
+ * subscribers.
+ *
+ * The remedy is the state shape, not a quieter diff. A key-stable array diff would need an
+ * identity key the diff has no business knowing, and even then the *paths* would still be
+ * positional — `items.0.title` names position zero, and so does the RFC-6902 pointer the
+ * devtools agents build from it.
+ *
+ * Normalising to `{ ids, entities }` makes `entities.abc.title` stable across insert, remove
+ * and reorder.
+ *
+ * **What this does not do:** `ids` is still an array, so a reorder still reports `ids.0`,
+ * `ids.1` and so on. That cost is confined rather than removed. A list container subscribes to
+ * `ids` and reorders its children; rows subscribe to `entities.<id>.<field>` and stay asleep.
+ * The promise is cost proportional to what actually changed.
+ *
+ * @module @yoltra/core
+ */
+/** What an entity may be keyed by. */
+export type EntityId = string | number;
+/**
+ * A normalised collection.
+ *
+ * @typeParam T - The entity.
+ * @typeParam Id - Its key type.
+ *
+ * @public
+ */
+export interface EntityState<T, Id extends EntityId = string> {
+    /** Order. Reordering touches this and nothing under `entities`. */
+    readonly ids: readonly Id[];
+    /** Identity-keyed, so a path to one entity survives every change to the others. */
+    readonly entities: Readonly<Record<Id, T>>;
+}
+/** A change to apply to one entity. */
+export interface EntityUpdate<T, Id extends EntityId> {
+    readonly id: Id;
+    readonly changes: Partial<T>;
+}
+/** How an adapter identifies and orders its entities. */
+export interface EntityAdapterOptions<T, Id extends EntityId> {
+    /** Defaults to reading `id`. */
+    readonly selectId?: (entity: T) => Id;
+    /**
+     * Keeps `ids` sorted.
+     *
+     * @remarks
+     * Omit it and `ids` holds insertion order, which is cheaper: with a comparer, any change
+     * that could affect position re-sorts. The sorted array is only adopted when it actually
+     * differs, so a sort that changes nothing reports nothing.
+     */
+    readonly sortComparer?: (a: T, b: T) => number;
+}
+/**
+ * Reducer helpers, selectors, and the subscription paths that make the shape worth having.
+ *
+ * @public
+ */
+export interface EntityAdapter<T, Id extends EntityId = string> {
+    getInitialState(): EntityState<T, Id>;
+    getInitialState<Extra extends object>(extra: Extra): EntityState<T, Id> & Extra;
+    /** Adds an entity. Existing ids are left alone — this is not an upsert. */
+    addOne<S extends EntityState<T, Id>>(state: S, entity: T): S;
+    addMany<S extends EntityState<T, Id>>(state: S, entities: readonly T[]): S;
+    /** Adds or replaces one entity wholesale. */
+    setOne<S extends EntityState<T, Id>>(state: S, entity: T): S;
+    setMany<S extends EntityState<T, Id>>(state: S, entities: readonly T[]): S;
+    /** Replaces the whole collection. */
+    setAll<S extends EntityState<T, Id>>(state: S, entities: readonly T[]): S;
+    /** Merges `changes` into one entity. Unknown ids are ignored. */
+    updateOne<S extends EntityState<T, Id>>(state: S, update: EntityUpdate<T, Id>): S;
+    updateMany<S extends EntityState<T, Id>>(state: S, updates: readonly EntityUpdate<T, Id>[]): S;
+    /** Adds, or merges into an existing entity. */
+    upsertOne<S extends EntityState<T, Id>>(state: S, entity: T): S;
+    upsertMany<S extends EntityState<T, Id>>(state: S, entities: readonly T[]): S;
+    removeOne<S extends EntityState<T, Id>>(state: S, id: Id): S;
+    removeMany<S extends EntityState<T, Id>>(state: S, ids: readonly Id[]): S;
+    removeAll<S extends EntityState<T, Id>>(state: S): S;
+    selectIds(state: EntityState<T, Id>): readonly Id[];
+    selectEntities(state: EntityState<T, Id>): Readonly<Record<Id, T>>;
+    selectAll(state: EntityState<T, Id>): readonly T[];
+    selectById(state: EntityState<T, Id>, id: Id): T | undefined;
+    selectTotal(state: EntityState<T, Id>): number;
+    /** Path to the order array. Subscribe here for a list that reorders. */
+    readonly idsPath: string;
+    /** Path to one entity, or to a field of it. */
+    pathTo(id: Id, field?: string): string;
+    /** Wildcard across every entity's `field`, for the loose subscription registry. */
+    anyField(field: string): string;
+}
+/**
+ * Builds an adapter for one entity type.
+ *
+ * @example
+ * ```ts
+ * const todos = createEntityAdapter<Todo>();
+ *
+ * const spec: ReducerSpec<EntityState<Todo>, EM> = {
+ *   state: todos.getInitialState(),
+ *   when: { keys: eventKeys<EM>()([['todos', 'toggled']]) },
+ *   reducer: (state, event) =>
+ *     todos.updateOne(state, { id: event.payload.id, changes: { done: event.payload.done } }),
+ * };
+ *
+ * // and in a component
+ * useAtomicProp({ reducer: 'todos', property: todos.pathTo(id, 'title') });
+ * ```
+ *
+ * @public
+ */
+export declare function createEntityAdapter<T, Id extends EntityId = string>(options?: EntityAdapterOptions<T, Id>): EntityAdapter<T, Id>;

package/dist/types/eventBus/EventBus.d.ts

@@ -1,4 +1,4 @@
-import { EventMapBase } from '../types';
+import { Event, EventMapBase } from '../types';
 /**
  * Minimal, synchronous pub/sub event bus keyed by **channel** and **type**.
  *
@@ -53,7 +53,10 @@ export declare class EventBus<EM extends EventMapBase> {
      * @typeParam T - Type key within channel `C` (must be a string key of `EM[C]`).
      * @param channel - Channel name to subscribe to.
      * @param type - Event type within the channel.
-     * @param handler - Function invoked with the payload type `EM[C][T]`.
+     * @param handler - Function invoked with the payload type `EM[C][T]`. It optionally
+     * receives the **source event** as a second argument when the emitter supplies one, so
+     * subscribers can read the true `id` (and any `meta`) instead of reconstructing an event
+     * from the payload alone. Handlers that declare only `payload` remain valid.
      * @returns An **unsubscribe** function that removes this handler.
      *
      * @example
@@ -66,9 +69,16 @@ export declare class EventBus<EM extends EventMapBase> {
      * off();
      * ```
      *
+     * @example Reading the source event
+     * ```ts
+     * bus.on('data', 'loaded', (payload, event) => {
+     *   console.log('event id:', event?.id);
+     * });
+     * ```
+     *
      * @public
      */
-    on<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, handler: (payload: EM[C][T]) => void): () => void;
+    on<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, handler: (payload: EM[C][T], event?: Event<EM, C, T>) => void): () => void;
     /**
      * Removes a specific handler previously added with {@link EventBus.on | `on`}.
      *
@@ -89,7 +99,7 @@ export declare class EventBus<EM extends EventMapBase> {
      *
      * @public
      */
-    off<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, handler: (payload: EM[C][T]) => void): void;
+    off<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, handler: (payload: EM[C][T], event?: Event<EM, C, T>) => void): void;
     /**
      * Emits an event to all subscribers of the exact `(channel, type)`.
      *
@@ -101,6 +111,9 @@ export declare class EventBus<EM extends EventMapBase> {
      * @param channel - Channel name to emit on.
      * @param type - Event type to emit.
      * @param payload - Payload matching `EM[C][T]`.
+     * @param event - Optional **source event**, forwarded to handlers as a second argument.
+     * Supply it whenever the caller already holds the real event so subscribers observe its
+     * true `id` rather than reconstructing one; omitting it keeps the original behaviour.
      *
      * @example
      * ```ts
@@ -109,7 +122,7 @@ export declare class EventBus<EM extends EventMapBase> {
      *
      * @public
      */
-    emit<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, payload: EM[C][T]): void;
+    emit<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, payload: EM[C][T], event?: Event<EM, C, T>): void;
     /**
      * Clears **all** listeners across all channels/types.
      *

package/dist/types/eventBus/LooseEventBus.d.ts

@@ -1,45 +1,6 @@
 /**
  * @module @yoltra/core
  */
-/**
- * Flexible, synchronous pub/sub bus that supports **exact** and **pattern** event subscriptions.
- *
- * @typeParam C - Channel name type (defaults to `string`).
- * @typeParam T - Event type name type (defaults to `string`). Types are treated as **dot-separated paths** (e.g. `"a.b.c"`).
- * @typeParam P - Payload type for all events (defaults to `any`).
- *
- * @remarks
- * - **Exact handlers** subscribe to a specific `(channel, type)` pair. Type keys are **normalized** by stripping a single leading dot (`".foo"` → `"foo"`).
- * - **Pattern handlers** subscribe using wildcards over dot-separated segments:
- *   - `*`   matches **one** segment.
- *   - `**`  matches **zero or more** segments (greedy).
- * - On {@link LooseEventBus.emit | `emit`}, exact handlers fire first, then any matching pattern handlers.
- * - Handlers are **de-duplicated**: if the same function is both exact and pattern-registered, it is called **once**.
- * - Handler invocation is **synchronous**. Exceptions are caught and logged; remaining handlers still run.
- *
- * @example
- * ```ts
- * type C = 'ui' | 'data';
- * type T = string;
- * type P = unknown;
- *
- * const bus = new LooseEventBus<C, T, P>();
- *
- * // Exact
- * const offA = bus.on('ui', 'panel.open', () => console.log('panel opened'));
- *
- * // Patterns
- * const offB = bus.on('ui', 'panel.*', () => console.log('any single sub-event under panel'));
- * const offC = bus.on('ui', 'panel.**', () => console.log('any depth under panel'));
- *
- * bus.emit('ui', 'panel.open', null);
- * // => exact fires, then 'panel.*', then 'panel.**'
- *
- * offA(); offB(); offC(); // unsubscribe
- * ```
- *
- * @public
- */
 export declare class LooseEventBus<C extends string = string, T extends string = string, P = any> {
     /**
      * Exact handlers: `channel → type → [handlers]`.
@@ -51,6 +12,24 @@ export declare class LooseEventBus<C extends string = string, T extends string =
      * @internal
      */
     private patternHandlers;
+    /**
+     * Patterns bucketed by their first segment, so an emit tests only what could match.
+     *
+     * @remarks
+     * Delivery used to walk every pattern registered on the channel and run the full segment
+     * matcher against each. That is linear in the number of patterns rather than in the number
+     * that match, and it re-split both the pattern and the subject on every test — for a thousand
+     * patterns, two thousand string splits to deliver one event.
+     *
+     * A subject's first segment can only be matched by a pattern whose first segment is that same
+     * literal, or is `*` or `**`. Bucketing on that turns the common shape — distinct event
+     * families like `panel.*` and `order.**` — from a scan of everything into a map lookup plus
+     * the handful that begin with a wildcard.
+     *
+     * It buys nothing for a channel where every pattern starts with `**`, since all of those must
+     * still be tested. That is the honest worst case, and it is unchanged rather than worsened.
+     */
+    private patternIndex;
     /**
      * Subscribes a handler to either an **exact** type or a **pattern**.
      *
@@ -142,6 +121,23 @@ export declare class LooseEventBus<C extends string = string, T extends string =
      * @public
      */
     emit(channel: C, type: T, payload: P): void;
+    /**
+     * Emits a payload that is only built if somebody is listening.
+     *
+     * @param channel - Channel to emit on.
+     * @param type - Concrete event type.
+     * @param make - Builds the payload. Called at most once, and only when a handler matched.
+     *
+     * @remarks
+     * Same matching as {@link LooseEventBus.emit}; the difference is *when* the payload exists.
+     * The store's change notification carries the old and new value at a path, and reading those
+     * means walking the state tree twice per path. Doing that eagerly meant a slice nobody had
+     * subscribed to paid the full cost of describing changes to an audience of nobody — the
+     * matching work was already being done to discover there were no handlers.
+     *
+     * @public
+     */
+    emitWith(channel: C, type: T, make: () => P): void;
     /**
      * Determines if a string is a **pattern** (contains `*`).
      * @param s - Event type or pattern string.
@@ -169,29 +165,56 @@ export declare class LooseEventBus<C extends string = string, T extends string =
      */
     private splitPath;
     /**
-     * Pattern matcher over dot-separated segments.
+     * Files a pattern under the first segment that could select it.
+     * @internal
+     */
+    private indexPattern;
+    /**
+     * Removes a pattern from the index. Paired with {@link LooseEventBus.offPattern}.
+     * @internal
+     */
+    private unindexPattern;
+    /**
+     * The handler lists of every pattern matching this subject.
+     *
+     * @remarks
+     * Shared by `emit` and `emitWith` so the two cannot drift on what "matching" means — which
+     * they could, being two copies of the same walk before.
+     *
+     * The subject is split once here rather than once per pattern tested.
+     *
+     * @internal
+     */
+    private matchingPatternHandlers;
+    /**
+     * Pattern matcher over dot-separated segments, which arrive already split.
      *
      * Rules:
      * - **literal**: exact match.
      * - `*`   : matches exactly **one** segment.
      * - `**`  : matches **zero or more** remaining segments (including empty).
      *
-     * @param pattern - Pattern (may include `*`/`**`).
-     * @param path - Subject event type key to test.
-     * @returns `true` if the pattern matches the path; otherwise `false`.
+     * @remarks
+     * Takes segments rather than strings so delivery can split each pattern once at registration
+     * and the subject once per emit, instead of both once per test. Re-splitting per test was most
+     * of what made wildcard delivery expensive: a thousand patterns meant two thousand string
+     * splits to deliver one event.
+     *
+     * @param pSegs - Pattern segments (may include `*`/`**`).
+     * @param sSegs - Subject segments to test.
+     * @returns `true` if the pattern matches; otherwise `false`.
      *
      * @example
      * ```ts
-     * matchPattern('a.*', 'a.b')        // true
-     * matchPattern('a.*', 'a.b.c')      // false
-     * matchPattern('a.**', 'a')         // true
-     * matchPattern('a.**', 'a.b.c')     // true
-     * matchPattern('**.end', 'x.y.end') // true
+     * matchSegments(['a', '*'], ['a', 'b'])           // true
+     * matchSegments(['a', '*'], ['a', 'b', 'c'])      // false
+     * matchSegments(['a', '**'], ['a'])               // true
+     * matchSegments(['**', 'end'], ['x', 'y', 'end']) // true
      * ```
      *
      * @internal
      */
-    private matchPattern;
+    private matchSegments;
     /**
      * Removes **all** listeners (exact and pattern). Useful for tests/HMR teardown.
      *

package/dist/types/index.d.ts

@@ -12,4 +12,12 @@ export { Store, createStore, typedEvents } from './store/Store';
 export { detectChangedProps } from './utils/detectChangedProps';
 export { freezeState } from './utils/immutability';
 export { eventKeys } from './types';
-export type { EventMapBase, EventKey, Event, EventUnion, Change, Emit, EmitOptions, InstrumentedEvent, InstrumentationObserver, Unsubscribe, StoreSpec, StoreInstance, ReducerSpec, ReducerFunction, ReducersMapAny, StateFromReducers, EMFromReducersStrict, EffectSpec, EffectFunction, MiddlewareFunction, MiddlewareSpec, MiddlewareInput, DeepReadonly, DeepRO, Primitive, Path, PathValue, WithGlob, Dotted, EventPhase, EventSubscriptionHandler, NarrowedEventHandler, When, EventFromWhen, EventConsumerType, EventConsumerMeta, } from './types';
+export type { EventMapBase, EventKey, Event, EventUnion, Change, Emit, EmitOptions, EventMeta, InstrumentedEvent, InstrumentationObserver, Unsubscribe, StoreSpec, StoreInstance, ReducerSpec, ReducerFunction, ReducersMapAny, StateFromReducers, EMFromReducersStrict, EffectSpec, EffectFunction, MiddlewareFunction, MiddlewareSpec, MiddlewareInput, DeepReadonly, DeepRO, Primitive, Path, PathValue, WithGlob, Dotted, EventPhase, EventSubscriptionHandler, NarrowedEventHandler, When, EventFromWhen, EventConsumerType, EventConsumerMeta, } from './types';
+export { createEntityAdapter } from './entity/entityAdapter';
+export type { EntityAdapter, EntityAdapterOptions, EntityId, EntityState, EntityUpdate, } from './entity/entityAdapter';
+export { decodeState, encodeState, encodeStateBounded } from './serialize/codec';
+export type { BoundedEncodeResult, EncodeOptions, EncodeReport, EncodeResult, } from './serialize/codec';
+export { dehydrate, hydrate, persist, withHydration } from './persistence/persist';
+export type { Hydration, PersistableStore, PersistenceAdapter, PersistencePhase, PersistOptions, } from './persistence/persist';
+export { createMemoryAdapter, createWebStorageAdapter } from './persistence/adapters';
+export type { WebStorageLike } from './persistence/adapters';

package/dist/types/persistence/adapters.d.ts

@@ -0,0 +1,33 @@
+import { PersistenceAdapter } from './persist';
+/** The slice of the Web Storage API used here. */
+export interface WebStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Wraps a Web Storage object.
+ *
+ * @remarks
+ * Pass `localStorage` or `sessionStorage` explicitly. Reading the global here would make this
+ * module unusable anywhere one does not exist, which includes a server render — exactly where
+ * hydration payloads are produced.
+ *
+ * @example
+ * ```ts
+ * const adapter = createWebStorageAdapter(localStorage);
+ * ```
+ *
+ * @public
+ */
+export declare function createWebStorageAdapter(storage: WebStorageLike): PersistenceAdapter;
+/**
+ * Keeps state in memory.
+ *
+ * @remarks
+ * For tests, and for a server render that wants the persistence path exercised without a
+ * store behind it. It forgets on restart, which is the whole of what it claims.
+ *
+ * @public
+ */
+export declare function createMemoryAdapter(initial?: Record<string, string>): PersistenceAdapter;

package/dist/types/persistence/persist.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Saving state, and starting from saved state.
+ *
+ * @remarks
+ * The two halves happen on opposite sides of the store's existence, which is why this is two
+ * functions rather than one. {@link hydrate} produces *initial slice state*, so the store is
+ * born hydrated; {@link persist} subscribes to a store that already exists.
+ *
+ * Restoring after construction is the obvious alternative and the wrong one. It means applying
+ * a whole-state snapshot to a live store, which emits a change across every path: a visible
+ * flash on boot, a burst of instrumentation entries describing changes nobody made, and
+ * effects observing a transition that never happened.
+ *
+ * @module @yoltra/core
+ */
+/** Where persisted state lives. Bring your own; core imports no platform global. */
+export interface PersistenceAdapter {
+    read(key: string): string | null | Promise<string | null>;
+    write(key: string, value: string): void | Promise<void>;
+    remove(key: string): void | Promise<void>;
+}
+/** Where a failure happened, so a handler can tell a bad write from a bad payload. */
+export type PersistencePhase = "read" | "write" | "decode" | "migrate";
+/** Shared configuration. */
+export interface PersistOptions {
+    /** Storage key. */
+    readonly key: string;
+    readonly adapter: PersistenceAdapter;
+    /**
+     * Schema version of what is written.
+     *
+     * @remarks
+     * Compared on read. A mismatch is handed to {@link PersistOptions.migrate}, and without one
+     * the stored value is discarded rather than trusted — reducers change, and a snapshot
+     * written against an older shape is not merely stale, it may not be valid state at all.
+     */
+    readonly version: number;
+    /** Slices to persist. Every slice by default. */
+    readonly slices?: readonly string[];
+    /** Coalescing window for writes, in milliseconds. Defaults to 250. */
+    readonly throttleMs?: number;
+    /**
+     * Upgrades a payload written by an older version.
+     *
+     * @returns The slices to restore, or `null` to start fresh.
+     */
+    readonly migrate?: (persisted: unknown, from: number) => Record<string, unknown> | null;
+    /**
+     * Called on any failure.
+     *
+     * @remarks
+     * Persistence never throws into the application it is persisting. A store that will not
+     * start because storage holds stale JSON is worse than one that starts fresh, and a full
+     * disk should not take down a page.
+     */
+    readonly onError?: (error: unknown, phase: PersistencePhase) => void;
+}
+/** What {@link hydrate} recovered. */
+export interface Hydration {
+    /** Slice states to start from. Empty when there was nothing usable to restore. */
+    readonly slices: Readonly<Record<string, unknown>>;
+    /** `true` when a payload was found, decoded and accepted. */
+    readonly restored: boolean;
+}
+/**
+ * Reads persisted state, ready to seed a store.
+ *
+ * @remarks
+ * Every read-side failure — missing, unparseable, wrong version with no migration, a
+ * migration that declines — resolves to "nothing to restore" and reports through
+ * {@link PersistOptions.onError}. Nothing throws.
+ *
+ * @example
+ * ```ts
+ * const hydration = await hydrate({ key: 'app', adapter, version: 3 });
+ * const store = createStore({
+ *   name: 'App',
+ *   reducer: withHydration({ todos: todosSpec }, hydration),
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function hydrate(options: PersistOptions & {
+    readonly source?: string;
+}): Promise<Hydration>;
+/** A reducer spec, as far as hydration cares: something carrying an initial `state`. */
+interface HasState {
+    state: unknown;
+}
+/**
+ * Replaces each reducer's initial state with what was restored for it.
+ *
+ * @remarks
+ * Slices absent from the payload keep their declared defaults, so adding a reducer does not
+ * invalidate everything written before it existed.
+ *
+ * @public
+ */
+export declare function withHydration<R extends Record<string, HasState>>(reducers: R, hydration: Hydration): R;
+/** The store surface persistence needs, which is two methods wide. */
+export interface PersistableStore {
+    getState(): unknown;
+    instrument(observer: (info: {
+        changedPaths?: readonly string[];
+    }) => void): () => void;
+}
+/**
+ * Writes state as it changes.
+ *
+ * @returns A function that stops persisting and flushes anything pending.
+ *
+ * @remarks
+ * Driven by `instrument` rather than the coarse subscription, so a change confined to a slice
+ * that is not persisted costs nothing at all. Writes are coalesced on the trailing edge.
+ *
+ * @public
+ */
+export declare function persist(store: PersistableStore, options: PersistOptions): () => void;
+/**
+ * Serializes a store for handoff, for example from a server render to the client.
+ *
+ * @public
+ */
+export declare function dehydrate(store: Pick<PersistableStore, "getState">, options: Pick<PersistOptions, "version" | "slices">): string;
+export {};