@catbee/utils 0.0.6 → 0.0.7

package/build/src/utils/type.utils.js

@@ -0,0 +1,196 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPrimitiveType = isPrimitiveType;
+exports.getTypeOf = getTypeOf;
+exports.isArrayOf = isArrayOf;
+exports.toStr = toStr;
+exports.toNum = toNum;
+exports.toBool = toBool;
+exports.ensureType = ensureType;
+/**
+ * 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
+ * ```
+ */
+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'
+ * ```
+ */
+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
+ * ```
+ */
+function isArrayOf(value, itemTypeGuard) {
+    if (!Array.isArray(value))
+        return false;
+    return value.every(item => 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
+ */
+function toStr(value, 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
+ */
+function toNum(value, defaultValue = 0) {
+    if (value === null || value === undefined)
+        return defaultValue;
+    if (typeof value === 'number')
+        return value;
+    try {
+        const 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
+ */
+function toBool(value, defaultValue = false) {
+    if (value === null || value === undefined)
+        return defaultValue;
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        const 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'
+ * ```
+ */
+function ensureType(value, expectedType, defaultValue) {
+    if (getTypeOf(value) === expectedType) {
+        return value;
+    }
+    return defaultValue;
+}
+//# sourceMappingURL=type.utils.js.map

package/build/src/utils/type.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.utils.js","sourceRoot":"","sources":["../../../src/utils/type.utils.ts"],"names":[],"mappings":"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","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\n/**\n * Check if a value is of a specific primitive type.\n *\n * @param value - Value to check\n * @param type - Type to check against\n * @returns Whether the value is of the specified type\n *\n * @example\n * ```typescript\n * isPrimitiveType('hello', 'string'); // true\n * isPrimitiveType(42, 'number'); // true\n * isPrimitiveType(true, 'boolean'); // true\n * isPrimitiveType(null, 'null'); // true\n * isPrimitiveType(undefined, 'undefined'); // true\n * isPrimitiveType({}, 'object'); // true\n * isPrimitiveType([], 'array'); // true\n * ```\n */\nexport function isPrimitiveType(\n  value: unknown,\n  type: 'string' | 'number' | 'boolean' | 'symbol' | 'bigint' | 'function' | 'object' | 'array' | 'null' | 'undefined'\n): boolean {\n  if (type === 'array') {\n    return Array.isArray(value);\n  }\n\n  if (type === 'null') {\n    return value === null;\n  }\n\n  if (type === 'undefined') {\n    return value === undefined;\n  }\n\n  if (type === 'object') {\n    // Only plain objects, not arrays or null\n    return typeof value === 'object' && value !== null && !Array.isArray(value);\n  }\n\n  return typeof value === type;\n}\n\n/**\n * Get the primitive type of a value as a string.\n *\n * @param value - Value to get the type of\n * @returns String representing the type\n *\n * @example\n * ```typescript\n * getTypeOf('hello'); // 'string'\n * getTypeOf(42); // 'number'\n * getTypeOf([]); // 'array'\n * getTypeOf(null); // 'null'\n * ```\n */\nexport function getTypeOf(value: unknown): string {\n  if (value === null) return 'null';\n  if (value === undefined) return 'undefined';\n  if (Array.isArray(value)) return 'array';\n  return typeof value;\n}\n\n/**\n * Type guard for checking if a value is an array of a specific type.\n *\n * @param value - Value to check\n * @param itemTypeGuard - Function that checks if items are of the expected type\n * @returns True if the value is an array with items of the expected type\n *\n * @example\n * ```typescript\n * isArrayOf([1, 2, 3], (item): item is number => typeof item === 'number'); // true\n * isArrayOf(['a', 'b', 'c'], (item): item is string => typeof item === 'string'); // true\n * isArrayOf([1, '2', 3], (item): item is number => typeof item === 'number'); // false\n * ```\n */\nexport function isArrayOf<T>(value: unknown, itemTypeGuard: (item: unknown) => item is T): value is T[] {\n  if (!Array.isArray(value)) return false;\n  return value.every(item => itemTypeGuard(item));\n}\n\n/**\n * Convert a value to a string.\n *\n * @param value - Value to convert\n * @param defaultValue - Default value if conversion fails\n * @returns String representation of the value\n */\nexport function toStr(value: unknown, defaultValue: string = ''): string {\n  if (value === null || value === undefined) return defaultValue;\n\n  try {\n    if (typeof value === 'object') {\n      return JSON.stringify(value);\n    }\n    return String(value);\n  } catch {\n    return defaultValue;\n  }\n}\n\n/**\n * Convert a value to a number.\n *\n * @param value - Value to convert\n * @param defaultValue - Default value if conversion fails\n * @returns Numeric representation of the value\n */\nexport function toNum(value: unknown, defaultValue: number = 0): number {\n  if (value === null || value === undefined) return defaultValue;\n\n  if (typeof value === 'number') return value;\n\n  try {\n    const num = Number(value);\n    return isNaN(num) ? defaultValue : num;\n  } catch {\n    return defaultValue;\n  }\n}\n\n/**\n * Convert a value to a boolean.\n *\n * @param value - Value to convert\n * @param defaultValue - Default value if conversion fails\n * @returns Boolean representation of the value\n */\nexport function toBool(value: unknown, defaultValue: boolean = false): boolean {\n  if (value === null || value === undefined) return defaultValue;\n\n  if (typeof value === 'boolean') return value;\n\n  if (typeof value === 'string') {\n    const lowercased = value.toLowerCase();\n    if (lowercased === 'true' || lowercased === 'yes' || lowercased === 'y' || lowercased === '1') {\n      return true;\n    }\n    if (lowercased === 'false' || lowercased === 'no' || lowercased === 'n' || lowercased === '0') {\n      return false;\n    }\n  }\n\n  if (typeof value === 'number') {\n    return value !== 0;\n  }\n\n  return defaultValue;\n}\n\n/**\n * Ensure a value matches the expected type, or provide a default.\n *\n * @param value - Value to check\n * @param expectedType - Expected primitive type\n * @param defaultValue - Default value to use if type doesn't match\n * @returns The value if it matches the type, otherwise the default\n *\n * @example\n * ```typescript\n * ensureType(42, 'number', 0); // 42\n * ensureType('42', 'number', 0); // 0\n * ensureType(undefined, 'string', 'default'); // 'default'\n * ```\n */\nexport function ensureType<T>(value: unknown, expectedType: string, defaultValue: T): T {\n  if (getTypeOf(value) === expectedType) {\n    return value as unknown as T;\n  }\n  return defaultValue;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catbee/utils",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.",
   "main": "build/src/index.js",
   "module": "build/esm/index.js",
@@ -29,7 +29,11 @@
     "coverage": "npm run test:coverage",
     "test:debug": "cross-env LOGGER_LEVEL=info jest",
     "add-license": "npx license-check-and-add add -f file-banner-lic.json && npm run lint:fix",
-    "check-license": "npx license-check-and-add check -f file-banner-lic.json"
+    "check-license": "npx license-check-and-add check -f file-banner-lic.json",
+    "docs:install": "cd docs && npm install",
+    "docs:start": "cd docs && npm run start",
+    "docs:build": "cd docs && npm run build",
+    "docs:serve": "npm run docs:build && cd docs && npm run serve"
   },
   "keywords": [
     "utils",