@catbee/utils 0.0.6 → 0.0.7

package/build/esm/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/esm/utils/stream.utils.js

@@ -0,0 +1,284 @@
+/*
+ * 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.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+import { Readable, Transform } from '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');
+ * ```
+ */
+export function bufferToStream(data) {
+    var readable = new 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
+ * ```
+ */
+export function streamToBuffer(stream) {
+    return __awaiter(this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            return [2 /*return*/, new Promise(function (resolve, reject) {
+                    var chunks = [];
+                    stream.on('data', function (chunk) { return chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)); });
+                    stream.on('end', function () { return 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
+ * ```
+ */
+export function streamToString(stream_1) {
+    return __awaiter(this, arguments, void 0, function (stream, encoding) {
+        var buffer;
+        if (encoding === void 0) { encoding = 'utf8'; }
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, streamToBuffer(stream)];
+                case 1:
+                    buffer = _a.sent();
+                    return [2 /*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
+ */
+export function createThrottleStream(bytesPerSecond) {
+    var bytesSent = 0;
+    var startTime = Date.now();
+    return new Transform({
+        transform: function (chunk, _encoding, callback) {
+            var elapsedSeconds = (Date.now() - startTime) / 1000;
+            var targetBytes = bytesPerSecond * elapsedSeconds;
+            var 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
+            var delay = ((bytesSent + chunkSize) / bytesPerSecond - elapsedSeconds) * 1000;
+            setTimeout(function () {
+                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`));
+ * ```
+ */
+export function createBatchStream(size, options) {
+    if (options === void 0) { options = {}; }
+    var objectMode = options.objectMode !== false;
+    var batch = [];
+    var buffers = [];
+    var bufferSize = 0;
+    return new Transform({
+        objectMode: objectMode,
+        transform: function (chunk, _encoding, callback) {
+            if (objectMode) {
+                batch.push(chunk);
+                if (batch.length >= size) {
+                    this.push(batch);
+                    batch = [];
+                }
+            }
+            else {
+                var buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                buffers.push(buffer);
+                bufferSize += buffer.length;
+                // Emit batches of exact size
+                var 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: function (callback) {
+            if (objectMode && batch.length > 0) {
+                this.push(batch);
+            }
+            else if (!objectMode && buffers.length > 0 && bufferSize > 0) {
+                var 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}`));
+ * ```
+ */
+export function createLineStream(options) {
+    if (options === void 0) { options = {}; }
+    var _a = options.encoding, encoding = _a === void 0 ? 'utf8' : _a, _b = options.includeNewlines, includeNewlines = _b === void 0 ? false : _b;
+    var buffer = '';
+    return new Transform({
+        objectMode: true,
+        transform: function (chunk, _encoding, callback) {
+            var e_1, _a;
+            var str = buffer + (Buffer.isBuffer(chunk) ? chunk.toString(encoding) : chunk);
+            var lines = str.split(/\r?\n/);
+            buffer = lines.pop() || '';
+            try {
+                for (var lines_1 = __values(lines), lines_1_1 = lines_1.next(); !lines_1_1.done; lines_1_1 = lines_1.next()) {
+                    var line = lines_1_1.value;
+                    this.push(includeNewlines ? line + '\n' : line);
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (lines_1_1 && !lines_1_1.done && (_a = lines_1.return)) _a.call(lines_1);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+            callback();
+        },
+        flush: function (callback) {
+            if (buffer) {
+                this.push(buffer);
+            }
+            callback();
+        }
+    });
+}
+//# sourceMappingURL=stream.utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stream.utils.js","sourceRoot":"","sources":["../../../src/utils/stream.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAqB,MAAM,QAAQ,CAAC;AAGhE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,IAAqB;IAClD,IAAM,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB;IACrC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAgB,cAAc,CAAC,MAAgB;;;YACnD,sBAAO,IAAI,OAAO,CAAS,UAAC,OAAO,EAAE,MAAM;oBACzC,IAAM,MAAM,GAAa,EAAE,CAAC;oBAC5B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAA,KAAK,IAAI,OAAA,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAhE,CAAgE,CAAC,CAAC;oBAC7F,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,cAAM,OAAA,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAA9B,CAA8B,CAAC,CAAC;oBACvD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;gBAC7B,CAAC,CAAC,EAAC;;;CACJ;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAgB,cAAc;wDAAC,MAAgB,EAAE,QAAiC;;QAAjC,yBAAA,EAAA,iBAAiC;;;wBACvE,qBAAM,cAAc,CAAC,MAAM,CAAC,EAAA;;oBAArC,MAAM,GAAG,SAA4B;oBAC3C,sBAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAC;;;;CAClC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,cAAsB;IACzD,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE3B,OAAO,IAAI,SAAS,CAAC;QACnB,SAAS,YAAC,KAAa,EAAE,SAAyB,EAAE,QAA2B;YAC7E,IAAM,cAAc,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC;YACvD,IAAM,WAAW,GAAG,cAAc,GAAG,cAAc,CAAC;YACpD,IAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC;YAE/B,iEAAiE;YACjE,IAAI,SAAS,GAAG,SAAS,IAAI,WAAW,EAAE,CAAC;gBACzC,SAAS,IAAI,SAAS,CAAC;gBACvB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBACtB,OAAO;YACT,CAAC;YAED,gCAAgC;YAChC,IAAM,KAAK,GAAG,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC,GAAG,cAAc,GAAG,cAAc,CAAC,GAAG,IAAI,CAAC;YAEjF,UAAU,CAAC;gBACT,SAAS,IAAI,SAAS,CAAC;gBACvB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACxB,CAAC,EAAE,KAAK,CAAC,CAAC;QACZ,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,OAAsC;IAAtC,wBAAA,EAAA,YAAsC;IACpF,IAAM,UAAU,GAAG,OAAO,CAAC,UAAU,KAAK,KAAK,CAAC;IAChD,IAAI,KAAK,GAAU,EAAE,CAAC;IACtB,IAAI,OAAO,GAAa,EAAE,CAAC;IAC3B,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,OAAO,IAAI,SAAS,CAAC;QACnB,UAAU,YAAA;QACV,SAAS,YAAC,KAAK,EAAE,SAAS,EAAE,QAAQ;YAClC,IAAI,UAAU,EAAE,CAAC;gBACf,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAClB,IAAI,KAAK,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;oBACzB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBACjB,KAAK,GAAG,EAAE,CAAC;gBACb,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,IAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACnE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACrB,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC;gBAE5B,6BAA6B;gBAC7B,IAAI,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBAClD,OAAO,QAAQ,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;oBAC/B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;oBACnC,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAClC,CAAC;gBACD,OAAO,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChD,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;YAC/B,CAAC;YAED,QAAQ,EAAE,CAAC;QACb,CAAC;QAED,KAAK,YAAC,QAAQ;YACZ,IAAI,UAAU,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACnC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,CAAC;iBAAM,IAAI,CAAC,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;gBAC/D,IAAI,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBAClD,OAAO,QAAQ,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;oBAC/B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;oBACnC,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAClC,CAAC;gBACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACxB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACtB,CAAC;YACH,CAAC;YACD,QAAQ,EAAE,CAAC;QACb,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAGM;IAHN,wBAAA,EAAA,YAGM;IAEE,IAAA,KAA+C,OAAO,SAArC,EAAjB,QAAQ,mBAAG,MAAM,KAAA,EAAE,KAA4B,OAAO,gBAAZ,EAAvB,eAAe,mBAAG,KAAK,KAAA,CAAa;IAC/D,IAAI,MAAM,GAAG,EAAE,CAAC;IAEhB,OAAO,IAAI,SAAS,CAAC;QACnB,UAAU,EAAE,IAAI;QAChB,SAAS,YAAC,KAAK,EAAE,SAAS,EAAE,QAAQ;;YAClC,IAAM,GAAG,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YACjF,IAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACjC,MAAM,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;;gBAE3B,KAAmB,IAAA,UAAA,SAAA,KAAK,CAAA,4BAAA,+CAAE,CAAC;oBAAtB,IAAM,IAAI,kBAAA;oBACb,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;gBAClD,CAAC;;;;;;;;;YAED,QAAQ,EAAE,CAAC;QACb,CAAC;QAED,KAAK,YAAC,QAAQ;YACZ,IAAI,MAAM,EAAE,CAAC;gBACX,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACpB,CAAC;YACD,QAAQ,EAAE,CAAC;QACb,CAAC;KACF,CAAC,CAAC;AACL,CAAC","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/esm/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

package/build/esm/utils/type.utils.js

@@ -0,0 +1,190 @@
+/*
+ * 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.
+ */
+/**
+ * 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 function isPrimitiveType(value, type) {
+    if (type === 'array') {
+        return Array.isArray(value);
+    }
+    if (type === 'null') {
+        return value === null;
+    }
+    if (type === 'undefined') {
+        return value === undefined;
+    }
+    if (type === 'object') {
+        // Only plain objects, not arrays or null
+        return typeof value === 'object' && value !== null && !Array.isArray(value);
+    }
+    return typeof value === type;
+}
+/**
+ * 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 function getTypeOf(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * 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 function isArrayOf(value, itemTypeGuard) {
+    if (!Array.isArray(value))
+        return false;
+    return value.every(function (item) { return itemTypeGuard(item); });
+}
+/**
+ * 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 function toStr(value, defaultValue) {
+    if (defaultValue === void 0) { defaultValue = ''; }
+    if (value === null || value === undefined)
+        return defaultValue;
+    try {
+        if (typeof value === 'object') {
+            return JSON.stringify(value);
+        }
+        return String(value);
+    }
+    catch (_a) {
+        return defaultValue;
+    }
+}
+/**
+ * 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 function toNum(value, defaultValue) {
+    if (defaultValue === void 0) { defaultValue = 0; }
+    if (value === null || value === undefined)
+        return defaultValue;
+    if (typeof value === 'number')
+        return value;
+    try {
+        var num = Number(value);
+        return isNaN(num) ? defaultValue : num;
+    }
+    catch (_a) {
+        return defaultValue;
+    }
+}
+/**
+ * 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 function toBool(value, defaultValue) {
+    if (defaultValue === void 0) { defaultValue = false; }
+    if (value === null || value === undefined)
+        return defaultValue;
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        var 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;
+}
+/**
+ * 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 function ensureType(value, expectedType, defaultValue) {
+    if (getTypeOf(value) === expectedType) {
+        return value;
+    }
+    return defaultValue;
+}
+//# sourceMappingURL=type.utils.js.map