@flurryx/store 0.8.3 → 1.0.0

package/dist/index.d.ts

@@ -1,10 +1,197 @@
 import { Signal, InjectionToken } from '@angular/core';
-import { ResourceState, KeyedResourceKey } from '@flurryx/core';
+import { ResourceState, KeyedResourceData, KeyedResourceKey } from '@flurryx/core';
 
+/** Message produced by `store.update(key, partial)` — merges partial state into a slot. */
+type UpdateStoreMessage<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> = {
+    readonly [K in TKey]: {
+        readonly type: "update";
+        readonly key: K;
+        readonly state: Partial<TData[K]>;
+    };
+}[TKey];
+/** Message produced by `store.clear(key)` — resets a single slot to its initial state. */
+type ClearStoreMessage<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> = {
+    readonly [K in TKey]: {
+        readonly type: "clear";
+        readonly key: K;
+    };
+}[TKey];
+/** Message produced by `store.clearAll()` — resets every slot in the store. */
+interface ClearAllStoreMessage<TData extends StoreDataShape<TData>> {
+    readonly type: "clearAll";
+}
+/** Message produced by `store.startLoading(key)` — sets `isLoading: true` and clears `status`/`errors`. */
+type StartLoadingStoreMessage<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> = {
+    readonly [K in TKey]: {
+        readonly type: "startLoading";
+        readonly key: K;
+    };
+}[TKey];
+/** Message produced by `store.stopLoading(key)` — sets `isLoading: false`. */
+type StopLoadingStoreMessage<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> = {
+    readonly [K in TKey]: {
+        readonly type: "stopLoading";
+        readonly key: K;
+    };
+}[TKey];
+/** Message produced by `store.updateKeyedOne(key, resourceKey, entity)` — merges a single entity into a keyed slot. */
+type UpdateKeyedOneStoreMessage<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> = {
+    readonly [K in KeyedStoreKey<TData, TKey>]: {
+        readonly type: "updateKeyedOne";
+        readonly key: K;
+        readonly resourceKey: KeyedResourceEntryKey<TData, K>;
+        readonly entity: KeyedResourceEntryValue<TData, K>;
+    };
+}[KeyedStoreKey<TData, TKey>];
+/** Message produced by `store.clearKeyedOne(key, resourceKey)` — removes a single entity from a keyed slot. */
+type ClearKeyedOneStoreMessage<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> = {
+    readonly [K in KeyedStoreKey<TData, TKey>]: {
+        readonly type: "clearKeyedOne";
+        readonly key: K;
+        readonly resourceKey: KeyedResourceEntryKey<TData, K>;
+    };
+}[KeyedStoreKey<TData, TKey>];
+/** Message produced by `store.startKeyedLoading(key, resourceKey)` — marks a single entity as loading. */
+type StartKeyedLoadingStoreMessage<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> = {
+    readonly [K in KeyedStoreKey<TData, TKey>]: {
+        readonly type: "startKeyedLoading";
+        readonly key: K;
+        readonly resourceKey: KeyedResourceEntryKey<TData, K>;
+    };
+}[KeyedStoreKey<TData, TKey>];
+/** Discriminated union of all typed store messages published to the broker channel. */
+type StoreMessage<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> = UpdateStoreMessage<TData, TKey> | ClearStoreMessage<TData, TKey> | ClearAllStoreMessage<TData> | StartLoadingStoreMessage<TData, TKey> | StopLoadingStoreMessage<TData, TKey> | UpdateKeyedOneStoreMessage<TData, TKey> | ClearKeyedOneStoreMessage<TData, TKey> | StartKeyedLoadingStoreMessage<TData, TKey>;
+/** Full store state captured at a point in time, keyed by slot name. Used by history and time travel. */
+type StoreSnapshot<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> = Partial<{
+    readonly [K in TKey]: TData[K];
+}>;
+/** Delivery status of a broker message: `"pending"` → `"acknowledged"` or `"dead-letter"`. */
+type StoreMessageStatus = "pending" | "acknowledged" | "dead-letter";
+
+/**
+ * Persisted broker message record stored in the active message channel.
+ *
+ * Message ids are allocated when the message is first published and remain stable
+ * across acknowledgement, replay, and dead-letter transitions.
+ */
+interface StoreMessageRecord<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> {
+    /** Stable message id used by `replay(...)` and dead-letter recovery APIs. */
+    readonly id: number;
+    /** Published store message payload. */
+    readonly message: StoreMessage<TData, TKey>;
+    /** Latest delivery status stored by the broker channel. */
+    readonly status: StoreMessageStatus;
+    /** Number of delivery attempts made for this message. */
+    readonly attempts: number;
+    /** Timestamp when the message was first published to the channel. */
+    readonly createdAt: number;
+    /** Timestamp of the most recent delivery attempt. */
+    readonly lastAttemptedAt: number | null;
+    /** Timestamp of the most recent successful acknowledgement, if any. */
+    readonly acknowledgedAt: number | null;
+    /** Last recorded delivery error, or `null` when the latest attempt succeeded. */
+    readonly error: string | null;
+}
+/** Minimal string-based storage adapter used by storage-backed message channels. */
+interface StoreMessageChannelStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Pluggable persistence channel used by the broker to store published messages.
+ *
+ * The default channel is in-memory, but storage-backed or custom providers can be
+ * supplied to keep messages available across refreshes or offline sessions.
+ */
+interface StoreMessageChannel<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> {
+    /** Stores a newly published message and allocates its stable message id. */
+    publish(message: StoreMessage<TData, TKey>): StoreMessageRecord<TData, TKey>;
+    /** Reads a single persisted message record by id. */
+    getMessage(id: number): StoreMessageRecord<TData, TKey> | undefined;
+    /** Reads every persisted message record from the channel. */
+    getMessages(): readonly StoreMessageRecord<TData, TKey>[];
+    /** Persists a new state for an existing message record. */
+    saveMessage(entry: StoreMessageRecord<TData, TKey>): void;
+}
+/** Optional store configuration used to override the default in-memory message channel. */
+interface StoreMessageChannelOptions<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> {
+    readonly channel?: StoreMessageChannel<TData, TKey>;
+}
+/** Options for {@link createCompositeStoreMessageChannel}. The first channel is the primary (reads + id allocation); replicas receive all writes. */
+interface CompositeStoreMessageChannelOptions<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> {
+    readonly channels: readonly StoreMessageChannel<TData, TKey>[];
+}
+/** Options for {@link createStorageStoreMessageChannel}. Provide a custom storage adapter, key, and optional serialize/deserialize hooks. */
+interface StorageStoreMessageChannelOptions<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> {
+    readonly storage: StoreMessageChannelStorage;
+    readonly storageKey: string;
+    readonly serialize?: (state: PersistedStoreMessageChannelState<TData, TKey>) => string;
+    readonly deserialize?: (value: string) => PersistedStoreMessageChannelState<TData, TKey>;
+}
+/** Options for {@link createLocalStorageStoreMessageChannel} and {@link createSessionStorageStoreMessageChannel}. Storage defaults to the browser global. */
+interface BrowserStorageStoreMessageChannelOptions<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> extends Omit<StorageStoreMessageChannelOptions<TData, TKey>, "storage"> {
+    readonly storage?: StoreMessageChannelStorage;
+}
+interface PersistedStoreMessageChannelState<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> {
+    readonly nextId: number;
+    readonly messages: readonly StoreMessageRecord<TData, TKey>[];
+}
+/**
+ * Creates an in-memory message channel. Messages are stored in a JavaScript array
+ * and lost on page refresh. This is the default channel when no `channel` option is provided.
+ */
+declare function createInMemoryStoreMessageChannel<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>>(): StoreMessageChannel<TData, TKey>;
+/**
+ * Creates a message channel backed by a custom storage adapter.
+ * Messages are serialized and persisted via the provided `storage` object.
+ * When the storage quota is exceeded, the oldest messages are evicted automatically.
+ *
+ * @param options - Storage adapter, key, and optional serialize/deserialize hooks.
+ */
+declare function createStorageStoreMessageChannel<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>>(options: StorageStoreMessageChannelOptions<TData, TKey>): StoreMessageChannel<TData, TKey>;
+/**
+ * Creates a message channel backed by `localStorage`.
+ * Messages survive page refreshes and browser restarts (same-origin only).
+ *
+ * @param options - Storage key and optional serialize/deserialize hooks.
+ */
+declare function createLocalStorageStoreMessageChannel<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>>(options: BrowserStorageStoreMessageChannelOptions<TData, TKey>): StoreMessageChannel<TData, TKey>;
+/**
+ * Creates a message channel backed by `sessionStorage`.
+ * Messages survive page refreshes but are lost when the browser tab closes.
+ *
+ * @param options - Storage key and optional serialize/deserialize hooks.
+ */
+declare function createSessionStorageStoreMessageChannel<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>>(options: BrowserStorageStoreMessageChannelOptions<TData, TKey>): StoreMessageChannel<TData, TKey>;
+/**
+ * Creates a composite message channel that fans out writes to multiple channels.
+ * The first channel is the primary (handles reads and id allocation); all channels receive writes.
+ *
+ * @param options - Array of channels. Must contain at least one.
+ */
+declare function createCompositeStoreMessageChannel<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>>(options: CompositeStoreMessageChannelOptions<TData, TKey>): StoreMessageChannel<TData, TKey>;
+
+/**
+ * Constraint type ensuring every key in a store data map holds a {@link ResourceState}.
+ */
 type StoreDataShape<TData> = {
     [K in keyof TData]: ResourceState<unknown>;
 };
+/**
+ * Extracts the string-typed keys from a store data map.
+ */
 type StoreKey<TData> = keyof TData & string;
+/** Extracts the value stored inside a store slot's `ResourceState<T>`. */
+type StoreResourceValue<TData extends StoreDataShape<TData>, K extends StoreKey<TData>> = TData[K] extends ResourceState<infer TValue> ? TValue : never;
+/** Narrows store keys whose `data` payload is a keyed resource map. */
+type KeyedStoreKey<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> = {
+    [K in TKey]: StoreResourceValue<TData, K> extends KeyedResourceData<infer _TResourceKey, infer _TValue> ? K : never;
+}[TKey];
+/** Extracts the resource key type for a keyed store slot. */
+type KeyedResourceEntryKey<TData extends StoreDataShape<TData>, K extends KeyedStoreKey<TData>> = StoreResourceValue<TData, K> extends KeyedResourceData<infer TResourceKey, unknown> ? TResourceKey : never;
+/** Extracts the entity value type for a keyed store slot. */
+type KeyedResourceEntryValue<TData extends StoreDataShape<TData>, K extends KeyedStoreKey<TData>> = StoreResourceValue<TData, K> extends KeyedResourceData<KeyedResourceKey, infer TValue> ? TValue : never;
 /**
  * Phantom-typed marker for a store resource slot.
  * Carries type information at compile time with zero runtime cost.
@@ -38,38 +225,349 @@ type InferData<TConfig extends StoreConfig> = {
 type ConfigToData<TConfig extends object> = {
     [K in keyof TConfig & string]: ResourceState<TConfig[K]>;
 };
+/**
+ * Optional runtime configuration for a store instance.
+ *
+ * The default channel is in-memory. Supply `channel` to persist broker messages
+ * elsewhere, such as local storage, session storage, a composite channel, or a
+ * custom provider.
+ */
+interface StoreOptions<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> extends StoreMessageChannelOptions<TData, TKey> {
+}
 /**
  * Shared store interface implemented by both BaseStore and LazyStore.
+ *
+ * All store instances expose these methods regardless of how they were created
+ * (interface-based, fluent, or enum-constrained builder).
  */
 interface IStore<TData extends StoreDataShape<TData>> {
+    /** Returns a read-only `Signal` for the given slot. */
     get<K extends StoreKey<TData>>(key: K): Signal<TData[K]>;
+    /** Merges a partial state into the given slot (immutable spread). */
     update<K extends StoreKey<TData>>(key: K, newState: Partial<TData[K]>): void;
+    /** Resets a slot to its initial idle state (`{ data: undefined, isLoading: false, … }`). */
     clear<K extends StoreKey<TData>>(key: K): void;
+    /** Resets every slot in this store. */
     clearAll(): void;
+    /** Marks a slot as loading: sets `isLoading: true` and clears `status`/`errors`. */
     startLoading<K extends StoreKey<TData>>(key: K): void;
+    /** Marks a slot as no longer loading: sets `isLoading: false`. */
     stopLoading<K extends StoreKey<TData>>(key: K): void;
+    /**
+     * Re-executes previously published channel message id(s).
+     *
+     * Unlike `travelTo(...)`, replay goes back through the broker/consumer path,
+     * so it can mutate the store again, truncate future history after time
+     * travel, and record new acknowledged history entries.
+     */
+    replay: StoreHistory<TData>["replay"];
+    /**
+     * Restores the store to a previously recorded history index.
+     *
+     * This navigates snapshots only and does not re-run any message.
+     */
+    travelTo: StoreHistory<TData>["travelTo"];
+    /** Moves one step backward in the recorded snapshot history when possible. */
+    undo: StoreHistory<TData>["undo"];
+    /** Moves one step forward in the recorded snapshot history when possible. */
+    redo: StoreHistory<TData>["redo"];
+    /**
+     * Returns a defensive copy of the recorded history.
+     *
+     * The first entry is always the initial snapshot captured when the store was created.
+     */
+    getHistory: StoreHistory<TData>["getHistory"];
+    /**
+     * Returns persisted broker message records from the configured channel.
+     *
+     * Use `getMessages(key)` to inspect only the messages that affected one store key.
+     */
+    getMessages: StoreHistory<TData>["getMessages"];
+    /**
+     * Returns messages that failed broker acknowledgement.
+     *
+     * These entries can be inspected for diagnostics and retried later.
+     */
+    getDeadLetters: StoreHistory<TData>["getDeadLetters"];
+    /** Replays a single dead-letter message by dead-letter id. */
+    replayDeadLetter: StoreHistory<TData>["replayDeadLetter"];
+    /** Attempts to replay all current dead-letter messages once. */
+    replayDeadLetters: StoreHistory<TData>["replayDeadLetters"];
+    /** Returns the currently restored snapshot index used by `travelTo`, `undo`, and `redo`. */
+    getCurrentIndex: StoreHistory<TData>["getCurrentIndex"];
+    /** Merges a single entity into a keyed slot and sets its status to `'Success'`. */
     updateKeyedOne<K extends StoreKey<TData>>(key: K, resourceKey: KeyedResourceKey, entity: unknown): void;
+    /** Removes a single entity (and its loading/status/errors) from a keyed slot. */
     clearKeyedOne<K extends StoreKey<TData>>(key: K, resourceKey: KeyedResourceKey): void;
+    /** Marks a single entity within a keyed slot as loading. */
     startKeyedLoading<K extends StoreKey<TData>>(key: K, resourceKey: KeyedResourceKey): void;
+    /**
+     * Registers a callback invoked whenever the given slot is updated.
+     * @returns A cleanup function that removes the listener.
+     */
     onUpdate<K extends StoreKey<TData>>(key: K, callback: (state: TData[K], previousState: TData[K]) => void): () => void;
 }
 
-declare abstract class BaseStore<TEnum extends Record<string, string | number>, TData extends {
+/**
+ * Creates a deep clone of the given value.
+ *
+ * **Warning:** Class instances with constructor logic, private fields, or
+ * non-enumerable state will not clone correctly. The clone preserves the
+ * prototype chain via `Object.create(Object.getPrototypeOf(...))` but does
+ * **not** invoke the constructor, so any side-effects or hidden state set
+ * during construction will be missing from the clone.
+ */
+declare function cloneValue<T>(value: T): T;
+/**
+ * Creates a minimal patch object that, when spread onto `currentState`, produces `snapshotState`.
+ * Properties present in the snapshot are cloned; properties absent from the snapshot are set to `undefined`.
+ *
+ * @param currentState - The current slot state.
+ * @param snapshotState - The target snapshot state to restore.
+ * @returns A partial state object suitable for `Signal.update()`.
+ */
+declare function createSnapshotRestorePatch<TState extends ResourceState<unknown>>(currentState: TState, snapshotState: TState): Partial<TState>;
+
+/**
+ * Single acknowledged point in store history.
+ *
+ * Entry `0` is always the initial snapshot captured when the history driver is
+ * created, so its `id`, `message`, and `acknowledgedAt` are `null`.
+ */
+interface StoreHistoryEntry<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> {
+    /** Stable message id used by `replay(...)`; `null` for the initial snapshot entry. */
+    readonly id: number | null;
+    /** Snapshot position used by `travelTo(index)`, `undo()`, and `redo()`. */
+    readonly index: number;
+    /** Acknowledged message that produced this snapshot; `null` for the initial entry. */
+    readonly message: StoreMessage<TData, TKey> | null;
+    /** Full store snapshot captured immediately after the message was acknowledged. */
+    readonly snapshot: StoreSnapshot<TData, TKey>;
+    /** Acknowledgement timestamp for the message; `null` for the initial snapshot entry. */
+    readonly acknowledgedAt: number | null;
+}
+/**
+ * Failed message tracked by the internal broker when the store consumer does not
+ * acknowledge a published message.
+ */
+interface StoreDeadLetterEntry<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> {
+    /** Stable dead-letter id used by `replayDeadLetter(id)`. */
+    readonly id: number;
+    /** Original message that failed acknowledgement. */
+    readonly message: StoreMessage<TData, TKey>;
+    /** Number of failed acknowledgement attempts for this dead letter. */
+    readonly attempts: number;
+    /** Last acknowledgement error captured for this dead letter. */
+    readonly error: string;
+    /** Timestamp of the most recent failure. */
+    readonly failedAt: number;
+}
+/**
+ * Public history and recovery API exposed on every store instance.
+ *
+ * `travelTo(...)` navigates snapshots by history index, while `replay(...)`
+ * re-executes previously published channel messages by their stable message ids.
+ */
+interface StoreHistory<TData extends StoreDataShape<TData>, TKey extends StoreKey<TData> = StoreKey<TData>> {
+    /**
+     * Re-executes one previously published message by id.
+     *
+     * The message does not need to have been acknowledged before. Replay resolves it
+     * from the configured message channel, sends it back through the broker/consumer
+     * flow, and may create a fresh acknowledged history entry if the replay succeeds.
+     *
+     * @throws {Error} When the id does not point to a persisted channel message.
+     * @returns Number of successfully acknowledged replayed messages.
+     */
+    replay(id: number): number;
+    /**
+     * Re-executes multiple previously published messages in the provided order.
+     *
+     * Every id must resolve to a persisted channel message. Replay stops with an error
+     * if any supplied id is invalid.
+     *
+     * @throws {Error} When any id does not point to a persisted channel message.
+     * @returns Number of successfully acknowledged replayed messages.
+     */
+    replay(ids: readonly number[]): number;
+    /**
+     * Restores the store to the snapshot recorded at a specific history index.
+     *
+     * This is snapshot navigation only. It does not publish or acknowledge any
+     * message and does not create a new history entry.
+     *
+     * @throws {Error} When the index is outside the recorded history range.
+     */
+    travelTo(index: number): void;
+    /**
+     * Moves to the previous recorded snapshot.
+     *
+     * Equivalent to `travelTo(getCurrentIndex() - 1)` when possible.
+     *
+     * @returns `true` when the pointer moved, otherwise `false` at the initial snapshot.
+     */
+    undo(): boolean;
+    /**
+     * Moves to the next recorded snapshot when history exists ahead of the current pointer.
+     *
+     * Equivalent to `travelTo(getCurrentIndex() + 1)` when possible.
+     *
+     * @returns `true` when the pointer moved, otherwise `false` at the latest snapshot.
+     */
+    redo(): boolean;
+    /** Returns a defensive copy of every recorded history entry, including the initial snapshot entry. */
+    getHistory(): readonly StoreHistoryEntry<TData, TKey>[];
+    /**
+     * Returns the history entries that affected a specific store key.
+     *
+     * The initial snapshot entry is always included as the first item. Messages such
+     * as `clearAll` that affect every key are included in every filtered view.
+     */
+    getHistory<K extends TKey>(key: K): readonly StoreHistoryEntry<TData, K>[];
+    /** Returns a defensive copy of the current dead-letter collection. */
+    getDeadLetters(): readonly StoreDeadLetterEntry<TData, TKey>[];
+    /** Returns every message currently stored in the configured channel. */
+    getMessages(): readonly StoreMessageRecord<TData, TKey>[];
+    /** Returns channel messages that affected a specific store key. */
+    getMessages<K extends TKey>(key: K): readonly StoreMessageRecord<TData, K>[];
+    /**
+     * Republishes a single dead-letter message by dead-letter id.
+     *
+     * On success the dead letter is removed and a new acknowledged history entry is recorded.
+     *
+     * @returns `true` when the dead letter was acknowledged on replay, otherwise `false`.
+     */
+    replayDeadLetter(id: number): boolean;
+    /**
+     * Attempts to republish every current dead letter once.
+     *
+     * Successfully acknowledged dead letters are removed. Failures remain in the
+     * dead-letter collection with incremented attempt counts.
+     *
+     * @returns Number of dead letters successfully acknowledged during the replay attempt.
+     */
+    replayDeadLetters(): number;
+    /** Returns the currently restored history index used by snapshot navigation. */
+    getCurrentIndex(): number;
+}
+
+/**
+ * Abstract base class for flurryx stores.
+ *
+ * Backed by Angular `signal()` per slot, providing read-only `Signal` access
+ * and immutable updates. All writes go through the store's own methods to
+ * enforce single-owner encapsulation.
+ *
+ * Use the {@link Store} builder to create instances — do not subclass directly.
+ *
+ * @template TEnum - Record mapping slot names to their string/number keys.
+ * @template TData - Record mapping slot names to `ResourceState<T>` types.
+ */
+declare abstract class BaseStore<TEnum extends Record<string, string | number>, TData extends StoreDataShape<TData> & {
     [K in keyof TEnum]: ResourceState<unknown>;
 }> implements IStore<TData> {
     protected readonly storeEnum: TEnum;
     private readonly signalsState;
-    protected constructor(storeEnum: TEnum);
-    get<K extends keyof TData>(key: K): Signal<TData[K]>;
-    onUpdate<K extends keyof TData>(key: K, callback: (state: TData[K], previousState: TData[K]) => void): () => void;
-    update<K extends keyof TData>(key: K, newState: Partial<TData[K]>): void;
+    private readonly storeKeys;
+    private readonly history;
+    /** @inheritDoc */
+    readonly travelTo: (index: number) => void;
+    /** @inheritDoc */
+    readonly undo: () => boolean;
+    /** @inheritDoc */
+    readonly redo: () => boolean;
+    /** @inheritDoc */
+    readonly getDeadLetters: () => readonly StoreDeadLetterEntry<TData, StoreKey<TData>>[];
+    /** @inheritDoc */
+    readonly replayDeadLetter: (id: number) => boolean;
+    /** @inheritDoc */
+    readonly replayDeadLetters: () => number;
+    /** @inheritDoc */
+    readonly getCurrentIndex: () => number;
+    /** @inheritDoc */
+    replay(id: number): number;
+    /** @inheritDoc */
+    replay(ids: readonly number[]): number;
+    /** @inheritDoc */
+    getHistory(): readonly StoreHistoryEntry<TData>[];
+    /** @inheritDoc */
+    getHistory<K extends StoreKey<TData>>(key: K): readonly StoreHistoryEntry<TData, K>[];
+    /** @inheritDoc */
+    getMessages(): readonly StoreMessageRecord<TData>[];
+    /** @inheritDoc */
+    getMessages<K extends StoreKey<TData>>(key: K): readonly StoreMessageRecord<TData, K>[];
+    protected constructor(storeEnum: TEnum, options?: StoreOptions<TData>);
+    /**
+     * Returns a **read-only** `Signal` for the given store slot.
+     *
+     * @param key - The slot name to read.
+     * @returns A `Signal` wrapping the slot's current {@link ResourceState}.
+     */
+    get<K extends StoreKey<TData>>(key: K): Signal<TData[K]>;
+    /**
+     * Registers a callback fired after every `update` or `clear` on the given slot.
+     *
+     * @param key - The slot to watch.
+     * @param callback - Receives the new state and the previous state.
+     * @returns A cleanup function that removes the listener when called.
+     */
+    onUpdate<K extends StoreKey<TData>>(key: K, callback: (state: TData[K], previousState: TData[K]) => void): () => void;
+    /**
+     * Partially updates a slot by merging `newState` into the current value (immutable spread).
+     *
+     * @param key - The slot to update.
+     * @param newState - Partial state to merge (e.g. `{ data: newData, status: 'Success' }`).
+     */
+    update<K extends StoreKey<TData>>(key: K, newState: Partial<TData[K]>): void;
+    /** Resets every slot in this store to its initial idle state. */
     clearAll(): void;
-    clear<K extends keyof TData>(key: K): void;
-    startLoading<K extends keyof TData>(key: K): void;
-    stopLoading<K extends keyof TData>(key: K): void;
-    updateKeyedOne<K extends keyof TData>(key: K, resourceKey: KeyedResourceKey, entity: unknown): void;
-    clearKeyedOne<K extends keyof TData>(key: K, resourceKey: KeyedResourceKey): void;
-    startKeyedLoading<K extends keyof TData>(key: K, resourceKey: KeyedResourceKey): void;
+    /**
+     * Resets a single slot to `{ data: undefined, isLoading: false, status: undefined, errors: undefined }`.
+     *
+     * @param key - The slot to clear.
+     */
+    clear<K extends StoreKey<TData>>(key: K): void;
+    /**
+     * Marks a slot as loading: sets `isLoading: true` and clears `status` and `errors`.
+     *
+     * @param key - The slot to mark as loading.
+     */
+    startLoading<K extends StoreKey<TData>>(key: K): void;
+    /**
+     * Marks a slot as no longer loading: sets `isLoading: false`.
+     * Does **not** clear `status` or `errors`.
+     *
+     * @param key - The slot to stop loading.
+     */
+    stopLoading<K extends StoreKey<TData>>(key: K): void;
+    /**
+     * Merges a single entity into a {@link KeyedResourceData} slot.
+     * Sets its status to `'Success'` and clears per-key errors.
+     * The top-level `isLoading` is recalculated based on remaining loading keys.
+     *
+     * @param key - The keyed slot name.
+     * @param resourceKey - The entity identifier (e.g. `'inv-123'`).
+     * @param entity - The entity value to store.
+     */
+    updateKeyedOne<K extends StoreKey<TData>>(key: K, resourceKey: KeyedResourceKey, entity: unknown): void;
+    /**
+     * Removes a single entity from a {@link KeyedResourceData} slot,
+     * including its loading flag, status, and errors.
+     * Recalculates the top-level `isLoading` from the remaining keys.
+     *
+     * @param key - The keyed slot name.
+     * @param resourceKey - The entity identifier to remove.
+     */
+    clearKeyedOne<K extends StoreKey<TData>>(key: K, resourceKey: KeyedResourceKey): void;
+    /**
+     * Marks a single entity within a keyed slot as loading.
+     * Clears its status and errors. If the slot data is not yet a {@link KeyedResourceData},
+     * falls back to `startLoading(key)`.
+     *
+     * @param key - The keyed slot name.
+     * @param resourceKey - The entity identifier to mark as loading.
+     */
+    startKeyedLoading<K extends StoreKey<TData>>(key: K, resourceKey: KeyedResourceKey): void;
     private notifyUpdateHooks;
     private initializeState;
 }
@@ -82,17 +580,54 @@ declare abstract class BaseStore<TEnum extends Record<string, string | number>,
 declare class LazyStore<TData extends StoreDataShape<TData>> implements IStore<TData> {
     private readonly signals;
     private readonly hooks;
-    constructor();
+    private readonly history;
+    /** @inheritDoc */
+    readonly travelTo: (index: number) => void;
+    /** @inheritDoc */
+    readonly undo: () => boolean;
+    /** @inheritDoc */
+    readonly redo: () => boolean;
+    /** @inheritDoc */
+    getMessages(): readonly StoreMessageRecord<TData>[];
+    /** @inheritDoc */
+    getMessages<K extends StoreKey<TData>>(key: K): readonly StoreMessageRecord<TData, K>[];
+    /** @inheritDoc */
+    readonly getDeadLetters: () => readonly StoreDeadLetterEntry<TData, StoreKey<TData>>[];
+    /** @inheritDoc */
+    readonly replayDeadLetter: (id: number) => boolean;
+    /** @inheritDoc */
+    readonly replayDeadLetters: () => number;
+    /** @inheritDoc */
+    readonly getCurrentIndex: () => number;
+    /** @inheritDoc */
+    replay(id: number): number;
+    /** @inheritDoc */
+    replay(ids: readonly number[]): number;
+    /** @inheritDoc */
+    getHistory(): readonly StoreHistoryEntry<TData>[];
+    /** @inheritDoc */
+    getHistory<K extends StoreKey<TData>>(key: K): readonly StoreHistoryEntry<TData, K>[];
+    constructor(options?: StoreOptions<TData>);
     private getOrCreate;
+    /** @inheritDoc */
     get<K extends StoreKey<TData>>(key: K): Signal<TData[K]>;
+    /** @inheritDoc */
     update<K extends StoreKey<TData>>(key: K, newState: Partial<TData[K]>): void;
+    /** @inheritDoc */
     clear<K extends StoreKey<TData>>(key: K): void;
+    /** @inheritDoc */
     clearAll(): void;
+    /** @inheritDoc */
     startLoading<K extends StoreKey<TData>>(key: K): void;
+    /** @inheritDoc */
     stopLoading<K extends StoreKey<TData>>(key: K): void;
+    /** @inheritDoc */
     updateKeyedOne<K extends StoreKey<TData>>(key: K, resourceKey: KeyedResourceKey, entity: unknown): void;
+    /** @inheritDoc */
     clearKeyedOne<K extends StoreKey<TData>>(key: K, resourceKey: KeyedResourceKey): void;
+    /** @inheritDoc */
     startKeyedLoading<K extends StoreKey<TData>>(key: K, resourceKey: KeyedResourceKey): void;
+    /** @inheritDoc */
     onUpdate<K extends StoreKey<TData>>(key: K, callback: (state: TData[K], previousState: TData[K]) => void): () => void;
     private notifyHooks;
 }
@@ -101,25 +636,70 @@ declare class LazyStore<TData extends StoreDataShape<TData>> implements IStore<T
  * Intermediate builder step after .resource('key') — awaits .as<T>().
  */
 interface AsStep<TAccum extends StoreConfig, TKey extends string> {
+    /**
+     * Assign the resource value type for the previously declared key.
+     *
+     * Returns the main fluent builder so you can define more resources, configure
+     * mirrors, or call `.build()`.
+     *
+     * @example
+     * ```ts
+     * const CustomersStore = Store
+     *   .resource('CUSTOMERS').as<Customer[]>()
+     *   .build();
+     * ```
+     */
     as<T>(): StoreBuilder<TAccum & Record<TKey, ResourceDef<T>>>;
 }
 /**
  * Fluent builder for creating stores.
- * Accumulates resource definitions then produces an InjectionToken on .build().
+ * Accumulates resource definitions then produces an `InjectionToken` on `.build()`.
  */
 interface StoreBuilder<TAccum extends StoreConfig> {
+    /** Define a new resource slot. Chain `.as<T>()` to set its type. */
     resource<TKey extends string>(key: TKey): AsStep<TAccum, TKey>;
+    /**
+     * Mirror a slot from another store. When the source updates, the target is kept in sync.
+     *
+     * @param source - The source store's `InjectionToken`.
+     * @param sourceKey - The key to watch on the source store.
+     * @param targetKey - The key on this store to write to. Defaults to `sourceKey`.
+     */
     mirror<TSourceData extends StoreDataShape<TSourceData>>(source: InjectionToken<IStore<TSourceData>>, sourceKey: StoreKey<TSourceData>, targetKey?: StoreKey<TAccum>): StoreBuilder<TAccum>;
+    /**
+     * Mirror one slot to another **within the same store**.
+     * Source and target keys must be different.
+     *
+     * @param sourceKey - The slot to read from.
+     * @param targetKey - The slot to write to.
+     */
     mirrorSelf(sourceKey: StoreKey<TAccum>, targetKey: StoreKey<TAccum>): StoreBuilder<TAccum>;
+    /**
+     * Accumulate single-entity fetches from a source store into a `KeyedResourceData` slot.
+     *
+     * @param source - The source store's `InjectionToken`.
+     * @param sourceKey - The single-entity key on the source store.
+     * @param options - Must include `extractId` to derive the entity's key from its data.
+     * @param targetKey - The keyed slot on this store. Defaults to `sourceKey`.
+     */
     mirrorKeyed<TSourceData extends StoreDataShape<TSourceData>, TEntity>(source: InjectionToken<IStore<TSourceData>>, sourceKey: StoreKey<TSourceData>, options: {
         extractId: (data: TEntity | undefined) => KeyedResourceKey | undefined;
     }, targetKey?: StoreKey<TAccum>): StoreBuilder<TAccum>;
-    build(): InjectionToken<BaseStore<InferEnum<TAccum>, InferData<TAccum>>>;
+    /**
+     * Finalize the builder and create an `InjectionToken` (`providedIn: 'root'`).
+     * All mirrors are wired up automatically when Angular creates the store.
+     */
+    build(options?: StoreOptions<InferData<TAccum>>): InjectionToken<BaseStore<InferEnum<TAccum>, InferData<TAccum>>>;
 }
 /** Keys from the enum that have NOT yet been defined. */
 type Remaining<TEnum extends Record<string, string>, TAccum extends StoreConfig> = Exclude<keyof TEnum & string, keyof TAccum>;
 /** Intermediate .as<T>() step for the constrained builder. */
 interface ConstrainedAsStep<TEnum extends Record<string, string>, TAccum extends StoreConfig, TKey extends string> {
+    /**
+     * Assign the resource value type for the selected enum key.
+     *
+     * Returns the constrained builder for the remaining enum keys.
+     */
     as<T>(): ConstrainedBuilder<TEnum, TAccum & Record<TKey, ResourceDef<T>>>;
 }
 /**
@@ -127,22 +707,94 @@ interface ConstrainedAsStep<TEnum extends Record<string, string>, TAccum extends
  * defined yet. `.build()` is only available when all keys are accounted for.
  */
 type ConstrainedBuilder<TEnum extends Record<string, string>, TAccum extends StoreConfig> = [Remaining<TEnum, TAccum>] extends [never] ? {
+    /**
+     * Mirror a slot from another store. When the source updates, the target is kept in sync.
+     *
+     * @param source - The source store's `InjectionToken`.
+     * @param sourceKey - The key to watch on the source store.
+     * @param targetKey - The key on this store to write to. Defaults to `sourceKey`.
+     */
     mirror<TSourceData extends StoreDataShape<TSourceData>>(source: InjectionToken<IStore<TSourceData>>, sourceKey: StoreKey<TSourceData>, targetKey?: StoreKey<TAccum>): ConstrainedBuilder<TEnum, TAccum>;
+    /**
+     * Mirror one slot to another within the same store.
+     * Source and target keys must be different.
+     *
+     * @param sourceKey - The slot to read from.
+     * @param targetKey - The slot to write to.
+     */
     mirrorSelf(sourceKey: StoreKey<TAccum>, targetKey: StoreKey<TAccum>): ConstrainedBuilder<TEnum, TAccum>;
+    /**
+     * Accumulate single-entity fetches from a source store into a keyed slot.
+     *
+     * @param source - The source store's `InjectionToken`.
+     * @param sourceKey - The single-entity key on the source store.
+     * @param options - Must include `extractId` to derive the entity's key from its data.
+     * @param targetKey - The keyed slot on this store. Defaults to `sourceKey`.
+     */
     mirrorKeyed<TSourceData extends StoreDataShape<TSourceData>, TEntity>(source: InjectionToken<IStore<TSourceData>>, sourceKey: StoreKey<TSourceData>, options: {
         extractId: (data: TEntity | undefined) => KeyedResourceKey | undefined;
     }, targetKey?: StoreKey<TAccum>): ConstrainedBuilder<TEnum, TAccum>;
-    build(): InjectionToken<BaseStore<InferEnum<TAccum>, InferData<TAccum>>>;
+    /**
+     * Finalize the builder and create an `InjectionToken` (`providedIn: 'root'`).
+     * Available only after all enum keys have been defined.
+     */
+    build(options?: StoreOptions<InferData<TAccum>>): InjectionToken<BaseStore<InferEnum<TAccum>, InferData<TAccum>>>;
 } : {
+    /** Define the next resource slot from the remaining enum keys. */
     resource<TKey extends Remaining<TEnum, TAccum>>(key: TKey): ConstrainedAsStep<TEnum, TAccum, TKey>;
 };
+/**
+ * Interface-based builder for `Store.for<Config>()`.
+ *
+ * Uses a config interface for compile-time shape only, so no runtime enum is required.
+ */
 interface InterfaceBuilder<TConfig extends object> {
+    /**
+     * Mirror a slot from another store. When the source updates, the target is kept in sync.
+     *
+     * @param source - The source store's `InjectionToken`.
+     * @param sourceKey - The key to watch on the source store.
+     * @param targetKey - The key on this store to write to. Defaults to `sourceKey`.
+     */
     mirror<TSourceData extends StoreDataShape<TSourceData>>(source: InjectionToken<IStore<TSourceData>>, sourceKey: StoreKey<TSourceData>, targetKey?: StoreKey<ConfigToData<TConfig>>): InterfaceBuilder<TConfig>;
+    /**
+     * Mirror one slot to another within the same store.
+     * Source and target keys must be different.
+     *
+     * @param sourceKey - The slot to read from.
+     * @param targetKey - The slot to write to.
+     */
     mirrorSelf(sourceKey: StoreKey<ConfigToData<TConfig>>, targetKey: StoreKey<ConfigToData<TConfig>>): InterfaceBuilder<TConfig>;
+    /**
+     * Accumulate single-entity fetches from a source store into a keyed slot.
+     *
+     * @param source - The source store's `InjectionToken`.
+     * @param sourceKey - The single-entity key on the source store.
+     * @param options - Must include `extractId` to derive the entity's key from its data.
+     * @param targetKey - The keyed slot on this store. Defaults to `sourceKey`.
+     */
     mirrorKeyed<TSourceData extends StoreDataShape<TSourceData>, TEntity>(source: InjectionToken<IStore<TSourceData>>, sourceKey: StoreKey<TSourceData>, options: {
         extractId: (data: TEntity | undefined) => KeyedResourceKey | undefined;
     }, targetKey?: StoreKey<ConfigToData<TConfig>>): InterfaceBuilder<TConfig>;
-    build(): InjectionToken<IStore<ConfigToData<TConfig>>>;
+    /**
+     * Finalize the interface-based builder and create a store `InjectionToken`.
+     *
+     * The resulting token is registered with `providedIn: 'root'` and resolves to
+     * a `LazyStore` implementing `IStore<ConfigToData<TConfig>>`.
+     *
+     * @returns An Angular `InjectionToken` for the configured store.
+     *
+     * @example
+     * ```ts
+     * interface ChatStoreConfig {
+     *   SESSIONS: ChatSession[];
+     *   MESSAGES: ChatMessage[];
+     * }
+     *
+     * export const ChatStore = Store.for<ChatStoreConfig>().build();
+     * ```
+     */
+    build(options?: StoreOptions<ConfigToData<TConfig>>): InjectionToken<IStore<ConfigToData<TConfig>>>;
 }
 interface StoreEntry {
     /**
@@ -151,6 +803,16 @@ interface StoreEntry {
      * or call .build() when done.
      */
     resource<TKey extends string>(key: TKey): {
+        /**
+         * Set the resource value type and continue the fluent builder chain.
+         *
+         * @example
+         * ```ts
+         * const UsersStore = Store
+         *   .resource('USERS').as<User[]>()
+         *   .build();
+         * ```
+         */
         as<T>(): StoreBuilder<Record<TKey, ResourceDef<T>>>;
     };
     /**
@@ -197,9 +859,31 @@ interface StoreEntry {
  */
 declare const Store: StoreEntry;
 
+/**
+ * Clears every store instance tracked by flurryx.
+ *
+ * Calls `clearAll()` on each registered store, resetting all slots to their
+ * initial idle state. Useful for logout, tenant switching, or test cleanup.
+ *
+ * @example
+ * ```ts
+ * import { clearAllStores } from '@flurryx/store';
+ *
+ * logout() {
+ *   clearAllStores();
+ * }
+ * ```
+ */
 declare function clearAllStores(): void;
 
+/**
+ * Options for {@link mirrorKey}.
+ */
 interface MirrorOptions {
+    /**
+     * Angular `DestroyRef` (or any object with an `onDestroy` method) for
+     * automatic cleanup. When provided, the mirror stops when the ref is destroyed.
+     */
     destroyRef?: {
         onDestroy: (fn: () => void) => void;
     };
@@ -217,8 +901,21 @@ interface MirrorOptions {
  */
 declare function mirrorKey<TSource extends StoreDataShape<TSource>, TTarget extends StoreDataShape<TTarget>>(source: IStore<TSource>, sourceKey: StoreKey<TSource>, target: IStore<TTarget>, targetKeyOrOptions?: StoreKey<TTarget> | MirrorOptions, options?: MirrorOptions): () => void;
 
+/**
+ * Options for {@link collectKeyed}.
+ *
+ * @template TEntity - The entity type emitted by the source store.
+ */
 interface CollectKeyedOptions<TEntity> {
+    /**
+     * Extracts the entity identifier from the source data.
+     * Return `undefined` to skip accumulation for that emission.
+     */
     extractId: (data: TEntity | undefined) => KeyedResourceKey | undefined;
+    /**
+     * Angular `DestroyRef` (or any object with an `onDestroy` method) for
+     * automatic cleanup. When provided, collection stops when the ref is destroyed.
+     */
     destroyRef?: {
         onDestroy: (fn: () => void) => void;
     };
@@ -241,4 +938,4 @@ interface CollectKeyedOptions<TEntity> {
  */
 declare function collectKeyed<TSource extends StoreDataShape<TSource>, TTarget extends StoreDataShape<TTarget>, TEntity = unknown>(source: IStore<TSource>, sourceKey: StoreKey<TSource>, target: IStore<TTarget>, targetKeyOrOptions?: StoreKey<TTarget> | CollectKeyedOptions<TEntity>, options?: CollectKeyedOptions<TEntity>): () => void;
 
-export { BaseStore, type CollectKeyedOptions, type ConfigToData, type IStore, LazyStore, type MirrorOptions, Store, clearAllStores, collectKeyed, mirrorKey };
+export { BaseStore, type BrowserStorageStoreMessageChannelOptions, type ClearAllStoreMessage, type ClearKeyedOneStoreMessage, type ClearStoreMessage, type CollectKeyedOptions, type CompositeStoreMessageChannelOptions, type ConfigToData, type IStore, LazyStore, type MirrorOptions, type StartKeyedLoadingStoreMessage, type StartLoadingStoreMessage, type StopLoadingStoreMessage, type StorageStoreMessageChannelOptions, Store, type StoreDeadLetterEntry, type StoreHistory, type StoreHistoryEntry, type StoreMessage, type StoreMessageChannel, type StoreMessageChannelOptions, type StoreMessageChannelStorage, type StoreMessageRecord, type StoreMessageStatus, type StoreOptions, type StoreSnapshot, type UpdateKeyedOneStoreMessage, type UpdateStoreMessage, clearAllStores, cloneValue, collectKeyed, createCompositeStoreMessageChannel, createInMemoryStoreMessageChannel, createLocalStorageStoreMessageChannel, createSessionStorageStoreMessageChannel, createSnapshotRestorePatch, createStorageStoreMessageChannel, mirrorKey };