@catbee/utils 0.0.8-rc.2 → 0.0.8-rc.4

package/build/esm/types/api-response.d.ts

@@ -1,151 +0,0 @@
-/**
- * Generic API response format.
- * Used to wrap any successful or failed response from the server.
- */
-export interface ApiResponse<T = any> {
-    /** Payload returned from the API. Can be any shape depending on the endpoint. */
-    data: T | null;
-    /** Indicates whether an error occurred (true = error, false = success). */
-    error: boolean;
-    /** Success message describing the result of the operation. */
-    message: string;
-    /** Unique request ID for traceability in logs (e.g., from a middleware). */
-    requestId: string;
-    /** ISO timestamp when the response was generated. */
-    timestamp: string;
-}
-/**
- * Generic pagination structure used for paged lists (e.g., /users?page=1).
- */
-export interface Pagination<T = any> {
-    /** List of records for the current page. */
-    content: T[];
-    /** Metadata about the pagination state. */
-    pagination: {
-        /** Total number of records across all pages. */
-        totalRecords: number;
-        /** Total number of pages available. */
-        totalPages: number;
-        /** Current page number (1-based index). */
-        page: number;
-        /** Number of records per page. */
-        limit: number;
-        /** Field by which the data is sorted. */
-        sortBy: string;
-        /** Sort order: ascending or descending. */
-        sortOrder: 'asc' | 'desc';
-    };
-}
-/**
- * Alias for paginated API response.
- * Allows semantic naming like `PaginationResponse<User>` or `PaginationResponse<Post>`.
- */
-export type PaginationResponse<T = any> = Pagination<T>;
-/**
- * Error response structure with additional metadata.
- * Used for providing richer error information to clients.
- */
-export interface ApiErrorResponse extends Omit<ApiResponse<never>, 'data'> {
-    /** Error always true for error responses */
-    error: true;
-    /** HTTP status code */
-    status: number;
-    /** Path to the resource that caused the error */
-    path: string;
-    /** Stack trace of the error (if available) */
-    stack?: string[];
-}
-/**
- * Success response structure with strongly typed data.
- * Used for providing successful responses to clients.
- */
-export interface ApiSuccessResponse<T = any> extends ApiResponse<T> {
-    /** Error always false for success responses */
-    error: false;
-    /** HTTP status code (usually 200) */
-    status?: number;
-}
-/**
- * Response structure for batch operations.
- * Used when multiple operations are performed in a single request.
- */
-export interface BatchResponse<T = any> {
-    /** Overall success/failure indicator */
-    success: boolean;
-    /** Total number of operations */
-    total: number;
-    /** Number of successful operations */
-    successful: number;
-    /** Number of failed operations */
-    failed: number;
-    /** Results of individual operations */
-    results: Array<{
-        /** Identifier for this operation */
-        id: string | number;
-        /** Success/failure indicator for this operation */
-        success: boolean;
-        /** Response data for this operation */
-        data?: T;
-        /** Error information if this operation failed */
-        error?: {
-            message: string;
-            code?: string;
-        };
-    }>;
-}
-/**
- * Response structure for asynchronous operations.
- * Used when the operation will complete in the future.
- */
-export interface AsyncOperationResponse {
-    /** Always true for async operations */
-    async: true;
-    /** Job or task ID to check status later */
-    jobId: string;
-    /** Estimated completion time in seconds (if known) */
-    estimatedTime?: number;
-    /** URL to check status */
-    statusUrl: string;
-}
-/**
- * Response structure for streaming operations.
- * Used when data is returned as a stream rather than all at once.
- */
-export interface StreamResponse {
-    /** Stream identifier */
-    streamId: string;
-    /** Stream type (e.g., 'json', 'binary') */
-    streamType: string;
-    /** Total size in bytes (if known) */
-    totalSize?: number;
-    /** Chunk size in bytes */
-    chunkSize: number;
-}
-/**
- * Sort direction enumeration.
- */
-export declare enum SortDirection {
-    /** Ascending sort order */
-    ASC = "asc",
-    /** Descending sort order */
-    DESC = "desc"
-}
-/**
- * Pagination parameters for API requests.
- */
-export interface PaginationParams {
-    /** Current page number (1-based index) */
-    page: number;
-    /** Number of records per page */
-    limit: number;
-    /** Field by which the data is sorted */
-    sortBy: string;
-    /** Sort order: ascending or descending */
-    sortOrder: SortDirection;
-    /** Optional search query */
-    search?: string;
-}
-/**
- * Type that combines pagination parameters with additional data.
- */
-export type WithPagination<T = {}> = PaginationParams & T;

package/build/esm/types/api-response.js

@@ -1,33 +0,0 @@
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
- *
- * 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.
- */
-/**
- * Sort direction enumeration.
- */
-export var SortDirection;
-(function (SortDirection) {
-    /** Ascending sort order */
-    SortDirection["ASC"] = "asc";
-    /** Descending sort order */
-    SortDirection["DESC"] = "desc";
-})(SortDirection || (SortDirection = {}));

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

@@ -1,124 +0,0 @@
-/**
- * A type that represents a configurable toggle.
- * Can be `true`, `false`, or a custom configuration object `T`.
- */
-export type ToggleConfig<T> = boolean | T;
-/**
- * A type representing a value that can be `null` or `undefined`.
- */
-export type Nullable<T> = T | null | undefined;
-/**
- * A type representing a value that may or may not be present.
- */
-export type Optional<T> = T | undefined;
-/**
- * A type that makes all properties of `T` deeply optional.
- */
-export type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
-};
-/**
- * A type that makes all properties of `T` readonly, recursively.
- */
-export type DeepReadonly<T> = {
-    readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
-};
-/**
- * A type that converts a union of types into an intersection.
- */
-export type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
-/**
- * A type representing a promise or a plain value.
- */
-export type MaybePromise<T> = T | Promise<T>;
-/**
- * A type representing a record with string keys and values of type `T`.
- */
-export type StringKeyedRecord<T> = Record<string, T>;
-/**
- * A type representing a function that returns `R` and optionally receives arguments `A`.
- */
-export type Func<A extends any[] = any[], R = any> = (...args: A) => R;
-/**
- * A type representing a partial pick from `T` (like Partial + Pick combined)
- */
-export type PartialPick<T, K extends keyof T> = Partial<Pick<T, K>> & Omit<T, K>;
-/**
- * A type that deeply stringifies all properties of T or makes them null.
- */
-export type DeepStringifyOrNull<T> = T extends string | number | boolean | bigint | boolean | symbol | null | undefined | null ? string | null : T extends Array<infer U> ? Array<DeepStringifyOrNull<U>> : T extends object ? {
-    [K in keyof T]: DeepStringifyOrNull<T[K]>;
-} : string | null;
-/**
- * A type representing a non-empty array of T.
- */
-export type NonEmptyArray<T> = [T, ...T[]];
-/**
- * A type representing the union of all property values of T.
- */
-export type ValueOf<T> = T[keyof T];
-/**
- * A type that makes all properties of T mutable (removes readonly).
- */
-export type Mutable<T> = {
-    -readonly [P in keyof T]: T[P];
-};
-/**
- * A type that gets the keys of T whose values are assignable to U.
- */
-export type KeysOfType<T, U> = {
-    [K in keyof T]: T[K] extends U ? K : never;
-}[keyof T];
-/**
- * Require at least one of the keys in K to be present in T.
- */
-export type RequireAtLeastOne<T, K extends keyof T = keyof T> = K extends keyof T ? {
-    [P in K]-?: T[P];
-} & Omit<T, K> : never;
-/**
- * A record type with optional keys.
- */
-export type RecordOptional<K extends string | number | symbol, T> = {
-    [P in K]?: T;
-};
-/**
- * Primitive types in TypeScript.
- */
-export type Primitive = string | number | boolean | bigint | symbol | undefined | null;
-/**
- * Recursively unwraps Promise types to get their resolved value type.
- */
-export type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;
-/**
- * Picks properties from T that are of type U.
- */
-export type PickByType<T, U> = {
-    [P in keyof T as T[P] extends U ? P : never]: T[P];
-};
-/**
- * Makes all properties of T required recursively.
- */
-export type DeepRequired<T> = {
-    [P in keyof T]-?: T[P] extends object ? DeepRequired<T[P]> : T[P];
-};
-/**
- * Checks if two types are exactly equal.
- * Returns true or false as type.
- */
-export type IsEqual<T, U> = (<G>() => G extends T ? 1 : 2) extends <G>() => G extends U ? 1 : 2 ? true : false;
-/**
- * Makes all properties of an object writable (removes readonly).
- */
-export type Writable<T> = {
-    -readonly [P in keyof T]: T[P];
-};
-/**
- * Makes specific keys K of type T optional.
- */
-export type Optional2<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-/**
- * Creates a type with all properties of T except those with types assignable to U.
- */
-export type Without<T, U> = {
-    [P in keyof T as T[P] extends U ? never : P]: T[P];
-};

package/build/esm/types/index.js

@@ -1,24 +0,0 @@
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
- *
- * 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 {};

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

@@ -1,267 +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 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;
-    };
-    /** 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;
-}

package/build/esm/types/server.js

@@ -1,24 +0,0 @@
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
- *
- * 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 {};