@catbee/utils 2.0.0-next.0 → 2.0.0-next.1

package/types/api-response.d.ts

@@ -1,175 +0,0 @@
-/*
- * The MIT License
- * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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.
- */
-
-/**
- * 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/types/common.d.ts

@@ -1,148 +0,0 @@
-/*
- * The MIT License
- * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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.
- */
-
-/**
- * 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/types/config.d.ts

@@ -1,88 +0,0 @@
-/*
- * The MIT License
- * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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.
- */
-
-import type { LoggerLevels } from '@catbee/utils/logger';
-export interface CatbeeConfig {
-    logger?: {
-        /**
-         * Logging level (e.g., 'info', 'debug', 'warn', 'error')
-         * Environment variable: LOGGER_LEVEL
-         * Default: 'info' in production, 'debug' in development
-         */
-        level?: LoggerLevels;
-        /**
-         * Name of the logger instance (defaults to npm package name)
-         * Environment variable: LOGGER_NAME
-         * Default: value of npm_package_name or '@catbee/utils'
-         */
-        name?: string;
-        /**
-         * Enables pretty-print logging in development.
-         * Has no effect in production.
-         * Environment variable: LOGGER_PRETTY
-         * Default: true in development, false in production
-         */
-        pretty?: boolean;
-        /**
-         * Enables colorized output for pretty-print (default: true)
-         * Environment variable: LOGGER_PRETTY_COLORIZE
-         */
-        colorize?: boolean;
-        /**
-         * Single line output for pretty-print (default: false)
-         * Environment variable: LOGGER_PRETTY_SINGLE_LINE
-         */
-        singleLine?: boolean;
-        /**
-         * Directory to write log files to (if empty, file logging is disabled)
-         * Environment variable: LOGGER_DIR
-         * Eg: process.cwd() + '/logs'
-         * Note: Directory must exist, it is not created automatically
-         */
-        dir?: string;
-    };
-    cache: {
-        /**
-         * Default TTL (time to live) for cache entries in milliseconds
-         * Environment variable: CACHE_DEFAULT_TTL_SECONDS
-         * Default: 3600000 (1 hour)
-         */
-        defaultTtl: number;
-    };
-    server: {
-        /**
-         * Skip healthz endpoint even if health checks are configured
-         * Default: false
-         * Set to true to return 200 OK for /healthz without checks
-         * Useful in environments where a simple liveness probe is needed
-         * without performing actual health checks
-         * Example: Kubernetes liveness probe
-         * Note: This does not disable the health check functionality itself
-         *       Health checks can still be performed programmatically
-         *       or via other endpoints if needed
-         * Environment variable: SERVER_SKIP_HEALTHZ
-         */
-        skipHealthz: boolean;
-    };
-}