@kikiutils/shared 20.0.1 → 20.1.0

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('?');