katanakit-js 2.2.1 → 2.12.9

package/dist/core/services/logger.service.d.ts

@@ -1,36 +1,102 @@
 import type { LogLevel, LogStrategy } from "../../types/index.js";
 /**
  * Concrete strategy: native console output.
+ * Pass an instance to {@link useSetStrategy} to redirect logs.
+ *
+ * @example
+ * ```ts
+ * import { ConsoleStrategy, useSetStrategy } from "katanakit-js";
+ *
+ * useSetStrategy(ConsoleStrategy);
+ * ```
  */
-export declare class ConsoleStrategy implements LogStrategy {
-    useOutput(level: LogLevel, message: string, data?: unknown): void;
-}
+export declare const ConsoleStrategy: LogStrategy;
 /**
- * Singleton context: holds the active strategy and keeps `this` bound through
- * arrow-function methods so destructured exports remain safe.
+ * Sets the active log level. Messages below this level are suppressed.
+ *
+ * @param level - The minimum log level to output.
+ *
+ * @example
+ * ```ts
+ * import { useSetLogLevel } from "katanakit-js";
+ *
+ * useSetLogLevel("warn"); // only warn and error will be output
+ * ```
  */
-export declare class LoggerService {
-    private static instance;
-    private strategy;
-    private constructor();
-    static getInstance(): LoggerService;
-    useSetStrategy: (strategy: LogStrategy) => void;
-    /**
-     * Overloads allow:
-     * - message only: `useLog("message")`
-     * - message + data: `useLog("message", { id: 1 })`
-     * - level + message + data: `useLog("error", "something failed", { code: 500 })`
-     */
-    useLog: {
-        (message: string, data?: unknown): void;
-        (level: LogLevel, message: string, data?: unknown): void;
-    };
-    useError: (message: string, data?: unknown) => void;
-    useClear: () => void;
-    useTable: (data: unknown) => void;
-}
-export declare const useClear: () => void, useLog: {
-    (message: string, data?: unknown): void;
-    (level: LogLevel, message: string, data?: unknown): void;
-}, useError: (message: string, data?: unknown) => void, useTable: (data: unknown) => void, useSetStrategy: (strategy: LogStrategy) => void;
+export declare function useSetLogLevel(level: LogLevel): void;
+/**
+ * Swaps the active log strategy (e.g. for tests or telemetry).
+ *
+ * @param newStrategy - A {@link LogStrategy} implementation.
+ *
+ * @example
+ * ```ts
+ * import { useSetStrategy } from "katanakit-js";
+ *
+ * useSetStrategy({
+ *   useOutput(level, message, data) {
+ *     // send to external telemetry
+ *   },
+ * });
+ * ```
+ */
+export declare function useSetStrategy(newStrategy: LogStrategy): void;
+/**
+ * Logs a message and/or data. Level is always the **last** argument.
+ *
+ * @param messageOrData - A string message or arbitrary data.
+ * @param dataOrLevel - Data to attach, or the log level.
+ * @param level - The log level when data is also provided.
+ *
+ * @example
+ * ```ts
+ * import { useLog } from "katanakit-js";
+ *
+ * useLog("Application started");
+ * useLog("Cache miss", "warn");
+ * useLog("Database timeout", { query: "SELECT 1" }, "error");
+ * useLog({ id: 1 }, "debug");
+ * ```
+ */
+export declare function useLog(messageOrData: unknown, dataOrLevel?: unknown, level?: LogLevel): void;
+/**
+ * Log a message with optional data and level.
+ *
+ * @param level - The log level ("log", "info", "warn", "error", "debug")
+ * @param message - The message to log
+ * @param data - Optional data to attach
+ *
+ * @example
+ * ```ts
+ * import { useLogger } from "katanakit-js";
+ *
+ * useLogger("info", "Application started");
+ * useLogger("error", "Database timeout", { query: "SELECT 1" });
+ * ```
+ */
+export declare function useLogger(level?: LogLevel, message?: unknown, data?: unknown): void;
+/**
+ * Clears the console.
+ *
+ * @example
+ * ```ts
+ * import { useLoggerClear } from "katanakit-js";
+ *
+ * useLoggerClear();
+ * ```
+ */
+export declare function useLoggerClear(): void;
+/**
+ * Displays tabular data in the console.
+ *
+ * @param data - The data to display as a table.
+ *
+ * @example
+ * ```ts
+ * import { useLoggerTable } from "katanakit-js";
+ *
+ * useLoggerTable([{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]);
+ * ```
+ */
+export declare function useLoggerTable(data: unknown): void;
 //# sourceMappingURL=logger.service.d.ts.map

package/dist/core/services/logger.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/logger.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAElE;;GAEG;AACH,qBAAa,eAAgB,YAAW,WAAW;IAClD,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAMhE;CACD;AAED;;;GAGG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAc;IAE9B,OAAO,eAEN;IAED,OAAc,WAAW,IAAI,aAAa,CAKzC;IAEM,cAAc,aAAc,WAAW,KAAG,IAAI,CAEnD;IAEF;;;;;OAKG;IACI,MAAM,EAAE;QACd,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;QACxC,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;KACzD,CAWC;IAEK,QAAQ,YAAa,MAAM,SAAS,OAAO,KAAG,IAAI,CAEvD;IAEK,QAAQ,QAAO,IAAI,CAExB;IAEK,QAAQ,SAAU,OAAO,KAAG,IAAI,CAErC;CACF;AAGD,eAAO,MAAQ,QAAQ,QAVA,IAAI,EAUF,MAAM;cA7BnB,MAAM,SAAS,OAAO,GAAG,IAAI;YAC/B,QAAQ,WAAW,MAAM,SAAS,OAAO,GAAG,IAAI;GA4BzB,QAAQ,YAdZ,MAAM,SAAS,OAAO,KAAG,IAAI,EAcf,QAAQ,SANzB,OAAO,KAAG,IAAI,EAMa,cAAc,aAxC/B,WAAW,KAAG,IAyCtB,CAAC"}
+{"version":3,"file":"logger.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/logger.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAOlE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,EAAE,WAe7B,CAAC;AAsBF;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEpD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAE7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,aAAa,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,IAAI,CA+B5F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,KAAK,GAAE,QAAgB,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAE1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAElD"}

package/dist/core/services/logger.service.js

@@ -1,60 +1,186 @@
+const LOG_LEVELS = ["log", "info", "warn", "error", "debug"];
+const isLogLevel = (value) => typeof value === "string" && LOG_LEVELS.includes(value);
 /**
  * Concrete strategy: native console output.
+ * Pass an instance to {@link useSetStrategy} to redirect logs.
+ *
+ * @example
+ * ```ts
+ * import { ConsoleStrategy, useSetStrategy } from "katanakit-js";
+ *
+ * useSetStrategy(ConsoleStrategy);
+ * ```
  */
-export class ConsoleStrategy {
+export const ConsoleStrategy = {
+    /**
+     * Outputs a log message to the native console.
+     *
+     * @param level - The log level (`log`, `info`, `warn`, `error`, `debug`).
+     * @param message - The message string.
+     * @param data - Optional data to attach to the log.
+     */
     useOutput(level, message, data) {
         if (data !== undefined) {
             console[level](`[${level.toUpperCase()}] ${message}`, data);
             return;
         }
         console[level](`[${level.toUpperCase()}] ${message}`);
-    }
+    },
+};
+/** Log level priority (lower = more verbose). */
+const LEVEL_PRIORITY = {
+    debug: 0,
+    log: 1,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+/** Module-level log level. Defaults to `"info"`. */
+let logLevel = "info";
+/** Module-level log strategy. Defaults to {@link ConsoleStrategy}. */
+let strategy = ConsoleStrategy;
+/** Check if a message at the given level should be output. */
+function shouldLog(level) {
+    return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[logLevel];
+}
+/**
+ * Sets the active log level. Messages below this level are suppressed.
+ *
+ * @param level - The minimum log level to output.
+ *
+ * @example
+ * ```ts
+ * import { useSetLogLevel } from "katanakit-js";
+ *
+ * useSetLogLevel("warn"); // only warn and error will be output
+ * ```
+ */
+export function useSetLogLevel(level) {
+    logLevel = level;
+}
+/**
+ * Swaps the active log strategy (e.g. for tests or telemetry).
+ *
+ * @param newStrategy - A {@link LogStrategy} implementation.
+ *
+ * @example
+ * ```ts
+ * import { useSetStrategy } from "katanakit-js";
+ *
+ * useSetStrategy({
+ *   useOutput(level, message, data) {
+ *     // send to external telemetry
+ *   },
+ * });
+ * ```
+ */
+export function useSetStrategy(newStrategy) {
+    strategy = newStrategy;
 }
 /**
- * Singleton context: holds the active strategy and keeps `this` bound through
- * arrow-function methods so destructured exports remain safe.
+ * Logs a message and/or data. Level is always the **last** argument.
+ *
+ * @param messageOrData - A string message or arbitrary data.
+ * @param dataOrLevel - Data to attach, or the log level.
+ * @param level - The log level when data is also provided.
+ *
+ * @example
+ * ```ts
+ * import { useLog } from "katanakit-js";
+ *
+ * useLog("Application started");
+ * useLog("Cache miss", "warn");
+ * useLog("Database timeout", { query: "SELECT 1" }, "error");
+ * useLog({ id: 1 }, "debug");
+ * ```
  */
-export class LoggerService {
-    static instance;
-    strategy;
-    constructor() {
-        this.strategy = new ConsoleStrategy();
+export function useLog(messageOrData, dataOrLevel, level) {
+    // If level is explicitly provided, use it
+    if (level !== undefined) {
+        if (!shouldLog(level))
+            return;
+        const message = typeof messageOrData === "string" ? messageOrData : String(messageOrData);
+        strategy.useOutput(level, message, dataOrLevel);
+        return;
     }
-    static getInstance() {
-        if (!LoggerService.instance) {
-            LoggerService.instance = new LoggerService();
+    if (dataOrLevel === undefined) {
+        if (!shouldLog("info"))
+            return;
+        if (typeof messageOrData === "string") {
+            strategy.useOutput("info", messageOrData);
         }
-        return LoggerService.instance;
+        else {
+            strategy.useOutput("info", "", messageOrData);
+        }
+        return;
     }
-    useSetStrategy = (strategy) => {
-        this.strategy = strategy;
-    };
-    /**
-     * Overloads allow:
-     * - message only: `useLog("message")`
-     * - message + data: `useLog("message", { id: 1 })`
-     * - level + message + data: `useLog("error", "something failed", { code: 500 })`
-     */
-    useLog = (param1, param2, param3) => {
-        const levels = ["log", "info", "warn", "error", "debug"];
-        if (levels.includes(param1)) {
-            const level = param1;
-            const message = typeof param2 === "string" ? param2 : String(param2 ?? "");
-            this.strategy.useOutput(level, message, param3);
+    if (isLogLevel(dataOrLevel)) {
+        if (!shouldLog(dataOrLevel))
             return;
+        if (typeof messageOrData === "string") {
+            strategy.useOutput(dataOrLevel, messageOrData);
         }
-        this.strategy.useOutput("info", param1, param2);
-    };
-    useError = (message, data) => {
-        this.strategy.useOutput("error", message, data);
-    };
-    useClear = () => {
-        console.clear();
-    };
-    useTable = (data) => {
-        console.table(data);
-    };
+        else {
+            strategy.useOutput(dataOrLevel, "", messageOrData);
+        }
+    }
+    else {
+        if (!shouldLog("info"))
+            return;
+        const message = typeof messageOrData === "string" ? messageOrData : String(messageOrData);
+        strategy.useOutput("info", message, dataOrLevel);
+    }
+}
+/**
+ * Log a message with optional data and level.
+ *
+ * @param level - The log level ("log", "info", "warn", "error", "debug")
+ * @param message - The message to log
+ * @param data - Optional data to attach
+ *
+ * @example
+ * ```ts
+ * import { useLogger } from "katanakit-js";
+ *
+ * useLogger("info", "Application started");
+ * useLogger("error", "Database timeout", { query: "SELECT 1" });
+ * ```
+ */
+export function useLogger(level = "log", message, data) {
+    useLog(message, data, level);
+}
+/**
+ * Clears the console.
+ *
+ * @example
+ * ```ts
+ * import { useLoggerClear } from "katanakit-js";
+ *
+ * useLoggerClear();
+ * ```
+ */
+export function useLoggerClear() {
+    console.clear();
+}
+/**
+ * Displays tabular data in the console.
+ *
+ * @param data - The data to display as a table.
+ *
+ * @example
+ * ```ts
+ * import { useLoggerTable } from "katanakit-js";
+ *
+ * useLoggerTable([{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]);
+ * ```
+ */
+export function useLoggerTable(data) {
+    console.table(data);
 }
-// Singleton instance and destructured exports.
-export const { useClear, useLog, useError, useTable, useSetStrategy } = LoggerService.getInstance();
+useLoggerTable([
+    {
+        id: 1,
+        name: "Alice",
+    },
+]);
 //# sourceMappingURL=logger.service.js.map

package/dist/core/services/logger.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.service.js","sourceRoot":"","sources":["../../../src/core/services/logger.service.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,eAAe;IAC3B,SAAS,CAAC,KAAe,EAAE,OAAe,EAAE,IAAc;QACzD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,WAAW,EAAE,KAAK,OAAO,EAAE,EAAE,IAAI,CAAC,CAAC;YAC5D,OAAO;QACR,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,WAAW,EAAE,KAAK,OAAO,EAAE,CAAC,CAAC;IACvD,CAAC;CACD;AAED;;;GAGG;AACH,MAAM,OAAO,aAAa;IACjB,MAAM,CAAC,QAAQ,CAAgB;IAC/B,QAAQ,CAAc;IAE9B;QACC,IAAI,CAAC,QAAQ,GAAG,IAAI,eAAe,EAAE,CAAC;IACvC,CAAC;IAEM,MAAM,CAAC,WAAW;QACxB,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC;YAC7B,aAAa,CAAC,QAAQ,GAAG,IAAI,aAAa,EAAE,CAAC;QAC9C,CAAC;QACD,OAAO,aAAa,CAAC,QAAQ,CAAC;IAC/B,CAAC;IAEM,cAAc,GAAG,CAAC,QAAqB,EAAQ,EAAE;QACvD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC1B,CAAC,CAAC;IAEF;;;;;OAKG;IACI,MAAM,GAGT,CAAC,MAAyB,EAAE,MAAgB,EAAE,MAAgB,EAAQ,EAAE;QAC3E,MAAM,MAAM,GAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAErE,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAkB,CAAC,EAAE,CAAC;YACzC,MAAM,KAAK,GAAG,MAAkB,CAAC;YACjC,MAAM,OAAO,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;YAC3E,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YAChD,OAAO;QACR,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,CAAC,CAAC;IAEK,QAAQ,GAAG,CAAC,OAAe,EAAE,IAAc,EAAQ,EAAE;QAC3D,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACjD,CAAC,CAAC;IAEK,QAAQ,GAAG,GAAS,EAAE;QAC5B,OAAO,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC,CAAC;IAEK,QAAQ,GAAG,CAAC,IAAa,EAAQ,EAAE;QACzC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC,CAAC;CACF;AAED,+CAA+C;AAC/C,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,GACpE,aAAa,CAAC,WAAW,EAAE,CAAC"}
+{"version":3,"file":"logger.service.js","sourceRoot":"","sources":["../../../src/core/services/logger.service.ts"],"names":[],"mappings":"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"}

package/dist/core/services/reactive.service.d.ts

@@ -1,22 +1,149 @@
-import type { IReactiveService, SignalGetter, SignalSetter, StorageTarget, Subscribable, ToggleSignalSetter } from "../../types/index.js";
+import type { SignalGetter, SignalSetter, StorageTarget, Subscribable, ToggleSignalSetter } from "../../types/index.js";
 /**
- * Minimal reactive kernel (Observer / Publisher-Subscriber) implemented as a
- * Facade + Singleton. Signals are closures with explicit dependency tracking.
+ * Creates a reactive signal with a getter and setter.
+ *
+ * The getter is callable and also exposes a `useSubscribe` method for
+ * listening to value changes. The setter accepts either a direct value or
+ * an updater function.
+ *
+ * @typeParam T - The signal value type.
+ * @param initialValue - The initial value of the signal.
+ * @returns A tuple of `[getter, setter]`.
+ *
+ * @example
+ * ```ts
+ * const [count, setCount] = useCreateSignal(0);
+ * count(); // 0
+ * setCount(1);
+ * count(); // 1
+ * setCount(prev => prev + 1);
+ * count(); // 2
+ *
+ * const unsub = count.useSubscribe((newVal, oldVal) => {
+ *   console.log(`${oldVal} -> ${newVal}`);
+ * });
+ * ```
  */
-export default class ReactiveService implements IReactiveService {
-    private static instance;
-    private isBatching;
-    private batchQueue;
-    private constructor();
-    static getInstance(): ReactiveService;
-    private NOTIFY;
-    useCreateSignal: <T>(initialValue: T) => [SignalGetter<T>, SignalSetter<T>];
-    useCreateEffect: (callback: () => void | (() => void), signals: Subscribable<unknown>[]) => (() => void);
-    useCreateMemo: <T>(computation: () => T, signals: Subscribable<unknown>[]) => SignalGetter<T>;
-    useCreateToggle: (initialValue?: boolean) => [SignalGetter<boolean>, ToggleSignalSetter];
-    useCreateStorageSignal: <T>(key: string, fallbackValue: T, target?: StorageTarget) => [SignalGetter<T>, SignalSetter<T>];
-    useCreateDebouncedSignal: <T>(initialValue: T, delayMs?: number) => [SignalGetter<T>, SignalSetter<T>];
-    useCreateBatch: () => ((callback: () => void) => void);
-}
-export declare const useCreateSignal: <T>(initialValue: T) => [SignalGetter<T>, SignalSetter<T>], useCreateEffect: (callback: () => void | (() => void), signals: Subscribable<unknown>[]) => (() => void), useCreateMemo: <T>(computation: () => T, signals: Subscribable<unknown>[]) => SignalGetter<T>, useCreateToggle: (initialValue?: boolean) => [SignalGetter<boolean>, ToggleSignalSetter], useCreateStorageSignal: <T>(key: string, fallbackValue: T, target?: StorageTarget) => [SignalGetter<T>, SignalSetter<T>], useCreateDebouncedSignal: <T>(initialValue: T, delayMs?: number) => [SignalGetter<T>, SignalSetter<T>], useCreateBatch: () => ((callback: () => void) => void);
+export declare function useCreateSignal<T>(initialValue: T): [SignalGetter<T>, SignalSetter<T>];
+/**
+ * Creates a side effect that re-runs whenever any of the provided signals
+ * emit a new value. An optional cleanup function returned from the callback
+ * is invoked before each re-run and on disposal.
+ *
+ * @param callback - Effect body. May return a cleanup function.
+ * @param signals - Array of subscribable signals to react to.
+ * @returns A dispose function that tears down all subscriptions and runs
+ *   the final cleanup.
+ *
+ * @example
+ * ```ts
+ * const [name, setName] = useCreateSignal("world");
+ * const dispose = useCreateEffect(() => {
+ *   console.log(`Hello, ${name()}!`);
+ *   return () => console.log("cleaning up");
+ * }, [name]);
+ *
+ * setName("Katana"); // logs "Hello, Katana!"
+ * dispose();         // logs "cleaning up"
+ * ```
+ */
+export declare function useCreateEffect(callback: () => void | (() => void), signals: Subscribable<unknown>[]): () => void;
+/**
+ * Creates a memoised signal whose value is derived from a computation.
+ * The computation re-runs whenever any of the provided signals change.
+ *
+ * @typeParam T - The computed value type.
+ * @param computation - Pure function that derives the value.
+ * @param signals - Signals the computation depends on.
+ * @returns A read-only getter for the memoised value.
+ *
+ * @example
+ * ```ts
+ * const [a, setA] = useCreateSignal(2);
+ * const [b, setB] = useCreateSignal(3);
+ * const sum = useCreateMemo(() => a() + b(), [a, b]);
+ * sum(); // 5
+ * setA(10);
+ * sum(); // 13
+ * ```
+ */
+export declare function useCreateMemo<T>(computation: () => T, signals: Subscribable<unknown>[]): SignalGetter<T>;
+/**
+ * Creates a boolean toggle signal.
+ *
+ * @param initialValue - Starting value (defaults to `false`).
+ * @returns A tuple of `[getter, { useSet, useToggle }]`.
+ *
+ * @example
+ * ```ts
+ * const [isOpen, { useSet, useToggle }] = useCreateToggle();
+ * isOpen();    // false
+ * useToggle();
+ * isOpen();    // true
+ * useSet(false);
+ * isOpen();    // false
+ * ```
+ */
+export declare function useCreateToggle(initialValue?: boolean): [SignalGetter<boolean>, ToggleSignalSetter];
+/**
+ * Creates a signal that persists its value to a storage backend
+ * (localStorage, sessionStorage, etc.). Reads the initial value from
+ * storage on creation.
+ *
+ * @typeParam T - The signal value type.
+ * @param key - Storage key.
+ * @param fallbackValue - Value used when the key is not in storage.
+ * @param target - Storage backend (defaults to `"localStorage"`).
+ * @returns A tuple of `[getter, setter]`. The setter writes through to
+ *   storage.
+ *
+ * @example
+ * ```ts
+ * const [theme, setTheme] = useCreateStorageSignal("theme", "dark");
+ * theme(); // "dark" (or whatever was stored)
+ * setTheme("light"); // persists to localStorage
+ * ```
+ */
+export declare function useCreateStorageSignal<T>(key: string, fallbackValue: T, target?: StorageTarget): [SignalGetter<T>, SignalSetter<T>];
+/**
+ * Creates a signal whose setter debounces writes by `delayMs` milliseconds.
+ * Useful for search inputs or any value that triggers expensive work.
+ *
+ * @typeParam T - The signal value type.
+ * @param initialValue - The initial value.
+ * @param delayMs - Debounce delay in milliseconds (defaults to `300`).
+ * @returns A tuple of `[getter, debouncedSetter]`. The setter exposes a
+ *   `useCancel()` method to abort a pending write.
+ *
+ * @example
+ * ```ts
+ * const [query, setQuery] = useCreateDebouncedSignal("", 250);
+ * setQuery("hello"); // won't update until 250ms of quiet
+ * setQuery.useCancel(); // abort pending write
+ * ```
+ */
+export declare function useCreateDebouncedSignal<T>(initialValue: T, delayMs?: number): [SignalGetter<T>, SignalSetter<T> & {
+    useCancel: () => void;
+}];
+/**
+ * Returns a batch function that defers signal notifications until the
+ * callback completes. Nested calls are supported -- only the outermost
+ * batch flushes the queue.
+ *
+ * @returns A `batch(callback)` function.
+ *
+ * @example
+ * ```ts
+ * const batch = useCreateBatch();
+ * const [a, setA] = useCreateSignal(0);
+ * const [b, setB] = useCreateSignal(0);
+ *
+ * batch(() => {
+ *   setA(1);
+ *   setB(2);
+ *   // listeners fire only once here, not twice
+ * });
+ * ```
+ */
+export declare function useCreateBatch(): (callback: () => void) => void;
 //# sourceMappingURL=reactive.service.d.ts.map

package/dist/core/services/reactive.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reactive.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/reactive.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,gBAAgB,EAChB,YAAY,EAEZ,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,MAAM,sBAAsB,CAAC;AAG9B;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,eAAgB,YAAW,gBAAgB;IAC/D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkB;IAEzC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAA8B;IAEhD,OAAO,eAAiB;IAExB,OAAc,WAAW,IAAI,eAAe,CAK3C;IAED,OAAO,CAAC,MAAM,CAMZ;IAEK,eAAe,GAAI,CAAC,gBAAgB,CAAC,KAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CA+B/E;IAEK,eAAe,aACX,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,WAC1B,YAAY,CAAC,OAAO,CAAC,EAAE,KAC9B,CAAC,MAAM,IAAI,CAAC,CAwCb;IAEK,aAAa,GAAI,CAAC,eACX,MAAM,CAAC,WACX,YAAY,CAAC,OAAO,CAAC,EAAE,KAC9B,YAAY,CAAC,CAAC,CAAC,CAQhB;IAEK,eAAe,8BAA2B,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC,CAK1F;IAEK,sBAAsB,GAAI,CAAC,OAC5B,MAAM,iBACI,CAAC,WACR,aAAa,KACnB,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CA6BnC;IAEK,wBAAwB,GAAI,CAAC,gBACrB,CAAC,uBAEb,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAgBnC;IAEK,cAAc,QAAO,CAAC,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC,CAgB1D;CACF;AAGD,eAAO,MACN,eAAe,GA/KW,CAAC,0DAgL3B,eAAe,aA9IJ,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,WAC1B,YAAY,CAAC,OAAO,CAAC,EAAE,KAC9B,CAAC,MAAM,IAAI,CAAC,EA6If,aAAa,GAnGW,CAAC,iCAEf,YAAY,CAAC,OAAO,CAAC,EAAE,sBAkGjC,eAAe,8BAvFkC,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC,EAwF5F,sBAAsB,GAjFW,CAAC,OAC5B,MAAM,6BAEH,aAAa,yCA+EtB,wBAAwB,GA/CW,CAAC,4EAgDpC,cAAc,QA3Bc,CAAC,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CA4BV,CAAC"}
+{"version":3,"file":"reactive.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/reactive.service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,YAAY,EAEZ,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,MAAM,sBAAsB,CAAC;AAsB9B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CA+BtF;AAOD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAC9B,QAAQ,EAAE,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,EACnC,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,GAC9B,MAAM,IAAI,CAwCZ;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC9B,WAAW,EAAE,MAAM,CAAC,EACpB,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,GAC9B,YAAY,CAAC,CAAC,CAAC,CAQjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,YAAY,UAAQ,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC,CAKjG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACvC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,CAAC,EAChB,MAAM,GAAE,aAA8B,GACpC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CA6BpC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EACzC,YAAY,EAAE,CAAC,EACf,OAAO,SAAM,GACX,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG;IAAE,SAAS,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC,CAuBhE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,IAAI,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAmB/D"}