ts-data-objects/common.d.ts

Simple lightweight library for enhancing plain JS objects with TypeScript wrappers enabling easy API data assertion and validation

/**
 * Custom internal error class for data validation failures.
 *
 * Provides detailed error messages when data validation fails, including:
 * - The expected data type name
 * - The actual value that failed validation
 * - Optional details about which specific validation failed
 *
 * @example
 * ```typescript
 * throw new DataValidationError('UserData', invalidData, 'age must be a number')
 * ```
 *
 * @category Core Component
 */
export declare class DataValidationError extends Error {
    /** Name of the expected type */
    dataType: string;
    /** The value that failed validation */
    value: unknown;
    /** Optional details about the validation failure */
    detail?: string;
    constructor(
    /** Name of the expected type */
    dataType: string, 
    /** The value that failed validation */
    value: unknown, 
    /** Optional details about the validation failure */
    detail?: string);
}

/**
 * Checks if a value is an array where every element satisfies the provided predicate
 *
 * @example
 * ```typescript
 * import { isArrayOf, isStr } from 'ts-data-objects'
 *
 * if (isArrayOf(someValue, isStr)) {
 *   someValue.push('someValue is string array')
 * }
 * ```
 *
 * @template T The expected type of array elements
 * @param value - The value to check
 * @param predicate - The type guard function to apply to each array element
 * @returns A type predicate indicating whether the value is an array of type T
 * @category Assertions
 */
export declare const isArrayOf: <T>(value: unknown, predicate: Predicate<T>) => value is T[];

/**
 * Type guard function for boolean values.
 *
 * @example
 * ```typescript
 * isBool(true)       // returns true
 * isBool('true')     // returns false
 * isBool(0)          // returns false
 * isBool(null)       // returns false
 * isBool(undefined)  // returns false
 * ```
 *
 * @param value - Any value to check
 * @returns Type predicate indicating if the value is a boolean
 * @category Assertions
 */
export declare const isBool: (value: unknown) => value is boolean;

/**
 * Type guard function for number values.
 *
 * @example
 * ```typescript
 * isNum(42)         // returns true
 * isNum('42')       // returns false
 * isNum(NaN)        // returns true - but will not occur in JSON data
 * isNum(null)       // returns false
 * isNum(undefined)  // returns false
 * ```
 *
 * @param value - Any value to check
 * @returns Type predicate indicating if the value is a number
 * @category Assertions
 */
export declare const isNum: (value: unknown) => value is number;

/**
 * Checks if a value satisfies the provided simple object predicate
 * - Intended for user generated TS data objects residing inside other interfaces
 *
 * @template T The expected type of the object
 * @param value - The value to check
 * @param predicate - The type guard function to check if the value is of type T
 * @returns A type predicate indicating whether the value is null, undefined, or of type T
 * @category Assertions
 */
export declare const isObject: <T>(value: unknown, predicate: Predicate<T> | PredicateFunction) => value is T;

/**
 * Checks if a value is either null, undefined, or an array where every element satisfies the provided predicate
 *
 * @template T The expected type of array elements
 * @param value - The value to check
 * @param predicate - The type guard function to apply to each array element
 * @returns A type predicate indicating whether the value is null, undefined, or an array of type T
 * @category Assertions
 */
export declare const isOptionalArrayOf: <T>(value: unknown, predicate: Predicate<T>) => value is T[];

/**
 * Type guard function for optional boolean values
 *
 * @example
 * ```typescript
 * isBool(true)       // returns true
 * isBool('true')     // returns false
 * isBool(0)          // returns false
 * isBool(null)       // returns true
 * isBool(undefined)  // returns true
 * ```
 *
 * @param value - Any value to check
 * @returns Type predicate indicating if the value is boolean or null/undefined
 * @category Assertions
 */
export declare const isOptionalBool: (value: unknown) => value is boolean;

/**
 * Type guard function for optional number values.
 *
 * @example
 * ```typescript
 * isNum(42)         // returns true
 * isNum('42')       // returns false
 * isNum(NaN)        // returns true
 * isNum(null)       // returns true
 * isNum(undefined)  // returns true
 * ```
 *
 * @param value - Any value to check
 * @returns Type predicate indicating if the value is a number
 * @category Assertions
 */
export declare const isOptionalNum: (value: unknown) => value is number;

/**
 * Checks if a value is either null, undefined, or satisfies the provided simple object predicate
 * - Intended for user generated TS data objects residing inside other interfaces
 *
 * @template T The expected type of the object
 * @param value - The value to check
 * @param predicate - The type guard function to check if the value is of type T
 * @returns A type predicate indicating whether the value is null, undefined, or of type T
 * @category Assertions
 */
export declare const isOptionalObject: <T>(value: unknown, predicate: Predicate<T>) => value is T;

/**
 * Type guard function for string values.
 *
 * @example
 * ```typescript
 * isStr('hello')    // returns true
 * isStr(42)         // returns false
 * isStr('')         // returns true
 * isStr(null)       // returns true
 * isStr(undefined)  // returns true
 * ```
 *
 * @param value - Any value to check
 * @returns Type predicate indicating if the value is a string
 * @category Assertions
 */
export declare const isOptionalStr: (value: unknown) => value is string;

/**
 * Type guard function for string values.
 *
 * @example
 * ```typescript
 * isStr('hello')    // returns true
 * isStr(42)         // returns false
 * isStr('')         // returns true
 * isStr(null)       // returns false
 * isStr(undefined)  // returns false
 * ```
 *
 * @param value - Any value to check
 * @returns Type predicate indicating if the value is a string
 * @category Assertions
 */
export declare const isStr: (value: unknown) => value is string;

/**
 * Type for a predicate function that performs a type guard check
 *
 * @template T The type being checked against
 * @param value - The unknown value to check
 * @returns A type predicate indicating whether the value is of type T
 * @category Assertions
 */
declare type Predicate<T> = (value: unknown) => value is T;

/**
 * A generic predicate function type that tests any value and returns a boolean.
 * - TS-wise inferior to {@link Predicate}, but is useful when writing custom predicate logic
 * inside one of functions
 *
 * @template T - The type of value being tested (inferred from usage)
 * @param value - The value to test
 * @returns A boolean indicating whether the value satisfies the predicate condition
 * @category Assertions
 */
declare type PredicateFunction = (value: any) => boolean;

export { }