@catbee/utils 1.0.5 → 2.0.0-next.0

package/type/index.mjs

@@ -0,0 +1,119 @@
+/*
+ * 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.
+ */
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/type/type.utils.ts
+function isPrimitiveType(value, type) {
+  if (type === "array") {
+    return Array.isArray(value);
+  }
+  if (type === "null") {
+    return value === null;
+  }
+  if (type === "undefined") {
+    return value === void 0;
+  }
+  if (type === "object") {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+  return typeof value === type;
+}
+__name(isPrimitiveType, "isPrimitiveType");
+function getTypeOf(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+__name(getTypeOf, "getTypeOf");
+function isArrayOf(value, itemTypeGuard) {
+  if (!Array.isArray(value)) return false;
+  return value.every((item) => itemTypeGuard(item));
+}
+__name(isArrayOf, "isArrayOf");
+function toStr(value, defaultValue = "") {
+  if (value === null || value === void 0) return defaultValue;
+  try {
+    if (typeof value === "object") {
+      return JSON.stringify(value);
+    }
+    return String(value);
+  } catch {
+    return defaultValue;
+  }
+}
+__name(toStr, "toStr");
+function toNum(value, defaultValue = 0) {
+  if (value === null || value === void 0) return defaultValue;
+  if (typeof value === "number") return value;
+  try {
+    const num = Number(value);
+    return isNaN(num) ? defaultValue : num;
+  } catch {
+    return defaultValue;
+  }
+}
+__name(toNum, "toNum");
+function toBool(value, defaultValue = false) {
+  if (value === null || value === void 0) return defaultValue;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    const lowercased = value.toLowerCase();
+    if (lowercased === "true" || lowercased === "yes" || lowercased === "y" || lowercased === "1") {
+      return true;
+    }
+    if (lowercased === "false" || lowercased === "no" || lowercased === "n" || lowercased === "0") {
+      return false;
+    }
+  }
+  if (typeof value === "number") {
+    return value !== 0;
+  }
+  return defaultValue;
+}
+__name(toBool, "toBool");
+function ensureType(value, expectedType, defaultValue) {
+  if (getTypeOf(value) === expectedType) {
+    return value;
+  }
+  return defaultValue;
+}
+__name(ensureType, "ensureType");
+function isDefined(value) {
+  return value !== null && value !== void 0;
+}
+__name(isDefined, "isDefined");
+function isEmpty(value) {
+  if (value == null) return true;
+  if (typeof value === "string") return value.trim().length === 0;
+  if (Array.isArray(value)) return value.length === 0;
+  if (value instanceof Map || value instanceof Set) return value.size === 0;
+  if (typeof value === "object") return Object.keys(value).length === 0;
+  return false;
+}
+__name(isEmpty, "isEmpty");
+
+export { ensureType, getTypeOf, isArrayOf, isDefined, isEmpty, isPrimitiveType, toBool, toNum, toStr };

package/type/type.utils.d.ts

@@ -0,0 +1,129 @@
+/*
+ * 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.
+ */
+
+/**
+ * Check if a value is of a specific primitive type.
+ *
+ * @param value - Value to check
+ * @param type - Type to check against
+ * @returns Whether the value is of the specified type
+ *
+ * @example
+ * ```typescript
+ * isPrimitiveType('hello', 'string'); // true
+ * isPrimitiveType(42, 'number'); // true
+ * isPrimitiveType(true, 'boolean'); // true
+ * isPrimitiveType(null, 'null'); // true
+ * isPrimitiveType(undefined, 'undefined'); // true
+ * isPrimitiveType({}, 'object'); // true
+ * isPrimitiveType([], 'array'); // true
+ * ```
+ */
+export declare function isPrimitiveType(value: unknown, type: 'string' | 'number' | 'boolean' | 'symbol' | 'bigint' | 'function' | 'object' | 'array' | 'null' | 'undefined'): boolean;
+/**
+ * Get the primitive type of a value as a string.
+ *
+ * @param value - Value to get the type of
+ * @returns String representing the type
+ *
+ * @example
+ * ```typescript
+ * getTypeOf('hello'); // 'string'
+ * getTypeOf(42); // 'number'
+ * getTypeOf([]); // 'array'
+ * getTypeOf(null); // 'null'
+ * ```
+ */
+export declare function getTypeOf(value: unknown): string;
+/**
+ * Type guard for checking if a value is an array of a specific type.
+ *
+ * @param value - Value to check
+ * @param itemTypeGuard - Function that checks if items are of the expected type
+ * @returns True if the value is an array with items of the expected type
+ *
+ * @example
+ * ```typescript
+ * isArrayOf([1, 2, 3], (item): item is number => typeof item === 'number'); // true
+ * isArrayOf(['a', 'b', 'c'], (item): item is string => typeof item === 'string'); // true
+ * isArrayOf([1, '2', 3], (item): item is number => typeof item === 'number'); // false
+ * ```
+ */
+export declare function isArrayOf<T>(value: unknown, itemTypeGuard: (item: unknown) => item is T): value is T[];
+/**
+ * Convert a value to a string.
+ *
+ * @param value - Value to convert
+ * @param defaultValue - Default value if conversion fails
+ * @returns String representation of the value
+ */
+export declare function toStr(value: unknown, defaultValue?: string): string;
+/**
+ * Convert a value to a number.
+ *
+ * @param value - Value to convert
+ * @param defaultValue - Default value if conversion fails
+ * @returns Numeric representation of the value
+ */
+export declare function toNum(value: unknown, defaultValue?: number): number;
+/**
+ * Convert a value to a boolean.
+ *
+ * @param value - Value to convert
+ * @param defaultValue - Default value if conversion fails
+ * @returns Boolean representation of the value
+ */
+export declare function toBool(value: unknown, defaultValue?: boolean): boolean;
+/**
+ * Ensure a value matches the expected type, or provide a default.
+ *
+ * @param value - Value to check
+ * @param expectedType - Expected primitive type
+ * @param defaultValue - Default value to use if type doesn't match
+ * @returns The value if it matches the type, otherwise the default
+ *
+ * @example
+ * ```typescript
+ * ensureType(42, 'number', 0); // 42
+ * ensureType('42', 'number', 0); // 0
+ * ensureType(undefined, 'string', 'default'); // 'default'
+ * ```
+ */
+export declare function ensureType<T>(value: unknown, expectedType: string, defaultValue: T): T;
+/**
+ * Check whether a value is neither null nor undefined.
+ * Useful in filter chains and guards.
+ *
+ * @param value - Value to check
+ * @returns True when value !== null && value !== undefined
+ */
+export declare function isDefined<T>(value: T | null | undefined): value is T;
+/**
+ * Check whether a value is empty.
+ * Supports strings, arrays, maps, sets and plain objects.
+ *
+ * @param value - Value to inspect
+ * @returns True when value is considered empty
+ */
+export declare function isEmpty(value: any): boolean;

package/types/api-response.d.ts

@@ -0,0 +1,175 @@
+/*
+ * 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

@@ -0,0 +1,148 @@
+/*
+ * 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

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

package/types/index.cjs

@@ -0,0 +1,34 @@
+/*
+ * 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.
+ */
+
+'use strict';
+
+// src/types/api-response.ts
+var SortDirection = /* @__PURE__ */ (function(SortDirection2) {
+  SortDirection2["ASC"] = "asc";
+  SortDirection2["DESC"] = "desc";
+  return SortDirection2;
+})({});
+
+exports.SortDirection = SortDirection;