@yoltra/core 0.3.0 → 0.5.0

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

package/dist/types/reducer/Reducer.d.ts

@@ -1,4 +1,4 @@
-import { EventMapBase, EventUnion, ReducerFunction } from '../types';
+import { EventMapBase, EventUnion, ReducerFunction } from '../types.js';
 /**
  * Thin wrapper around a pure reducer function (stateful event consumer):
  * given a state `S` and an event (from {@link EventUnion | `EventUnion<EM>`}),

package/dist/types/serialize/codec.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Lossless encoding of store state for the wire.
+ *
+ * @remarks
+ * The wire is JSON, and `JSON.stringify` is not a safe way to put arbitrary state on it. It does
+ * not fail on the values it cannot represent — it quietly destroys them. A `Map` becomes `{}`, a
+ * `Set` becomes `{}`, a `Date` becomes a string, `undefined` disappears from objects entirely,
+ * and a `BigInt` or a cycle throws from inside a handler nobody awaits.
+ *
+ * Silent destruction is the dangerous half. The panel showed `{}` where a `Map` lived, which is
+ * merely wrong; but time-travel then sent that `{}` back and applied it to the running store,
+ * replacing a live `Map` with an empty object in the user's own application. A debugging tool
+ * corrupting the program it is inspecting is the worst failure available to it.
+ *
+ * Values are therefore tagged rather than coerced. Anything JSON can carry travels unchanged;
+ * anything it cannot is wrapped in a marker object that {@link decodeState} reverses exactly.
+ *
+ * @module
+ */
+/** Options for {@link encodeState}. */
+export interface EncodeOptions {
+    /**
+     * Redacts a value before it leaves the process.
+     *
+     * @remarks
+     * State frequently holds tokens, session material and personal data, and devtools traffic
+     * crosses a socket to another process. Return the replacement value, or the value itself to
+     * keep it. Applied before encoding, so a redacted value is encoded like any other.
+     */
+    readonly sanitize?: (path: string, value: unknown) => unknown;
+    /**
+     * Maximum number of nodes to encode. Beyond it, subtrees are replaced by a truncation marker.
+     *
+     * @remarks
+     * A snapshot larger than the hub's frame cap is rejected outright, which reads to the user as
+     * a panel that hangs. Truncating visibly is a better failure: the panel renders, and says
+     * where it stopped. Defaults to 100000.
+     */
+    readonly maxNodes?: number;
+}
+/** Reports what an encode had to compromise. Empty when nothing was lost. */
+export interface EncodeReport {
+    /** Node budget was exhausted and some subtrees were replaced by markers. */
+    readonly truncated: boolean;
+    /** Values no JSON representation exists for, by path — functions, symbols, DOM nodes. */
+    readonly unsupported: readonly string[];
+}
+/** Result of {@link encodeState}. */
+export interface EncodeResult {
+    readonly value: unknown;
+    readonly report: EncodeReport;
+}
+/**
+ * Encodes a value into something `JSON.stringify` can carry losslessly.
+ *
+ * @param input - Any value, including one holding `Map`, `Set`, `Date`, `BigInt` or cycles.
+ * @param options - Redaction and size limits.
+ * @returns The encoded value plus a report of anything that could not be represented.
+ *
+ * @example
+ * ```ts
+ * const { value } = encodeState({ index: new Map([['a', 1]]) });
+ * JSON.stringify(value); // safe, and decodeState restores the Map
+ * ```
+ *
+ * @public
+ */
+export declare function encodeState(input: unknown, options?: EncodeOptions): EncodeResult;
+/**
+ * Reverses {@link encodeState}.
+ *
+ * @param input - A value produced by `encodeState` (typically after a JSON round trip).
+ * @returns The original structure, with `Map`, `Set`, `Date` and friends restored.
+ *
+ * @remarks
+ * Unsupported markers decode to `undefined`: a function cannot be reconstructed, and inventing a
+ * placeholder would be worse than an absent value. Cycles are restored by resolving references
+ * after the tree is built, so a decoded structure is cyclic exactly where the original was.
+ *
+ * @public
+ */
+export declare function decodeState(input: unknown): unknown;
+/** Outcome of {@link encodeStateBounded}. */
+export interface BoundedEncodeResult {
+    /** The encoded value, small enough to send. */
+    readonly value: unknown;
+    /** `true` when the state did not fit and parts were replaced by markers. */
+    readonly truncated: boolean;
+    /** Explains what was dropped, for display beside a partial tree. */
+    readonly note?: string;
+}
+/**
+ * Encodes a value, shrinking it until its serialized form fits within `maxBytes`.
+ *
+ * @param input - Any value.
+ * @param maxBytes - Byte budget for the serialized form.
+ * @param options - Passed through to {@link encodeState}.
+ *
+ * @returns The encoded value and whether anything had to be dropped.
+ *
+ * @remarks
+ * A frame larger than the hub's cap is not merely slow — it is rejected, and the connection with
+ * it, so the client reconnects, asks again, is refused again, and the panel sits waiting through
+ * a loop with nothing on screen to explain it. The size therefore has to be bounded before the
+ * frame is sent rather than discovered afterwards.
+ *
+ * Node count is a poor proxy for bytes: a hundred nodes holding base64 blobs outweigh a hundred
+ * thousand holding integers. So this measures the encoded output and, when it is too large,
+ * scales the node budget by how far over it went and measures again. Scaling by the overshoot
+ * rather than halving matters: from a default of a hundred thousand nodes, repeated halving
+ * needs a dozen rounds to reach the hundreds, so a state that could have been shown in part
+ * would have been abandoned instead.
+ *
+ * Truncation is reported rather than performed silently. A partial tree presented as the state is
+ * worse than no tree at all: a debugger that quietly lies about state is not a debugger.
+ *
+ * @public
+ */
+export declare function encodeStateBounded(input: unknown, maxBytes: number, options?: EncodeOptions): BoundedEncodeResult;

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

@@ -1,4 +1,4 @@
-import { Event, EventMapBase, EventKey, EventUnion, Change, DeepReadonly, EffectSpec, MiddlewareFunction, ReducersMapAny, ReducerSpec, StateFromReducers, StoreInstance, StoreSpec, Unsubscribe, EMFromReducersStrict, Emit, EmitOptions, InstrumentationObserver, EventPhase, NarrowedEventHandler, When } from '../types';
+import { Event, EventMapBase, EventKey, EventUnion, Change, DeepReadonly, EffectSpec, EventMeta, MiddlewareInput, ReducersMapAny, ReducerSpec, StateFromReducers, StoreInstance, StoreSpec, Unsubscribe, EMFromReducersStrict, Emit, EmitOptions, InstrumentationObserver, EventPhase, NarrowedEventHandler, When } from '../types.js';
 export declare class Store<EM extends EventMapBase, R extends string, S extends Record<R, any>> implements StoreInstance<R, S, EM> {
     /**
      * Store name (used by DevTools & diagnostics).
@@ -47,7 +47,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
     private readonly listeners;
     /**
      * Registered effect handlers keyed by `"channel::type"` for O(1) lookup.
-     * Used for effects with explicit `keys` or legacy `events` targeting.
+     * Used for effects with explicit `keys` targeting.
      *
      * @internal
      */
@@ -102,12 +102,33 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * @internal
      */
     private readonly replayEnabled;
+    /**
+     * Produces the `id` for each emitted event. Defaults to `crypto.randomUUID()`; overridable
+     * via {@link StoreSpec.idFactory} for runtimes lacking it or for deterministic tests.
+     *
+     * @internal
+     */
+    private readonly idFactory;
     /**
      * Optional hook invoked when an effect throws/rejects. See
      * {@link StoreSpec.onEffectError}. `await emit()` never rejects on effect
      * failure — this is how callers observe effect errors.
      */
     private readonly onEffectError?;
+    /**
+     * Optional hook invoked when a reducer throws. See {@link StoreSpec.onReducerError}. The
+     * failing slice is isolated rather than the event being rolled back, so this is the only
+     * signal that a reducer misbehaved.
+     */
+    private readonly onReducerError?;
+    /**
+     * `slice:channel:type` combinations already warned about for payload aliasing.
+     *
+     * @remarks
+     * Development-only diagnostics have to stay quiet enough to be read. One warning names the
+     * pattern; repeating it once per event would bury it.
+     */
+    private readonly warnedPayloadAliases;
     /**
      * Pending events awaiting the **synchronous** reduce phase (middleware +
      * reducers + subscribers + coarse listeners). Drained by {@link drainReduce}.
@@ -317,6 +338,11 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * For each changed **leaf path** (via {@link detectChangedProps}), emits that leaf and
      * all of its **ancestors** once (e.g., `"data"`, `"data.123"`, `"data.123.title"`).
      *
+     * A slice whose state **is** a single value — a primitive, a `Map`/`Set`, a `Date` — has no
+     * leaf below its root, and `detectChangedProps` reports its change as the empty path `""`.
+     * That path is emitted as-is, so `connect({ reducer, property: "" })` (and any `**` pattern)
+     * hears it. It has no ancestors to walk.
+     *
      * **State Immutability**: When a slice changes, a new state object is created via
      * shallow spread: `{ ...this.state, [sliceName]: newSlice }`. This ensures that
      * `this.state` reference changes, enabling efficient change detection via `===`.
@@ -327,6 +353,30 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @internal
      */
+    /**
+     * Reduces one slice and contains any error it raises.
+     *
+     * @returns `true` when the slice changed.
+     *
+     * @remarks
+     * The single funnel both dispatch paths go through, which is the point. Keyed reducers run
+     * through `reducerBus`, whose handler loop caught and logged; pattern reducers were called
+     * straight from the drain, so their errors escaped to the caller instead. The same bug in the
+     * same reducer therefore produced two different outcomes depending on how the slice happened
+     * to be targeted — a keyed reducer's throw let the event commit and its effects run, while a
+     * pattern reducer's throw aborted the commit and notified nobody, not even the uncommitted
+     * subscribers a veto would have reached.
+     *
+     * The semantics are now the same either way: **the failing slice is isolated.** Its state is
+     * unchanged, every other slice still reduces, and the event still commits if anything else
+     * changed. Rolling the whole event back would be tidier in principle, but fine-grained
+     * subscribers are notified inside `forwardEvent` as each slice commits, so an event that
+     * reverted afterwards would have already told components about a value that no longer exists.
+     * Isolation keeps every notification truthful.
+     *
+     * @internal
+     */
+    private forwardEventGuarded;
     private forwardEvent;
     /**
      * Returns a structured introspection snapshot for DevTools UIs.
@@ -400,6 +450,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
         type: string;
         payload: any;
         id: string;
+        meta?: EventMeta;
     }>): void;
     /**
      * Emits a typed event `(channel, type, payload)`.
@@ -605,13 +656,21 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
     /**
      * Registers a middleware (runs **before** reducers).
      *
-     * @param mw - Middleware `(state, event, emit) => boolean|Promise<boolean>`.
-     *        Return `false` to cancel event propagation.
+     * @param mw - Middleware `(state, event, emit) => boolean`. Return `false` to cancel event
+     *        propagation.
      * @returns Unsubscribe function that removes this middleware.
      *
+     * @remarks
+     * **Synchronous, and that is the contract.** The reduce phase completes before `emit()`
+     * returns, so the commit decision has to be available in the same tick. An `async` middleware
+     * returns a Promise, every Promise is truthy, and the veto would therefore never fire — the
+     * event would commit while the middleware was still deciding. The type rejects it; this note
+     * exists because the examples here used to teach it. Do authorization and validation here, and
+     * anything that needs to await in an effect.
+     *
      * @example Logging middleware
      * ```ts
-     * const off = store.registerMiddleware(async (state, event) => {
+     * const off = store.registerMiddleware((state, event) => {
      *   console.log('Event:', event.channel, event.type, event.payload);
      *   return true; // allow
      * });
@@ -628,12 +687,12 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @public
      */
-    registerMiddleware(mw: MiddlewareFunction<DeepReadonly<S>, EM>): Unsubscribe;
+    registerMiddleware(mw: MiddlewareInput<DeepReadonly<S>, EM>): Unsubscribe;
     /**
      * Dynamically **adds** a named slice reducer at runtime.
      *
      * @param name - New slice name (must not already exist).
-     * @param spec - Reducer spec (state, events, reducer).
+     * @param spec - Reducer spec (state, when, reducer).
      * @returns Disposer function that **removes** the slice (and its state).
      *
      * @example
@@ -657,7 +716,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * Effects are **keyed** by `(channel, type)` for O(1) lookup (no scanning all effects).
      *
-     * @param spec - Effect specification with `events` (EventKeys) and `effect` (handler).
+     * @param spec - Effect specification with `when` targeting and `effect` (handler).
      * @returns Unsubscribe function.
      *
      * @example Logging effect
@@ -723,7 +782,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @public
      */
-    replaceMiddleware(next: MiddlewareFunction<DeepReadonly<S>, EM>[]): void;
+    replaceMiddleware(next: MiddlewareInput<DeepReadonly<S>, EM>[]): void;
     /**
      * Replaces all registered **effects** (HMR-friendly).
      *
@@ -780,7 +839,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      */
     hotReplace(partial: {
         reducer?: Record<R, ReducerSpec<S[R], EM>>;
-        middleware?: MiddlewareFunction<DeepReadonly<S>, EM>[];
+        middleware?: MiddlewareInput<DeepReadonly<S>, EM>[];
         effects?: Array<EffectSpec<DeepReadonly<S>, EM>>;
         preserveState?: boolean;
     }): void;
@@ -789,7 +848,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * and wires `(channel, type)` listeners on the reducer bus.
      *
      * @param name - Slice name.
-     * @param rSpec - Reducer spec (state, events, reducer).
+     * @param rSpec - Reducer spec (state, when, reducer).
      * @param opts - `{ preserveState: boolean }` whether to keep existing state.
      *
      * @internal
@@ -806,9 +865,9 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      */
     private unmountSlice;
     /**
-     * Normalizes event targeting from `when` or legacy `events` to an array of EventKeys.
+     * Normalizes event targeting from `when` to an array of EventKeys.
      *
-     * @param spec - Object with optional `when` and/or `events` properties.
+     * @param spec - Object with an optional `when` matcher.
      * @returns Array of `[channel, type]` pairs.
      *
      * @internal
@@ -887,13 +946,15 @@ export declare function createStore<S extends Record<string, any>, EM extends Ev
     reducer?: {
         [K in keyof S]?: ReducerSpec<S[K], EM>;
     };
-    middleware?: MiddlewareFunction<DeepReadonly<S>, EM>[];
+    middleware?: MiddlewareInput<DeepReadonly<S>, EM>[];
     effects?: Array<EffectSpec<DeepReadonly<S>, EM>>;
     dedupWindowMs?: number;
+    idFactory?: () => string;
     devtools?: {
         allowReplay?: boolean;
     };
     onEffectError?: (error: unknown, event: EventUnion<EM>) => void;
+    onReducerError?: (error: unknown, event: EventUnion<EM>, slice: string) => void;
 }): StoreInstance<keyof S & string, S, EM>;
 /**
  * Creates a store with types inferred from the reducers map.
@@ -926,13 +987,15 @@ export declare function createStore<S extends Record<string, any>, EM extends Ev
 export declare function createStore<RM extends ReducersMapAny>(cfg: {
     name: string;
     reducer: RM;
-    middleware?: MiddlewareFunction<DeepReadonly<StateFromReducers<RM>>, EMFromReducersStrict<RM>>[];
+    middleware?: MiddlewareInput<DeepReadonly<StateFromReducers<RM>>, EMFromReducersStrict<RM>>[];
     effects?: Array<EffectSpec<DeepReadonly<StateFromReducers<RM>>, EMFromReducersStrict<RM>>>;
     dedupWindowMs?: number;
+    idFactory?: () => string;
     devtools?: {
         allowReplay?: boolean;
     };
     onEffectError?: (error: unknown, event: EventUnion<EMFromReducersStrict<RM>>) => void;
+    onReducerError?: (error: unknown, event: EventUnion<EMFromReducersStrict<RM>>, slice: string) => void;
 }): StoreInstance<keyof RM & string, StateFromReducers<RM>, EMFromReducersStrict<RM>>;
 /**
  * Utility to define **typed** `(channel, events[])` definitions for reducer specs.