katanakit-js 2.2.1 → 2.12.9

package/dist/infrastructure/storage/storage.service.d.ts

@@ -1,48 +1,126 @@
 import type { StorageStrategy, StorageTarget } from "../../types/index.js";
 /**
- * Base strategy handling safe JSON serialization over a Web Storage backend.
- */
-declare abstract class WebStorageStrategy implements StorageStrategy {
-    private readonly storage;
-    protected constructor(storage: Storage);
-    useGetItem<T = unknown>(key: string): T | null;
-    useSetItem(key: string, value: unknown): void;
-    useRemoveItem(key: string): void;
-    useClear(): void;
-}
-/**
- * Concrete strategy backed by `window.localStorage`.
- */
-export declare class LocalStorageStrategy extends WebStorageStrategy {
-    constructor();
-}
-/**
- * Concrete strategy backed by `window.sessionStorage`.
- */
-export declare class SessionStorageStrategy extends WebStorageStrategy {
-    constructor();
-}
-/**
- * Concrete strategy backed by an in-memory store (SSR fallback).
- */
-export declare class MemoryStorageStrategy extends WebStorageStrategy {
-    constructor();
-}
-/**
- * Storage facade (Singleton + Strategy). Lazily picks browser storage or an
- * in-memory fallback so importing this module never crashes in SSR (Node/Bun).
- */
-export default class StorageService {
-    private static instance;
-    private strategies;
-    private constructor();
-    static getInstance(): StorageService;
-    private getStrategies;
-    useGetStorage: <T = unknown>(key: string, target?: StorageTarget) => T | null;
-    useSetStorage: (key: string, value: unknown, target?: StorageTarget) => void;
-    useRemoveStorage: (key: string, target?: StorageTarget) => void;
-    useClearStorage: (target?: StorageTarget) => void;
-}
-export declare const useClearStorage: (target?: StorageTarget) => void, useGetStorage: <T = unknown>(key: string, target?: StorageTarget) => T | null, useRemoveStorage: (key: string, target?: StorageTarget) => void, useSetStorage: (key: string, value: unknown, target?: StorageTarget) => void;
-export {};
+ * Creates a new in-memory `Storage` instance.
+ *
+ * @returns A fresh `MemoryStorage` that conforms to the Web Storage API.
+ *
+ * @example
+ * ```ts
+ * const mem = createMemoryStorage();
+ * mem.setItem("key", JSON.stringify({ a: 1 }));
+ * ```
+ */
+export declare function createMemoryStorage(): Storage;
+/**
+ * Creates a strategy backed by `window.localStorage`.
+ *
+ * @param storage - Optional storage instance (defaults to `window.localStorage`).
+ * @returns A {@link StorageStrategy}.
+ *
+ * @example
+ * ```ts
+ * const strategy = LocalStorageStrategy();
+ * strategy.useSetItem("token", "abc123");
+ * ```
+ */
+export declare function LocalStorageStrategy(storage?: Storage): StorageStrategy;
+/**
+ * Creates a strategy backed by `window.sessionStorage`.
+ *
+ * @param storage - Optional storage instance (defaults to `window.sessionStorage`).
+ * @returns A {@link StorageStrategy}.
+ *
+ * @example
+ * ```ts
+ * const strategy = SessionStorageStrategy();
+ * strategy.useSetItem("session", data);
+ * ```
+ */
+export declare function SessionStorageStrategy(storage?: Storage): StorageStrategy;
+/**
+ * Creates a strategy backed by an in-memory store (SSR / private-mode fallback).
+ *
+ * @returns A {@link StorageStrategy} using an in-memory `Storage` backend.
+ *
+ * @example
+ * ```ts
+ * const strategy = MemoryStorageStrategy();
+ * strategy.useSetItem("temp", "value");
+ * ```
+ */
+export declare function MemoryStorageStrategy(): StorageStrategy;
+/**
+ * Runs `fn` with request-isolated in-memory storage (SSR).
+ * Use this around a request handler so `useSetStorage` / `useGetStorage`
+ * share state within the request but not across requests.
+ *
+ * @typeParam T - Return type of `fn`.
+ * @param fn - The function to run within the storage scope.
+ * @returns The return value of `fn`.
+ *
+ * @example
+ * ```ts
+ * import { useRunStorageScope, useSetStorage, useGetStorage } from "katanakit-js";
+ *
+ * export default defineEventHandler((event) => {
+ *   return useRunStorageScope(() => {
+ *     useSetStorage("req-id", event.context.id);
+ *     return useGetStorage("req-id");
+ *   });
+ * });
+ * ```
+ */
+export declare function useRunStorageScope<T>(fn: () => T): T;
+/**
+ * Retrieves a value from storage by key.
+ *
+ * @typeParam T - Expected value type.
+ * @param key - The storage key.
+ * @param target - Which storage backend to use (default: `"localStorage"`).
+ * @returns The deserialized value, or `null` if not found.
+ *
+ * @example
+ * ```ts
+ * const token = useGetStorage<string>("auth_token");
+ * const session = useGetStorage<SessionData>("session", "sessionStorage");
+ * ```
+ */
+export declare const useGetStorage: <T = unknown>(key: string, target?: StorageTarget) => T | null;
+/**
+ * Stores a value under the given key (serialized as JSON).
+ *
+ * @param key - The storage key.
+ * @param value - The value to store.
+ * @param target - Which storage backend to use (default: `"localStorage"`).
+ *
+ * @example
+ * ```ts
+ * useSetStorage("auth_token", "abc123");
+ * useSetStorage("user", { name: "Alice" }, "sessionStorage");
+ * ```
+ */
+export declare const useSetStorage: (key: string, value: unknown, target?: StorageTarget) => void;
+/**
+ * Removes a value from storage by key.
+ *
+ * @param key - The storage key to remove.
+ * @param target - Which storage backend to use (default: `"localStorage"`).
+ *
+ * @example
+ * ```ts
+ * useRemoveStorage("auth_token");
+ * ```
+ */
+export declare const useRemoveStorage: (key: string, target?: StorageTarget) => void;
+/**
+ * Clears all values from the specified storage backend.
+ *
+ * @param target - Which storage backend to clear (default: `"localStorage"`).
+ *
+ * @example
+ * ```ts
+ * useClearStorage("sessionStorage");
+ * ```
+ */
+export declare const useClearStorage: (target?: StorageTarget) => void;
 //# sourceMappingURL=storage.service.d.ts.map

package/dist/infrastructure/storage/storage.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.service.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/storage/storage.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE3E;;GAEG;AACH,uBAAe,kBAAmB,YAAW,eAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAA9C,SAAS,aAA8B,OAAO,EAAE,OAAO,EAAI;IAE3D,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAO7C;IAED,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAG5C;IAED,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE/B;IAED,QAAQ,IAAI,IAAI,CAEf;CACD;AAiCD;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,kBAAkB;IAC3D,cAEC;CACD;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,kBAAkB;IAC7D,cAEC;CACD;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,kBAAkB;IAC5D,cAEC;CACD;AAED;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,cAAc;IAClC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiB;IACxC,OAAO,CAAC,UAAU,CAAuD;IAEzE,OAAO,eAAiB;IAExB,OAAc,WAAW,IAAI,cAAc,CAK1C;IAED,OAAO,CAAC,aAAa;IAWd,aAAa,GAAI,CAAC,GAAG,OAAO,OAC7B,MAAM,WACH,aAAa,KACnB,CAAC,GAAG,IAAI,CAAoD;IAExD,aAAa,QACd,MAAM,SACJ,OAAO,WACN,aAAa,KACnB,IAAI,CAAwD;IAExD,gBAAgB,QAAS,MAAM,WAAU,aAAa,KAAoB,IAAI,CACpC;IAE1C,eAAe,YAAY,aAAa,KAAoB,IAAI,CAC9B;CACzC;AAGD,eAAO,MAAQ,eAAe,YALK,aAAa,KAAoB,IAAI,EAKxC,aAAa,GAnBpB,CAAC,iBACnB,MAAM,WACH,aAAa,eAiBwB,gBAAgB,QAR9B,MAAM,WAAU,aAAa,KAAoB,IAAI,EAQrB,aAAa,QAbvE,MAAM,SACJ,OAAO,WACN,aAAa,KACnB,IAWyB,CAAC"}
+{"version":3,"file":"storage.service.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/storage/storage.service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA2F3E;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,OAA6B,GAAG,eAAe,CAE5F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,OAA+B,GAAG,eAAe,CAEhG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CAEvD;AA0ED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEpD;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,GAAG,OAAO,OACnC,MAAM,WACH,aAAa,KACnB,CAAC,GAAG,IAAkD,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,QACpB,MAAM,SACJ,OAAO,WACN,aAAa,KACnB,IAAsD,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,QAAS,MAAM,WAAU,aAAa,KAAoB,IAC5C,CAAC;AAE5C;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,YAAY,aAAa,KAAoB,IACtC,CAAC"}

package/dist/infrastructure/storage/storage.service.js

@@ -1,33 +1,63 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+// ============================================================
+// Strategy factories (plain objects implementing StorageStrategy)
+// ============================================================
 /**
- * Base strategy handling safe JSON serialization over a Web Storage backend.
+ * Creates a `StorageStrategy` backed by a Web Storage backend (`localStorage`
+ * or `sessionStorage`) with safe JSON serialization and error handling.
+ *
+ * @param storage - A native `Storage` instance (e.g. `window.localStorage`).
+ * @returns A {@link StorageStrategy} object.
  */
-class WebStorageStrategy {
-    storage;
-    constructor(storage) {
-        this.storage = storage;
-    }
-    useGetItem(key) {
-        try {
-            const raw = this.storage.getItem(key);
-            return raw ? JSON.parse(raw) : null;
-        }
-        catch {
-            return this.storage.getItem(key);
-        }
-    }
-    useSetItem(key, value) {
-        const serialized = typeof value === "string" ? value : JSON.stringify(value);
-        this.storage.setItem(key, serialized);
-    }
-    useRemoveItem(key) {
-        this.storage.removeItem(key);
-    }
-    useClear() {
-        this.storage.clear();
-    }
+function createWebStorageStrategy(storage) {
+    return {
+        useGetItem(key) {
+            try {
+                const raw = storage.getItem(key);
+                return raw ? JSON.parse(raw) : null;
+            }
+            catch {
+                try {
+                    return storage.getItem(key);
+                }
+                catch {
+                    return null;
+                }
+            }
+        },
+        useSetItem(key, value) {
+            try {
+                const serialized = typeof value === "string" ? value : JSON.stringify(value);
+                storage.setItem(key, serialized);
+            }
+            catch {
+                // Quota exceeded, private mode, or unavailable storage — ignore.
+            }
+        },
+        useRemoveItem(key) {
+            try {
+                storage.removeItem(key);
+            }
+            catch {
+                // Ignore unavailable storage.
+            }
+        },
+        useClear() {
+            try {
+                storage.clear();
+            }
+            catch {
+                // Ignore unavailable storage.
+            }
+        },
+    };
 }
+// ============================================================
+// In-memory Storage implementation
+// ============================================================
 /**
- * In-memory Web Storage implementation used as an SSR fallback.
+ * In-memory `Storage` implementation used as an SSR / private-mode fallback.
+ * Each instance owns its own Map — never share one across requests.
  */
 class MemoryStorage {
     store = new Map();
@@ -51,58 +81,198 @@ class MemoryStorage {
     }
 }
 /**
- * Concrete strategy backed by `window.localStorage`.
+ * Creates a new in-memory `Storage` instance.
+ *
+ * @returns A fresh `MemoryStorage` that conforms to the Web Storage API.
+ *
+ * @example
+ * ```ts
+ * const mem = createMemoryStorage();
+ * mem.setItem("key", JSON.stringify({ a: 1 }));
+ * ```
  */
-export class LocalStorageStrategy extends WebStorageStrategy {
-    constructor() {
-        super(window.localStorage);
-    }
+export function createMemoryStorage() {
+    return new MemoryStorage();
 }
+// ============================================================
+// Concrete strategy factories
+// ============================================================
 /**
- * Concrete strategy backed by `window.sessionStorage`.
+ * Creates a strategy backed by `window.localStorage`.
+ *
+ * @param storage - Optional storage instance (defaults to `window.localStorage`).
+ * @returns A {@link StorageStrategy}.
+ *
+ * @example
+ * ```ts
+ * const strategy = LocalStorageStrategy();
+ * strategy.useSetItem("token", "abc123");
+ * ```
  */
-export class SessionStorageStrategy extends WebStorageStrategy {
-    constructor() {
-        super(window.sessionStorage);
-    }
+export function LocalStorageStrategy(storage = window.localStorage) {
+    return createWebStorageStrategy(storage);
 }
 /**
- * Concrete strategy backed by an in-memory store (SSR fallback).
+ * Creates a strategy backed by `window.sessionStorage`.
+ *
+ * @param storage - Optional storage instance (defaults to `window.sessionStorage`).
+ * @returns A {@link StorageStrategy}.
+ *
+ * @example
+ * ```ts
+ * const strategy = SessionStorageStrategy();
+ * strategy.useSetItem("session", data);
+ * ```
  */
-export class MemoryStorageStrategy extends WebStorageStrategy {
-    constructor() {
-        super(new MemoryStorage());
-    }
+export function SessionStorageStrategy(storage = window.sessionStorage) {
+    return createWebStorageStrategy(storage);
 }
 /**
- * Storage facade (Singleton + Strategy). Lazily picks browser storage or an
- * in-memory fallback so importing this module never crashes in SSR (Node/Bun).
+ * Creates a strategy backed by an in-memory store (SSR / private-mode fallback).
+ *
+ * @returns A {@link StorageStrategy} using an in-memory `Storage` backend.
+ *
+ * @example
+ * ```ts
+ * const strategy = MemoryStorageStrategy();
+ * strategy.useSetItem("temp", "value");
+ * ```
  */
-export default class StorageService {
-    static instance;
-    strategies = null;
-    constructor() { }
-    static getInstance() {
-        if (!StorageService.instance) {
-            StorageService.instance = new StorageService();
-        }
-        return StorageService.instance;
+export function MemoryStorageStrategy() {
+    return createWebStorageStrategy(createMemoryStorage());
+}
+/** Request-scoped storage strategies for SSR (avoids cross-request leaks). */
+const ssrStorageAls = new AsyncLocalStorage();
+/** Lazily-initialized browser strategies (cached once). */
+let browserStrategies = null;
+function createMemoryStrategies() {
+    return {
+        localStorage: MemoryStorageStrategy(),
+        sessionStorage: MemoryStorageStrategy(),
+    };
+}
+function tryCreateBrowserStrategies() {
+    const local = tryCreateWebStorage("localStorage");
+    const session = tryCreateWebStorage("sessionStorage");
+    return {
+        localStorage: local ?? MemoryStorageStrategy(),
+        sessionStorage: session ?? MemoryStorageStrategy(),
+    };
+}
+/**
+ * Probes Web Storage availability (Safari private mode throws on setItem).
+ *
+ * @param kind - Which storage backend to probe.
+ * @returns A {@link StorageStrategy} or `null` if the backend is unavailable.
+ */
+function tryCreateWebStorage(kind) {
+    try {
+        const storage = window[kind];
+        const probeKey = "__kk_storage_probe__";
+        storage.setItem(probeKey, "1");
+        storage.removeItem(probeKey);
+        return kind === "localStorage" ? LocalStorageStrategy(storage) : SessionStorageStrategy(storage);
     }
-    getStrategies() {
-        if (!this.strategies) {
-            const hasWindow = typeof window !== "undefined";
-            this.strategies = {
-                localStorage: hasWindow ? new LocalStorageStrategy() : new MemoryStorageStrategy(),
-                sessionStorage: hasWindow ? new SessionStorageStrategy() : new MemoryStorageStrategy(),
-            };
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolves the active strategy map: browser strategies (cached), ALS-scoped
+ * strategies (SSR request), or ephemeral memory strategies (SSR fallback).
+ */
+function getStrategies() {
+    const hasWindow = typeof window !== "undefined";
+    if (hasWindow) {
+        if (!browserStrategies) {
+            browserStrategies = tryCreateBrowserStrategies();
         }
-        return this.strategies;
+        return browserStrategies;
     }
-    useGetStorage = (key, target = "localStorage") => this.getStrategies()[target].useGetItem(key);
-    useSetStorage = (key, value, target = "localStorage") => this.getStrategies()[target].useSetItem(key, value);
-    useRemoveStorage = (key, target = "localStorage") => this.getStrategies()[target].useRemoveItem(key);
-    useClearStorage = (target = "localStorage") => this.getStrategies()[target].useClear();
+    // SSR: prefer ALS-scoped strategies (isolated per request).
+    const scoped = ssrStorageAls.getStore();
+    if (scoped)
+        return scoped;
+    // No scope — ephemeral store (no cross-request leak, no cross-call persistence).
+    return createMemoryStrategies();
 }
-// Singleton instance and destructured exports.
-export const { useClearStorage, useGetStorage, useRemoveStorage, useSetStorage } = StorageService.getInstance();
+// ============================================================
+// Public API
+// ============================================================
+/**
+ * Runs `fn` with request-isolated in-memory storage (SSR).
+ * Use this around a request handler so `useSetStorage` / `useGetStorage`
+ * share state within the request but not across requests.
+ *
+ * @typeParam T - Return type of `fn`.
+ * @param fn - The function to run within the storage scope.
+ * @returns The return value of `fn`.
+ *
+ * @example
+ * ```ts
+ * import { useRunStorageScope, useSetStorage, useGetStorage } from "katanakit-js";
+ *
+ * export default defineEventHandler((event) => {
+ *   return useRunStorageScope(() => {
+ *     useSetStorage("req-id", event.context.id);
+ *     return useGetStorage("req-id");
+ *   });
+ * });
+ * ```
+ */
+export function useRunStorageScope(fn) {
+    return ssrStorageAls.run(createMemoryStrategies(), fn);
+}
+/**
+ * Retrieves a value from storage by key.
+ *
+ * @typeParam T - Expected value type.
+ * @param key - The storage key.
+ * @param target - Which storage backend to use (default: `"localStorage"`).
+ * @returns The deserialized value, or `null` if not found.
+ *
+ * @example
+ * ```ts
+ * const token = useGetStorage<string>("auth_token");
+ * const session = useGetStorage<SessionData>("session", "sessionStorage");
+ * ```
+ */
+export const useGetStorage = (key, target = "localStorage") => getStrategies()[target].useGetItem(key);
+/**
+ * Stores a value under the given key (serialized as JSON).
+ *
+ * @param key - The storage key.
+ * @param value - The value to store.
+ * @param target - Which storage backend to use (default: `"localStorage"`).
+ *
+ * @example
+ * ```ts
+ * useSetStorage("auth_token", "abc123");
+ * useSetStorage("user", { name: "Alice" }, "sessionStorage");
+ * ```
+ */
+export const useSetStorage = (key, value, target = "localStorage") => getStrategies()[target].useSetItem(key, value);
+/**
+ * Removes a value from storage by key.
+ *
+ * @param key - The storage key to remove.
+ * @param target - Which storage backend to use (default: `"localStorage"`).
+ *
+ * @example
+ * ```ts
+ * useRemoveStorage("auth_token");
+ * ```
+ */
+export const useRemoveStorage = (key, target = "localStorage") => getStrategies()[target].useRemoveItem(key);
+/**
+ * Clears all values from the specified storage backend.
+ *
+ * @param target - Which storage backend to clear (default: `"localStorage"`).
+ *
+ * @example
+ * ```ts
+ * useClearStorage("sessionStorage");
+ * ```
+ */
+export const useClearStorage = (target = "localStorage") => getStrategies()[target].useClear();
 //# sourceMappingURL=storage.service.js.map

package/dist/infrastructure/storage/storage.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.service.js","sourceRoot":"","sources":["../../../src/infrastructure/storage/storage.service.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAe,kBAAkB;IACO,OAAO;IAA9C,YAAuC,OAAgB;uBAAhB,OAAO;IAAY,CAAC;IAE3D,UAAU,CAAc,GAAW;QAClC,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACtC,OAAO,GAAG,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAO,CAAC,CAAC,CAAC,IAAI,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAiB,CAAC;QAClD,CAAC;IACF,CAAC;IAED,UAAU,CAAC,GAAW,EAAE,KAAc;QACrC,MAAM,UAAU,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC7E,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACvC,CAAC;IAED,aAAa,CAAC,GAAW;QACxB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,QAAQ;QACP,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACD;AAED;;GAEG;AACH,MAAM,aAAa;IACV,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1C,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACxB,CAAC;IAED,KAAK;QACJ,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;IAED,OAAO,CAAC,GAAW;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IACpC,CAAC;IAED,GAAG,CAAC,KAAa;QAChB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;IACrD,CAAC;IAED,UAAU,CAAC,GAAW;QACrB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,CAAC,GAAW,EAAE,KAAa;QACjC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC5B,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,kBAAkB;IAC3D;QACC,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAC5B,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,kBAAkB;IAC7D;QACC,KAAK,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAC9B,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,kBAAkB;IAC5D;QACC,KAAK,CAAC,IAAI,aAAa,EAAE,CAAC,CAAC;IAC5B,CAAC;CACD;AAED;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,cAAc;IAC1B,MAAM,CAAC,QAAQ,CAAiB;IAChC,UAAU,GAAkD,IAAI,CAAC;IAEzE,gBAAuB,CAAC;IAEjB,MAAM,CAAC,WAAW;QACxB,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,CAAC;YAC9B,cAAc,CAAC,QAAQ,GAAG,IAAI,cAAc,EAAE,CAAC;QAChD,CAAC;QACD,OAAO,cAAc,CAAC,QAAQ,CAAC;IAChC,CAAC;IAEO,aAAa;QACpB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACtB,MAAM,SAAS,GAAG,OAAO,MAAM,KAAK,WAAW,CAAC;YAChD,IAAI,CAAC,UAAU,GAAG;gBACjB,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC,CAAC,IAAI,qBAAqB,EAAE;gBAClF,cAAc,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,sBAAsB,EAAE,CAAC,CAAC,CAAC,IAAI,qBAAqB,EAAE;aACtF,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC;IACxB,CAAC;IAEM,aAAa,GAAG,CACtB,GAAW,EACX,MAAM,GAAkB,cAAc,EAC3B,EAAE,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,MAAM,CAAC,CAAC,UAAU,CAAI,GAAG,CAAC,CAAC;IAExD,aAAa,GAAG,CACtB,GAAW,EACX,KAAc,EACd,MAAM,GAAkB,cAAc,EAC/B,EAAE,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,MAAM,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAExD,gBAAgB,GAAG,CAAC,GAAW,EAAE,MAAM,GAAkB,cAAc,EAAQ,EAAE,CACvF,IAAI,CAAC,aAAa,EAAE,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAE1C,eAAe,GAAG,CAAC,MAAM,GAAkB,cAAc,EAAQ,EAAE,CACzE,IAAI,CAAC,aAAa,EAAE,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC;CACzC;AAED,+CAA+C;AAC/C,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,GAC/E,cAAc,CAAC,WAAW,EAAE,CAAC"}
+{"version":3,"file":"storage.service.js","sourceRoot":"","sources":["../../../src/infrastructure/storage/storage.service.ts"],"names":[],"mappings":"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"}

package/dist/infrastructure/theme/theme.service.d.ts

@@ -1,30 +1,94 @@
-import type { IThemeService, ThemeMode, ThemeOptions } from "../../types/index.js";
-/**
- * Theme facade (Singleton) over the DOM and Storage, with a media-query listener.
- */
-export declare class ThemeService implements IThemeService {
-    private static instance;
-    private mode;
-    private storageKey;
-    private attribute;
-    private target;
-    private onChange?;
-    private mediaQuery;
-    private cleanMediaQueryListener;
-    private constructor();
-    static getInstance(): ThemeService;
-    private IS_BROWSER;
-    useInitTheme: (options?: ThemeOptions) => void;
-    useSetThemeMode: (mode: ThemeMode) => void;
-    useGetThemeMode: () => ThemeMode;
-    useGetResolved: () => "light" | "dark";
-    usePrefersColorScheme: () => boolean;
-    useToggleTheme: () => void;
-    useResetTheme: () => void;
-    useDestroyTheme: () => void;
-    private APPLY_THEME;
-    private SETUP_MEDIA_QUERY_LISTENER;
-}
-export declare const THEME_SERVICE: ThemeService;
-export declare const useInitTheme: (options?: ThemeOptions) => void, useSetThemeMode: (mode: ThemeMode) => void, useGetThemeMode: () => ThemeMode, useGetResolved: () => "light" | "dark", usePrefersColorScheme: () => boolean, useToggleTheme: () => void, useResetTheme: () => void, useDestroyTheme: () => void;
+import type { ThemeMode, ThemeOptions } from "../../types/index.js";
+/**
+ * Initializes the theme system. Reads the stored preference (or falls back
+ * to `defaultMode`), applies the theme, and registers a system color-scheme
+ * listener for `"system"` mode.
+ *
+ * @param options - Configuration for the theme system.
+ *
+ * @example
+ * ```ts
+ * useInitTheme({
+ *   defaultMode: "dark",
+ *   storageKey: "app-theme",
+ *   onChange: (mode, resolved) => console.log(mode, resolved),
+ * });
+ * ```
+ */
+export declare const useInitTheme: (options?: ThemeOptions) => void;
+/**
+ * Sets the theme mode and persists it to storage.
+ *
+ * @param newMode - The desired theme mode (`"light"`, `"dark"`, or `"system"`).
+ *
+ * @example
+ * ```ts
+ * useSetThemeMode("dark");
+ * ```
+ */
+export declare const useSetThemeMode: (newMode: ThemeMode) => void;
+/**
+ * Returns the current theme mode (may be `"system"`).
+ *
+ * @returns The active {@link ThemeMode}.
+ *
+ * @example
+ * ```ts
+ * const current = useGetThemeMode(); // "light" | "dark" | "system"
+ * ```
+ */
+export declare const useGetThemeMode: () => ThemeMode;
+/**
+ * Returns the resolved theme (`"light"` or `"dark"`), accounting for system
+ * preference when mode is `"system"`.
+ *
+ * @returns The resolved color scheme.
+ *
+ * @example
+ * ```ts
+ * const scheme = useGetResolved(); // "light" or "dark"
+ * ```
+ */
+export declare const useGetResolved: () => "light" | "dark";
+/**
+ * Checks whether the user's OS is set to prefer a dark color scheme.
+ *
+ * @returns `true` if the system prefers dark mode.
+ *
+ * @example
+ * ```ts
+ * if (usePrefersColorScheme()) {
+ *   // user prefers dark
+ * }
+ * ```
+ */
+export declare const usePrefersColorScheme: () => boolean;
+/**
+ * Toggles between `"light"` and `"dark"` (ignores `"system"`).
+ *
+ * @example
+ * ```ts
+ * useToggleTheme(); // light -> dark, dark -> light
+ * ```
+ */
+export declare const useToggleTheme: () => void;
+/**
+ * Resets the theme to `"system"` and removes the stored preference.
+ *
+ * @example
+ * ```ts
+ * useResetTheme();
+ * ```
+ */
+export declare const useResetTheme: () => void;
+/**
+ * Cleans up the media-query listener. Call this when the theme system is
+ * no longer needed (e.g. during teardown in tests).
+ *
+ * @example
+ * ```ts
+ * useDestroyTheme();
+ * ```
+ */
+export declare const useDestroyTheme: () => void;
 //# sourceMappingURL=theme.service.d.ts.map