@daltonr/pathwrite-store 0.9.0

package/dist/async-store.d.ts

@@ -0,0 +1,49 @@
+import type { SerializedPathState, PathStore } from "@daltonr/pathwrite-core";
+/**
+ * Minimal interface for an async key-value string storage backend.
+ * `@react-native-async-storage/async-storage` satisfies this interface directly,
+ * as does any other async key-value store with the same shape.
+ */
+export interface AsyncStorageAdapter {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    /**
+     * Return every key currently held in the storage backend.
+     * Required by `AsyncStorageStore.list()` and `AsyncStorageStore.clear()`.
+     * Implementations that don't need those methods may omit this.
+     */
+    getAllKeys?(): Promise<readonly string[]>;
+}
+export interface AsyncStorageStoreOptions {
+    /**
+     * The async storage backend to use.
+     * Pass `AsyncStorage` from `@react-native-async-storage/async-storage`,
+     * or any object that satisfies `AsyncStorageAdapter`.
+     */
+    storage: AsyncStorageAdapter;
+    /**
+     * Prefix prepended to every storage key to avoid collisions.
+     * Defaults to `"@daltonr/pathwrite:"`.
+     */
+    prefix?: string;
+}
+export declare class AsyncStorageStore implements PathStore {
+    private prefix;
+    private storage;
+    constructor(options: AsyncStorageStoreOptions);
+    private storageKey;
+    save(key: string, state: SerializedPathState): Promise<void>;
+    load(key: string): Promise<SerializedPathState | null>;
+    delete(key: string): Promise<void>;
+    /**
+     * Returns every key stored under this store's prefix, decoded back to the
+     * original key strings passed to `save()`.
+     */
+    list(): Promise<string[]>;
+    /**
+     * Removes every entry stored under this store's prefix.
+     */
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=async-store.d.ts.map

package/dist/async-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-store.d.ts","sourceRoot":"","sources":["../src/async-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE9E;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC;;;;OAIG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,OAAO,EAAE,mBAAmB,CAAC;IAC7B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,iBAAkB,YAAW,SAAS;IACjD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAsB;gBAEzB,OAAO,EAAE,wBAAwB;IAK7C,OAAO,CAAC,UAAU;IAIZ,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ5D,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAUtD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAiB/B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAM7B"}

package/dist/async-store.js

@@ -0,0 +1,67 @@
+export class AsyncStorageStore {
+    prefix;
+    storage;
+    constructor(options) {
+        this.prefix = options.prefix ?? "@daltonr/pathwrite:";
+        this.storage = options.storage;
+    }
+    storageKey(key) {
+        return this.prefix + encodeURIComponent(key);
+    }
+    async save(key, state) {
+        try {
+            await this.storage.setItem(this.storageKey(key), JSON.stringify(state));
+        }
+        catch (err) {
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    async load(key) {
+        try {
+            const raw = await this.storage.getItem(this.storageKey(key));
+            if (raw === null || raw === undefined)
+                return null;
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    async delete(key) {
+        try {
+            await this.storage.removeItem(this.storageKey(key));
+        }
+        catch (err) {
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    /**
+     * Returns every key stored under this store's prefix, decoded back to the
+     * original key strings passed to `save()`.
+     */
+    async list() {
+        if (!this.storage.getAllKeys) {
+            throw new Error("AsyncStorageStore.list() requires the AsyncStorageAdapter to implement getAllKeys(). " +
+                "Pass an adapter that supports key enumeration, such as @react-native-async-storage/async-storage.");
+        }
+        try {
+            const allKeys = await this.storage.getAllKeys();
+            return Array.from(allKeys)
+                .filter((k) => k.startsWith(this.prefix))
+                .map((k) => decodeURIComponent(k.slice(this.prefix.length)));
+        }
+        catch (err) {
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    /**
+     * Removes every entry stored under this store's prefix.
+     */
+    async clear() {
+        const keys = await this.list();
+        for (const key of keys) {
+            await this.delete(key);
+        }
+    }
+}
+//# sourceMappingURL=async-store.js.map

package/dist/async-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-store.js","sourceRoot":"","sources":["../src/async-store.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @daltonr/pathwrite-store
+ *
+ * Persistence adapters and observer utilities for PathEngine state.
+ *
+ * Stores (implement PathStore):
+ *   - HttpStore        — persists to a REST API
+ *   - LocalStorageStore — persists to browser localStorage (or any sync key-value adapter)
+ *   - AsyncStorageStore — persists to any async key-value store (e.g. AsyncStorage on React Native)
+ *
+ * Observer utilities:
+ *   - persistence      — PathObserver factory; wires any PathStore to an engine's event stream
+ *   - restoreOrStart   — convenience factory for the load/restore-or-start pattern
+ *
+ * Bring your own store:
+ *   Implement the PathStore interface (save / load / delete) to use any backend —
+ *   MongoDB Atlas SDK, SQLite, MMKV, IndexedDB, or anything else.
+ */
+import { PathEngine } from "@daltonr/pathwrite-core";
+import type { SerializedPathState, PathDefinition, PathData, PathObserver, ObserverStrategy, PathStore } from "@daltonr/pathwrite-core";
+export interface HttpStoreOptions {
+    /**
+     * Base URL for the API. Individual endpoint paths are appended to this.
+     * Example: "https://api.example.com" or "/api/wizard"
+     */
+    baseUrl: string;
+    /** Function that builds the save endpoint URL. Default: `${baseUrl}/state/${key}` */
+    saveUrl?: (key: string) => string;
+    /** Function that builds the load endpoint URL. Default: `${baseUrl}/state/${key}` */
+    loadUrl?: (key: string) => string;
+    /** Function that builds the delete endpoint URL. Default: `${baseUrl}/state/${key}` */
+    deleteUrl?: (key: string) => string;
+    /**
+     * Custom headers to include in all requests (e.g. auth tokens).
+     * Can be a static object or a function that returns headers (sync or async).
+     */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** Custom fetch implementation (useful for testing or SSR). Defaults to global fetch. */
+    fetch?: typeof fetch;
+    /** Called when a request fails. Can be used for logging or error handling. */
+    onError?: (error: Error, operation: "save" | "load" | "delete", key: string) => void;
+}
+export declare class HttpStore implements PathStore {
+    private options;
+    constructor(options: HttpStoreOptions);
+    private getHeaders;
+    save(key: string, state: SerializedPathState): Promise<void>;
+    load(key: string): Promise<SerializedPathState | null>;
+    delete(key: string): Promise<void>;
+}
+export interface PersistenceOptions {
+    /** The store to persist state to. Any PathStore implementation works. */
+    store: PathStore;
+    /** Storage key that identifies this path's saved state. */
+    key: string;
+    /** When to automatically save. Defaults to `"onNext"`. */
+    strategy?: ObserverStrategy;
+    /**
+     * Debounce window in milliseconds. When > 0, rapid events are collapsed into
+     * a single save after the window expires. Only useful with `"onEveryChange"`.
+     * Defaults to 0 (no debouncing).
+     */
+    debounceMs?: number;
+    /** Called after every successful save. */
+    onSaveSuccess?: () => void;
+    /** Called when a save fails. The engine continues regardless. */
+    onSaveError?: (error: Error) => void;
+}
+/**
+ * Returns a `PathObserver` that automatically persists engine state to the
+ * provided store based on the chosen strategy.
+ *
+ * Works with any PathStore — HttpStore, LocalStorageStore, AsyncStorageStore,
+ * or a custom implementation.
+ *
+ * ```typescript
+ * const store = new LocalStorageStore();
+ * const engine = new PathEngine({
+ *   observers: [
+ *     persistence({ store, key: "user:123:onboarding", strategy: "onNext" }),
+ *   ],
+ * });
+ * ```
+ */
+export declare function persistence(options: PersistenceOptions): PathObserver;
+export interface RestoreOrStartOptions {
+    /** The store to load saved state from. Any PathStore implementation works. */
+    store: PathStore;
+    /** Storage key that identifies this path's saved state. */
+    key: string;
+    /** Path definition to start when no saved state exists. */
+    path: PathDefinition<any>;
+    /**
+     * Map of all path definitions that may appear in serialized state
+     * (active path + any sub-paths). Defaults to `{ [path.id]: path }`.
+     */
+    pathDefinitions?: Record<string, PathDefinition<any>>;
+    /** Initial data for a fresh (non-restored) start. Defaults to `{}`. */
+    initialData?: PathData;
+    /**
+     * Observers to wire on the engine before the first event fires.
+     * Build these explicitly — e.g. `persistence({ store, key })` — and
+     * pass them here. `restoreOrStart` does not create any observers itself.
+     */
+    observers?: PathObserver[];
+}
+/**
+ * Handles the load/restore-or-start pattern in a single call.
+ *
+ * Tries to load saved state from the store. If found, restores the engine
+ * to the saved position. If not found, starts a fresh path.
+ *
+ * ```typescript
+ * const store = new AsyncStorageStore({ storage: AsyncStorage });
+ * const key = "user:123:onboarding";
+ *
+ * const { engine, restored } = await restoreOrStart({
+ *   store,
+ *   key,
+ *   path: onboardingWizard,
+ *   initialData: { name: "", email: "" },
+ *   observers: [
+ *     persistence({ store, key, strategy: "onNext" }),
+ *   ],
+ * });
+ * ```
+ */
+export declare function restoreOrStart(options: RestoreOrStartOptions): Promise<{
+    engine: PathEngine;
+    restored: boolean;
+}>;
+export { matchesStrategy } from "@daltonr/pathwrite-core";
+export type { PathData, PathDefinition, PathEvent, PathObserver, PathEngineOptions, PathSnapshot, PathStep, PathStepContext, SerializedPathState, ObserverStrategy, PathStore, } from "@daltonr/pathwrite-core";
+export { LocalStorageStore } from "./local-store";
+export type { LocalStorageStoreOptions, StorageAdapter } from "./local-store";
+export { AsyncStorageStore } from "./async-store";
+export type { AsyncStorageStoreOptions, AsyncStorageAdapter } from "./async-store";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,228 @@
+/**
+ * @daltonr/pathwrite-store
+ *
+ * Persistence adapters and observer utilities for PathEngine state.
+ *
+ * Stores (implement PathStore):
+ *   - HttpStore        — persists to a REST API
+ *   - LocalStorageStore — persists to browser localStorage (or any sync key-value adapter)
+ *   - AsyncStorageStore — persists to any async key-value store (e.g. AsyncStorage on React Native)
+ *
+ * Observer utilities:
+ *   - persistence      — PathObserver factory; wires any PathStore to an engine's event stream
+ *   - restoreOrStart   — convenience factory for the load/restore-or-start pattern
+ *
+ * Bring your own store:
+ *   Implement the PathStore interface (save / load / delete) to use any backend —
+ *   MongoDB Atlas SDK, SQLite, MMKV, IndexedDB, or anything else.
+ */
+import { PathEngine, matchesStrategy } from "@daltonr/pathwrite-core";
+export class HttpStore {
+    options;
+    constructor(options) {
+        const baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.options = {
+            baseUrl,
+            saveUrl: options.saveUrl ?? ((key) => `${baseUrl}/state/${encodeURIComponent(key)}`),
+            loadUrl: options.loadUrl ?? ((key) => `${baseUrl}/state/${encodeURIComponent(key)}`),
+            deleteUrl: options.deleteUrl ?? ((key) => `${baseUrl}/state/${encodeURIComponent(key)}`),
+            fetch: options.fetch ?? fetch.bind(globalThis),
+            headers: options.headers,
+            onError: options.onError,
+        };
+    }
+    async getHeaders() {
+        if (!this.options.headers)
+            return {};
+        if (typeof this.options.headers === "function") {
+            return await this.options.headers();
+        }
+        return this.options.headers;
+    }
+    async save(key, state) {
+        try {
+            const url = this.options.saveUrl(key);
+            const headers = await this.getHeaders();
+            const response = await this.options.fetch(url, {
+                method: "PUT",
+                headers: { "Content-Type": "application/json", ...headers },
+                body: JSON.stringify(state),
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.options.onError?.(err, "save", key);
+            throw err;
+        }
+    }
+    async load(key) {
+        try {
+            const url = this.options.loadUrl(key);
+            const headers = await this.getHeaders();
+            const response = await this.options.fetch(url, {
+                method: "GET",
+                headers: { "Content-Type": "application/json", ...headers },
+            });
+            if (response.status === 404)
+                return null;
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            const data = await response.json();
+            return data;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.options.onError?.(err, "load", key);
+            throw err;
+        }
+    }
+    async delete(key) {
+        try {
+            const url = this.options.deleteUrl(key);
+            const headers = await this.getHeaders();
+            const response = await this.options.fetch(url, {
+                method: "DELETE",
+                headers: { ...headers },
+            });
+            if (response.status === 404)
+                return;
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.options.onError?.(err, "delete", key);
+            throw err;
+        }
+    }
+}
+/**
+ * Returns a `PathObserver` that automatically persists engine state to the
+ * provided store based on the chosen strategy.
+ *
+ * Works with any PathStore — HttpStore, LocalStorageStore, AsyncStorageStore,
+ * or a custom implementation.
+ *
+ * ```typescript
+ * const store = new LocalStorageStore();
+ * const engine = new PathEngine({
+ *   observers: [
+ *     persistence({ store, key: "user:123:onboarding", strategy: "onNext" }),
+ *   ],
+ * });
+ * ```
+ */
+export function persistence(options) {
+    const strategy = options.strategy ?? "onNext";
+    const debounceMs = options.debounceMs ?? 0;
+    let saveTimer = null;
+    let pendingSave = null;
+    const performSave = (engine) => {
+        if (pendingSave)
+            return pendingSave;
+        pendingSave = (async () => {
+            const state = engine.exportState();
+            if (!state)
+                return;
+            try {
+                await options.store.save(options.key, state);
+                options.onSaveSuccess?.();
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                options.onSaveError?.(err);
+            }
+        })().finally(() => { pendingSave = null; });
+        return pendingSave;
+    };
+    const scheduleSave = (engine) => {
+        if (debounceMs > 0) {
+            if (saveTimer)
+                clearTimeout(saveTimer);
+            saveTimer = setTimeout(() => {
+                saveTimer = null;
+                performSave(engine);
+            }, debounceMs);
+        }
+        else {
+            performSave(engine);
+        }
+    };
+    return (event, engine) => {
+        if (strategy === "onComplete") {
+            if (event.type === "completed") {
+                const finalState = {
+                    version: 1,
+                    pathId: event.pathId,
+                    currentStepIndex: -1,
+                    data: event.data,
+                    visitedStepIds: [],
+                    pathStack: [],
+                    _isNavigating: false,
+                };
+                options.store.save(options.key, finalState)
+                    .then(() => options.onSaveSuccess?.())
+                    .catch((error) => {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    options.onSaveError?.(err);
+                });
+            }
+            return;
+        }
+        if (matchesStrategy(strategy, event))
+            scheduleSave(engine);
+        if (event.type === "completed") {
+            options.store.delete(options.key).catch((err) => {
+                console.warn("[pathwrite] Failed to delete saved state after completion:", err);
+            });
+        }
+    };
+}
+/**
+ * Handles the load/restore-or-start pattern in a single call.
+ *
+ * Tries to load saved state from the store. If found, restores the engine
+ * to the saved position. If not found, starts a fresh path.
+ *
+ * ```typescript
+ * const store = new AsyncStorageStore({ storage: AsyncStorage });
+ * const key = "user:123:onboarding";
+ *
+ * const { engine, restored } = await restoreOrStart({
+ *   store,
+ *   key,
+ *   path: onboardingWizard,
+ *   initialData: { name: "", email: "" },
+ *   observers: [
+ *     persistence({ store, key, strategy: "onNext" }),
+ *   ],
+ * });
+ * ```
+ */
+export async function restoreOrStart(options) {
+    const observers = options.observers ?? [];
+    const pathDefs = options.pathDefinitions ?? { [options.path.id]: options.path };
+    const saved = await options.store.load(options.key);
+    let engine;
+    let restored;
+    if (saved) {
+        engine = PathEngine.fromState(saved, pathDefs, { observers });
+        restored = true;
+    }
+    else {
+        engine = new PathEngine({ observers });
+        await engine.start(options.path, options.initialData);
+        restored = false;
+    }
+    return { engine, restored };
+}
+// Re-export core types and utilities for convenience
+export { matchesStrategy } from "@daltonr/pathwrite-core";
+export { LocalStorageStore } from "./local-store";
+export { AsyncStorageStore } from "./async-store";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/local-store.d.ts

@@ -0,0 +1,51 @@
+import type { SerializedPathState, PathStore } from "@daltonr/pathwrite-core";
+/**
+ * Minimal interface for a synchronous key-value string storage backend.
+ * Both `localStorage` and `sessionStorage` satisfy this interface, as does
+ * any custom stub you inject for testing or SSR environments.
+ */
+export interface StorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    /**
+     * Return every key currently held in the storage backend.
+     * Required by `LocalStorageStore.list()` and `LocalStorageStore.clear()`.
+     * Implementations that don't need those methods may omit this.
+     */
+    getAllKeys?(): string[];
+}
+export interface LocalStorageStoreOptions {
+    /**
+     * Prefix prepended to every storage key to avoid collisions.
+     * Defaults to `"@daltonr/pathwrite:"`.
+     */
+    prefix?: string;
+    /**
+     * Storage backend to use.
+     * - Omit (or `undefined`): uses global `localStorage` when available, otherwise falls back to
+     *   an in-process memory store (useful in Node / test environments).
+     * - Pass a `StorageAdapter` (e.g. `sessionStorage`, or a custom stub): uses that object.
+     * - Pass `null`: forces the in-memory fallback regardless of environment.
+     */
+    storage?: StorageAdapter | null;
+}
+export declare class LocalStorageStore implements PathStore {
+    private prefix;
+    private storage;
+    constructor(options?: LocalStorageStoreOptions);
+    private storageKey;
+    save(key: string, state: SerializedPathState): Promise<void>;
+    load(key: string): Promise<SerializedPathState | null>;
+    delete(key: string): Promise<void>;
+    /**
+     * Returns every key stored under this store's prefix, decoded back to the
+     * original key strings passed to `save()`.
+     */
+    list(): Promise<string[]>;
+    /**
+     * Removes every entry stored under this store's prefix.
+     */
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=local-store.d.ts.map

package/dist/local-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-store.d.ts","sourceRoot":"","sources":["../src/local-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE9E;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,UAAU,CAAC,IAAI,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;CACjC;AAoBD,qBAAa,iBAAkB,YAAW,SAAS;IACjD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAiB;gBAEpB,OAAO,GAAE,wBAA6B;IAwBlD,OAAO,CAAC,UAAU;IAIZ,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ5D,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAUtD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAiB/B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAM7B"}

package/dist/local-store.js

@@ -0,0 +1,105 @@
+function createMemoryStorage() {
+    const map = new Map();
+    return {
+        getItem(key) {
+            return map.has(key) ? map.get(key) : null;
+        },
+        setItem(key, value) {
+            map.set(key, value);
+        },
+        removeItem(key) {
+            map.delete(key);
+        },
+        getAllKeys() {
+            return Array.from(map.keys());
+        },
+    };
+}
+export class LocalStorageStore {
+    prefix;
+    storage;
+    constructor(options = {}) {
+        this.prefix = options.prefix ?? "@daltonr/pathwrite:";
+        if (options.storage !== undefined) {
+            this.storage = options.storage !== null ? options.storage : createMemoryStorage();
+        }
+        else if (typeof localStorage !== "undefined") {
+            this.storage = {
+                getItem: (k) => localStorage.getItem(k),
+                setItem: (k, v) => localStorage.setItem(k, v),
+                removeItem: (k) => localStorage.removeItem(k),
+                getAllKeys: () => {
+                    const keys = [];
+                    for (let i = 0; i < localStorage.length; i++) {
+                        const k = localStorage.key(i);
+                        if (k !== null)
+                            keys.push(k);
+                    }
+                    return keys;
+                },
+            };
+        }
+        else {
+            this.storage = createMemoryStorage();
+        }
+    }
+    storageKey(key) {
+        return this.prefix + encodeURIComponent(key);
+    }
+    async save(key, state) {
+        try {
+            this.storage.setItem(this.storageKey(key), JSON.stringify(state));
+        }
+        catch (err) {
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    async load(key) {
+        try {
+            const raw = this.storage.getItem(this.storageKey(key));
+            if (raw === null || raw === undefined)
+                return null;
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    async delete(key) {
+        try {
+            this.storage.removeItem(this.storageKey(key));
+        }
+        catch (err) {
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    /**
+     * Returns every key stored under this store's prefix, decoded back to the
+     * original key strings passed to `save()`.
+     */
+    async list() {
+        if (!this.storage.getAllKeys) {
+            throw new Error("LocalStorageStore.list() requires the StorageAdapter to implement getAllKeys(). " +
+                "Add getAllKeys() to your custom adapter or use the built-in localStorage/memory backends.");
+        }
+        try {
+            return this.storage
+                .getAllKeys()
+                .filter((k) => k.startsWith(this.prefix))
+                .map((k) => decodeURIComponent(k.slice(this.prefix.length)));
+        }
+        catch (err) {
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    /**
+     * Removes every entry stored under this store's prefix.
+     */
+    async clear() {
+        const keys = await this.list();
+        for (const key of keys) {
+            await this.delete(key);
+        }
+    }
+}
+//# sourceMappingURL=local-store.js.map

package/dist/local-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-store.js","sourceRoot":"","sources":["../src/local-store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@daltonr/pathwrite-store",
+  "version": "0.9.0",
+  "description": "Persistence adapters for PathEngine — LocalStorageStore (browser), AsyncStorageStore (React Native / any async key-value store), and HttpStore (REST API)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "pathwrite",
+    "wizard",
+    "persistence",
+    "storage",
+    "http",
+    "localstorage",
+    "async-storage",
+    "react-native"
+  ],
+  "author": "Richard Dalton",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/daltonr/pathwrite.git",
+    "directory": "packages/store"
+  },
+  "dependencies": {
+    "@daltonr/pathwrite-core": "^0.9.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}