@catbee/utils 0.0.6 → 0.0.8-next.0

package/build/esm/types/server.d.ts

@@ -1,285 +0,0 @@
-import { Express, json, NextFunction, urlencoded, Request, Response } from 'express';
-import { ExpressServer } from '../servers/server';
-import { HelmetOptions } from 'helmet';
-import { CompressionOptions } from 'compression';
-import { CookieParseOptions } from 'cookie-parser';
-import { LoggerLevels } from '../utils/logger.utils';
-import http from 'http';
-import { CorsOptions } from 'cors';
-import { ToggleConfig } from '.';
-/**
- * Server configuration interface with smart defaults and full customization.
- * All options are designed with security and performance best practices.
- * Most options can be overridden via environment variables.
- */
-export interface ServerConfig {
-    /** Port the server should listen on (default: 3000, env: PORT)
-     *  - default: 3000
-     */
-    port: number;
-    /** Optional host address for binding (default: '0.0.0.0', env: HOST)
-     *  - default: '0.0.0.0'
-     */
-    host?: string;
-    /** CORS configuration (default: false disables CORS, or provide options object)
-     *  - default: false
-     */
-    cors?: ToggleConfig<CorsOptions>;
-    /** Enable Helmet security headers (default: false disables Helmet, or provide options object)
-     *  - default: false
-     */
-    helmet?: ToggleConfig<HelmetOptions>;
-    /** Enable gzip/deflate compression (default: false disables compression, or provide options object)
-     *  - default: false
-     */
-    compression?: ToggleConfig<CompressionOptions>;
-    /** Request body parsing with size limits
-     *  - json: { limit: '1mb' }
-     *  - urlencoded: { extended: true, limit: '1mb' }
-     */
-    bodyParser?: {
-        /** JSON parser (default: { limit: '1mb' }) */
-        json?: Parameters<typeof json>[0];
-        /** URL-encoded parser (default: { extended: true, limit: '1mb' }) */
-        urlencoded?: Parameters<typeof urlencoded>[0];
-    };
-    /** Enable cookie parsing with options (default: false)
-     *  - default: false
-     */
-    cookieParser?: ToggleConfig<CookieParseOptions>;
-    /** Trust proxy headers (default: false)
-     *  - default: false
-     */
-    trustProxy?: boolean;
-    /** Static file serving configuration for assets, uploads, etc.
-     *  - path: file system path to serve
-     *  - route: URL route prefix (default: "/")
-     *  - maxAge: cache max age (default: 0)
-     *  - etag: enable ETag headers (default: true)
-     *  - immutable: enable immutable caching (default: false)
-     *  - lastModified: enable last-modified caching (default: true)
-     *  - cacheControl: enable Cache-Control headers (default: true)
-     */
-    staticFolders?: Array<{
-        /** URL route prefix (default: "/") */
-        path?: string;
-        /** File system path to serve */
-        directory: string;
-        /** Cache-Control: max-age=<duration> (default: 0) */
-        maxAge?: string;
-        /** Enable ETag headers (default: true) */
-        etag?: boolean;
-        /** Enable immutable caching (default: false) */
-        immutable?: boolean;
-        /** Enable last-modified caching (default: true) */
-        lastModified?: boolean;
-        /** Enable Cache-Control headers (default: true) */
-        cacheControl?: boolean;
-    }>;
-    /** Enable microservice mode (default: false)
-     *  - default: false
-     */
-    isMicroservice?: boolean;
-    /** Service name for headers/metrics (default: 'express_app', env: APP_NAME)
-     *  - default: 'express_app'
-     */
-    appName?: string;
-    /** Global response headers (default: {})
-     *  - default: {}
-     */
-    globalHeaders?: Record<string, string | (() => string)>;
-    /** Rate limiting settings
-     *  - enable: false
-     *  - windowMs: 15 * 60 * 1000
-     *  - max: 100
-     *  - message: 'Too many requests'
-     *  - standardHeaders: true
-     *  - legacyHeaders: false
-     */
-    rateLimit?: {
-        /** Enable rate limiting (default: false) */
-        enable: boolean;
-        /** Time window in ms (default: 900000 - 15 minutes) */
-        windowMs?: number;
-        /** Max requests per window (default: 100) */
-        max?: number;
-        /** Rate limit message (default: 'Too many requests') */
-        message?: string;
-        /** Add standard headers (default: true) */
-        standardHeaders?: boolean;
-        /** Add legacy headers (default: false) */
-        legacyHeaders?: boolean;
-    };
-    /** Request logging configuration
-     *  - enable: true in dev, false in prod
-     *  - ignorePaths: skips /healthz, /favicon.ico, /metrics, /docs, /.well-known
-     *  - skipNotFoundRoutes: false
-     */
-    requestLogging?: {
-        /** Enable request logging (default: true in dev, false in prod) */
-        enable: boolean;
-        /** Ignore paths function or string[] (default: skips /healthz, /favicon.ico, /metrics, /docs, /.well-known) */
-        ignorePaths?: string[] | ((req: Request, res: Response) => boolean);
-        /** Skip logging for not found routes (default: false) */
-        skipNotFoundRoutes?: boolean;
-    };
-    /** Health check settings
-     *  - path: '/healthz'
-     *  - detailed: true
-     *  - withGlobalPrefix: false
-     */
-    healthCheck?: {
-        /** Health check path (default: '/healthz') */
-        path?: string;
-        /** Custom checks (default: []) */
-        checks?: Array<{
-            name: string;
-            check: () => Promise<boolean> | boolean;
-        }>;
-        /** Show detailed checks status in response (default: true) */
-        detailed?: boolean;
-        /** Include in global prefix (default: false) */
-        withGlobalPrefix?: boolean;
-    };
-    /** Request timeout in ms (default: 30000 - 30 seconds)
-     *  - default: 30000
-     */
-    requestTimeout?: number;
-    /** Response timing configuration
-     *  - enable: false
-     *  - addHeader: true
-     *  - logOnComplete: false
-     */
-    responseTime?: {
-        /** Enable timing (default: false) */
-        enable: boolean;
-        /** Add X-Response-Time header (default: true) */
-        addHeader?: boolean;
-        /** Log completion time (default: false) */
-        logOnComplete?: boolean;
-    };
-    /** Request ID configuration
-     *  - headerName: 'x-request-id'
-     *  - exposeHeader: true
-     *  - generator: uuid()
-     */
-    requestId?: {
-        /** Header name (default: 'x-request-id') */
-        headerName?: string;
-        /** Add to response headers (default: true) */
-        exposeHeader?: boolean;
-        /** ID generator (default: uuid()) */
-        generator?: () => string;
-    };
-    /** Global route prefix (default: '/')
-     *  - default: '/'
-     */
-    globalPrefix?: string;
-    /** OpenAPI documentation
-     *  - enable: false
-     *  - mountPath: '/docs'
-     *  - verbose: false
-     *  - withGlobalPrefix: false
-     */
-    openApi?: {
-        /** Enable docs (default: false) */
-        enable: boolean;
-        /** UI path (default: '/docs') */
-        mountPath?: string;
-        /** Spec file path (required if enabled) */
-        filePath?: string;
-        /** Enable verbose logs (default: false) */
-        verbose?: boolean;
-        /** Include in global prefix (default: false) */
-        withGlobalPrefix?: boolean;
-    };
-    /** Logger settings
-     *  - name: 'express_app'
-     *  - level: 'info'
-     *  - prettyPrint: default true if process.env.NODE_ENV === 'development'
-     *  - singleLine: false
-     */
-    logger?: {
-        /** Logger name (default: 'express_app') */
-        name?: string;
-        /** Log level (default: 'info') */
-        level?: LoggerLevels;
-        /** Pretty print (default: true in dev) */
-        prettyPrint?: boolean;
-        /** Single line output for pretty print (default: false) */
-        singleLine?: boolean;
-    };
-    /** Prometheus metrics
-     *  - enable: false
-     *  - path: '/metrics'
-     *  - withGlobalPrefix: false
-     */
-    metrics?: {
-        /** Enable metrics (default: false) */
-        enable: boolean;
-        /** Metrics path (default: '/metrics') */
-        path?: string;
-        /** Include in global prefix (default: false) */
-        withGlobalPrefix?: boolean;
-    };
-    /** Service version header
-     *  - enable: false
-     *  - headerName: 'x-service-version'
-     *  - version: '0.0.0'
-     */
-    serviceVersion?: {
-        /** Enable version header (default: false) */
-        enable: boolean;
-        /** Header name (default: 'x-service-version') */
-        headerName?: string;
-        /** Version value (default: '0.0.0') */
-        version?: string | (() => string);
-    };
-    /**
-     * HTTPS configuration (if provided, server will use HTTPS)
-     * Requires 'key' and 'cert' at minimum.
-     * @command - to generate self-signed certificates
-     * ```bash
-     * choco install mkcert
-     * mkcert -key-file localhost-key.pem -cert-file localhost-cert.pem localhost 127.0.0.1 ::1
-     * ```
-     */
-    https?: {
-        /** Path to SSL private key file (PEM) */
-        key: string;
-        /** Path to SSL certificate file (PEM) */
-        cert: string;
-        /** Optional path to CA bundle file (PEM) */
-        ca?: string;
-        /** Optional passphrase for the private key */
-        passphrase?: string;
-        /** Any other https.ServerOptions */
-        [key: string]: any;
-    };
-}
-/**
- * Server lifecycle hooks for custom behavior injection.
- * Allows extending server functionality without modifying core code.
- * All hooks can be async and support error handling.
- */
-export interface ServerHooks {
-    /** Called before any middleware or routes are initialized - good for early setup */
-    beforeInit?: (server: ExpressServer) => Promise<void> | void;
-    /** Called after middleware and routes are set up - good for final configuration */
-    afterInit?: (server: ExpressServer) => Promise<void> | void;
-    /** Called just before the server starts listening - good for last-minute checks */
-    beforeStart?: (app: Express) => Promise<void> | void;
-    /** Called after the server starts successfully - good for announcing readiness */
-    afterStart?: (server: http.Server) => Promise<void> | void;
-    /** Called before graceful shutdown begins - good for cleanup preparation */
-    beforeStop?: (server: http.Server) => Promise<void> | void;
-    /** Called after server has stopped - good for final cleanup */
-    afterStop?: () => Promise<void> | void;
-    /** Custom global error handler - overrides the default error handling */
-    onError?: (error: Error, req: Request, res: Response, next: NextFunction) => void;
-    /** Called at the start of each request - good for request preprocessing */
-    onRequest?: (req: Request, res: Response, next: NextFunction) => void;
-    /** Called before response is sent - good for response modification */
-    onResponse?: (req: Request, res: Response, next: NextFunction) => void;
-}
-//# sourceMappingURL=server.d.ts.map

package/build/esm/types/server.js

@@ -1,25 +0,0 @@
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-export {};
-//# sourceMappingURL=server.js.map

package/build/esm/types/server.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/types/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Express, json, NextFunction, urlencoded, Request, Response } from 'express';\nimport { ExpressServer } from '../servers/server';\nimport { HelmetOptions } from 'helmet';\nimport { CompressionOptions } from 'compression';\nimport { CookieParseOptions } from 'cookie-parser';\nimport { LoggerLevels } from '../utils/logger.utils';\nimport http from 'http';\nimport { CorsOptions } from 'cors';\nimport { ToggleConfig } from '.';\n\n/**\n * Server configuration interface with smart defaults and full customization.\n * All options are designed with security and performance best practices.\n * Most options can be overridden via environment variables.\n */\nexport interface ServerConfig {\n  /** Port the server should listen on (default: 3000, env: PORT)\n   *  - default: 3000\n   */\n  port: number;\n  /** Optional host address for binding (default: '0.0.0.0', env: HOST)\n   *  - default: '0.0.0.0'\n   */\n  host?: string;\n\n  /** CORS configuration (default: false disables CORS, or provide options object)\n   *  - default: false\n   */\n  cors?: ToggleConfig<CorsOptions>;\n\n  /** Enable Helmet security headers (default: false disables Helmet, or provide options object)\n   *  - default: false\n   */\n  helmet?: ToggleConfig<HelmetOptions>;\n\n  /** Enable gzip/deflate compression (default: false disables compression, or provide options object)\n   *  - default: false\n   */\n  compression?: ToggleConfig<CompressionOptions>;\n\n  /** Request body parsing with size limits\n   *  - json: { limit: '1mb' }\n   *  - urlencoded: { extended: true, limit: '1mb' }\n   */\n  bodyParser?: {\n    /** JSON parser (default: { limit: '1mb' }) */\n    json?: Parameters<typeof json>[0];\n    /** URL-encoded parser (default: { extended: true, limit: '1mb' }) */\n    urlencoded?: Parameters<typeof urlencoded>[0];\n  };\n\n  /** Enable cookie parsing with options (default: false)\n   *  - default: false\n   */\n  cookieParser?: ToggleConfig<CookieParseOptions>;\n\n  /** Trust proxy headers (default: false)\n   *  - default: false\n   */\n  trustProxy?: boolean;\n\n  /** Static file serving configuration for assets, uploads, etc.\n   *  - path: file system path to serve\n   *  - route: URL route prefix (default: \"/\")\n   *  - maxAge: cache max age (default: 0)\n   *  - etag: enable ETag headers (default: true)\n   *  - immutable: enable immutable caching (default: false)\n   *  - lastModified: enable last-modified caching (default: true)\n   *  - cacheControl: enable Cache-Control headers (default: true)\n   */\n  staticFolders?: Array<{\n    /** URL route prefix (default: \"/\") */\n    path?: string;\n    /** File system path to serve */\n    directory: string;\n    /** Cache-Control: max-age=<duration> (default: 0) */\n    maxAge?: string;\n    /** Enable ETag headers (default: true) */\n    etag?: boolean;\n    /** Enable immutable caching (default: false) */\n    immutable?: boolean;\n    /** Enable last-modified caching (default: true) */\n    lastModified?: boolean;\n    /** Enable Cache-Control headers (default: true) */\n    cacheControl?: boolean;\n  }>;\n\n  /** Enable microservice mode (default: false)\n   *  - default: false\n   */\n  isMicroservice?: boolean;\n\n  /** Service name for headers/metrics (default: 'express_app', env: APP_NAME)\n   *  - default: 'express_app'\n   */\n  appName?: string;\n\n  /** Global response headers (default: {})\n   *  - default: {}\n   */\n  globalHeaders?: Record<string, string | (() => string)>;\n\n  /** Rate limiting settings\n   *  - enable: false\n   *  - windowMs: 15 * 60 * 1000\n   *  - max: 100\n   *  - message: 'Too many requests'\n   *  - standardHeaders: true\n   *  - legacyHeaders: false\n   */\n  rateLimit?: {\n    /** Enable rate limiting (default: false) */\n    enable: boolean;\n    /** Time window in ms (default: 900000 - 15 minutes) */\n    windowMs?: number;\n    /** Max requests per window (default: 100) */\n    max?: number;\n    /** Rate limit message (default: 'Too many requests') */\n    message?: string;\n    /** Add standard headers (default: true) */\n    standardHeaders?: boolean;\n    /** Add legacy headers (default: false) */\n    legacyHeaders?: boolean;\n  };\n\n  /** Request logging configuration\n   *  - enable: true in dev, false in prod\n   *  - ignorePaths: skips /healthz, /favicon.ico, /metrics, /docs, /.well-known\n   *  - skipNotFoundRoutes: false\n   */\n  requestLogging?: {\n    /** Enable request logging (default: true in dev, false in prod) */\n    enable: boolean;\n    /** Ignore paths function or string[] (default: skips /healthz, /favicon.ico, /metrics, /docs, /.well-known) */\n    ignorePaths?: string[] | ((req: Request, res: Response) => boolean);\n    /** Skip logging for not found routes (default: false) */\n    skipNotFoundRoutes?: boolean;\n  };\n\n  /** Health check settings\n   *  - path: '/healthz'\n   *  - detailed: true\n   *  - withGlobalPrefix: false\n   */\n  healthCheck?: {\n    /** Health check path (default: '/healthz') */\n    path?: string;\n    /** Custom checks (default: []) */\n    checks?: Array<{\n      name: string;\n      check: () => Promise<boolean> | boolean;\n    }>;\n    /** Show detailed checks status in response (default: true) */\n    detailed?: boolean;\n    /** Include in global prefix (default: false) */\n    withGlobalPrefix?: boolean;\n  };\n\n  /** Request timeout in ms (default: 30000 - 30 seconds)\n   *  - default: 30000\n   */\n  requestTimeout?: number;\n\n  /** Response timing configuration\n   *  - enable: false\n   *  - addHeader: true\n   *  - logOnComplete: false\n   */\n  responseTime?: {\n    /** Enable timing (default: false) */\n    enable: boolean;\n    /** Add X-Response-Time header (default: true) */\n    addHeader?: boolean;\n    /** Log completion time (default: false) */\n    logOnComplete?: boolean;\n  };\n\n  /** Request ID configuration\n   *  - headerName: 'x-request-id'\n   *  - exposeHeader: true\n   *  - generator: uuid()\n   */\n  requestId?: {\n    /** Header name (default: 'x-request-id') */\n    headerName?: string;\n    /** Add to response headers (default: true) */\n    exposeHeader?: boolean;\n    /** ID generator (default: uuid()) */\n    generator?: () => string;\n  };\n\n  /** Global route prefix (default: '/')\n   *  - default: '/'\n   */\n  globalPrefix?: string;\n\n  /** OpenAPI documentation\n   *  - enable: false\n   *  - mountPath: '/docs'\n   *  - verbose: false\n   *  - withGlobalPrefix: false\n   */\n  openApi?: {\n    /** Enable docs (default: false) */\n    enable: boolean;\n    /** UI path (default: '/docs') */\n    mountPath?: string;\n    /** Spec file path (required if enabled) */\n    filePath?: string;\n    /** Enable verbose logs (default: false) */\n    verbose?: boolean;\n    /** Include in global prefix (default: false) */\n    withGlobalPrefix?: boolean;\n  };\n\n  /** Logger settings\n   *  - name: 'express_app'\n   *  - level: 'info'\n   *  - prettyPrint: default true if process.env.NODE_ENV === 'development'\n   *  - singleLine: false\n   */\n  logger?: {\n    /** Logger name (default: 'express_app') */\n    name?: string;\n    /** Log level (default: 'info') */\n    level?: LoggerLevels;\n    /** Pretty print (default: true in dev) */\n    prettyPrint?: boolean;\n    /** Single line output for pretty print (default: false) */\n    singleLine?: boolean;\n  };\n\n  /** Prometheus metrics\n   *  - enable: false\n   *  - path: '/metrics'\n   *  - withGlobalPrefix: false\n   */\n  metrics?: {\n    /** Enable metrics (default: false) */\n    enable: boolean;\n    /** Metrics path (default: '/metrics') */\n    path?: string;\n    /** Include in global prefix (default: false) */\n    withGlobalPrefix?: boolean;\n  };\n\n  /** Service version header\n   *  - enable: false\n   *  - headerName: 'x-service-version'\n   *  - version: '0.0.0'\n   */\n  serviceVersion?: {\n    /** Enable version header (default: false) */\n    enable: boolean;\n    /** Header name (default: 'x-service-version') */\n    headerName?: string;\n    /** Version value (default: '0.0.0') */\n    version?: string | (() => string);\n  };\n\n  /**\n   * HTTPS configuration (if provided, server will use HTTPS)\n   * Requires 'key' and 'cert' at minimum.\n   * @command - to generate self-signed certificates\n   * ```bash\n   * choco install mkcert\n   * mkcert -key-file localhost-key.pem -cert-file localhost-cert.pem localhost 127.0.0.1 ::1\n   * ```\n   */\n  https?: {\n    /** Path to SSL private key file (PEM) */\n    key: string;\n    /** Path to SSL certificate file (PEM) */\n    cert: string;\n    /** Optional path to CA bundle file (PEM) */\n    ca?: string;\n    /** Optional passphrase for the private key */\n    passphrase?: string;\n    /** Any other https.ServerOptions */\n    [key: string]: any;\n  };\n}\n\n/**\n * Server lifecycle hooks for custom behavior injection.\n * Allows extending server functionality without modifying core code.\n * All hooks can be async and support error handling.\n */\nexport interface ServerHooks {\n  /** Called before any middleware or routes are initialized - good for early setup */\n  beforeInit?: (server: ExpressServer) => Promise<void> | void;\n  /** Called after middleware and routes are set up - good for final configuration */\n  afterInit?: (server: ExpressServer) => Promise<void> | void;\n  /** Called just before the server starts listening - good for last-minute checks */\n  beforeStart?: (app: Express) => Promise<void> | void;\n  /** Called after the server starts successfully - good for announcing readiness */\n  afterStart?: (server: http.Server) => Promise<void> | void;\n  /** Called before graceful shutdown begins - good for cleanup preparation */\n  beforeStop?: (server: http.Server) => Promise<void> | void;\n  /** Called after server has stopped - good for final cleanup */\n  afterStop?: () => Promise<void> | void;\n  /** Custom global error handler - overrides the default error handling */\n  onError?: (error: Error, req: Request, res: Response, next: NextFunction) => void;\n  /** Called at the start of each request - good for request preprocessing */\n  onRequest?: (req: Request, res: Response, next: NextFunction) => void;\n  /** Called before response is sent - good for response modification */\n  onResponse?: (req: Request, res: Response, next: NextFunction) => void;\n}\n"]}

package/build/esm/utils/array.utils.d.ts

@@ -1,168 +0,0 @@
-/**
- * Splits an array into chunks of the specified size.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The array to split into chunks.
- * @param {number} size - The number of elements per chunk.
- * @returns {T[][]} A new array containing chunked arrays.
- * @throws {TypeError} If array is not an array.
- * @throws {Error} If chunk size is not a positive integer.
- */
-export declare function chunk<T>(array: T[], size: number): T[][];
-/**
- * Removes duplicate values from an array.
- * Optionally enforces uniqueness by a key function.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @param {(item: T) => unknown} [keyFn] - Optional function to determine uniqueness by key.
- * @returns {T[]} A new array with unique values.
- */
-export declare function unique<T>(array: T[], keyFn?: (item: T) => unknown): T[];
-/**
- * Deeply flattens a nested array to a single-level array.
- *
- * @template T The leaf type of array elements.
- * @param {any[]} array - The (possibly deeply nested) input array.
- * @returns {T[]} A deeply flattened array.
- */
-export declare function flattenDeep<T>(array: any[]): T[];
-/**
- * Returns a random element from an array, or undefined if empty.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @returns {T | undefined} A randomly selected item, or undefined if array is empty or not an array.
- */
-export declare function random<T>(array: T[]): T | undefined;
-/**
- * Groups items in an array by a key or key function.
- *
- * @template T The type of array elements.
- * @overload
- * @param {T[]} array - The array to group.
- * @param {keyof T} key - Property key to group by.
- * @returns {Record<string, T[]>}
- * @overload
- * @param {T[]} array - The array to group.
- * @param {(item: T) => string | number | symbol} keyFn - Function to generate group key from item.
- * @returns {Record<K, T[]>}
- * @param {T[]} array - The array to group.
- * @param {keyof T | ((item: T) => string | number | symbol)} keyOrFn - Property key or key-generating function.
- * @returns {Record<string | number | symbol, T[]>} An object mapping group keys to item arrays.
- */
-export declare function groupBy<T>(array: T[], key: keyof T): Record<string, T[]>;
-export declare function groupBy<T, K extends string | number | symbol>(array: T[], keyFn: (item: T) => K): Record<K, T[]>;
-/**
- * Shuffles an array using the Fisher-Yates algorithm.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @returns {T[]} A new shuffled array.
- * @throws {TypeError} If array is not an array.
- */
-export declare function shuffle<T>(array: T[]): T[];
-/**
- * Returns an array of property values from an array of objects.
- *
- * @template T The type of array elements.
- * @template K The object property to pluck.
- * @param {T[]} array - The input array.
- * @param {K} key - The property name to pluck.
- * @returns {T[K][]} Array of property values.
- */
-export declare function pluck<T, K extends keyof T>(array: T[], key: K): T[K][];
-/**
- * Returns values in array A that are not in array B.
- *
- * @template T The type of array elements.
- * @param {T[]} a - First array.
- * @param {T[]} b - Second array.
- * @returns {T[]} Elements in A that are not in B.
- */
-export declare function difference<T>(a: T[], b: T[]): T[];
-/**
- * Returns common values between arrays A and B.
- *
- * @template T The type of array elements.
- * @param {T[]} a - First array.
- * @param {T[]} b - Second array.
- * @returns {T[]} Elements that exist in both arrays.
- */
-export declare function intersect<T>(a: T[], b: T[]): T[];
-/**
- * Sorts an array of objects by a nested key using Merge Sort (O(n log n)).
- * Missing/undefined keys are sorted to the "end" (asc) or "start" (desc).
- *
- * @template T The type of array elements (objects).
- * @param {T[]} array - Array of objects to sort.
- * @param {string | ((item: T) => any)} key - Dot-notated key (e.g., "profile.age") or function.
- * @param {"asc" | "desc"} [direction="asc"] - Sort direction: 'asc' or 'desc'.
- * @returns {T[]} A new sorted array.
- * @throws {TypeError} If array is not an array.
- */
-export declare function mergeSort<T>(array: T[], key: string | ((item: T) => any), direction?: 'asc' | 'desc'): T[];
-/**
- * Combines multiple arrays into a single array of grouped elements.
- * Output array length equals the length of the shortest input array.
- *
- * @example zip([1, 2], ['a', 'b']) => [[1, 'a'], [2, 'b']]
- * @param {...Array<T>[]} arrays - Two or more arrays to zip together.
- * @returns {Array<T[]>} Array of grouped elements.
- */
-export declare function zip<T>(...arrays: T[][]): T[][];
-/**
- * Splits an array into two arrays based on a predicate function.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @param {(item: T, index: number, array: T[]) => boolean} predicate - Function to test each element.
- * @returns {[T[], T[]]} A tuple of two arrays: [matched, unmatched].
- */
-export declare function partition<T>(array: T[], predicate: (item: T, index: number, array: T[]) => boolean): [T[], T[]];
-/**
- * Generates an array of numbers within a specified range.
- *
- * @param {number} start - Start of range (inclusive).
- * @param {number} end - End of range (exclusive).
- * @param {number} [step=1] - Step between numbers.
- * @returns {number[]} Array of numbers in range.
- */
-export declare function range(start: number, end: number, step?: number): number[];
-/**
- * Returns the first n elements of an array.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @param {number} [n=1] - Number of elements to take.
- * @returns {T[]} New array with first n elements.
- */
-export declare function take<T>(array: T[], n?: number): T[];
-/**
- * Takes elements from the array while predicate returns true.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @param {(item: T, index: number) => boolean} predicate - Function to test each element.
- * @returns {T[]} New array with taken elements.
- */
-export declare function takeWhile<T>(array: T[], predicate: (item: T, index: number) => boolean): T[];
-/**
- * Removes all falsy values from an array.
- * False, null, 0, "", undefined, and NaN are falsy.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @returns {NonNullable<T>[]} New array with falsy values removed.
- */
-export declare function compact<T>(array: T[]): NonNullable<T>[];
-/**
- * Counts array elements by a key function.
- *
- * @template T The type of array elements.
- * @param {T[]} array - The input array.
- * @param {(item: T) => string | number | symbol} keyFn - Function to generate count key.
- * @returns {Record<string, number>} Object with counts by key.
- */
-export declare function countBy<T>(array: T[], keyFn: (item: T) => string | number | symbol): Record<string, number>;
-//# sourceMappingURL=array.utils.d.ts.map