@flurryx/store 1.0.1 → 1.1.0

package/dist/index.d.cts

@@ -67,6 +67,8 @@ type StoreSnapshot<TData extends StoreDataShape<TData>, TKey extends StoreKey<TD
 }>;
 /** Delivery status of a broker message: `"pending"` → `"acknowledged"` or `"dead-letter"`. */
 type StoreMessageStatus = "pending" | "acknowledged" | "dead-letter";
+/** Error message thrown when `restoreResource()` receives a key that is not a valid store key. */
+declare const INVALID_STORE_KEY_ERROR = "Invalid store key";
 
 /**
  * Persisted broker message record stored in the active message channel.
@@ -256,7 +258,7 @@ interface IStore<TData extends StoreDataShape<TData>> {
     /**
      * Re-executes previously published channel message id(s).
      *
-     * Unlike `travelTo(...)`, replay goes back through the broker/consumer path,
+     * Unlike `restoreStoreAt(...)`, 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.
      */
@@ -266,7 +268,19 @@ interface IStore<TData extends StoreDataShape<TData>> {
      *
      * This navigates snapshots only and does not re-run any message.
      */
-    travelTo: StoreHistory<TData>["travelTo"];
+    restoreStoreAt: StoreHistory<TData>["restoreStoreAt"];
+    /**
+     * Restores a single store key to its state at a specific history index.
+     *
+     * Unlike `restoreStoreAt(index)` which restores the full snapshot, this method
+     * only restores the specified key while leaving other keys unaffected.
+     * This is snapshot navigation only. It does not publish or acknowledge any
+     * message and does not create a new history entry.
+     *
+     * @param key - The store key to restore.
+     * @param index - Optional history index. Defaults to the current index.
+     */
+    restoreResource: StoreHistory<TData>["restoreResource"];
     /** 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. */
@@ -293,7 +307,7 @@ interface IStore<TData extends StoreDataShape<TData>> {
     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`. */
+    /** Returns the currently restored snapshot index used by `restoreStoreAt`, `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;
@@ -345,7 +359,7 @@ declare function createSnapshotRestorePatch<TState extends ResourceState<unknown
 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()`. */
+    /** Snapshot position used by `restoreStoreAt(index)`, `undo()`, and `redo()`. */
     readonly index: number;
     /** Acknowledged message that produced this snapshot; `null` for the initial entry. */
     readonly message: StoreMessage<TData, TKey> | null;
@@ -373,7 +387,7 @@ interface StoreDeadLetterEntry<TData extends StoreDataShape<TData>, TKey extends
 /**
  * Public history and recovery API exposed on every store instance.
  *
- * `travelTo(...)` navigates snapshots by history index, while `replay(...)`
+ * `restoreStoreAt(...)` 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>> {
@@ -406,11 +420,25 @@ interface StoreHistory<TData extends StoreDataShape<TData>, TKey extends StoreKe
      *
      * @throws {Error} When the index is outside the recorded history range.
      */
-    travelTo(index: number): void;
+    restoreStoreAt(index: number): void;
+    /**
+     * Restores a single store key to its state at a specific history index.
+     *
+     * Unlike `restoreStoreAt(index)` which restores the full snapshot, this method
+     * only restores the specified key while leaving other keys unaffected.
+     * This is snapshot navigation only. It does not publish or acknowledge any
+     * message and does not create a new history entry.
+     *
+     * @param key - The store key to restore.
+     * @param index - Optional history index. Defaults to the current index.
+     * @throws {Error} When the key is not a valid store key.
+     * @throws {Error} When the index is outside the recorded history range.
+     */
+    restoreResource<K extends TKey>(key: K, index?: number): void;
     /**
      * Moves to the previous recorded snapshot.
      *
-     * Equivalent to `travelTo(getCurrentIndex() - 1)` when possible.
+     * Equivalent to `restoreStoreAt(getCurrentIndex() - 1)` when possible.
      *
      * @returns `true` when the pointer moved, otherwise `false` at the initial snapshot.
      */
@@ -418,7 +446,7 @@ interface StoreHistory<TData extends StoreDataShape<TData>, TKey extends StoreKe
     /**
      * Moves to the next recorded snapshot when history exists ahead of the current pointer.
      *
-     * Equivalent to `travelTo(getCurrentIndex() + 1)` when possible.
+     * Equivalent to `restoreStoreAt(getCurrentIndex() + 1)` when possible.
      *
      * @returns `true` when the pointer moved, otherwise `false` at the latest snapshot.
      */
@@ -485,7 +513,9 @@ declare abstract class BaseStore<TEnum extends Record<string, string | number>,
     private readonly storeKeys;
     private readonly historyDriver;
     /** @inheritDoc */
-    readonly travelTo: (index: number) => void;
+    readonly restoreStoreAt: (index: number) => void;
+    /** @inheritDoc */
+    readonly restoreResource: <K extends StoreKey<TData>>(key: K, index?: number) => void;
     /** @inheritDoc */
     readonly undo: () => boolean;
     /** @inheritDoc */
@@ -604,7 +634,9 @@ declare class LazyStore<TData extends StoreDataShape<TData>> implements IStore<T
     private readonly hooks;
     private readonly historyDriver;
     /** @inheritDoc */
-    readonly travelTo: (index: number) => void;
+    readonly restoreStoreAt: (index: number) => void;
+    /** @inheritDoc */
+    readonly restoreResource: <K extends StoreKey<TData>>(key: K, index?: number) => void;
     /** @inheritDoc */
     readonly undo: () => boolean;
     /** @inheritDoc */
@@ -968,4 +1000,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 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 };
+export { BaseStore, type BrowserStorageStoreMessageChannelOptions, type ClearAllStoreMessage, type ClearKeyedOneStoreMessage, type ClearStoreMessage, type CollectKeyedOptions, type CompositeStoreMessageChannelOptions, type ConfigToData, INVALID_STORE_KEY_ERROR, 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 };

package/dist/index.d.ts

@@ -67,6 +67,8 @@ type StoreSnapshot<TData extends StoreDataShape<TData>, TKey extends StoreKey<TD
 }>;
 /** Delivery status of a broker message: `"pending"` → `"acknowledged"` or `"dead-letter"`. */
 type StoreMessageStatus = "pending" | "acknowledged" | "dead-letter";
+/** Error message thrown when `restoreResource()` receives a key that is not a valid store key. */
+declare const INVALID_STORE_KEY_ERROR = "Invalid store key";
 
 /**
  * Persisted broker message record stored in the active message channel.
@@ -256,7 +258,7 @@ interface IStore<TData extends StoreDataShape<TData>> {
     /**
      * Re-executes previously published channel message id(s).
      *
-     * Unlike `travelTo(...)`, replay goes back through the broker/consumer path,
+     * Unlike `restoreStoreAt(...)`, 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.
      */
@@ -266,7 +268,19 @@ interface IStore<TData extends StoreDataShape<TData>> {
      *
      * This navigates snapshots only and does not re-run any message.
      */
-    travelTo: StoreHistory<TData>["travelTo"];
+    restoreStoreAt: StoreHistory<TData>["restoreStoreAt"];
+    /**
+     * Restores a single store key to its state at a specific history index.
+     *
+     * Unlike `restoreStoreAt(index)` which restores the full snapshot, this method
+     * only restores the specified key while leaving other keys unaffected.
+     * This is snapshot navigation only. It does not publish or acknowledge any
+     * message and does not create a new history entry.
+     *
+     * @param key - The store key to restore.
+     * @param index - Optional history index. Defaults to the current index.
+     */
+    restoreResource: StoreHistory<TData>["restoreResource"];
     /** 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. */
@@ -293,7 +307,7 @@ interface IStore<TData extends StoreDataShape<TData>> {
     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`. */
+    /** Returns the currently restored snapshot index used by `restoreStoreAt`, `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;
@@ -345,7 +359,7 @@ declare function createSnapshotRestorePatch<TState extends ResourceState<unknown
 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()`. */
+    /** Snapshot position used by `restoreStoreAt(index)`, `undo()`, and `redo()`. */
     readonly index: number;
     /** Acknowledged message that produced this snapshot; `null` for the initial entry. */
     readonly message: StoreMessage<TData, TKey> | null;
@@ -373,7 +387,7 @@ interface StoreDeadLetterEntry<TData extends StoreDataShape<TData>, TKey extends
 /**
  * Public history and recovery API exposed on every store instance.
  *
- * `travelTo(...)` navigates snapshots by history index, while `replay(...)`
+ * `restoreStoreAt(...)` 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>> {
@@ -406,11 +420,25 @@ interface StoreHistory<TData extends StoreDataShape<TData>, TKey extends StoreKe
      *
      * @throws {Error} When the index is outside the recorded history range.
      */
-    travelTo(index: number): void;
+    restoreStoreAt(index: number): void;
+    /**
+     * Restores a single store key to its state at a specific history index.
+     *
+     * Unlike `restoreStoreAt(index)` which restores the full snapshot, this method
+     * only restores the specified key while leaving other keys unaffected.
+     * This is snapshot navigation only. It does not publish or acknowledge any
+     * message and does not create a new history entry.
+     *
+     * @param key - The store key to restore.
+     * @param index - Optional history index. Defaults to the current index.
+     * @throws {Error} When the key is not a valid store key.
+     * @throws {Error} When the index is outside the recorded history range.
+     */
+    restoreResource<K extends TKey>(key: K, index?: number): void;
     /**
      * Moves to the previous recorded snapshot.
      *
-     * Equivalent to `travelTo(getCurrentIndex() - 1)` when possible.
+     * Equivalent to `restoreStoreAt(getCurrentIndex() - 1)` when possible.
      *
      * @returns `true` when the pointer moved, otherwise `false` at the initial snapshot.
      */
@@ -418,7 +446,7 @@ interface StoreHistory<TData extends StoreDataShape<TData>, TKey extends StoreKe
     /**
      * Moves to the next recorded snapshot when history exists ahead of the current pointer.
      *
-     * Equivalent to `travelTo(getCurrentIndex() + 1)` when possible.
+     * Equivalent to `restoreStoreAt(getCurrentIndex() + 1)` when possible.
      *
      * @returns `true` when the pointer moved, otherwise `false` at the latest snapshot.
      */
@@ -485,7 +513,9 @@ declare abstract class BaseStore<TEnum extends Record<string, string | number>,
     private readonly storeKeys;
     private readonly historyDriver;
     /** @inheritDoc */
-    readonly travelTo: (index: number) => void;
+    readonly restoreStoreAt: (index: number) => void;
+    /** @inheritDoc */
+    readonly restoreResource: <K extends StoreKey<TData>>(key: K, index?: number) => void;
     /** @inheritDoc */
     readonly undo: () => boolean;
     /** @inheritDoc */
@@ -604,7 +634,9 @@ declare class LazyStore<TData extends StoreDataShape<TData>> implements IStore<T
     private readonly hooks;
     private readonly historyDriver;
     /** @inheritDoc */
-    readonly travelTo: (index: number) => void;
+    readonly restoreStoreAt: (index: number) => void;
+    /** @inheritDoc */
+    readonly restoreResource: <K extends StoreKey<TData>>(key: K, index?: number) => void;
     /** @inheritDoc */
     readonly undo: () => boolean;
     /** @inheritDoc */
@@ -968,4 +1000,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 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 };
+export { BaseStore, type BrowserStorageStoreMessageChannelOptions, type ClearAllStoreMessage, type ClearKeyedOneStoreMessage, type ClearStoreMessage, type CollectKeyedOptions, type CompositeStoreMessageChannelOptions, type ConfigToData, INVALID_STORE_KEY_ERROR, 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 };