@catbee/utils 0.0.6 → 0.0.7

package/build/src/utils/request.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"request.utils.js","sourceRoot":"","sources":["../../../src/utils/request.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Options for parsing and validating request parameters.\n */\nexport interface ValidationOptions {\n  /** Whether to throw an error on validation failure */\n  throwOnError?: boolean;\n\n  /** Custom error message for validation failures */\n  errorMessage?: string;\n\n  /** Default value to use if parameter is missing */\n  defaultValue?: any;\n\n  /** Whether the parameter is required */\n  required?: boolean;\n}\n\n/**\n * Result of a parameter validation operation.\n */\nexport interface ValidationResult<T> {\n  /** Whether validation was successful */\n  isValid: boolean;\n\n  /** The validated and potentially transformed value */\n  value: T | null;\n\n  /** Error message if validation failed */\n  error?: string;\n}\n\n/**\n * Safely parses a string parameter to a number.\n *\n * @param value - String value to parse\n * @param options - Validation options\n * @returns Validation result containing the parsed number or error\n */\nexport function parseNumberParam(value: string | undefined, options: ValidationOptions = {}): ValidationResult<number> {\n  const { throwOnError = false, errorMessage = 'Invalid number parameter', defaultValue, required = false } = options;\n\n  // Handle undefined case\n  if (value === undefined) {\n    if (required) {\n      const error = `Required number parameter is missing`;\n      if (throwOnError) throw new Error(error);\n      return { isValid: false, value: null, error };\n    }\n\n    return {\n      isValid: defaultValue !== undefined,\n      value: defaultValue !== undefined ? defaultValue : null,\n      error: defaultValue === undefined ? 'Missing parameter with no default' : undefined\n    };\n  }\n\n  // Parse and validate the number\n  const num = Number(value);\n  if (isNaN(num)) {\n    if (throwOnError) throw new Error(errorMessage);\n    return { isValid: false, value: null, error: errorMessage };\n  }\n\n  return { isValid: true, value: num };\n}\n\n/**\n * Safely parses a string parameter to a boolean.\n *\n * @param value - String value to parse\n * @param options - Validation options\n * @returns Validation result containing the parsed boolean or error\n */\nexport function parseBooleanParam(\n  value: string | undefined,\n  options: ValidationOptions = {}\n): ValidationResult<boolean> {\n  const { throwOnError = false, errorMessage = 'Invalid boolean parameter', defaultValue, required = false } = options;\n\n  // Handle undefined case\n  if (value === undefined) {\n    if (required) {\n      const error = `Required boolean parameter is missing`;\n      if (throwOnError) throw new Error(error);\n      return { isValid: false, value: null, error };\n    }\n\n    return {\n      isValid: defaultValue !== undefined,\n      value: defaultValue !== undefined ? defaultValue : null,\n      error: defaultValue === undefined ? 'Missing parameter with no default' : undefined\n    };\n  }\n\n  // Parse the boolean value with various allowed formats\n  const lowercaseValue = value.toLowerCase();\n  if (['true', 't', 'yes', 'y', '1'].includes(lowercaseValue)) {\n    return { isValid: true, value: true };\n  }\n\n  if (['false', 'f', 'no', 'n', '0'].includes(lowercaseValue)) {\n    return { isValid: true, value: false };\n  }\n\n  if (throwOnError) throw new Error(errorMessage);\n  return { isValid: false, value: null, error: errorMessage };\n}\n\n/**\n * Extracts pagination parameters from request query parameters.\n *\n * @param query - Query parameters object\n * @param defaultPage - Default page number if not specified (defaults to 1)\n * @param defaultLimit - Default per page size if not specified (defaults to 20)\n * @param maxLimitSize - Maximum allowed per page size (defaults to 100)\n * @returns Object containing validated page and limit\n */\nexport function extractPaginationParams(\n  query: Record<string, string | string[]>,\n  defaultPage: number = 1,\n  defaultLimit: number = 20,\n  maxLimitSize: number = 100\n): { page: number; limit: number } {\n  // Parse page parameter\n  const pageParam = typeof query.page === 'string' ? query.page : undefined;\n  const pageResult = parseNumberParam(pageParam, { defaultValue: defaultPage });\n\n  // Parse limit parameter\n  const limitParam = typeof query.limit === 'string' ? query.limit : undefined;\n  const limitResult = parseNumberParam(limitParam, { defaultValue: defaultLimit });\n\n  // Ensure valid values (handle 0 → fallback to default)\n  const page = pageResult.value && pageResult.value > 0 ? pageResult.value : defaultPage;\n\n  const limit = limitResult.value && limitResult.value > 0 ? Math.min(limitResult.value, maxLimitSize) : defaultLimit;\n\n  return { page, limit };\n}\n\n/**\n * Extracts sorting parameters from request query parameters.\n *\n * @param query - Query parameters object\n * @param allowedFields - Array of field names that are allowed to be sorted\n * @param defaultSort - Default sort configuration if not specified\n * @returns Object containing sort field and direction\n */\nexport function extractSortParams(\n  query: Record<string, string | string[]>,\n  allowedFields: string[],\n  defaultSort: { sortBy: string; sortOrder: 'asc' | 'desc' } = { sortBy: 'createdAt', sortOrder: 'desc' }\n): { sortBy: string; sortOrder: 'asc' | 'desc' } {\n  let sortBy = defaultSort.sortBy;\n  let sortOrder: 'asc' | 'desc' = defaultSort.sortOrder;\n\n  // Extract from `sortBy` or `sort`\n  if (typeof query.sortBy === 'string') {\n    sortBy = query.sortBy;\n  } else if (Array.isArray(query.sortBy)) {\n    sortBy = query.sortBy[0];\n  } else if (typeof query.sort === 'string') {\n    sortBy = query.sort.startsWith('-') ? query.sort.slice(1) : query.sort;\n    sortOrder = query.sort.startsWith('-') ? 'desc' : 'asc';\n  } else if (Array.isArray(query.sort)) {\n    sortBy = query.sort[0].startsWith('-') ? query.sort[0].slice(1) : query.sort[0];\n    sortOrder = query.sort[0].startsWith('-') ? 'desc' : 'asc';\n  }\n\n  // Explicit sortOrder (overrides inferred one if valid)\n  if (typeof query.sortOrder === 'string') {\n    const order = query.sortOrder.toLowerCase();\n    if (order === 'asc' || order === 'desc') {\n      sortOrder = order;\n    }\n  }\n\n  // Validate field\n  if (!allowedFields.includes(sortBy)) {\n    sortBy = defaultSort.sortBy;\n  }\n\n  return { sortBy, sortOrder };\n}\n\n/**\n * Extracts filter parameters from query parameters based on allowed filter fields.\n *\n * @param query - Query parameters object\n * @param allowedFilters - Array of field names that are allowed to be used as filters\n * @returns Object containing the filters as key-value pairs\n */\nexport function extractFilterParams(\n  query: Record<string, string | string[]>,\n  allowedFilters: string[]\n): Record<string, string | string[]> {\n  const filters: Record<string, string | string[]> = {};\n\n  // Find filter parameters in the query\n  for (const field of allowedFilters) {\n    if (field in query) {\n      filters[field] = query[field];\n    }\n  }\n\n  return filters;\n}\n"]}
+{"version":3,"file":"request.utils.js","sourceRoot":"","sources":["../../../src/utils/request.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Request } from 'express';\nimport { SortDirection, WithPagination } from '../types/api-response';\nimport { BadRequestException } from './exception.utils';\n\n/**\n * Options for parsing and validating request parameters.\n */\nexport interface ValidationOptions {\n  /** Whether to throw an error on validation failure */\n  throwOnError?: boolean;\n\n  /** Custom error message for validation failures */\n  errorMessage?: string;\n\n  /** Default value to use if parameter is missing */\n  defaultValue?: any;\n\n  /** Whether the parameter is required */\n  required?: boolean;\n}\n\n/**\n * Result of a parameter validation operation.\n */\nexport interface ValidationResult<T> {\n  /** Whether validation was successful */\n  isValid: boolean;\n\n  /** The validated and potentially transformed value */\n  value: T | null;\n\n  /** Error message if validation failed */\n  error?: string;\n}\n\n/**\n * Extracts pagination, sorting, and optional search params from a request.\n *\n * @param req - Express request\n * @returns Object containing validated pagination, sorting, and additional query params\n */\nexport const getPaginationParams = <T = {}>(req: Request): WithPagination<T> => {\n  const query = req.query as Record<string, string | string[]>;\n\n  // Extract page & limit\n  const { page, limit } = extractPaginationParams(query, 1, 20, 100);\n  const { sortBy, sortOrder } = extractSortParams(query, []);\n\n  // Optional search param\n  const search = typeof query.search === 'string' ? query.search : undefined;\n\n  return {\n    ...(query as T),\n    page,\n    limit,\n    sortBy,\n    sortOrder: sortOrder as SortDirection,\n    search\n  };\n};\n\n/**\n * Safely parses a string parameter to a number.\n *\n * @param value - String value to parse\n * @param options - Validation options\n * @returns Validation result containing the parsed number or error\n */\nexport function parseNumberParam(value: string | undefined, options: ValidationOptions = {}): ValidationResult<number> {\n  const { throwOnError = false, errorMessage = 'Invalid number parameter', defaultValue, required = false } = options;\n\n  // Handle undefined case\n  if (value === undefined) {\n    if (required) {\n      const error = `Required number parameter is missing`;\n      if (throwOnError) throw new BadRequestException(error);\n      return { isValid: false, value: null, error };\n    }\n\n    return {\n      isValid: defaultValue !== undefined,\n      value: defaultValue !== undefined ? defaultValue : null,\n      error: defaultValue === undefined ? 'Missing parameter with no default' : undefined\n    };\n  }\n\n  // Parse and validate the number\n  const num = Number(value);\n  if (isNaN(num)) {\n    if (throwOnError) throw new BadRequestException(errorMessage);\n    return { isValid: false, value: null, error: errorMessage };\n  }\n\n  return { isValid: true, value: num };\n}\n\n/**\n * Safely parses a string parameter to a boolean.\n *\n * @param value - String value to parse\n * @param options - Validation options\n * @returns Validation result containing the parsed boolean or error\n */\nexport function parseBooleanParam(\n  value: string | undefined,\n  options: ValidationOptions = {}\n): ValidationResult<boolean> {\n  const { throwOnError = false, errorMessage = 'Invalid boolean parameter', defaultValue, required = false } = options;\n\n  // Handle undefined case\n  if (value === undefined) {\n    if (required) {\n      const error = `Required boolean parameter is missing`;\n      if (throwOnError) throw new BadRequestException(error);\n      return { isValid: false, value: null, error };\n    }\n\n    return {\n      isValid: defaultValue !== undefined,\n      value: defaultValue !== undefined ? defaultValue : null,\n      error: defaultValue === undefined ? 'Missing parameter with no default' : undefined\n    };\n  }\n\n  // Parse the boolean value with various allowed formats\n  const lowercaseValue = value.toLowerCase();\n  if (['true', 't', 'yes', 'y', '1'].includes(lowercaseValue)) {\n    return { isValid: true, value: true };\n  }\n\n  if (['false', 'f', 'no', 'n', '0'].includes(lowercaseValue)) {\n    return { isValid: true, value: false };\n  }\n\n  if (throwOnError) throw new BadRequestException(errorMessage);\n  return { isValid: false, value: null, error: errorMessage };\n}\n\n/**\n * Extracts pagination parameters from request query parameters.\n *\n * @param query - Query parameters object\n * @param defaultPage - Default page number if not specified (defaults to 1)\n * @param defaultLimit - Default per page size if not specified (defaults to 20)\n * @param maxLimitSize - Maximum allowed per page size (defaults to 100)\n * @returns Object containing validated page and limit\n */\nexport function extractPaginationParams(\n  query: Record<string, string | string[]>,\n  defaultPage: number = 1,\n  defaultLimit: number = 20,\n  maxLimitSize: number = 100\n): { page: number; limit: number } {\n  // Parse page parameter\n  const pageParam = typeof query.page === 'string' ? query.page : undefined;\n  const pageResult = parseNumberParam(pageParam, { defaultValue: defaultPage });\n\n  // Parse limit parameter\n  const limitParam = typeof query.limit === 'string' ? query.limit : undefined;\n  const limitResult = parseNumberParam(limitParam, { defaultValue: defaultLimit });\n\n  // Ensure valid values (handle 0 → fallback to default)\n  const page = pageResult.value && pageResult.value > 0 ? pageResult.value : defaultPage;\n\n  const limit = limitResult.value && limitResult.value > 0 ? Math.min(limitResult.value, maxLimitSize) : defaultLimit;\n\n  return { page, limit };\n}\n\n/**\n * Extracts sorting parameters from request query parameters.\n *\n * @param query - Query parameters object\n * @param allowedFields - Array of field names that are allowed to be sorted\n * @param defaultSort - Default sort configuration if not specified\n * @returns Object containing sort field and direction\n */\nexport function extractSortParams(\n  query: Record<string, string | string[]>,\n  allowedFields: string[],\n  defaultSort: { sortBy: string; sortOrder: 'asc' | 'desc' } = { sortBy: 'createdAt', sortOrder: 'desc' }\n): { sortBy: string; sortOrder: 'asc' | 'desc' } {\n  let sortBy = defaultSort.sortBy;\n  let sortOrder: 'asc' | 'desc' = defaultSort.sortOrder;\n\n  // Extract from `sortBy` or `sort`\n  if (typeof query.sortBy === 'string') {\n    sortBy = query.sortBy;\n  } else if (Array.isArray(query.sortBy)) {\n    sortBy = query.sortBy[0];\n  } else if (typeof query.sort === 'string') {\n    sortBy = query.sort.startsWith('-') ? query.sort.slice(1) : query.sort;\n    sortOrder = query.sort.startsWith('-') ? 'desc' : 'asc';\n  } else if (Array.isArray(query.sort)) {\n    sortBy = query.sort[0].startsWith('-') ? query.sort[0].slice(1) : query.sort[0];\n    sortOrder = query.sort[0].startsWith('-') ? 'desc' : 'asc';\n  }\n\n  // Explicit sortOrder (overrides inferred one if valid)\n  if (typeof query.sortOrder === 'string') {\n    const order = query.sortOrder.toLowerCase();\n    if (order === 'asc' || order === 'desc') {\n      sortOrder = order;\n    }\n  }\n\n  // Validate field\n  if (allowedFields.length && !allowedFields.includes(sortBy)) {\n    sortBy = defaultSort.sortBy;\n  }\n\n  return { sortBy, sortOrder };\n}\n\n/**\n * Extracts filter parameters from query parameters based on allowed filter fields.\n *\n * @param query - Query parameters object\n * @param allowedFilters - Array of field names that are allowed to be used as filters\n * @returns Object containing the filters as key-value pairs\n */\nexport function extractFilterParams(\n  query: Record<string, string | string[]>,\n  allowedFilters: string[]\n): Record<string, string | string[]> {\n  const filters: Record<string, string | string[]> = {};\n\n  // Find filter parameters in the query\n  for (const field of allowedFilters) {\n    if (field in query) {\n      filters[field] = query[field];\n    }\n  }\n\n  return filters;\n}\n"]}

package/build/src/utils/stream.utils.d.ts

@@ -0,0 +1,88 @@
+import { Readable, Transform } from 'stream';
+import { BufferEncoding } from './crypto.utils';
+/**
+ * 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');
+ * ```
+ */
+export 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
+ * ```
+ */
+export 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
+ * ```
+ */
+export 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
+ */
+export 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`));
+ * ```
+ */
+export 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}`));
+ * ```
+ */
+export declare function createLineStream(options?: {
+    encoding?: BufferEncoding;
+    includeNewlines?: boolean;
+}): Transform;
+//# sourceMappingURL=stream.utils.d.ts.map

package/build/src/utils/stream.utils.js

@@ -0,0 +1,218 @@
+"use strict";
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025 Catbee Technologies
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bufferToStream = bufferToStream;
+exports.streamToBuffer = streamToBuffer;
+exports.streamToString = streamToString;
+exports.createThrottleStream = createThrottleStream;
+exports.createBatchStream = createBatchStream;
+exports.createLineStream = createLineStream;
+const stream_1 = require("stream");
+/**
+ * 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');
+ * ```
+ */
+function bufferToStream(data) {
+    const readable = new stream_1.Readable();
+    readable.push(data);
+    readable.push(null); // End of stream
+    return 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
+ * ```
+ */
+async function streamToBuffer(stream) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        stream.on('data', chunk => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+        stream.on('end', () => resolve(Buffer.concat(chunks)));
+        stream.on('error', reject);
+    });
+}
+/**
+ * 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
+ * ```
+ */
+async function streamToString(stream, encoding = 'utf8') {
+    const buffer = await streamToBuffer(stream);
+    return buffer.toString(encoding);
+}
+/**
+ * Create a transform stream that limits the rate of data flow.
+ *
+ * @param bytesPerSecond - Maximum bytes per second
+ * @returns Transform stream that throttles data flow
+ */
+function createThrottleStream(bytesPerSecond) {
+    let bytesSent = 0;
+    let startTime = Date.now();
+    return new stream_1.Transform({
+        transform(chunk, _encoding, callback) {
+            const elapsedSeconds = (Date.now() - startTime) / 1000;
+            const targetBytes = bytesPerSecond * elapsedSeconds;
+            const chunkSize = chunk.length;
+            // If we've sent fewer bytes than our target, just send the chunk
+            if (bytesSent + chunkSize <= targetBytes) {
+                bytesSent += chunkSize;
+                callback(null, chunk);
+                return;
+            }
+            // Otherwise we need to throttle
+            const delay = ((bytesSent + chunkSize) / bytesPerSecond - elapsedSeconds) * 1000;
+            setTimeout(() => {
+                bytesSent += chunkSize;
+                callback(null, chunk);
+            }, delay);
+        }
+    });
+}
+/**
+ * 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`));
+ * ```
+ */
+function createBatchStream(size, options = {}) {
+    const objectMode = options.objectMode !== false;
+    let batch = [];
+    let buffers = [];
+    let bufferSize = 0;
+    return new stream_1.Transform({
+        objectMode,
+        transform(chunk, _encoding, callback) {
+            if (objectMode) {
+                batch.push(chunk);
+                if (batch.length >= size) {
+                    this.push(batch);
+                    batch = [];
+                }
+            }
+            else {
+                const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                buffers.push(buffer);
+                bufferSize += buffer.length;
+                // Emit batches of exact size
+                let combined = Buffer.concat(buffers, bufferSize);
+                while (combined.length >= size) {
+                    this.push(combined.slice(0, size));
+                    combined = combined.slice(size);
+                }
+                buffers = combined.length > 0 ? [combined] : [];
+                bufferSize = combined.length;
+            }
+            callback();
+        },
+        flush(callback) {
+            if (objectMode && batch.length > 0) {
+                this.push(batch);
+            }
+            else if (!objectMode && buffers.length > 0 && bufferSize > 0) {
+                let combined = Buffer.concat(buffers, bufferSize);
+                while (combined.length >= size) {
+                    this.push(combined.slice(0, size));
+                    combined = combined.slice(size);
+                }
+                if (combined.length > 0) {
+                    this.push(combined);
+                }
+            }
+            callback();
+        }
+    });
+}
+/**
+ * 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}`));
+ * ```
+ */
+function createLineStream(options = {}) {
+    const { encoding = 'utf8', includeNewlines = false } = options;
+    let buffer = '';
+    return new stream_1.Transform({
+        objectMode: true,
+        transform(chunk, _encoding, callback) {
+            const str = buffer + (Buffer.isBuffer(chunk) ? chunk.toString(encoding) : chunk);
+            const lines = str.split(/\r?\n/);
+            buffer = lines.pop() || '';
+            for (const line of lines) {
+                this.push(includeNewlines ? line + '\n' : line);
+            }
+            callback();
+        },
+        flush(callback) {
+            if (buffer) {
+                this.push(buffer);
+            }
+            callback();
+        }
+    });
+}
+//# sourceMappingURL=stream.utils.js.map

package/build/src/utils/stream.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.utils.js","sourceRoot":"","sources":["../../../src/utils/stream.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Readable, Transform, TransformCallback } from 'stream';\nimport { BufferEncoding } from './crypto.utils';\n\n/**\n * Convert a buffer or string to a readable stream.\n *\n * @param data - Buffer or string to convert\n * @returns Readable stream containing the data\n *\n * @example\n * ```typescript\n * const stream = bufferToStream(Buffer.from('Hello world'));\n * // or\n * const stream = bufferToStream('Hello world');\n * ```\n */\nexport function bufferToStream(data: Buffer | string): Readable {\n  const readable = new Readable();\n  readable.push(data);\n  readable.push(null); // End of stream\n  return readable;\n}\n\n/**\n * Convert a readable stream to a buffer.\n *\n * @param stream - Readable stream to convert\n * @returns Promise resolving to a buffer containing all stream data\n *\n * @example\n * ```typescript\n * const buffer = await streamToBuffer(fs.createReadStream('file.txt'));\n * console.log(buffer.toString()); // Contents of file.txt\n * ```\n */\nexport async function streamToBuffer(stream: Readable): Promise<Buffer> {\n  return new Promise<Buffer>((resolve, reject) => {\n    const chunks: Buffer[] = [];\n    stream.on('data', chunk => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));\n    stream.on('end', () => resolve(Buffer.concat(chunks)));\n    stream.on('error', reject);\n  });\n}\n\n/**\n * Convert a readable stream to a string.\n *\n * @param stream - Readable stream to convert\n * @param encoding - Character encoding (default: 'utf8')\n * @returns Promise resolving to a string containing all stream data\n *\n * @example\n * ```typescript\n * const content = await streamToString(fs.createReadStream('file.txt'));\n * console.log(content); // Contents of file.txt as string\n * ```\n */\nexport async function streamToString(stream: Readable, encoding: BufferEncoding = 'utf8'): Promise<string> {\n  const buffer = await streamToBuffer(stream);\n  return buffer.toString(encoding);\n}\n\n/**\n * Create a transform stream that limits the rate of data flow.\n *\n * @param bytesPerSecond - Maximum bytes per second\n * @returns Transform stream that throttles data flow\n */\nexport function createThrottleStream(bytesPerSecond: number): Transform {\n  let bytesSent = 0;\n  let startTime = Date.now();\n\n  return new Transform({\n    transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback) {\n      const elapsedSeconds = (Date.now() - startTime) / 1000;\n      const targetBytes = bytesPerSecond * elapsedSeconds;\n      const chunkSize = chunk.length;\n\n      // If we've sent fewer bytes than our target, just send the chunk\n      if (bytesSent + chunkSize <= targetBytes) {\n        bytesSent += chunkSize;\n        callback(null, chunk);\n        return;\n      }\n\n      // Otherwise we need to throttle\n      const delay = ((bytesSent + chunkSize) / bytesPerSecond - elapsedSeconds) * 1000;\n\n      setTimeout(() => {\n        bytesSent += chunkSize;\n        callback(null, chunk);\n      }, delay);\n    }\n  });\n}\n\n/**\n * Create a transform stream that batches data into chunks of specified size.\n *\n * @param size - Size of each batch (items for object mode, bytes for binary mode)\n * @param options - Stream options\n * @returns Transform stream that batches data\n *\n * @example\n * ```typescript\n * // Batch lines from a file into arrays of 100 lines each\n * createReadStream('large-file.txt')\n *   .pipe(createLineStream())\n *   .pipe(createBatchStream(100))\n *   .on('data', batch => console.log(`Processing batch of ${batch.length} lines`));\n * ```\n */\nexport function createBatchStream(size: number, options: { objectMode?: boolean } = {}): Transform {\n  const objectMode = options.objectMode !== false;\n  let batch: any[] = [];\n  let buffers: Buffer[] = [];\n  let bufferSize = 0;\n\n  return new Transform({\n    objectMode,\n    transform(chunk, _encoding, callback) {\n      if (objectMode) {\n        batch.push(chunk);\n        if (batch.length >= size) {\n          this.push(batch);\n          batch = [];\n        }\n      } else {\n        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);\n        buffers.push(buffer);\n        bufferSize += buffer.length;\n\n        // Emit batches of exact size\n        let combined = Buffer.concat(buffers, bufferSize);\n        while (combined.length >= size) {\n          this.push(combined.slice(0, size));\n          combined = combined.slice(size);\n        }\n        buffers = combined.length > 0 ? [combined] : [];\n        bufferSize = combined.length;\n      }\n\n      callback();\n    },\n\n    flush(callback) {\n      if (objectMode && batch.length > 0) {\n        this.push(batch);\n      } else if (!objectMode && buffers.length > 0 && bufferSize > 0) {\n        let combined = Buffer.concat(buffers, bufferSize);\n        while (combined.length >= size) {\n          this.push(combined.slice(0, size));\n          combined = combined.slice(size);\n        }\n        if (combined.length > 0) {\n          this.push(combined);\n        }\n      }\n      callback();\n    }\n  });\n}\n\n/**\n * Create a transform stream that splits text data by newlines.\n *\n * @param options - Options for the line stream\n * @returns Transform stream that emits lines\n *\n * @example\n * ```typescript\n * // Process a file line by line\n * createReadStream('file.txt')\n *   .pipe(createLineStream())\n *   .on('data', line => console.log(`Line: ${line}`));\n * ```\n */\nexport function createLineStream(\n  options: {\n    encoding?: BufferEncoding;\n    includeNewlines?: boolean;\n  } = {}\n): Transform {\n  const { encoding = 'utf8', includeNewlines = false } = options;\n  let buffer = '';\n\n  return new Transform({\n    objectMode: true,\n    transform(chunk, _encoding, callback) {\n      const str = buffer + (Buffer.isBuffer(chunk) ? chunk.toString(encoding) : chunk);\n      const lines = str.split(/\\r?\\n/);\n      buffer = lines.pop() || '';\n\n      for (const line of lines) {\n        this.push(includeNewlines ? line + '\\n' : line);\n      }\n\n      callback();\n    },\n\n    flush(callback) {\n      if (buffer) {\n        this.push(buffer);\n      }\n      callback();\n    }\n  });\n}\n"]}

package/build/src/utils/type.utils.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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;
+//# sourceMappingURL=type.utils.d.ts.map