@catbee/utils/stream/index.d.ts

A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.

/*
 * The MIT License
 * 
 * Copyright (c) 2026 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 { Readable, Transform } from 'node:stream';
import { BufferEncoding } from '@catbee/utils/crypto';

/**
 * 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;

export { bufferToStream, createBatchStream, createLineStream, createThrottleStream, streamToBuffer, streamToString };