katanakit-js 2.2.1 → 2.12.9

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

@@ -1,44 +1,229 @@
-import type { IAppUtils, IDataUtils, ISystemUtils } from "../../types/index.js";
-/**
- * Data utilities implemented as a Singleton.
- */
-export declare class DataUtils implements IDataUtils {
-    private static instance;
-    private constructor();
-    static getInstance(): DataUtils;
-    useUnique: <T>(array: T[]) => T[];
-    useChunk: <T>(array: T[], size: number) => T[][];
-    useGroupBy: <T>(array: T[], key: keyof T | ((item: T) => string)) => Record<string, T[]>;
-    useIsObject: (item: unknown) => item is Record<string, unknown>;
-    useDeepClone: <T>(value: T) => T;
-    useDeepMerge: <T extends Record<string, unknown>>(target: T, source: Record<string, unknown>) => T;
-    usePick: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>;
-    useOmit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
-}
-/**
- * System utilities implemented as a Singleton.
- */
-export declare class SystemUtils implements ISystemUtils {
-    private static instance;
-    private constructor();
-    static getInstance(): SystemUtils;
-    useSleep: (ms: number) => Promise<void>;
-    useRetry: <T>(fn: () => Promise<T>, retries?: number, delayMs?: number) => Promise<T>;
-    useCopyToClipboard: (text: string) => Promise<boolean>;
-    useGetUrlParams: (urlString: string) => Record<string, string>;
-    useRound: (value: string | number, decimals?: number) => number;
-    useAverage: (numbers: number[]) => number;
-}
-/**
- * Main facade composing data and system utilities.
- */
-export declare class AppUtils implements IAppUtils {
-    private static instance;
-    readonly data: IDataUtils;
-    readonly system: ISystemUtils;
-    private constructor();
-    static getInstance(): AppUtils;
-}
-export declare const useUnique: <T>(array: T[]) => T[], useChunk: <T>(array: T[], size: number) => T[][], useGroupBy: <T>(array: T[], key: ((item: T) => string) | keyof T) => Record<string, T[]>, useIsObject: (item: unknown) => item is Record<string, unknown>, useDeepClone: <T>(value: T) => T, useDeepMerge: <T extends Record<string, unknown>>(target: T, source: Record<string, unknown>) => T, usePick: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>, useOmit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
-export declare const useSleep: (ms: number) => Promise<void>, useRetry: <T>(fn: () => Promise<T>, retries?: number, delayMs?: number) => Promise<T>, useCopyToClipboard: (text: string) => Promise<boolean>, useGetUrlParams: (urlString: string) => Record<string, string>, useRound: (value: string | number, decimals?: number) => number, useAverage: (numbers: number[]) => number;
+/**
+ * Returns a new array with duplicate values removed, preserving first-seen order.
+ *
+ * @typeParam T - Element type.
+ * @param array - The input array.
+ * @returns A new array with unique values.
+ *
+ * @example
+ * ```ts
+ * useUnique([1, 2, 2, 3, 1]); // [1, 2, 3]
+ * useUnique(["a", "b", "a"]); // ["a", "b"]
+ * ```
+ */
+export declare function useUnique<T>(array: T[]): T[];
+/**
+ * Splits an array into chunks of the given size.
+ *
+ * @typeParam T - Element type.
+ * @param array - The input array.
+ * @param size - Number of elements per chunk (must be > 0).
+ * @returns An array of chunks.
+ * @throws {Error} If `size` is less than or equal to 0.
+ *
+ * @example
+ * ```ts
+ * useChunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ * useChunk(["a", "b", "c"], 1);  // [["a"], ["b"], ["c"]]
+ * ```
+ */
+export declare function useChunk<T>(array: T[], size: number): T[][];
+/**
+ * Groups array items by a key property or key selector function.
+ *
+ * @typeParam T - Element type.
+ * @param array - The input array.
+ * @param key - A property name or a function that returns the group key.
+ * @returns An object mapping group keys to arrays of items.
+ *
+ * @example
+ * ```ts
+ * const items = [
+ *   { type: "fruit", name: "apple" },
+ *   { type: "veggie", name: "carrot" },
+ *   { type: "fruit", name: "banana" },
+ * ];
+ * useGroupBy(items, "type");
+ * // { fruit: [{ type: "fruit", name: "apple" }, { type: "fruit", name: "banana" }], veggie: [...] }
+ *
+ * useGroupBy(items, (item) => item.type.toUpperCase());
+ * // { FRUIT: [...], VEGGIE: [...] }
+ * ```
+ */
+export declare function useGroupBy<T>(array: T[], key: keyof T | ((item: T) => string)): Record<string, T[]>;
+/**
+ * Type guard that checks whether a value is a plain object (not null, not
+ * an array).
+ *
+ * @param item - The value to test.
+ * @returns `true` if the value is a plain `Record<string, unknown>`.
+ *
+ * @example
+ * ```ts
+ * useIsObject({ a: 1 });       // true
+ * useIsObject([1, 2]);          // false
+ * useIsObject(null);            // false
+ * useIsObject("hello");         // false
+ * ```
+ */
+export declare function useIsObject(item: unknown): item is Record<string, unknown>;
+/**
+ * Deep clones a value using `structuredClone` with a JSON fallback for
+ * environments that do not support it.
+ *
+ * @typeParam T - Value type.
+ * @param value - The value to clone.
+ * @returns A deep copy of the value.
+ *
+ * @example
+ * ```ts
+ * const original = { a: { b: 1 } };
+ * const copy = useDeepClone(original);
+ * copy.a.b = 2;
+ * original.a.b; // 1 (unchanged)
+ * ```
+ */
+export declare function useDeepClone<T>(value: T): T;
+/**
+ * Deep merges `source` into a shallow copy of `target`. Nested plain
+ * objects are merged recursively. Skips prototype-pollution keys
+ * (`__proto__`, `constructor`, `prototype`).
+ *
+ * @typeParam T - Target object type.
+ * @param target - The base object (not mutated).
+ * @param source - The object to merge in.
+ * @returns A new merged object.
+ *
+ * @example
+ * ```ts
+ * const base = { a: 1, b: { c: 2, d: 3 } };
+ * const override = { b: { c: 99, e: 4 }, f: 5 };
+ * useDeepMerge(base, override);
+ * // { a: 1, b: { c: 99, d: 3, e: 4 }, f: 5 }
+ * ```
+ */
+export declare function useDeepMerge<T extends Record<string, unknown>>(target: T, source: Record<string, unknown>): T;
+/**
+ * Picks the listed keys from an object into a new object.
+ *
+ * @typeParam T - Source object type.
+ * @typeParam K - Keys to pick.
+ * @param obj - The source object.
+ * @param keys - Array of keys to include.
+ * @returns A new object with only the picked keys.
+ *
+ * @example
+ * ```ts
+ * const user = { id: 1, name: "Alice", email: "a@b.com" };
+ * usePick(user, ["id", "name"]); // { id: 1, name: "Alice" }
+ * ```
+ */
+export declare function usePick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+/**
+ * Omits the listed keys from an object, returning a shallow copy without
+ * them. Shallow on purpose to avoid `structuredClone` failures on
+ * non-cloneable values.
+ *
+ * @typeParam T - Source object type.
+ * @typeParam K - Keys to omit.
+ * @param obj - The source object.
+ * @param keys - Array of keys to exclude.
+ * @returns A new object without the omitted keys.
+ *
+ * @example
+ * ```ts
+ * const user = { id: 1, name: "Alice", password: "secret" };
+ * useOmit(user, ["password"]); // { id: 1, name: "Alice" }
+ * ```
+ */
+export declare function useOmit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+/**
+ * Returns a promise that resolves after `ms` milliseconds.
+ *
+ * @param ms - Delay in milliseconds.
+ * @returns A promise that resolves after the delay.
+ *
+ * @example
+ * ```ts
+ * await useSleep(1000); // waits 1 second
+ * console.log("done");
+ * ```
+ */
+export declare function useSleep(ms: number): Promise<void>;
+/**
+ * Retries an async function with a fixed delay between attempts.
+ *
+ * @typeParam T - The resolved value type.
+ * @param fn - The async function to retry.
+ * @param retries - Maximum number of retries (defaults to `3`).
+ * @param delayMs - Delay between retries in milliseconds (defaults to `1000`).
+ * @returns The resolved value of `fn`.
+ * @throws The last error if all retries are exhausted.
+ *
+ * @example
+ * ```ts
+ * const data = await useRetry(() => fetch("/api").then(r => r.json()), 3, 500);
+ * ```
+ */
+export declare function useRetry<T>(fn: () => Promise<T>, retries?: number, delayMs?: number): Promise<T>;
+/**
+ * Copies text to the clipboard (browser only). Returns `false` on failure
+ * or in non-browser environments (SSR).
+ *
+ * @param text - The text to copy.
+ * @returns `true` if the text was copied, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * const ok = await useCopyToClipboard("Hello, world!");
+ * console.log(ok); // true (in a browser with clipboard API)
+ * ```
+ */
+export declare function useCopyToClipboard(text: string): Promise<boolean>;
+/**
+ * Parses query parameters from a URL string into a plain object.
+ * Returns an empty object for invalid URLs.
+ *
+ * @param urlString - The URL to parse.
+ * @returns An object mapping parameter names to values.
+ *
+ * @example
+ * ```ts
+ * useGetUrlParams("https://example.com?q=hello&page=1");
+ * // { q: "hello", page: "1" }
+ *
+ * useGetUrlParams("not-a-url"); // {}
+ * ```
+ */
+export declare function useGetUrlParams(urlString: string): Record<string, string>;
+/**
+ * Rounds a number (or numeric string) to the specified number of decimal
+ * places. Returns `0` for non-numeric input.
+ *
+ * @param value - The number or numeric string to round.
+ * @param decimals - Number of decimal places (defaults to `2`).
+ * @returns The rounded number.
+ *
+ * @example
+ * ```ts
+ * useRound(3.14159, 2);   // 3.14
+ * useRound("5.678", 1);   // 5.7
+ * useRound("not-a-num");   // 0
+ * ```
+ */
+export declare function useRound(value: string | number, decimals?: number): number;
+/**
+ * Computes the arithmetic mean of an array of numbers. Returns `0` for an
+ * empty array.
+ *
+ * @param numbers - The input numbers.
+ * @returns The arithmetic mean.
+ *
+ * @example
+ * ```ts
+ * useAverage([1, 2, 3, 4, 5]); // 3
+ * useAverage([]);               // 0
+ * ```
+ */
+export declare function useAverage(numbers: number[]): number;
 //# sourceMappingURL=utils.service.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"utils.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/utils.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/utils.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAE5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAK3D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC3B,KAAK,EAAE,CAAC,EAAE,EACV,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC,GAClC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAYrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAK3C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,CAAC,CAkBH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAQ1F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAS1F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,SAAI,EAAE,OAAO,SAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAQ/F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOvE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOzE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAKrE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAIpD"}