@catbee/utils 0.0.8-rc.4 → 1.0.2

package/build/index.d.ts

@@ -26,6 +26,7 @@ import { AsyncLocalStorage } from 'async_hooks';
 import { BinaryToTextEncoding, CipherGCMTypes } from 'crypto';
 import express, { RequestHandler, Router, Request, Response, NextFunction, Express, json, urlencoded } from 'express';
 import fs, { Stats } from 'fs';
+import { Readable, Transform } from 'stream';
 import * as prom_client from 'prom-client';
 import http from 'http';
 import https from 'https';
@@ -37,7 +38,7 @@ import { CorsOptions } from 'cors';
 /**
  * Logger type for application-wide logging.
  */
-type Logger = pino.Logger;
+type Logger = Logger$1;
 /**
  * Logger levels for application-wide logging.
  */
@@ -158,12 +159,14 @@ declare const _globalThis: typeof globalThis;
  * - Returns a request-scoped logger from AsyncLocalStorage if available
  * - Falls back to the global (singleton) logger
  * - Initializes the global logger if not created yet
+ * - If newInstance is true, returns a fresh logger without any context
  *
- * @returns {Logger} The logger instance (request-bound or global root logger)
+ * @param {boolean} newInstance - If true, returns a fresh logger without any context
+ * @returns {Logger} The logger instance (request-bound or global root logger or fresh instance)
  */
-declare function getLogger(): Logger$1;
+declare function getLogger(newInstance?: boolean): Logger$1;
 /**
- * Logger instance for the global context.
+ * Returns a fresh logger instance without any request context.
  * This logger is used for logging messages that are not tied to a specific request.
  */
 declare const logger: pino.Logger;
@@ -1182,12 +1185,190 @@ declare function createSignedToken(payload: Record<string, any>, secret: string,
  */
 declare function verifySignedToken(token: string, secret: string): Record<string, any> | null;
 
+/**
+ * Format options for the formatDate function
+ */
+interface DateFormatOptions {
+    /** Date format pattern (default: 'yyyy-MM-dd') */
+    format?: string;
+    /** Locale to use for formatting (default: system locale) */
+    locale?: string | string[];
+    /** Time zone to use (default: system time zone) */
+    timeZone?: string;
+}
+/**
+ * Format a date according to the specified format pattern.
+ *
+ * @param date - Date to format
+ * @param options - Formatting options
+ * @returns Formatted date string
+ *
+ * @example
+ * ```typescript
+ * // Format as ISO date
+ * formatDate(new Date(), { format: 'yyyy-MM-dd' }); // '2023-05-15'
+ *
+ * // Format with time
+ * formatDate(new Date(), { format: 'yyyy-MM-dd HH:mm:ss' }); // '2023-05-15 14:30:22'
+ *
+ * // Format with locale
+ * formatDate(new Date(), { format: 'PPPP', locale: 'fr-FR' }); // 'lundi 15 mai 2023'
+ * ```
+ */
+declare function formatDate(date: Date | number, options?: DateFormatOptions): string;
+/**
+ * Format a date as relative time (e.g., "5 minutes ago", "in 3 days").
+ *
+ * @param date - Date to format
+ * @param now - Reference date (default: current time)
+ * @param locale - Locale to use for formatting
+ * @returns Formatted relative time string
+ */
+declare function formatRelativeTime(date: Date | number, now?: Date | number, locale?: string | string[]): string;
+/**
+ * Parse a date string or timestamp into a Date object.
+ *
+ * @param input - Date string or timestamp to parse
+ * @param fallback - Fallback date if parsing fails
+ * @returns Parsed Date object or fallback
+ *
+ * @example
+ * ```typescript
+ * parseDate('2023-05-15'); // Date object for May 15, 2023
+ * parseDate('invalid', new Date()); // Returns current date as fallback
+ * ```
+ */
+declare function parseDate(input: string | number, fallback?: Date): Date | null;
+/**
+ * Calculate the difference between two dates in the specified unit.
+ *
+ * @param date1 - First date
+ * @param date2 - Second date (default: current time)
+ * @param unit - Unit of time for the difference
+ * @returns Difference in the specified unit
+ *
+ * @example
+ * ```typescript
+ * // Get difference in days
+ * dateDiff(new Date('2023-05-15'), new Date('2023-05-10'), 'days'); // 5
+ *
+ * // Get difference in hours
+ * dateDiff(new Date('2023-05-15T10:00:00'), new Date('2023-05-15T06:00:00'), 'hours'); // 4
+ * ```
+ */
+declare function dateDiff(date1: Date | number, date2?: Date | number, unit?: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'): number;
+/**
+ * Add a specified amount of time to a date.
+ *
+ * @param date - Base date
+ * @param amount - Amount to add (can be negative)
+ * @param unit - Unit of time to add
+ * @returns New date with the addition
+ *
+ * @example
+ * ```typescript
+ * // Add 5 days
+ * addToDate(new Date('2023-05-15'), 5, 'days'); // Date for May 20, 2023
+ *
+ * // Subtract 2 hours
+ * addToDate(new Date('2023-05-15T10:00:00'), -2, 'hours'); // Date for May 15, 2023 08:00:00
+ * ```
+ */
+declare function addToDate(date: Date | number, amount: number, unit: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'): Date;
+/**
+ * Get the start of a time period containing the specified date.
+ *
+ * @param date - Date to get the start from
+ * @param unit - Time unit
+ * @returns Date object representing the start of the time unit
+ *
+ * @example
+ * ```typescript
+ * // Get start of day (midnight)
+ * startOf(new Date('2023-05-15T14:30:00'), 'day'); // Date for May 15, 2023 00:00:00
+ *
+ * // Get start of month
+ * startOf(new Date('2023-05-15'), 'month'); // Date for May 1, 2023
+ * ```
+ */
+declare function startOf(date: Date | number, unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'): Date;
+/**
+ * Get the end of a time period containing the specified date.
+ *
+ * @param date - Date to get the end from
+ * @param unit - Time unit
+ * @returns Date object representing the end of the time unit
+ *
+ * @example
+ * ```typescript
+ * // Get end of day (23:59:59.999)
+ * endOf(new Date('2023-05-15T14:30:00'), 'day'); // Date for May 15, 2023 23:59:59.999
+ *
+ * // Get end of month
+ * endOf(new Date('2023-05-15'), 'month'); // Date for May 31, 2023 23:59:59.999
+ * ```
+ */
+declare function endOf(date: Date | number, unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'): Date;
+/**
+ * Check if a date is between two other dates.
+ *
+ * @param date - Date to check
+ * @param start - Start date of the range
+ * @param end - End date of the range
+ * @param inclusive - Whether the comparison should be inclusive of start/end
+ * @returns True if the date is within the range
+ *
+ * @example
+ * ```typescript
+ * const date = new Date('2023-05-15');
+ * const start = new Date('2023-05-10');
+ * const end = new Date('2023-05-20');
+ *
+ * isBetween(date, start, end); // true
+ * ```
+ */
+declare function isBetween(date: Date | number, start: Date | number, end: Date | number, inclusive?: boolean): boolean;
+/**
+ * Check if a year is a leap year.
+ *
+ * @param year - Year to check (or date object)
+ * @returns True if the year is a leap year
+ */
+declare function isLeapYear(year: number | Date): boolean;
+/**
+ * Get the number of days in a month.
+ *
+ * @param year - Year
+ * @param month - Month (0-11)
+ * @returns Number of days in the month
+ */
+declare function daysInMonth(year: number | Date, month?: number): number;
+
+/**
+ * Parameter decoration definition for method parameters
+ */
+interface ParamDefinition {
+    /** Parameter position in method signature */
+    index: number;
+    /** Type of parameter (query, body, etc.) */
+    type: 'query' | 'param' | 'body' | 'req' | 'res' | 'logger' | 'reqHeader' | 'reqId' | 'cookie';
+    /** Optional key for extracting specific property */
+    key?: string;
+    /** Optional ParamOptions for advanced extraction */
+    options?: ParamOptions;
+}
 type Constructor<T = any> = new (...args: any[]) => T;
 declare class DIContainer {
     private instances;
     private constructing;
+    private propertyInjections;
     register<T>(target: Constructor<T>): void;
+    /**
+     * Register a property injection to be resolved when the target class is instantiated
+     */
+    registerPropertyInjection(target: object, propertyKey: string | symbol, injectClass: Constructor): void;
     get<T>(target: Constructor<T>): T;
+    private applyPropertyInjections;
     clear(): void;
 }
 /**
@@ -1203,6 +1384,16 @@ declare function Injectable(): ClassDecorator;
  * @returns Property decorator that injects the specified class into the property
  */
 declare function Inject<T>(targetClass: new (...args: any[]) => T): PropertyDecorator;
+/**
+ * Inject function for retrieving instances from the DI container.
+ * @param targetClass - The class to inject
+ *
+ * @returns The instance of the requested class
+ *
+ * @example
+ * const a = inject(TestClass);
+ */
+declare function inject<T>(targetClass: new (...args: any[]) => T): T;
 /**
  * Decorator for GET HTTP method routes.
  *
@@ -1299,11 +1490,11 @@ declare const Connect: (path: string) => MethodDecorator;
  */
 declare function Controller(basePath: string): ClassDecorator;
 /**
- * Decorator that applies middleware to a controller method.
+ * Decorator that applies middleware to a controller method or an entire controller.
  * Multiple middlewares can be applied and will execute in order.
  *
  * @param middlewares - Express middleware functions to apply
- * @returns Method decorator
+ * @returns Method decorator or Class decorator
  *
  * @example
  * ```ts
@@ -1312,39 +1503,89 @@ declare function Controller(basePath: string): ClassDecorator;
  * getProtectedResource() {
  *   // This route is protected by auth middleware
  * }
+ *
+ * @Controller('/api')
+ * @Use(commonMiddleware)
+ * class ApiController {
+ *   // All routes in this controller use the middleware
+ * }
  * ```
  */
-declare function Use(...middlewares: RequestHandler[]): MethodDecorator;
+declare function Use(...middlewares: RequestHandler[]): MethodDecorator & ClassDecorator;
+/**
+ * Options for parameter decorators
+ * @template T - Type of the parameter value after transformation
+ *
+ * @property type - Base type of the parameter (default: 'string')'
+ * @property dataType - Data structure type (single, array, object)
+ * @property delimiter - Delimiter for array types
+ * @property default - Default value if parameter is missing
+ * @property required - Whether the parameter is required
+ * @property throwError - Throw error on validation failure
+ * @property validate - Custom validation function
+ * @property transform - Custom transformation function
+ */
+interface ParamOptions<T = any> {
+    /** Base type of the parameter (default: 'string') */
+    type?: 'string' | 'number' | 'boolean';
+    /** Data structure type (default: 'single') */
+    dataType?: 'single' | 'array' | 'object';
+    /** Delimiter for array types (default: ',') */
+    delimiter?: string;
+    /** Default value if parameter is missing */
+    default?: T;
+    /** Whether the parameter is required (default: false) */
+    required?: boolean;
+    /** Throw error on validation failure (default: true) */
+    throwError?: boolean;
+    /** Minimum value for number type */
+    min?: number;
+    /** Maximum value for number type */
+    max?: number;
+    /** Regex pattern the value must match */
+    pattern?: RegExp;
+    /** Name of the pattern for error messages */
+    patternName?: string;
+    /** Custom validation function */
+    validate?: (value: any) => boolean;
+    /** Custom transformation function */
+    transform?: (value: any) => any;
+}
+declare function createParamDecorator(type: ParamDefinition['type'], key?: string): (paramKey?: string) => ParameterDecorator;
+declare function createParamDecoratorWithoutParam(type: ParamDefinition['type']): () => ParameterDecorator;
 /**
  * Decorator that extracts query parameters from request.
  *
  * @param paramKey - Optional key to extract specific query parameter
+ * @param options - Optional ParamOptions
  * @returns Parameter decorator
  *
  * @example
  * ```ts
  * @Get('/search')
- * search(@Query('term') searchTerm: string) {
- *   // searchTerm will contain the value of req.query.term
+ * search(@Query('term') term: string, @Query('page', { type: 'number', default: 1 }) page: number) {
+ *   // term will contain the value of req.query.term
+ *   // page will contain the numeric value of req.query.page or default to 1
  * }
  * ```
  */
-declare const Query: (paramKey?: string) => ParameterDecorator;
+declare const Query: (paramKey?: string, options?: ParamOptions) => ParameterDecorator;
 /**
  * Decorator that extracts route parameters from request.
  *
  * @param paramKey - Optional key to extract specific route parameter
+ * @param options - Optional ParamOptions
  * @returns Parameter decorator
  *
- * @example
+ *  @example
  * ```ts
  * @Get('/users/:id')
- * getUser(@Param('id') userId: string) {
- *   // userId will contain the value of req.params.id
+ * getUser(@Param('id') id: string) {
+ *   // id will contain the value of req.params.id
  * }
  * ```
  */
-declare const Param: (paramKey?: string) => ParameterDecorator;
+declare const Param: (paramKey?: string, options?: ParamOptions) => ParameterDecorator;
 /**
  * Decorator that extracts body or body property from request.
  *
@@ -1365,6 +1606,60 @@ declare const Param: (paramKey?: string) => ParameterDecorator;
  * ```
  */
 declare const Body: (paramKey?: string) => ParameterDecorator;
+/**
+ * Decorator that injects a logger instance.
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/log')
+ * log(@ReqLogger() logger: Logger) {
+ *   logger.info('Logging request...');
+ * }
+ * ```
+ */
+declare const ReqLogger: () => ParameterDecorator;
+/**
+ * Decorator that extracts request ID from headers.
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/data')
+ * getData(@ReqId() reqId: string) {
+ *  // reqId will contain the value of req.headers['x-request-id'] or req.id
+ * }
+ * ```
+ */
+declare const ReqId: () => ParameterDecorator;
+/**
+ * Decorator that extracts request headers.
+ * @param key - Optional key to extract specific header
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/data')
+ * getData(@ReqHeader('Authorization') authHeader: string) {
+ *   // authHeader will contain the value of req.headers['authorization']
+ * }
+ * ```
+ */
+declare const ReqHeader: (paramKey?: string) => ParameterDecorator;
+/**
+ * Decorator that extracts cookies from request.
+ * @param key - Optional key to extract specific cookie
+ * @returns Parameter decorator
+ *
+ * @example
+ * ```ts
+ * @Get('/data')
+ * getData(@ReqCookie('session_id') sessionId: string) {
+ *   // sessionId will contain the value of req.cookies['session_id']
+ * }
+ * ```
+ */
+declare const ReqCookie: (paramKey?: string) => ParameterDecorator;
 /**
  * Decorator that injects the entire request object.
  *
@@ -1379,7 +1674,7 @@ declare const Body: (paramKey?: string) => ParameterDecorator;
  * }
  * ```
  */
-declare const Req: (paramKey?: string) => ParameterDecorator;
+declare const Req: () => ParameterDecorator;
 /**
  * Decorator that injects the response object.
  *
@@ -1394,7 +1689,7 @@ declare const Req: (paramKey?: string) => ParameterDecorator;
  * }
  * ```
  */
-declare const Res: (paramKey?: string) => ParameterDecorator;
+declare const Res: () => ParameterDecorator;
 /**
  * Decorator that sets a custom HTTP status code for a response.
  *
@@ -1464,7 +1759,7 @@ declare function Headers(headers: Record<string, string> | string, value?: strin
  * Useful for pre-processing or logging.
  *
  * @param fn - Function to execute before the handler
- * @returns Method decorator
+ * @returns Method decorator or Class decorator
  *
  * @example
  * ```ts
@@ -1473,15 +1768,21 @@ declare function Headers(headers: Record<string, string> | string, value?: strin
  * getUser(@Param('id') id: string) {
  *   // Function will log before this handler runs
  * }
+ *
+ * @Controller('/api')
+ * @Before((req, res) => console.log(`API access: ${req.path}`))
+ * class ApiController {
+ *   // Hook runs before all routes in this controller
+ * }
  * ```
  */
-declare function Before(fn: Function): MethodDecorator;
+declare function Before(fn: Function): MethodDecorator & ClassDecorator;
 /**
  * Decorator that registers a function to run after route handler execution.
  * Can access the handler's result.
  *
  * @param fn - Function to execute after the handler
- * @returns Method decorator
+ * @returns Method decorator or Class decorator
  *
  * @example
  * ```ts
@@ -1491,9 +1792,15 @@ declare function Before(fn: Function): MethodDecorator;
  *   // After this handler, the function will log the returned data
  *   return { id, name: 'Example' };
  * }
+ *
+ * @Controller('/api')
+ * @After((req, res, result) => console.log(`API response: ${JSON.stringify(result)}`))
+ * class ApiController {
+ *   // Hook runs after all routes in this controller
+ * }
  * ```
  */
-declare function After(fn: Function): MethodDecorator;
+declare function After(fn: Function): MethodDecorator & ClassDecorator;
 /**
  * Decorator that requires specific roles for accessing a route.
  * Must be used with authentication middleware.
@@ -1585,7 +1892,7 @@ declare function RateLimit(options: {
  * Decorator that sets the content type for the response.
  *
  * @param type - MIME type for the response
- * @returns Method decorator
+ * @returns Method decorator or Class decorator
  *
  * @example
  * ```ts
@@ -1594,9 +1901,15 @@ declare function RateLimit(options: {
  * downloadPdf() {
  *   return this.fileService.generatePdf();
  * }
+ *
+ * @Controller('/api/json')
+ * @ContentType('application/json')
+ * class JsonApiController {
+ *   // All routes in this controller use this content type
+ * }
  * ```
  */
-declare function ContentType(type: string): MethodDecorator;
+declare function ContentType(type: string): MethodDecorator & ClassDecorator;
 /**
  * Decorator that adds API versioning to a route.
  *
@@ -3489,6 +3802,142 @@ declare function isObject(value: unknown): value is Record<string, any>;
  */
 declare function getAllPaths(obj: Record<string, any>, parentPath?: string): string[];
 
+/**
+ * Options for timing function execution.
+ */
+interface TimingOptions {
+    /** Optional label for the timing (defaults to function name) */
+    label?: string;
+    /** Whether to log the timing (default: false) */
+    log?: boolean;
+    /** Log level to use if logging is enabled (default: 'debug') */
+    logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error';
+}
+/**
+ * Result of a timing operation.
+ */
+interface TimingResult {
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Duration in seconds */
+    durationSec: number;
+    /** Start timestamp */
+    startTime: number;
+    /** End timestamp */
+    endTime: number;
+    /** Label used for the timing */
+    label: string;
+}
+/**
+ * Measure the execution time of a synchronous function.
+ *
+ * @param fn - Function to measure
+ * @param options - Timing options
+ * @returns Result containing the return value and timing information
+ *
+ * @example
+ * ```typescript
+ * const { result, timing } = timeSync(() => {
+ *   // Some expensive operation
+ *   return computeResult();
+ * }, { label: 'Computation', log: true });
+ *
+ * console.log(`Result: ${result}, took ${timing.durationMs}ms`);
+ * ```
+ */
+declare function timeSync<T>(fn: () => T, options?: TimingOptions): {
+    result: T;
+    timing: TimingResult;
+};
+/**
+ * Measure the execution time of an asynchronous function.
+ *
+ * @param fn - Async function to measure
+ * @param options - Timing options
+ * @returns Promise resolving to result and timing information
+ *
+ * @example
+ * ```typescript
+ * const { result, timing } = await timeAsync(async () => {
+ *   // Some expensive async operation
+ *   const data = await fetchData();
+ *   return processData(data);
+ * }, { label: 'API Request', log: true });
+ *
+ * console.log(`Fetched ${result.length} items in ${timing.durationSec.toFixed(2)}s`);
+ * ```
+ */
+declare function timeAsync<T>(fn: () => Promise<T>, options?: TimingOptions): Promise<{
+    result: T;
+    timing: TimingResult;
+}>;
+/**
+ * Create a timing decorator for class methods.
+ *
+ * @param options - Timing options
+ * @returns Method decorator
+ *
+ * @example
+ * ```typescript
+ * class DataService {
+ *   @timed({ log: true, logLevel: 'info' })
+ *   async fetchData() {
+ *     // ...implementation
+ *   }
+ * }
+ * ```
+ */
+declare function timed(options?: TimingOptions): (target: any, propertyKeyOrContext: string | symbol | any, descriptor?: PropertyDescriptor) => void;
+/**
+ * Memoize function results with optional TTL and max cache size.
+ *
+ * @param fn - Function to memoize
+ * @param options - Memoization options
+ * @returns Memoized function
+ *
+ * @example
+ * ```typescript
+ * // Cache results for 30 seconds, with a maximum of 100 entries
+ * const cachedFetch = memoize(
+ *   async (url) => {
+ *     const response = await fetch(url);
+ *     return response.json();
+ *   },
+ *   { ttl: 30000, maxSize: 100, cacheKey: (url) => url }
+ * );
+ * ```
+ */
+declare function memoize<T, Args extends any[]>(fn: (...args: Args) => T, options?: {
+    /** Time-to-live in milliseconds (default: indefinite) */
+    ttl?: number;
+    /** Maximum cache size (default: unlimited) */
+    maxSize?: number;
+    /** Function to generate a cache key from arguments */
+    cacheKey?: (...args: Args) => string;
+    /** Auto-cleanup interval in milliseconds (default: disabled) */
+    autoCleanupMs?: number;
+}): (...args: Args) => T;
+/**
+ * Track memory usage for a function execution.
+ *
+ * @param fn - Function to track
+ * @param options - Memory tracking options
+ * @returns Result and memory usage information
+ */
+declare function trackMemoryUsage<T>(fn: () => T, options?: {
+    /** Whether to log the memory usage (default: false) */
+    log?: boolean;
+    /** Label for the memory tracking (default: function name) */
+    label?: string;
+}): {
+    result: T;
+    memoryUsage: {
+        before: NodeJS.MemoryUsage;
+        after: NodeJS.MemoryUsage;
+        diff: Record<string, number>;
+    };
+};
+
 /**
  * Options for parsing and validating request parameters.
  */
@@ -3573,6 +4022,92 @@ declare function extractSortParams(query: Record<string, string | string[]>, all
  */
 declare function extractFilterParams(query: Record<string, string | string[]>, allowedFilters: string[]): Record<string, string | string[]>;
 
+/**
+ * Convert a buffer or string to a readable stream.
+ *
+ * @param data - Buffer or string to convert
+ * @returns Readable stream containing the data
+ *
+ * @example
+ * ```typescript
+ * const stream = bufferToStream(Buffer.from('Hello world'));
+ * // or
+ * const stream = bufferToStream('Hello world');
+ * ```
+ */
+declare function bufferToStream(data: Buffer | string): Readable;
+/**
+ * Convert a readable stream to a buffer.
+ *
+ * @param stream - Readable stream to convert
+ * @returns Promise resolving to a buffer containing all stream data
+ *
+ * @example
+ * ```typescript
+ * const buffer = await streamToBuffer(fs.createReadStream('file.txt'));
+ * console.log(buffer.toString()); // Contents of file.txt
+ * ```
+ */
+declare function streamToBuffer(stream: Readable): Promise<Buffer>;
+/**
+ * Convert a readable stream to a string.
+ *
+ * @param stream - Readable stream to convert
+ * @param encoding - Character encoding (default: 'utf8')
+ * @returns Promise resolving to a string containing all stream data
+ *
+ * @example
+ * ```typescript
+ * const content = await streamToString(fs.createReadStream('file.txt'));
+ * console.log(content); // Contents of file.txt as string
+ * ```
+ */
+declare function streamToString(stream: Readable, encoding?: BufferEncoding): Promise<string>;
+/**
+ * Create a transform stream that limits the rate of data flow.
+ *
+ * @param bytesPerSecond - Maximum bytes per second
+ * @returns Transform stream that throttles data flow
+ */
+declare function createThrottleStream(bytesPerSecond: number): Transform;
+/**
+ * Create a transform stream that batches data into chunks of specified size.
+ *
+ * @param size - Size of each batch (items for object mode, bytes for binary mode)
+ * @param options - Stream options
+ * @returns Transform stream that batches data
+ *
+ * @example
+ * ```typescript
+ * // Batch lines from a file into arrays of 100 lines each
+ * createReadStream('large-file.txt')
+ *   .pipe(createLineStream())
+ *   .pipe(createBatchStream(100))
+ *   .on('data', batch => console.log(`Processing batch of ${batch.length} lines`));
+ * ```
+ */
+declare function createBatchStream(size: number, options?: {
+    objectMode?: boolean;
+}): Transform;
+/**
+ * Create a transform stream that splits text data by newlines.
+ *
+ * @param options - Options for the line stream
+ * @returns Transform stream that emits lines
+ *
+ * @example
+ * ```typescript
+ * // Process a file line by line
+ * createReadStream('file.txt')
+ *   .pipe(createLineStream())
+ *   .on('data', line => console.log(`Line: ${line}`));
+ * ```
+ */
+declare function createLineStream(options?: {
+    encoding?: BufferEncoding;
+    includeNewlines?: boolean;
+}): Transform;
+
 /**
  * Capitalizes the first character of a string.
  *
@@ -3666,6 +4201,96 @@ declare function reverse(str: string): string;
  */
 declare function countOccurrences(str: string, substring: string, caseSensitive?: boolean): number;
 
+/**
+ * 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
+ * ```
+ */
+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'
+ * ```
+ */
+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
+ * ```
+ */
+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
+ */
+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
+ */
+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
+ */
+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'
+ * ```
+ */
+declare function ensureType<T>(value: unknown, expectedType: string, defaultValue: T): T;
+
 /**
  * Appends query parameters to a given URL.
  *
@@ -5128,4 +5753,4 @@ declare class ServerConfigBuilder {
     private setEnabled;
 }
 
-export { After, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type AsyncOperationResponse, type Awaited$1 as Awaited, BUILD_MARKER, BadGatewayException, BadRequestException, type BatchResponse, Before, Body, type BufferEncoding, Cache, CircuitBreakerOpenError, type CircuitBreakerOptions, CircuitBreakerState, ConflictException, Connect, ContentType, ContextStore, Controller, DIContainer, type DecryptionOptions, type DeepPartial, type DeepReadonly, type DeepRequired, type DeepStringifyOrNull, Delete, type EncryptionOptions, type EncryptionResult, Env, Environment, type ErrorHandlerOptions, ErrorResponse, ExpressServer, ForbiddenException, type Func, GatewayTimeoutException, Get, Head, Header, Headers, HttpCode, HttpError, HttpStatusCodes, Inject, Injectable, InsufficientStorageException, InternalServerErrorException, type IsEqual, type KeysOfType, Log, type Logger, type LoggerLevels, type MaybePromise, MethodNotAllowedException, type Middleware, type Mutable, NoContentResponse, type NonEmptyArray, NotAcceptableException, NotFoundException, type Nullable, type Optional, type Optional2, Options, PaginatedResponse, type Pagination, type PaginationParams, type PaginationResponse, Param, type PartialPick, Patch, type PathOptions, PayloadTooLargeException, type PickByType, Post, type Primitive, Put, Query, RateLimit, type RecordOptional, Redirect, RedirectResponse, Req, RequestTimeoutException, type RequireAtLeastOne, Res, Roles, type ServerConfig, ServerConfigBuilder, type ServerHooks, ServiceUnavailableException, SortDirection, type Store, StoreKeys, type StreamResponse, type StringKeyedRecord, SuccessResponse, TTLCache, type TTLCacheOptions, type TaskQueue, Timeout, type ToggleConfig, TooManyRequestsException, Trace, TypedContextKey, UnauthorizedException, type UnionToIntersection, UnprocessableEntityException, UnsupportedMediaTypeException, type UrlOptions, Use, type ValidationOptions, type ValidationResult, type ValueOf, Version, type WithPagination, type Without, type Writable, _globalThis, abortable, addRedactFields, addSensitiveFields, appendQueryParams, appendTextFile, capitalize, chunk, circuitBreaker, compact, copyDir, copyFile, countBy, countOccurrences, createChildLogger, createDeferred, createDirectory, createErrorResponse, createFinalErrorResponse, createHttpError, createPaginatedResponse, createRequestLogger, createSignedToken, createSuccessResponse, createTaskQueue, createTempDir, createTempFile, createUrlBuilder, debounce, decrypt, deepFreeze, deepObjMerge, defaultSensitiveFields, deleteDirRecursive, deleteFileIfExists, difference, emptyDir, encrypt, ensureDir, ensureEmptyDir, equalsIgnoreCase, errorHandler, extractFilterParams, extractPaginationParams, extractQueryParams, extractSortParams, fileExists, filterObject, findFilesByPattern, findInDir, findNewestFile, findOldestFile, flattenDeep, flattenObject, generateApiKey, generateRandomBytes, generateRandomBytesAsString, getAllPaths, getConfig, getDirSize, getDirStats, getDomain, getErrorMessage, getExtension, getFileSize, getFileStats, getFromContext, getLogger, getPaginationParams, getRedactCensor, getRequestId, getSubdirectories, getValueByPath, groupBy, hasErrorShape, hasRequiredProps, hash, healthCheck, hmac, intersect, isAlpha, isAlphanumeric, isArray, isBase64, isCreditCard, isDateInRange, isDirectory, isEmail, isEqual, isFile, isHexColor, isHttpError, isIPv4, isIPv6, isISODate, isLengthBetween, isNumberBetween, isNumeric, isObjEmpty, isObject, isPhone, isPlainObject, isPort, isStrongPassword, isURL, isUUID, isValidJSON, isValidUrl, joinPaths, listFiles, logError, logger, mapObject, mask, matchesPattern, md5, memoizeAsync, mergeSort, moveDir, moveFile, nanoId, normalizeUrl, omit, parseBooleanParam, parseNumberParam, parseQueryString, parseTypedQueryParams, partition, pick, pluck, random, randomBase64, randomHex, randomInt, randomString, range, rateLimit, readDirectory, readFileBuffer, readJsonFile, readTextFile, redact, registerControllers, removeQueryParams, requestId, responseTime, retry, reverse, runInBatches, runInSeries, runWithConcurrency, safeCompare, safeReadJsonFile, sendResponse, setConfig, setRedactCensor, setSensitiveFields, setValueByPath, settleAll, setupRequestContext, sha1, sha256, sha256Hmac, shuffle, singletonAsync, sleep, slugify, streamFile, stripHtml, take, takeWhile, throttle, timeout, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, truncate, unique, uuid, validateAll, verifySignedToken, walkDir, watchDir, watchDirRecursive, waterfall, withErrorHandling, withTimeout, writeJsonFile, writeTextFile, zip };
+export { After, type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type AsyncOperationResponse, type Awaited$1 as Awaited, BUILD_MARKER, BadGatewayException, BadRequestException, type BatchResponse, Before, Body, type BufferEncoding, Cache, CircuitBreakerOpenError, type CircuitBreakerOptions, CircuitBreakerState, ConflictException, Connect, ContentType, ContextStore, Controller, DIContainer, type DateFormatOptions, type DecryptionOptions, type DeepPartial, type DeepReadonly, type DeepRequired, type DeepStringifyOrNull, Delete, type EncryptionOptions, type EncryptionResult, Env, Environment, type ErrorHandlerOptions, ErrorResponse, ExpressServer, ForbiddenException, type Func, GatewayTimeoutException, Get, Head, Header, Headers, HttpCode, HttpError, HttpStatusCodes, Inject, Injectable, InsufficientStorageException, InternalServerErrorException, type IsEqual, type KeysOfType, Log, type Logger, type LoggerLevels, type MaybePromise, MethodNotAllowedException, type Middleware, type Mutable, NoContentResponse, type NonEmptyArray, NotAcceptableException, NotFoundException, type Nullable, type Optional, type Optional2, Options, PaginatedResponse, type Pagination, type PaginationParams, type PaginationResponse, Param, type ParamOptions, type PartialPick, Patch, type PathOptions, PayloadTooLargeException, type PickByType, Post, type Primitive, Put, Query, RateLimit, type RecordOptional, Redirect, RedirectResponse, Req, ReqCookie, ReqHeader, ReqId, ReqLogger, RequestTimeoutException, type RequireAtLeastOne, Res, Roles, type ServerConfig, ServerConfigBuilder, type ServerHooks, ServiceUnavailableException, SortDirection, type Store, StoreKeys, type StreamResponse, type StringKeyedRecord, SuccessResponse, TTLCache, type TTLCacheOptions, type TaskQueue, Timeout, type TimingOptions, type TimingResult, type ToggleConfig, TooManyRequestsException, Trace, TypedContextKey, UnauthorizedException, type UnionToIntersection, UnprocessableEntityException, UnsupportedMediaTypeException, type UrlOptions, Use, type ValidationOptions, type ValidationResult, type ValueOf, Version, type WithPagination, type Without, type Writable, _globalThis, abortable, addRedactFields, addSensitiveFields, addToDate, appendQueryParams, appendTextFile, bufferToStream, capitalize, chunk, circuitBreaker, compact, copyDir, copyFile, countBy, countOccurrences, createBatchStream, createChildLogger, createDeferred, createDirectory, createErrorResponse, createFinalErrorResponse, createHttpError, createLineStream, createPaginatedResponse, createParamDecorator, createParamDecoratorWithoutParam, createRequestLogger, createSignedToken, createSuccessResponse, createTaskQueue, createTempDir, createTempFile, createThrottleStream, createUrlBuilder, dateDiff, daysInMonth, debounce, decrypt, deepFreeze, deepObjMerge, defaultSensitiveFields, deleteDirRecursive, deleteFileIfExists, difference, emptyDir, encrypt, endOf, ensureDir, ensureEmptyDir, ensureType, equalsIgnoreCase, errorHandler, extractFilterParams, extractPaginationParams, extractQueryParams, extractSortParams, fileExists, filterObject, findFilesByPattern, findInDir, findNewestFile, findOldestFile, flattenDeep, flattenObject, formatDate, formatRelativeTime, generateApiKey, generateRandomBytes, generateRandomBytesAsString, getAllPaths, getConfig, getDirSize, getDirStats, getDomain, getErrorMessage, getExtension, getFileSize, getFileStats, getFromContext, getLogger, getPaginationParams, getRedactCensor, getRequestId, getSubdirectories, getTypeOf, getValueByPath, groupBy, hasErrorShape, hasRequiredProps, hash, healthCheck, hmac, inject, intersect, isAlpha, isAlphanumeric, isArray, isArrayOf, isBase64, isBetween, isCreditCard, isDateInRange, isDirectory, isEmail, isEqual, isFile, isHexColor, isHttpError, isIPv4, isIPv6, isISODate, isLeapYear, isLengthBetween, isNumberBetween, isNumeric, isObjEmpty, isObject, isPhone, isPlainObject, isPort, isPrimitiveType, isStrongPassword, isURL, isUUID, isValidJSON, isValidUrl, joinPaths, listFiles, logError, logger, mapObject, mask, matchesPattern, md5, memoize, memoizeAsync, mergeSort, moveDir, moveFile, nanoId, normalizeUrl, omit, parseBooleanParam, parseDate, parseNumberParam, parseQueryString, parseTypedQueryParams, partition, pick, pluck, random, randomBase64, randomHex, randomInt, randomString, range, rateLimit, readDirectory, readFileBuffer, readJsonFile, readTextFile, redact, registerControllers, removeQueryParams, requestId, responseTime, retry, reverse, runInBatches, runInSeries, runWithConcurrency, safeCompare, safeReadJsonFile, sendResponse, setConfig, setRedactCensor, setSensitiveFields, setValueByPath, settleAll, setupRequestContext, sha1, sha256, sha256Hmac, shuffle, singletonAsync, sleep, slugify, startOf, streamFile, streamToBuffer, streamToString, stripHtml, take, takeWhile, throttle, timeAsync, timeSync, timed, timeout, toBool, toCamelCase, toKebabCase, toNum, toPascalCase, toSnakeCase, toStr, trackMemoryUsage, truncate, unique, uuid, validateAll, verifySignedToken, walkDir, watchDir, watchDirRecursive, waterfall, withErrorHandling, withTimeout, writeJsonFile, writeTextFile, zip };