@catbee/utils 2.0.0-next.0 → 2.0.0-next.1

package/server/index.mjs

@@ -30,12 +30,12 @@ import { requestId, setupRequestContext, timeout, responseTime, errorHandler } f
 import { Env } from '@catbee/utils/env';
 import { getLogger } from '@catbee/utils/logger';
 import { ServiceUnavailableException, InternalServerErrorException, NotFoundException } from '@catbee/utils/exception';
-import fs from 'fs';
-import { defaultServerConfig, defaultCatbeeConfig } from '@catbee/utils/config';
-import { deepObjMerge } from '@catbee/utils/obj';
-import { fileExists } from '@catbee/utils/fs';
-import { isPort } from '@catbee/utils/validate';
+import { getCatbeeServerGlobalConfig } from '@catbee/utils/config';
+import { deepObjMerge, deepClone } from '@catbee/utils/obj';
+import { fileExists, readFile, readFileSync } from '@catbee/utils/fs';
+import { isPort } from '@catbee/utils/validation';
 import { optionalRequire } from '@catbee/utils/async';
+import { uuid } from '@catbee/utils/id';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -498,7 +498,10 @@ var ServerConfigBuilder = class {
   * ```
   */
   withBodyParser(opts) {
-    this.config.bodyParser = deepObjMerge({}, this.config.bodyParser ?? {}, opts);
+    this.config.bodyParser = {
+      ...this.config.bodyParser,
+      ...opts
+    };
     return this;
   }
   /**
@@ -641,7 +644,7 @@ var ServerConfigBuilder = class {
   * ```
   */
   build() {
-    const config = deepObjMerge({}, defaultServerConfig, this.config);
+    const config = deepObjMerge({}, getCatbeeServerGlobalConfig(), this.config);
     if (config.openApi?.enable && !config.openApi.filePath) {
       throw new Error("OpenAPI is enabled but no filePath is specified");
     }
@@ -651,7 +654,7 @@ var ServerConfigBuilder = class {
     });
   }
   mergeConfig(key, value) {
-    const current = typeof this.config[key] === "object" && this.config[key] !== null ? this.config[key] : {};
+    const current = this.config[key] && typeof this.config[key] === "object" ? deepClone(this.config[key]) : {};
     this.config[key] = deepObjMerge({}, current, value);
   }
   setEnabled(key, enable, overrides = {}) {
@@ -662,9 +665,11 @@ var ServerConfigBuilder = class {
     return this;
   }
 };
-
-// src/server/server.ts
-var getDependencyErrorMessage = /* @__PURE__ */ __name((packageName, x) => `Missing required dependency ${x ? `for ${x}` : ""}: ${packageName}. Please install it to proceed.`, "getDependencyErrorMessage");
+var getDependencyErrorMessage = /* @__PURE__ */ __name((packageName, context) => {
+  const ctxPart = context ? `for ${context}` : "";
+  const spacer = ctxPart ? ` ${ctxPart}` : "";
+  return `Missing required dependency${spacer}: ${packageName}. Please install it to proceed.`;
+}, "getDependencyErrorMessage");
 var DependencyErrors = {
   express: getDependencyErrorMessage("express"),
   helmet: getDependencyErrorMessage("helmet"),
@@ -729,10 +734,10 @@ var ExpressServer = class {
   * - Request tracing
   */
   constructor(config, hooks = {}) {
-    if (this.isBuiltServerConfig(config)) {
+    if (this.hasBuildMarker(config)) {
       this.config = config;
     } else {
-      this.config = deepObjMerge({}, defaultServerConfig, config);
+      this.config = deepObjMerge({}, getCatbeeServerGlobalConfig(), config);
     }
     if (!isPort(this.config.port)) {
       const msg = `Port must be a valid number between 1 and 65535, got: ${this.config.port}`;
@@ -834,7 +839,7 @@ var ExpressServer = class {
   async runHook(hook, ...args) {
     try {
       const fn = this.hooks[hook];
-      if (fn) await fn.apply(null, args);
+      if (fn) await fn(...args);
     } catch (err) {
       getLogger().error({
         err,
@@ -881,7 +886,7 @@ var ExpressServer = class {
     this.app.use(requestId({
       headerName: this.config.requestId?.headerName,
       exposeHeader: this.config.requestId?.exposeHeader,
-      generator: this.config.requestId?.generator
+      generator: this.config.requestId?.generator || uuid
     }));
     this.app.use(setupRequestContext({
       headerName: this.config.requestId?.headerName,
@@ -1045,7 +1050,7 @@ var ExpressServer = class {
         }
         this.app.use(openApiMountPath, apiReference({
           spec: {
-            content: await fs.promises.readFile(openApiFilePath, "utf8")
+            content: await readFile(openApiFilePath, "utf8")
           }
         }));
         if (this.config.openApi?.verbose) {
@@ -1109,7 +1114,7 @@ var ExpressServer = class {
     const healthCheckPath = this.normalizePath(this.config.healthCheck?.path || "/healthz", this.config.healthCheck?.withGlobalPrefix);
     this.app.get(healthCheckPath, async (_req, res) => {
       try {
-        if (!this.healthChecks.length || defaultCatbeeConfig.server.skipHealthz) {
+        if (!this.healthChecks.length || getCatbeeServerGlobalConfig().skipHealthz) {
           return res.status(HttpStatusCodes.OK).json(new SuccessResponse("OK"));
         }
         const checkResults = await Promise.allSettled(this.healthChecks.map(async ({ name, check }) => {
@@ -1208,7 +1213,7 @@ var ExpressServer = class {
   */
   async ready() {
     try {
-      if (!this.healthChecks.length || defaultCatbeeConfig.server.skipHealthz) return true;
+      if (!this.healthChecks.length || getCatbeeServerGlobalConfig().skipHealthz) return true;
       const checkResults = await Promise.allSettled(this.healthChecks.map(async ({ name, check }) => {
         try {
           const status = await Promise.resolve(check());
@@ -1297,11 +1302,11 @@ var ExpressServer = class {
         if (this.config.https) {
           const httpsOptions = {
             ...this.config.https,
-            key: fs.readFileSync(this.config.https.key),
-            cert: fs.readFileSync(this.config.https.cert)
+            key: readFileSync(this.config.https.key),
+            cert: readFileSync(this.config.https.cert)
           };
           if (this.config.https.ca) {
-            httpsOptions.ca = fs.readFileSync(this.config.https.ca);
+            httpsOptions.ca = readFileSync(this.config.https.ca);
           }
           if (this.config.https.passphrase) {
             httpsOptions.passphrase = this.config.https.passphrase;
@@ -1526,7 +1531,7 @@ var ExpressServer = class {
   /**
   * Get server configuration
   *
-  * @return {*}  {ServerConfig}
+  * @return {*}  {CatbeeServerConfig}
   */
   getConfig() {
     return this.config;
@@ -1600,7 +1605,7 @@ var ExpressServer = class {
       throw new Error(msg);
     }
   }
-  isBuiltServerConfig(config) {
+  hasBuildMarker(config) {
     if (config?.[BUILD_MARKER]) {
       return true;
     }

package/stream/index.d.ts

@@ -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/string/index.d.ts

@@ -22,4 +22,105 @@
  * 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;
+
+export { capitalize, countOccurrences, equalsIgnoreCase, mask, reverse, slugify, stripHtml, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, toTitleCase, truncate };

package/type/index.cjs

@@ -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;
   }

package/type/index.d.ts

@@ -22,4 +22,110 @@
  * 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;
+
+export { ensureType, getTypeOf, isArrayOf, isDefined, isEmpty, isPrimitiveType, toBool, toNum, toStr };

package/type/index.mjs

@@ -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;
   }