@catbee/utils 0.0.8-next.0 → 0.0.8-rc.1

package/build/esm/utils/response.utils.js

@@ -0,0 +1,284 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+import { getRequestId } from './context-store.utils';
+import { Env } from './env.utils';
+import { uuid } from './id.utils';
+/**
+ * Standard HTTP response wrapper for successful responses.
+ * Implements the `ApiResponse<T>` interface and sets default values.
+ *
+ * @typeParam T - The shape of the data returned in the response.
+ */
+var SuccessResponse = /** @class */ (function () {
+    /**
+     * Constructs a new success response.
+     *
+     * @param {string} message - Optional message to override the default.
+     * @param {T} [data] - Optional data payload.
+     */
+    function SuccessResponse(message, data) {
+        var _a;
+        /** Message describing the result of the operation. */
+        this.message = 'Success';
+        /** Whether the response is an error. Always false in success responses. */
+        this.error = false;
+        /** The payload returned from the API. */
+        this.data = null;
+        /** Timestamp when the response was generated, in ISO format. */
+        this.timestamp = new Date().toISOString();
+        /** Unique identifier for this response, useful for request tracing. */
+        this.requestId = (_a = getRequestId()) !== null && _a !== void 0 ? _a : uuid();
+        if (message)
+            this.message = message;
+        this.data = data !== null && data !== void 0 ? data : null;
+    }
+    return SuccessResponse;
+}());
+export { SuccessResponse };
+/**
+ * Wrapper for error responses that extends the native `Error` object.
+ * Implements `ApiResponse` but omits the `data` field (which should not be present in errors).
+ */
+var ErrorResponse = /** @class */ (function (_super) {
+    __extends(ErrorResponse, _super);
+    /**
+     * Constructs a new error response.
+     *
+     * @param {string} message - The error message to display or log.
+     * @param {number} [status=500] - Optional HTTP status code (defaults to 500).
+     */
+    function ErrorResponse(message, status) {
+        if (status === void 0) { status = 500; }
+        var _a;
+        var _this = _super.call(this, message) || this;
+        /** Indicates that this is an error. Always true. */
+        _this.error = true;
+        /** Timestamp when the error occurred, in ISO format. */
+        _this.timestamp = new Date().toISOString();
+        /** Unique identifier for this error instance. */
+        _this.requestId = (_a = getRequestId()) !== null && _a !== void 0 ? _a : uuid();
+        _this.status = status;
+        _this.name = _this.constructor.name;
+        Error.captureStackTrace(_this, _this.constructor);
+        return _this;
+    }
+    return ErrorResponse;
+}(Error));
+export { ErrorResponse };
+/**
+ * Response with paginated data extending the standard success response.
+ * Useful for APIs that return large collections of data.
+ *
+ * @typeParam T - The shape of each item in the paginated collection.
+ */
+var PaginatedResponse = /** @class */ (function (_super) {
+    __extends(PaginatedResponse, _super);
+    /**
+     * Constructs a new paginated response.
+     *
+     * @param {T[]} items - The current page of items.
+     * @param {Object} pagination - Pagination information.
+     * @param {number} pagination.total - Total number of items across all pages.
+     * @param {number} pagination.page - Current page number (1-based).
+     * @param {number} pagination.pageSize - Number of items per page.
+     * @param {string} [message="Success"] - Optional custom message.
+     */
+    function PaginatedResponse(items, pagination, message) {
+        if (message === void 0) { message = 'Success'; }
+        var _this = _super.call(this, message, items) || this;
+        _this.total = pagination.total;
+        _this.page = pagination.page;
+        _this.pageSize = pagination.pageSize;
+        _this.totalPages = Math.ceil(_this.total / _this.pageSize);
+        _this.hasNext = _this.page < _this.totalPages;
+        _this.hasPrevious = _this.page > 1;
+        return _this;
+    }
+    return PaginatedResponse;
+}(SuccessResponse));
+export { PaginatedResponse };
+/**
+ * Specialized response for operations that don't return data (HTTP 204).
+ */
+var NoContentResponse = /** @class */ (function (_super) {
+    __extends(NoContentResponse, _super);
+    /**
+     * Constructs a new no-content response.
+     *
+     * @param {string} [message="Operation completed successfully"] - Optional custom message.
+     */
+    function NoContentResponse(message) {
+        if (message === void 0) { message = 'Operation completed successfully'; }
+        return _super.call(this, message, null) || this;
+    }
+    return NoContentResponse;
+}(SuccessResponse));
+export { NoContentResponse };
+/**
+ * Specialized response for redirects.
+ */
+var RedirectResponse = /** @class */ (function () {
+    /**
+     * Constructs a new redirect response.
+     *
+     * @param {string} url - The URL to redirect to.
+     * @param {number} [statusCode=302] - HTTP status code for the redirect.
+     */
+    function RedirectResponse(url, statusCode) {
+        if (statusCode === void 0) { statusCode = 302; }
+        var _a;
+        /** Whether the response is a redirect */
+        this.isRedirect = true;
+        /** Unique identifier for this response */
+        this.requestId = (_a = getRequestId()) !== null && _a !== void 0 ? _a : uuid();
+        this.redirectUrl = url;
+        this.statusCode = statusCode;
+    }
+    return RedirectResponse;
+}());
+export { RedirectResponse };
+/**
+ * Creates a standard success response.
+ *
+ * @typeParam T - The shape of the data returned in the response.
+ * @param {T} data - The data to include in the response.
+ * @param {string} [message="Success"] - Optional custom message.
+ * @returns {SuccessResponse<T>} A properly formatted success response.
+ */
+export function createSuccessResponse(data, message) {
+    if (message === void 0) { message = 'Success'; }
+    return new SuccessResponse(message, data);
+}
+/**
+ * Creates a standard error response.
+ *
+ * @param {string} message - The error message.
+ * @param {number} [statusCode=500] - HTTP status code for the error.
+ * @returns {ErrorResponse} A properly formatted error response.
+ */
+export function createErrorResponse(message, statusCode) {
+    if (statusCode === void 0) { statusCode = 500; }
+    return new ErrorResponse(message, statusCode);
+}
+/**
+ * Creates a final error response with request information.
+ *
+ * @param req - The original request object.
+ * @param status - The HTTP status code.
+ * @param message - The error message.
+ * @param error - The original error object (optional).
+ * @param options - Additional options for the response (optional).
+ * @returns A properly formatted final error response.
+ */
+export function createFinalErrorResponse(req, status, message, error, options) {
+    var isDev = Env.isDev();
+    var includeDetails = (options === null || options === void 0 ? void 0 : options.includeDetails) && isDev;
+    var response = {
+        error: true,
+        message: message,
+        timestamp: new Date().toISOString(),
+        requestId: (error === null || error === void 0 ? void 0 : error.requestId) || (req === null || req === void 0 ? void 0 : req.id) || uuid(),
+        status: status,
+        path: req.originalUrl || req.url
+    };
+    // Include stack trace in development mode if requested
+    if (includeDetails && (error === null || error === void 0 ? void 0 : error.stack)) {
+        response.stack = error.stack.split('\n').map(function (line) { return line.trim(); });
+    }
+    return response;
+}
+/**
+ * Creates a paginated response from array data.
+ *
+ * @typeParam T - The shape of each item in the collection.
+ * @param {T[]} allItems - The complete array of items to paginate.
+ * @param {number} page - The requested page (1-based).
+ * @param {number} pageSize - The number of items per page.
+ * @param {string} [message="Success"] - Optional custom message.
+ * @returns {PaginatedResponse<T>} A properly formatted paginated response.
+ */
+export function createPaginatedResponse(allItems, page, pageSize, message) {
+    if (message === void 0) { message = 'Success'; }
+    // Ensure valid pagination parameters
+    var validPage = Math.max(1, page);
+    var validPageSize = Math.max(1, pageSize);
+    // Calculate slice indices
+    var startIndex = (validPage - 1) * validPageSize;
+    var endIndex = startIndex + validPageSize;
+    // Get current page items
+    var pageItems = allItems.slice(startIndex, endIndex);
+    return new PaginatedResponse(pageItems, {
+        total: allItems.length,
+        page: validPage,
+        pageSize: validPageSize
+    }, message);
+}
+/**
+ * Adapter to convert API responses to Express.js response format.
+ *
+ * @param {any} res - Express response object.
+ * @param {SuccessResponse<any> | ErrorResponse | RedirectResponse} apiResponse - API response instance.
+ */
+export function sendResponse(res, apiResponse) {
+    // Handle redirects
+    if ('redirectUrl' in apiResponse) {
+        res.redirect(apiResponse.statusCode, apiResponse.redirectUrl);
+        return;
+    }
+    // Handle errors
+    if ('error' in apiResponse && apiResponse.error) {
+        var errorResponse = apiResponse;
+        res.status(errorResponse.status).json({
+            error: true,
+            message: errorResponse.message,
+            timestamp: errorResponse.timestamp,
+            requestId: errorResponse.requestId
+        });
+        return;
+    }
+    // Handle success responses
+    var successResponse = apiResponse;
+    // No content (204) shouldn't return a body
+    if (successResponse instanceof NoContentResponse) {
+        res.status(204).end();
+        return;
+    }
+    res.status(200).json(successResponse);
+}
+//# sourceMappingURL=response.utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"response.utils.js","sourceRoot":"","sources":["../../../src/utils/response.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license\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 { ApiErrorResponse, ApiResponse } from '../types/api-response';\nimport { getRequestId } from './context-store.utils';\nimport { Env } from './env.utils';\nimport { uuid } from './id.utils';\n\n/**\n * Standard HTTP response wrapper for successful responses.\n * Implements the `ApiResponse<T>` interface and sets default values.\n *\n * @typeParam T - The shape of the data returned in the response.\n */\nexport class SuccessResponse<T> implements ApiResponse<T> {\n  /** Message describing the result of the operation. */\n  message: string = 'Success';\n\n  /** Whether the response is an error. Always false in success responses. */\n  error: boolean = false;\n\n  /** The payload returned from the API. */\n  data: T | null = null;\n\n  /** Timestamp when the response was generated, in ISO format. */\n  timestamp: string = new Date().toISOString();\n\n  /** Unique identifier for this response, useful for request tracing. */\n  requestId: string = getRequestId() ?? uuid();\n\n  /**\n   * Constructs a new success response.\n   *\n   * @param {string} message - Optional message to override the default.\n   * @param {T} [data] - Optional data payload.\n   */\n  constructor(message: string, data?: T) {\n    if (message) this.message = message;\n    this.data = data ?? null;\n  }\n}\n\n/**\n * Wrapper for error responses that extends the native `Error` object.\n * Implements `ApiResponse` but omits the `data` field (which should not be present in errors).\n */\nexport class ErrorResponse extends Error implements Omit<ApiResponse<never>, 'data'> {\n  /** HTTP status code associated with the error (e.g., 404, 500). */\n  status: number;\n\n  /** Indicates that this is an error. Always true. */\n  error: boolean = true;\n\n  /** Timestamp when the error occurred, in ISO format. */\n  timestamp: string = new Date().toISOString();\n\n  /** Unique identifier for this error instance. */\n  requestId: string = getRequestId() ?? uuid();\n\n  /**\n   * Constructs a new error response.\n   *\n   * @param {string} message - The error message to display or log.\n   * @param {number} [status=500] - Optional HTTP status code (defaults to 500).\n   */\n  constructor(message: string, status: number = 500) {\n    super(message);\n    this.status = status;\n    this.name = this.constructor.name;\n    Error.captureStackTrace(this, this.constructor);\n  }\n}\n\n/**\n * Response with paginated data extending the standard success response.\n * Useful for APIs that return large collections of data.\n *\n * @typeParam T - The shape of each item in the paginated collection.\n */\nexport class PaginatedResponse<T> extends SuccessResponse<T[]> {\n  /** Total number of items across all pages */\n  total: number;\n\n  /** Current page number (1-based) */\n  page: number;\n\n  /** Number of items per page */\n  pageSize: number;\n\n  /** Total number of pages */\n  totalPages: number;\n\n  /** Whether there's a next page available */\n  hasNext: boolean;\n\n  /** Whether there's a previous page available */\n  hasPrevious: boolean;\n\n  /**\n   * Constructs a new paginated response.\n   *\n   * @param {T[]} items - The current page of items.\n   * @param {Object} pagination - Pagination information.\n   * @param {number} pagination.total - Total number of items across all pages.\n   * @param {number} pagination.page - Current page number (1-based).\n   * @param {number} pagination.pageSize - Number of items per page.\n   * @param {string} [message=\"Success\"] - Optional custom message.\n   */\n  constructor(items: T[], pagination: { total: number; page: number; pageSize: number }, message: string = 'Success') {\n    super(message, items);\n\n    this.total = pagination.total;\n    this.page = pagination.page;\n    this.pageSize = pagination.pageSize;\n\n    this.totalPages = Math.ceil(this.total / this.pageSize);\n    this.hasNext = this.page < this.totalPages;\n    this.hasPrevious = this.page > 1;\n  }\n}\n\n/**\n * Specialized response for operations that don't return data (HTTP 204).\n */\nexport class NoContentResponse extends SuccessResponse<null> {\n  /**\n   * Constructs a new no-content response.\n   *\n   * @param {string} [message=\"Operation completed successfully\"] - Optional custom message.\n   */\n  constructor(message: string = 'Operation completed successfully') {\n    super(message, null);\n  }\n}\n\n/**\n * Specialized response for redirects.\n */\nexport class RedirectResponse {\n  /** The URL to redirect to */\n  redirectUrl: string;\n\n  /** HTTP status code for the redirect (301, 302, 303, 307, 308) */\n  statusCode: number;\n\n  /** Whether the response is a redirect */\n  isRedirect: boolean = true;\n\n  /** Unique identifier for this response */\n  requestId: string = getRequestId() ?? uuid();\n\n  /**\n   * Constructs a new redirect response.\n   *\n   * @param {string} url - The URL to redirect to.\n   * @param {number} [statusCode=302] - HTTP status code for the redirect.\n   */\n  constructor(url: string, statusCode: number = 302) {\n    this.redirectUrl = url;\n    this.statusCode = statusCode;\n  }\n}\n\n/**\n * Creates a standard success response.\n *\n * @typeParam T - The shape of the data returned in the response.\n * @param {T} data - The data to include in the response.\n * @param {string} [message=\"Success\"] - Optional custom message.\n * @returns {SuccessResponse<T>} A properly formatted success response.\n */\nexport function createSuccessResponse<T>(data: T, message: string = 'Success'): SuccessResponse<T> {\n  return new SuccessResponse<T>(message, data);\n}\n\n/**\n * Creates a standard error response.\n *\n * @param {string} message - The error message.\n * @param {number} [statusCode=500] - HTTP status code for the error.\n * @returns {ErrorResponse} A properly formatted error response.\n */\nexport function createErrorResponse(message: string, statusCode: number = 500): ErrorResponse {\n  return new ErrorResponse(message, statusCode);\n}\n\n/**\n * Creates a final error response with request information.\n *\n * @param req - The original request object.\n * @param status - The HTTP status code.\n * @param message - The error message.\n * @param error - The original error object (optional).\n * @param options - Additional options for the response (optional).\n * @returns A properly formatted final error response.\n */\nexport function createFinalErrorResponse(\n  req: Request,\n  status: number,\n  message: string,\n  error?: any,\n  options?: { includeDetails?: boolean }\n) {\n  const isDev = Env.isDev();\n  const includeDetails = options?.includeDetails && isDev;\n\n  const response: ApiErrorResponse = {\n    error: true,\n    message,\n    timestamp: new Date().toISOString(),\n    requestId: error?.requestId || req?.id || uuid(),\n    status,\n    path: req.originalUrl || req.url\n  };\n\n  // Include stack trace in development mode if requested\n  if (includeDetails && error?.stack) {\n    response.stack = error.stack.split('\\n').map((line: string) => line.trim());\n  }\n\n  return response;\n}\n\n/**\n * Creates a paginated response from array data.\n *\n * @typeParam T - The shape of each item in the collection.\n * @param {T[]} allItems - The complete array of items to paginate.\n * @param {number} page - The requested page (1-based).\n * @param {number} pageSize - The number of items per page.\n * @param {string} [message=\"Success\"] - Optional custom message.\n * @returns {PaginatedResponse<T>} A properly formatted paginated response.\n */\nexport function createPaginatedResponse<T>(\n  allItems: T[],\n  page: number,\n  pageSize: number,\n  message: string = 'Success'\n): PaginatedResponse<T> {\n  // Ensure valid pagination parameters\n  const validPage = Math.max(1, page);\n  const validPageSize = Math.max(1, pageSize);\n\n  // Calculate slice indices\n  const startIndex = (validPage - 1) * validPageSize;\n  const endIndex = startIndex + validPageSize;\n\n  // Get current page items\n  const pageItems = allItems.slice(startIndex, endIndex);\n\n  return new PaginatedResponse<T>(\n    pageItems,\n    {\n      total: allItems.length,\n      page: validPage,\n      pageSize: validPageSize\n    },\n    message\n  );\n}\n\n/**\n * Adapter to convert API responses to Express.js response format.\n *\n * @param {any} res - Express response object.\n * @param {SuccessResponse<any> | ErrorResponse | RedirectResponse} apiResponse - API response instance.\n */\nexport function sendResponse(res: any, apiResponse: SuccessResponse<any> | ErrorResponse | RedirectResponse): void {\n  // Handle redirects\n  if ('redirectUrl' in apiResponse) {\n    res.redirect(apiResponse.statusCode, apiResponse.redirectUrl);\n    return;\n  }\n\n  // Handle errors\n  if ('error' in apiResponse && apiResponse.error) {\n    const errorResponse = apiResponse as ErrorResponse;\n    res.status(errorResponse.status).json({\n      error: true,\n      message: errorResponse.message,\n      timestamp: errorResponse.timestamp,\n      requestId: errorResponse.requestId\n    });\n    return;\n  }\n\n  // Handle success responses\n  const successResponse = apiResponse as SuccessResponse<any>;\n\n  // No content (204) shouldn't return a body\n  if (successResponse instanceof NoContentResponse) {\n    res.status(204).end();\n    return;\n  }\n\n  res.status(200).json(successResponse);\n}\n"]}

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