@catbee/utils
Version:
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.
168 lines (165 loc) • 6.14 kB
TypeScript
/*
* The MIT 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
* 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
* ```
*/
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 };