@kikiutils/shared 20.0.0 → 20.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kikiutils/shared",
   "type": "module",
-  "version": "20.0.0",
+  "version": "20.1.0",
   "description": "A lightweight and modular utility library for modern JavaScript and TypeScript — includes secure hashing, flexible logging, datetime tools, Vue/web helpers, storage abstraction, and more.",
   "author": "kiki-kanri",
   "license": "MIT",
@@ -31,68 +31,41 @@
   ],
   "sideEffects": false,
   "exports": {
-    "./logger": {
-      "types": "./dist/logger/index.d.ts",
-      "import": "./dist/logger/index.js",
-      "require": null
-    },
-    "./logger/_internals/formatter": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/_internals/levels": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/_internals/logger": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/_internals/types": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/index": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/node": {
-      "types": "./dist/logger/node/index.d.ts",
-      "import": "./dist/logger/node/index.js",
-      "require": null
-    },
-    "./logger/node/_internals/file-writer": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/node/_internals/formatter": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/node/index": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./package.json": "./package.json",
-    "./types": {
-      "types": "./dist/types/index.d.ts",
-      "import": null,
-      "require": null
-    },
-    "./types/index": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./*": "./dist/*.js"
+    "./buffer": "./dist/buffer.js",
+    "./classes/enhanced-date": "./dist/classes/enhanced-date.js",
+    "./classes/path": "./dist/classes/path.js",
+    "./classes/precision-number": "./dist/classes/precision-number.js",
+    "./clipboard": "./dist/clipboard.js",
+    "./crypto-hash": "./dist/crypto-hash.js",
+    "./datetime": "./dist/datetime.js",
+    "./element-plus": "./dist/element-plus.js",
+    "./enum": "./dist/enum.js",
+    "./env": "./dist/env.js",
+    "./event-awaiter": "./dist/event-awaiter.js",
+    "./file": "./dist/file.js",
+    "./general": "./dist/general.js",
+    "./hash": "./dist/hash.js",
+    "./logger": "./dist/logger/index.js",
+    "./logger/node": "./dist/logger/node/index.js",
+    "./logger/node/types": "./dist/logger/node/types.js",
+    "./logger/types": "./dist/logger/types.js",
+    "./math": "./dist/math.js",
+    "./number": "./dist/number.js",
+    "./random": "./dist/random.js",
+    "./redis/script-runner": "./dist/redis/script-runner.js",
+    "./storages/lru/keyed-store": "./dist/storages/lru/keyed-store.js",
+    "./storages/redis/keyed-store": "./dist/storages/redis/keyed-store.js",
+    "./storages/redis/msgpack": "./dist/storages/redis/msgpack.js",
+    "./storages/redis/types": "./dist/storages/redis/types.js",
+    "./string": "./dist/string.js",
+    "./time": "./dist/time.js",
+    "./types": "./dist/types/index.js",
+    "./types/filtered-key-path": "./dist/types/filtered-key-path.js",
+    "./types/vue": "./dist/types/vue.js",
+    "./url": "./dist/url.js",
+    "./vue": "./dist/vue.js",
+    "./web": "./dist/web.js",
+    "./package.json": "./package.json"
   },
   "files": [
     "./dist",
@@ -172,10 +145,11 @@
   },
   "devDependencies": {
     "@antfu/eslint-config": "^10.0.0",
-    "@kikiutils/eslint-config": "^9.3.2",
+    "@arethetypeswrong/core": "^0.18.5",
+    "@kikiutils/eslint-config": "^10.1.0",
     "@kikiutils/tsconfigs": "^7.0.0",
     "@noble/hashes": "^2.4.0",
-    "@types/node": "^26.6.5",
+    "@types/node": "^26.6.6",
     "@vitest/coverage-v8": "^5.0.5",
     "async-validator": "^4.2.5",
     "bson": "^7.3.3",
@@ -184,16 +158,16 @@
     "date-fns": "^4.4.0",
     "decimal.js": "^10.6.0",
     "element-plus": "^2.14.7",
-    "eslint": "^10.13.0",
-    "file-type": "^22.2.0",
+    "eslint": "^10.14.0",
+    "file-type": "^22.3.0",
     "jsdom": "^30.1.3",
-    "knip": "^6.43.0",
+    "knip": "^6.44.1",
     "lru-cache": "^11.5.3",
     "millify": "^6.1.0",
-    "msgpackr": "^2.1.2",
+    "msgpackr": "^2.1.3",
     "publint": "^0.3.25",
     "rotating-file-stream": "^3.2.10",
-    "tsdown": "^0.23.3",
+    "tsdown": "^0.23.4",
     "typescript": "^6.0.3",
     "unplugin-unused": "^0.6.0",
     "vitest": "^5.0.5",

package/src/buffer.ts

@@ -36,6 +36,5 @@ export async function toBuffer(input: BinaryInput) {
     if (input instanceof ArrayBuffer) return Buffer.from(input);
     if (input instanceof Uint8Array) return Buffer.from(input.buffer, input.byteOffset, input.byteLength);
     if (typeof input.arrayBuffer === 'function') return Buffer.from(await input.arrayBuffer());
-    // eslint-disable-next-line style/max-len
     throw new TypeError('The provided input is not a supported binary type (Blob, Buffer, File, ArrayBuffer, or Uint8Array).');
 }

package/src/classes/enhanced-date.ts

@@ -100,7 +100,7 @@ export class EnhancedDate extends Date {
      *
      * @returns A new `EnhancedDate`, or `Invalid Date` if the array is empty or contains an invalid date.
      */
-    static max(dates: (Date | number)[]) {
+    static max(dates: Array<Date | number>) {
         return new EnhancedDate(dateFns.max(dates));
     }
 
@@ -111,7 +111,7 @@ export class EnhancedDate extends Date {
      *
      * @returns A new `EnhancedDate`, or `Invalid Date` if the array is empty or contains an invalid date.
      */
-    static min(dates: (Date | number)[]) {
+    static min(dates: Array<Date | number>) {
         return new EnhancedDate(dateFns.min(dates));
     }
 

package/src/classes/path.ts

@@ -373,7 +373,7 @@ export class Path {
             recursive?: boolean;
             withFileTypes: true;
         },
-    ): Promise<fs.Dirent<Buffer>[]>;
+    ): Promise<Array<fs.Dirent<Buffer>>>;
     readdir(...args: any): any {
         return fsp.readdir(this.#value, ...args);
     }

package/src/enum.ts

@@ -22,7 +22,7 @@
  * console.log(getEnumNumberValues(RecordType)); // => [0, 1]
  * ```
  */
-export function getEnumNumberValues<T extends Record<string, any>>(enumObject: T): Extract<T[keyof T], number>[] {
+export function getEnumNumberValues<T extends Record<string, any>>(enumObject: T): Array<Extract<T[keyof T], number>> {
     return getEnumValues(enumObject).filter((value) => typeof value === 'number');
 }
 
@@ -50,7 +50,7 @@ export function getEnumNumberValues<T extends Record<string, any>>(enumObject: T
  * console.log(getEnumStringValues(RecordType)); // => ['unknown']
  * ```
  */
-export function getEnumStringValues<T extends Record<string, any>>(enumObject: T): Extract<T[keyof T], string>[] {
+export function getEnumStringValues<T extends Record<string, any>>(enumObject: T): Array<Extract<T[keyof T], string>> {
     return getEnumValues(enumObject).filter((value) => typeof value === 'string');
 }
 
@@ -102,7 +102,7 @@ export function getEnumStringValues<T extends Record<string, any>>(enumObject: T
  * console.log(getEnumValues(RecordType)); // => [0, 1, 'unknown']
  * ```
  */
-export function getEnumValues<T extends Record<string, any>>(enumObject: T): (T[keyof T])[] {
+export function getEnumValues<T extends Record<string, any>>(enumObject: T): Array<T[keyof T]> {
     const values = Object.values(enumObject);
     const hasNumberValues = values.some((value) => typeof value === 'number');
     if (!hasNumberValues) return values;

package/src/event-awaiter.ts

@@ -11,7 +11,7 @@
  */
 export class EventAwaiter<T> {
     // Private instance properties
-    #promiseResolvers = new Map<string, ((value: PromiseLike<T | undefined> | T | undefined) => void)[]>();
+    #promiseResolvers = new Map<string, Array<(value: PromiseLike<T | undefined> | T | undefined) => void>>();
 
     // Public instance methods
 
@@ -69,6 +69,8 @@ export class EventAwaiter<T> {
                         break;
                     case 'strict':
                         throw new Error(`Duplicate wait detected for key: ${key}`);
+                    case undefined:
+                        break;
                 }
             }
 

package/src/logger/_internals/formatter.ts

@@ -6,7 +6,9 @@ import type { LoggerRecord } from './types';
 
 // Functions
 
-/** Native console formatting keeps user strings literal and objects expandable. */
+/**
+ * Native console formatting keeps user strings literal and objects expandable.
+ */
 export function formatLoggerConsoleArgs(record: LoggerRecord): unknown[] {
     if (typeof process !== 'undefined' && process.versions?.node) {
         const target = process[getLoggerStreamName(record.type)];
@@ -39,7 +41,9 @@ export function formatLoggerConsoleArgs(record: LoggerRecord): unknown[] {
     ];
 }
 
-/** Keeps data arguments intact so browser developer tools can expand objects. */
+/**
+ * Keeps data arguments intact so browser developer tools can expand objects.
+ */
 export function formatLoggerParts(record: LoggerRecord, colors = false): unknown[] {
     const parts: unknown[] = [];
     const paint = (text: string, color: string) => colors ? `\u001B[${color}m${text}\u001B[0m` : text;
@@ -51,7 +55,9 @@ export function formatLoggerParts(record: LoggerRecord, colors = false): unknown
     return parts;
 }
 
-/** Fixed local-time representation, deliberately without a per-second cache. */
+/**
+ * Fixed local-time representation, deliberately without a per-second cache.
+ */
 export function formatLoggerTime(date: Date): string {
     const pad = (value: number, width = 2) => String(value).padStart(width, '0');
     const day = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
@@ -59,7 +65,9 @@ export function formatLoggerTime(date: Date): string {
     return `[${day} ${time}.${pad(date.getMilliseconds(), 3)}]`;
 }
 
-/** Use native terminal detection; redirected streams still honor FORCE_COLOR. */
+/**
+ * Use native terminal detection; redirected streams still honor FORCE_COLOR.
+ */
 export function supportsLoggerColor(target: { hasColors?: () => boolean; isTTY?: boolean }): boolean {
     if (target.hasColors) return target.hasColors();
     const forced = process.env.FORCE_COLOR;

package/src/logger/_internals/logger.ts

@@ -10,7 +10,9 @@ import { loggerMethods } from './levels';
 import type { LoggerRecord } from './types';
 
 interface LoggerHooks {
-    /** A non-throwing reporter created by createDiagnosticReporter. */
+    /**
+     * A non-throwing reporter created by createDiagnosticReporter.
+     */
     report: (event: LoggerDiagnostic) => void;
     write: (record: LoggerRecord) => Promise<void> | void;
 }
@@ -29,7 +31,9 @@ const stringPresentationKeys = [
 
 // Functions
 
-/** A non-recursive, rate-limited diagnostic boundary shared by server and browser adapters. */
+/**
+ * A non-recursive, rate-limited diagnostic boundary shared by server and browser adapters.
+ */
 export function createDiagnosticReporter(
     onError?: (event: Readonly<LoggerDiagnostic>) => void,
     fallback?: (message: string) => void,

package/src/logger/node/_internals/file-writer.ts

@@ -26,7 +26,9 @@ const defaultMaxPendingBytes = 8 * 1024 * 1024;
 
 // Functions
 
-/** A bounded admission layer over the stream's own ordered write buffer; not a second FIFO. */
+/**
+ * A bounded admission layer over the stream's own ordered write buffer; not a second FIFO.
+ */
 export async function createFileWriter(
     options: LoggerFileOptions,
     report: (event: LoggerDiagnostic) => void,
@@ -213,7 +215,9 @@ export async function createFileWriter(
     });
 }
 
-/** Validate before mkdir, stream creation, or other filesystem side effects. */
+/**
+ * Validate before mkdir, stream creation, or other filesystem side effects.
+ */
 function validateFileOptions(options: LoggerFileOptions) {
     if (
         !options

package/src/logger/node/_internals/formatter.ts

@@ -5,7 +5,9 @@ import type { LoggerRecord } from '../../_internals/types';
 
 // Functions
 
-/** Preserve user ANSI for console output without invoking custom inspect callbacks/getters. */
+/**
+ * Preserve user ANSI for console output without invoking custom inspect callbacks/getters.
+ */
 export function formatNodeLoggerRecord(record: LoggerRecord, colors = false) {
     const message = record.args.map(
         (arg) => typeof arg === 'string'

package/src/logger/node/index.ts

@@ -107,6 +107,7 @@ export async function createNodeLogger(options: NodeLoggerOptions = {}): Promise
 
                 consoleTargets.clear();
             })();
+
             return closePromise;
         },
         getStats: () => writer?.getStats() ?? Object.freeze({
@@ -117,7 +118,9 @@ export async function createNodeLogger(options: NodeLoggerOptions = {}): Promise
     });
 }
 
-/** One error listener per shared output stream; retained until its last owning logger calls close(). */
+/**
+ * One error listener per shared output stream; retained until its last owning logger calls close().
+ */
 function writeConsole(
     target: NodeJS.WriteStream,
     text: string,

package/src/logger/node/types.ts

@@ -4,50 +4,74 @@ import type {
     LoggerOptions,
 } from '../types';
 
-/** Specify interval and/or maxSize. Size limits use positive integers with B, K, M, or G (binary units). */
+/**
+ * Specify interval and/or maxSize. Size limits use positive integers with B, K, M, or G (binary units).
+ */
 export type LoggerRotationOptions = {
-    /** Gzip historical files. Defaults to true. */
+    /**
+     * Gzip historical files. Defaults to true.
+     */
     compress?: boolean;
 
-    /** Number of historical files, excluding the active file. Defaults to 30. */
+    /**
+     * Number of historical files, excluding the active file. Defaults to 30.
+     */
     keepFiles?: number;
 
-    /** Maximum combined size of historical files. */
+    /**
+     * Maximum combined size of historical files.
+     */
     maxTotalSize?: string;
 } & (
   | {
-      /** Opt-in time rotation aligned to the system's local calendar boundary. */
+      /**
+       * Opt-in time rotation aligned to the system's local calendar boundary.
+       */
       interval: 'daily' | 'hourly';
       maxSize?: string;
   }
   | {
-      /** Opt-in time rotation aligned to the system's local calendar boundary. */
+      /**
+       * Opt-in time rotation aligned to the system's local calendar boundary.
+       */
       interval?: 'daily' | 'hourly';
       maxSize: string;
   }
 );
 
 export interface LoggerFileOptions {
-    /** Maximum unfinished payload bytes, including data already submitted to the stream. */
+    /**
+     * Maximum unfinished payload bytes, including data already submitted to the stream.
+     */
     maxPendingBytes?: number;
 
-    /** Resolved once at creation. The file is opened in append mode. */
+    /**
+     * Resolved once at creation. The file is opened in append mode.
+     */
     path: PathLike;
 
-    /** Omitted or false disables rotation. An object must specify interval or maxSize. */
+    /**
+     * Omitted or false disables rotation. An object must specify interval or maxSize.
+     */
     rotate?: false | LoggerRotationOptions;
 }
 
 export interface NodeLogger extends Logger {
-    /** Stop accepting records, finish accepted file writes, then release the stream. Not fsync. */
+    /**
+     * Stop accepting records, finish accepted file writes, then release the stream. Not fsync.
+     */
     close: () => Promise<void>;
 
-    /** A fresh, frozen file-output snapshot. Dropped/failed records still resolve their logging promises. */
+    /**
+     * A fresh, frozen file-output snapshot. Dropped/failed records still resolve their logging promises.
+     */
     getStats: () => Readonly<NodeLoggerStats>;
 }
 
 export interface NodeLoggerOptions extends LoggerOptions {
-    /** Disabled by default. Each logger owns at most one fixed file destination. */
+    /**
+     * Disabled by default. Each logger owns at most one fixed file destination.
+     */
     file?: false | LoggerFileOptions;
 }
 

package/src/logger/types.ts

@@ -1,7 +1,13 @@
-/** Minimum severity to emit; `success` uses the same threshold as `info`. */
+import type { SafePromise } from '../types';
+
+/**
+ * Minimum severity to emit; `success` uses the same threshold as `info`.
+ */
 export type LoggerLevel = 'debug' | 'error' | 'fatal' | 'info' | 'silent' | 'trace' | 'warn';
 
-/** A logging method, including the informational success presentation. */
+/**
+ * A logging method, including the informational success presentation.
+ */
 export type LoggerMethod = 'success' | Exclude<LoggerLevel, 'silent'>;
 
 /**
@@ -13,48 +19,68 @@ export type LoggerMethod = 'success' | Exclude<LoggerLevel, 'silent'>;
  */
 export interface Logger {
     configure: (options: Pick<LoggerOptions, 'console' | 'icons' | 'prefix' | 'suffix' | 'timestamp'>) => void;
-    debug: (...args: unknown[]) => Promise<void>;
-    error: (...args: unknown[]) => Promise<void>;
-    fatal: (...args: unknown[]) => Promise<void>;
-    info: (...args: unknown[]) => Promise<void>;
+    debug: (...args: unknown[]) => SafePromise<void>;
+    error: (...args: unknown[]) => SafePromise<void>;
+    fatal: (...args: unknown[]) => SafePromise<void>;
+    info: (...args: unknown[]) => SafePromise<void>;
 
-    /** Accepts success as an informational method; it is not a configurable threshold. */
+    /**
+     * Accepts success as an informational method; it is not a configurable threshold.
+     */
     isLevelEnabled: (level: LoggerLevel | LoggerMethod) => boolean;
 
-    /** Sets a severity threshold (not success); env restores environment-driven filtering. */
+    /**
+     * Sets a severity threshold (not success); env restores environment-driven filtering.
+     */
     setLevel: (level: 'env' | LoggerLevel) => void;
-    success: (...args: unknown[]) => Promise<void>;
-    trace: (...args: unknown[]) => Promise<void>;
-    warn: (...args: unknown[]) => Promise<void>;
+    success: (...args: unknown[]) => SafePromise<void>;
+    trace: (...args: unknown[]) => SafePromise<void>;
+    warn: (...args: unknown[]) => SafePromise<void>;
 }
 
-/** A shallow-frozen failure notification; nested error values retain their original ownership. */
+/**
+ * A shallow-frozen failure notification; nested error values retain their original ownership.
+ */
 export interface LoggerDiagnostic {
     droppedCount?: number;
     error?: unknown;
     message: string;
 
-    /** Same-type notifications suppressed since the previous emitted diagnostic. */
+    /**
+     * Same-type notifications suppressed since the previous emitted diagnostic.
+     */
     suppressedCount?: number;
     type: 'closed' | 'console' | 'file' | 'format' | 'invalid-level' | 'overflow';
 }
 
-/** Configuration shared by browser and server loggers. */
+/**
+ * Configuration shared by browser and server loggers.
+ */
 export interface LoggerOptions {
-    /** Enables console output. Defaults to `true`. */
+    /**
+     * Enables console output. Defaults to `true`.
+     */
     console?: boolean;
 
-    /** Enables Unicode level icons. Defaults to `true`. */
+    /**
+     * Enables Unicode level icons. Defaults to `true`.
+     */
     icons?: boolean;
 
-    /** Overrides LOG_LEVEL; `env` restores the environment-driven threshold. */
+    /**
+     * Overrides LOG_LEVEL; `env` restores the environment-driven threshold.
+     */
     level?: 'env' | LoggerLevel;
 
-    /** Best-effort, rate-limited notification; failures in this callback are contained. */
+    /**
+     * Best-effort, rate-limited notification; failures in this callback are contained.
+     */
     onError?: (event: Readonly<LoggerDiagnostic>) => void;
     prefix?: string;
     suffix?: string;
 
-    /** Enables the fixed local-time millisecond prefix. Defaults to `true`. */
+    /**
+     * Enables the fixed local-time millisecond prefix. Defaults to `true`.
+     */
     timestamp?: boolean;
 }

package/src/redis/script-runner.ts

@@ -14,7 +14,7 @@ import { createHash } from 'node:crypto';
  *
  * @returns A promise resolving to the Redis script result after execution completes.
  */
-export type RedisScriptRunner<T = unknown> = (keys: readonly string[], args: readonly (number | string)[]) => Promise<
+export type RedisScriptRunner<T = unknown> = (keys: readonly string[], args: ReadonlyArray<number | string>) => Promise<
     T
 >;
 

package/src/types/filtered-key-path.ts

@@ -22,7 +22,7 @@ type DefaultPath<
 export type FilteredKeyPath<T, U = never> = T extends ReadonlyArray<infer V> ? (IsTuple<T> extends true ? { [K in TupleKey<T>]-?: PathImpl<Exclude<K, symbol>, T[K], U> }[TupleKey<T>] : PathImpl<number, V, U>) : { [K in keyof T]-?: PathImpl<Exclude<K, symbol>, T[K], U> }[keyof T];
 /* eslint-enable style/max-len */
 
-type IsTuple<T extends ReadonlyArray<any>> = number extends T['length'] ? false : true;
+type IsTuple<T extends readonly any[]> = number extends T['length'] ? false : true;
 type PathImpl<K extends number | string, V, U> = [U] extends [never] ? DefaultPath<K, V> : ConditionalPath<K, V, U>;
 type TerminalType =
   | bigint
@@ -38,4 +38,4 @@ type TerminalType =
   | symbol
   | undefined;
 
-type TupleKey<T extends ReadonlyArray<any>> = Exclude<keyof T, keyof any[]>;
+type TupleKey<T extends readonly any[]> = Exclude<keyof T, keyof any[]>;

package/src/types/index.ts

@@ -40,3 +40,9 @@ export type ReadonlyPartialRecord<K extends keyof any, T> = Readonly<PartialReco
  * A readonly `Record`.
  */
 export type ReadonlyRecord<K extends keyof any, T> = Readonly<Record<K, T>>;
+
+/**
+ * A promise whose rejection is handled internally and can safely be left unawaited.
+ * This type only marks that contract; it does not add runtime rejection handling.
+ */
+export type SafePromise<T> = Promise<T> & { readonly __safePromise?: true };

package/src/url.ts

@@ -12,7 +12,6 @@
  * @throws Error if `redirectPath` is not a safe same-origin application path.
  */
 export function appendRedirectParamToUrl(url: string, redirectPath: string) {
-    // eslint-disable-next-line style/max-len
     if (!isSafeRedirectPath(redirectPath)) throw new Error(`Invalid redirect path: "${redirectPath}". Redirect paths must be safe same-origin paths starting with '/'.`);
 
     const [baseAndHash, rawQuery = ''] = url.split('?');