@catbee/utils 2.0.0-next.0 → 2.0.0

package/stream/index.d.ts

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -22,4 +22,93 @@
  * SOFTWARE.
  */
 
-export * from './stream.utils';
+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 };

package/stream/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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

package/string/index.cjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -93,10 +93,42 @@ function toTitleCase(str) {
   return str.split(/(\s+)/).map((part) => part.trim().length === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()).join("");
 }
 __name(toTitleCase, "toTitleCase");
+function escapeRegex(str) {
+  if (typeof str !== "string") throw new TypeError("Expected a string");
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+__name(escapeRegex, "escapeRegex");
+function unescapeHtml(str) {
+  if (typeof str !== "string") return "";
+  const entities = {
+    "&": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&#39;": "'",
+    "&#x27;": "'"
+  };
+  return str.replace(/&(?:amp|lt|gt|quot|#39|#x27);/g, (match) => entities[match] || match);
+}
+__name(unescapeHtml, "unescapeHtml");
+function isBlank(str) {
+  return typeof str === "string" && str.trim().length === 0;
+}
+__name(isBlank, "isBlank");
+function ellipsis(str, maxLength, suffix = "...") {
+  if (typeof str !== "string" || str.length <= maxLength) return str;
+  const truncated = str.slice(0, maxLength - suffix.length);
+  const lastSpace = truncated.lastIndexOf(" ");
+  return (lastSpace > 0 ? truncated.slice(0, lastSpace) : truncated) + suffix;
+}
+__name(ellipsis, "ellipsis");
 
 exports.capitalize = capitalize;
 exports.countOccurrences = countOccurrences;
+exports.ellipsis = ellipsis;
 exports.equalsIgnoreCase = equalsIgnoreCase;
+exports.escapeRegex = escapeRegex;
+exports.isBlank = isBlank;
 exports.mask = mask;
 exports.reverse = reverse;
 exports.slugify = slugify;
@@ -107,3 +139,4 @@ exports.toPascalCase = toPascalCase;
 exports.toSnakeCase = toSnakeCase;
 exports.toTitleCase = toTitleCase;
 exports.truncate = truncate;
+exports.unescapeHtml = unescapeHtml;

package/string/index.d.ts

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -22,4 +22,148 @@
  * SOFTWARE.
  */
 
-export * from './string.utils';
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The string with the first character in uppercase.
+ */
+declare function capitalize(str: string): string;
+/**
+ * Converts a string to kebab-case (e.g., "FooBar test" -> "foo-bar-test").
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The kebab-cased string.
+ */
+declare function toKebabCase(str: string): string;
+/**
+ * Converts a kebab-case or snake_case string to camelCase.
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The camelCased string.
+ */
+declare function toCamelCase(str: string): string;
+/**
+ * Converts a string to a URL-friendly slug (lowercase, dashes, alphanumeric).
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The slugified string.
+ */
+declare function slugify(str: string): string;
+/**
+ * Truncates a string to a specific length, appending '...' if truncated.
+ *
+ * @param {string} str - The input string.
+ * @param {number} len - The maximum length.
+ * @returns {string} The truncated string.
+ */
+declare function truncate(str: string, len: number): string;
+/**
+ * Converts a string to PascalCase (e.g., "foo-bar" -> "FooBar").
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The PascalCased string.
+ */
+declare function toPascalCase(str: string): string;
+/**
+ * Converts a string to snake_case (e.g., "FooBar test" -> "foo_bar_test").
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The snake_cased string.
+ */
+declare function toSnakeCase(str: string): string;
+/**
+ * Masks a string by replacing characters with a mask character.
+ * Useful for hiding sensitive information like credit cards or passwords.
+ *
+ * @param {string} str - The string to mask.
+ * @param {number} [visibleStart=0] - Number of characters to show at start.
+ * @param {number} [visibleEnd=0] - Number of characters to show at end.
+ * @param {string} [maskChar="*"] - Character to use for masking.
+ * @returns {string} The masked string.
+ */
+declare function mask(str: string, visibleStart?: number, visibleEnd?: number, maskChar?: string): string;
+/**
+ * Removes all HTML tags from a string.
+ *
+ * @param {string} str - The HTML string to process.
+ * @returns {string} The string with HTML tags removed.
+ */
+declare function stripHtml(str: string): string;
+/**
+ * Performs case-insensitive string comparison.
+ *
+ * @param {string} a - First string.
+ * @param {string} b - Second string.
+ * @returns {boolean} True if the strings are equal ignoring case.
+ */
+declare function equalsIgnoreCase(a: string, b: string): boolean;
+/**
+ * Reverses a string.
+ *
+ * @param {string} str - The string to reverse.
+ * @returns {string} The reversed string.
+ */
+declare function reverse(str: string): string;
+/**
+ * Counts occurrences of a substring within a string.
+ *
+ * @param {string} str - The source string.
+ * @param {string} substring - The substring to count.
+ * @param {boolean} [caseSensitive=true] - Whether to perform case-sensitive counting.
+ * @returns {number} Number of occurrences.
+ */
+declare function countOccurrences(str: string, substring: string, caseSensitive?: boolean): number;
+/**
+ * Convert a string to Title Case (each word capitalized).
+ * Preserves existing spacing and punctuation between words.
+ *
+ * @param str - Input string
+ * @returns Title-cased string
+ */
+declare function toTitleCase(str: string): string;
+/**
+ * Escapes special regex characters in a string.
+ *
+ * @param {string} str - The input string.
+ * @returns {string} String with regex characters escaped.
+ *
+ * @example
+ * escapeRegex('Hello (world)'); // 'Hello \\(world\\)'
+ */
+declare function escapeRegex(str: string): string;
+/**
+ * Unescapes HTML entities in a string.
+ *
+ * @param {string} str - The HTML string.
+ * @returns {string} String with HTML entities unescaped.
+ *
+ * @example
+ * unescapeHtml('&lt;div&gt;Hello&lt;/div&gt;'); // '<div>Hello</div>'
+ */
+declare function unescapeHtml(str: string): string;
+/**
+ * Checks if a string is blank (empty or only whitespace).
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if blank.
+ *
+ * @example
+ * isBlank('   '); // true
+ * isBlank('hello'); // false
+ */
+declare function isBlank(str: string): boolean;
+/**
+ * Truncates a string with an ellipsis, ensuring word boundaries.
+ *
+ * @param {string} str - The input string.
+ * @param {number} maxLength - Maximum length.
+ * @param {string} [suffix='...'] - Suffix to append.
+ * @returns {string} Truncated string.
+ *
+ * @example
+ * ellipsis('The quick brown fox', 10); // 'The quick...'
+ */
+declare function ellipsis(str: string, maxLength: number, suffix?: string): string;
+
+export { capitalize, countOccurrences, ellipsis, equalsIgnoreCase, escapeRegex, isBlank, mask, reverse, slugify, stripHtml, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, toTitleCase, truncate, unescapeHtml };

package/string/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -91,5 +91,34 @@ function toTitleCase(str) {
   return str.split(/(\s+)/).map((part) => part.trim().length === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()).join("");
 }
 __name(toTitleCase, "toTitleCase");
+function escapeRegex(str) {
+  if (typeof str !== "string") throw new TypeError("Expected a string");
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+__name(escapeRegex, "escapeRegex");
+function unescapeHtml(str) {
+  if (typeof str !== "string") return "";
+  const entities = {
+    "&": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&#39;": "'",
+    "&#x27;": "'"
+  };
+  return str.replace(/&(?:amp|lt|gt|quot|#39|#x27);/g, (match) => entities[match] || match);
+}
+__name(unescapeHtml, "unescapeHtml");
+function isBlank(str) {
+  return typeof str === "string" && str.trim().length === 0;
+}
+__name(isBlank, "isBlank");
+function ellipsis(str, maxLength, suffix = "...") {
+  if (typeof str !== "string" || str.length <= maxLength) return str;
+  const truncated = str.slice(0, maxLength - suffix.length);
+  const lastSpace = truncated.lastIndexOf(" ");
+  return (lastSpace > 0 ? truncated.slice(0, lastSpace) : truncated) + suffix;
+}
+__name(ellipsis, "ellipsis");
 
-export { capitalize, countOccurrences, equalsIgnoreCase, mask, reverse, slugify, stripHtml, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, toTitleCase, truncate };
+export { capitalize, countOccurrences, ellipsis, equalsIgnoreCase, escapeRegex, isBlank, mask, reverse, slugify, stripHtml, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, toTitleCase, truncate, unescapeHtml };

package/type/index.cjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -73,7 +73,7 @@ function toNum(value, defaultValue = 0) {
   if (typeof value === "number") return value;
   try {
     const num = Number(value);
-    return isNaN(num) ? defaultValue : num;
+    return Number.isNaN(num) ? defaultValue : num;
   } catch {
     return defaultValue;
   }
@@ -117,12 +117,29 @@ function isEmpty(value) {
   return false;
 }
 __name(isEmpty, "isEmpty");
+function isIterable(value) {
+  return value !== null && value !== void 0 && typeof value[Symbol.iterator] === "function";
+}
+__name(isIterable, "isIterable");
+function isAsyncIterable(value) {
+  return value !== null && value !== void 0 && typeof value[Symbol.asyncIterator] === "function";
+}
+__name(isAsyncIterable, "isAsyncIterable");
+function assertType(value, guard, message) {
+  if (!guard(value)) {
+    throw new TypeError(message || `Type assertion failed`);
+  }
+}
+__name(assertType, "assertType");
 
+exports.assertType = assertType;
 exports.ensureType = ensureType;
 exports.getTypeOf = getTypeOf;
 exports.isArrayOf = isArrayOf;
+exports.isAsyncIterable = isAsyncIterable;
 exports.isDefined = isDefined;
 exports.isEmpty = isEmpty;
+exports.isIterable = isIterable;
 exports.isPrimitiveType = isPrimitiveType;
 exports.toBool = toBool;
 exports.toNum = toNum;

package/type/index.d.ts

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -22,4 +22,146 @@
  * SOFTWARE.
  */
 
-export * from './type.utils';
+/**
+ * Check if a value is of a specific primitive type.
+ *
+ * @param value - Value to check
+ * @param type - Type to check against
+ * @returns Whether the value is of the specified type
+ *
+ * @example
+ * ```typescript
+ * isPrimitiveType('hello', 'string'); // true
+ * isPrimitiveType(42, 'number'); // true
+ * isPrimitiveType(true, 'boolean'); // true
+ * isPrimitiveType(null, 'null'); // true
+ * isPrimitiveType(undefined, 'undefined'); // true
+ * isPrimitiveType({}, 'object'); // true
+ * isPrimitiveType([], 'array'); // true
+ * ```
+ */
+declare function isPrimitiveType(value: unknown, type: 'string' | 'number' | 'boolean' | 'symbol' | 'bigint' | 'function' | 'object' | 'array' | 'null' | 'undefined'): boolean;
+/**
+ * Get the primitive type of a value as a string.
+ *
+ * @param value - Value to get the type of
+ * @returns String representing the type
+ *
+ * @example
+ * ```typescript
+ * getTypeOf('hello'); // 'string'
+ * getTypeOf(42); // 'number'
+ * getTypeOf([]); // 'array'
+ * getTypeOf(null); // 'null'
+ * ```
+ */
+declare function getTypeOf(value: unknown): string;
+/**
+ * Type guard for checking if a value is an array of a specific type.
+ *
+ * @param value - Value to check
+ * @param itemTypeGuard - Function that checks if items are of the expected type
+ * @returns True if the value is an array with items of the expected type
+ *
+ * @example
+ * ```typescript
+ * isArrayOf([1, 2, 3], (item): item is number => typeof item === 'number'); // true
+ * isArrayOf(['a', 'b', 'c'], (item): item is string => typeof item === 'string'); // true
+ * isArrayOf([1, '2', 3], (item): item is number => typeof item === 'number'); // false
+ * ```
+ */
+declare function isArrayOf<T>(value: unknown, itemTypeGuard: (item: unknown) => item is T): value is T[];
+/**
+ * Convert a value to a string.
+ *
+ * @param value - Value to convert
+ * @param defaultValue - Default value if conversion fails
+ * @returns String representation of the value
+ */
+declare function toStr(value: unknown, defaultValue?: string): string;
+/**
+ * Convert a value to a number.
+ *
+ * @param value - Value to convert
+ * @param defaultValue - Default value if conversion fails
+ * @returns Numeric representation of the value
+ */
+declare function toNum(value: unknown, defaultValue?: number): number;
+/**
+ * Convert a value to a boolean.
+ *
+ * @param value - Value to convert
+ * @param defaultValue - Default value if conversion fails
+ * @returns Boolean representation of the value
+ */
+declare function toBool(value: unknown, defaultValue?: boolean): boolean;
+/**
+ * Ensure a value matches the expected type, or provide a default.
+ *
+ * @param value - Value to check
+ * @param expectedType - Expected primitive type
+ * @param defaultValue - Default value to use if type doesn't match
+ * @returns The value if it matches the type, otherwise the default
+ *
+ * @example
+ * ```typescript
+ * ensureType(42, 'number', 0); // 42
+ * ensureType('42', 'number', 0); // 0
+ * ensureType(undefined, 'string', 'default'); // 'default'
+ * ```
+ */
+declare function ensureType<T>(value: unknown, expectedType: string, defaultValue: T): T;
+/**
+ * Check whether a value is neither null nor undefined.
+ * Useful in filter chains and guards.
+ *
+ * @param value - Value to check
+ * @returns True when value !== null && value !== undefined
+ */
+declare function isDefined<T>(value: T | null | undefined): value is T;
+/**
+ * Check whether a value is empty.
+ * Supports strings, arrays, maps, sets and plain objects.
+ *
+ * @param value - Value to inspect
+ * @returns True when value is considered empty
+ */
+declare function isEmpty(value: any): boolean;
+/**
+ * Type guard to check if a value is iterable.
+ *
+ * @param {unknown} value - Value to check.
+ * @returns {boolean} True if value is iterable.
+ *
+ * @example
+ * isIterable([1, 2, 3]); // true
+ * isIterable('hello'); // true
+ * isIterable(new Set([1, 2])); // true
+ */
+declare function isIterable<T = any>(value: unknown): value is Iterable<T>;
+/**
+ * Type guard to check if a value is an async iterable.
+ *
+ * @param {unknown} value - Value to check.
+ * @returns {boolean} True if value is async iterable.
+ *
+ * @example
+ * async function* gen() { yield 1; }
+ * isAsyncIterable(gen()); // true
+ */
+declare function isAsyncIterable<T = any>(value: unknown): value is AsyncIterable<T>;
+/**
+ * Asserts that a value is of a specific type, throwing an error if not.
+ *
+ * @template T
+ * @param {unknown} value - Value to assert.
+ * @param {(value: unknown) => value is T} guard - Type guard function.
+ * @param {string} [message] - Error message if assertion fails.
+ * @returns {asserts value is T}
+ *
+ * @example
+ * assertType(value, (v): v is string => typeof v === 'string', 'Expected string');
+ */
+declare function assertType<T>(value: unknown, guard: (value: unknown) => value is T, message?: string): asserts value is T;
+
+export { assertType, ensureType, getTypeOf, isArrayOf, isAsyncIterable, isDefined, isEmpty, isIterable, isPrimitiveType, toBool, toNum, toStr };

package/type/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -71,7 +71,7 @@ function toNum(value, defaultValue = 0) {
   if (typeof value === "number") return value;
   try {
     const num = Number(value);
-    return isNaN(num) ? defaultValue : num;
+    return Number.isNaN(num) ? defaultValue : num;
   } catch {
     return defaultValue;
   }
@@ -115,5 +115,19 @@ function isEmpty(value) {
   return false;
 }
 __name(isEmpty, "isEmpty");
+function isIterable(value) {
+  return value !== null && value !== void 0 && typeof value[Symbol.iterator] === "function";
+}
+__name(isIterable, "isIterable");
+function isAsyncIterable(value) {
+  return value !== null && value !== void 0 && typeof value[Symbol.asyncIterator] === "function";
+}
+__name(isAsyncIterable, "isAsyncIterable");
+function assertType(value, guard, message) {
+  if (!guard(value)) {
+    throw new TypeError(message || `Type assertion failed`);
+  }
+}
+__name(assertType, "assertType");
 
-export { ensureType, getTypeOf, isArrayOf, isDefined, isEmpty, isPrimitiveType, toBool, toNum, toStr };
+export { assertType, ensureType, getTypeOf, isArrayOf, isAsyncIterable, isDefined, isEmpty, isIterable, isPrimitiveType, toBool, toNum, toStr };

package/types/index.cjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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