@xylabs/typeof
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
Install
Using npm:
npm install {{name}}Using yarn:
yarn add {{name}}Using pnpm:
pnpm add {{name}}Using bun:
bun add {{name}}License
See the LICENSE file for license rights and limitations (LGPL-3.0-only).
Reference
packages
typeof
### .temp-typedoc
### functions
### <a id="ifDefined"></a>ifDefinedfunction ifDefined<T>(value, func): T | undefined;Invokes the callback only if the value is neither null nor undefined.
Type Parameters
T
T
Parameters
value
T
The value to check.
func
(value) => void
The callback to invoke with the value if it is defined.
Returns
T | undefined
The value if defined, or undefined otherwise.
### <a id="ifTypeOf"></a>ifTypeOffunction ifTypeOf<T, R>(
typeName,
value,
trueFunc,
isFunc?): R | undefined;Invokes the callback if the value matches the specified type, with an optional additional predicate.
Type Parameters
T
T
R
R
Parameters
typeName
The expected type name to match against.
value
unknown
The value to check.
trueFunc
(value) => R
The callback to invoke if the type matches.
isFunc?
(value) => boolean
Optional additional predicate that must also return true.
Returns
R | undefined
The result of trueFunc if the type matches (and isFunc passes), or undefined.
### <a id="isArray"></a>isArrayCall Signature
function isArray(value): value is readonly unknown[];Type guard that checks whether a value is an array.
Parameters
value
unknown
Returns
value is readonly unknown[]
Call Signature
function isArray<T>(value): value is Extract<T, readonly unknown[]>;Type guard that checks whether a value is an array.
Type Parameters
T
T
Parameters
value
T
Returns
value is Extract<T, readonly unknown[]>
### <a id="isArrayBufferView"></a>isArrayBufferViewCall Signature
function isArrayBufferView(value): value is ArrayBufferView<ArrayBufferLike>;Type guard that checks whether a value is an ArrayBufferView (e.g., TypedArray or DataView).
Parameters
value
unknown
Returns
value is ArrayBufferView<ArrayBufferLike>
Call Signature
function isArrayBufferView<T>(value): value is Extract<T, ArrayBufferView<ArrayBufferLike>>;Type guard that checks whether a value is an ArrayBufferView (e.g., TypedArray or DataView).
Type Parameters
T
T extends ArrayBufferView<ArrayBufferLike>
Parameters
value
T
Returns
value is Extract<T, ArrayBufferView<ArrayBufferLike>>
### <a id="isBigInt"></a>isBigIntCall Signature
function isBigInt(value): value is bigint;Type guard that checks whether a value is a bigint.
Parameters
value
unknown
Returns
value is bigint
Call Signature
function isBigInt<T>(value): value is Extract<T, bigint>;Type guard that checks whether a value is a bigint.
Type Parameters
T
T extends bigint
Parameters
value
T
Returns
value is Extract<T, bigint>
### <a id="isBlob"></a>isBlobCall Signature
function isBlob(value): value is Blob;Type guard that checks whether a value is a Blob instance.
Parameters
value
unknown
Returns
value is Blob
Call Signature
function isBlob<T>(value): value is Extract<T, Blob>;Type guard that checks whether a value is a Blob instance.
Type Parameters
T
T extends Blob
Parameters
value
T
Returns
value is Extract<T, Blob>
### <a id="isBoolean"></a>isBooleanCall Signature
function isBoolean(value): value is boolean;Type guard that checks whether a value is a boolean.
Parameters
value
unknown
Returns
value is boolean
Call Signature
function isBoolean<T>(value): value is Extract<T, boolean>;Type guard that checks whether a value is a boolean.
Type Parameters
T
T extends boolean
Parameters
value
T
Returns
value is Extract<T, boolean>
### <a id="isDataView"></a>isDataViewCall Signature
function isDataView(value): value is DataView<ArrayBufferLike>;Type guard that checks whether a value is a DataView instance.
Parameters
value
unknown
Returns
value is DataView<ArrayBufferLike>
Call Signature
function isDataView<T>(value): value is Extract<T, DataView<ArrayBufferLike>>;Type guard that checks whether a value is a DataView instance.
Type Parameters
T
T
Parameters
value
T
Returns
value is Extract<T, DataView<ArrayBufferLike>>
### <a id="isDate"></a>isDateCall Signature
function isDate(value): value is Date;Type guard that checks whether a value is a Date instance.
Parameters
value
unknown
Returns
value is Date
Call Signature
function isDate<T>(value): value is Extract<T, Date>;Type guard that checks whether a value is a Date instance.
Type Parameters
T
T
Parameters
value
T
Returns
value is Extract<T, Date>
### <a id="isDateString"></a>isDateStringCall Signature
function isDateString(value): value is string;Type guard that checks whether a value is a string that can be parsed as a valid date.
Parameters
value
unknown
Returns
value is string
Call Signature
function isDateString<T>(value): value is Extract<T, string>;Type guard that checks whether a value is a string that can be parsed as a valid date.
Type Parameters
T
T
Parameters
value
T
Returns
value is Extract<T, string>
### <a id="isDefined"></a>isDefinedfunction isDefined<T>(value): value is Exclude<T, undefined>;Type guard that checks whether a value is not undefined.
Type Parameters
T
T
Parameters
value
T
Returns
value is Exclude<T, undefined>
### <a id="isDefinedNotNull"></a>isDefinedNotNullfunction isDefinedNotNull<T>(value): value is Exclude<T, null | undefined>;Type guard that checks whether a value is neither undefined nor null.
Type Parameters
T
T
Parameters
value
T
Returns
value is Exclude<T, null | undefined>
### <a id="isEmpty"></a>isEmptyCall Signature
function isEmpty<T>(value): value is T;Type guard that checks whether a value is empty (empty string, empty array, or empty object).
Type Parameters
T
T
Parameters
value
unknown
Returns
value is T
Call Signature
function isEmpty<K, V, T>(value): value is Extract<T, Record<K, never>>;Type guard that checks whether a value is empty (empty string, empty array, or empty object).
Type Parameters
K
K extends RecordKey
V
V
T
T extends Record<K, V>
Parameters
value
T
Returns
value is Extract<T, Record<K, never>>
Call Signature
function isEmpty<T>(value): value is Extract<T, never[]>;Type guard that checks whether a value is empty (empty string, empty array, or empty object).
Type Parameters
T
T extends unknown[]
Parameters
value
T
Returns
value is Extract<T, never[]>
### <a id="isEmptyArray"></a>isEmptyArrayCall Signature
function isEmptyArray(value): value is [];Type guard that checks whether a value is an empty array.
Parameters
value
unknown
Returns
value is []
Call Signature
function isEmptyArray<T>(value): value is Extract<T, unknown[]>;Type guard that checks whether a value is an empty array.
Type Parameters
T
T extends unknown[]
Parameters
value
T
Returns
value is Extract<T, unknown[]>
### <a id="isEmptyObject"></a>isEmptyObjectCall Signature
function isEmptyObject(value): value is {};Type guard that checks whether a value is an object with no own keys.
Parameters
value
unknown
Returns
value is {}
Call Signature
function isEmptyObject<K, V, T>(value): value is Extract<T, Record<K, never>>;Type guard that checks whether a value is an object with no own keys.
Type Parameters
K
K extends RecordKey
V
V
T
T extends Record<K, V>
Parameters
value
T
Returns
value is Extract<T, Record<K, never>>
### <a id="isEmptyString"></a>isEmptyStringCall Signature
function isEmptyString(value): value is "";Type guard that checks whether a value is an empty string.
Parameters
value
unknown
Returns
value is ""
Call Signature
function isEmptyString<T>(value): value is Extract<T, "">;Type guard that checks whether a value is an empty string.
Type Parameters
T
T extends string
Parameters
value
T
Returns
value is Extract<T, "">
### <a id="isError"></a>isErrorCall Signature
function isError(value): value is Error;Type guard that checks whether a value is an Error instance.
Parameters
value
unknown
Returns
value is Error
Call Signature
function isError<T>(value): value is Extract<T, Error>;Type guard that checks whether a value is an Error instance.
Type Parameters
T
T
Parameters
value
T
Returns
value is Extract<T, Error>
### <a id="isFalsy"></a>isFalsyCall Signature
function isFalsy<T>(value): value is Extract<T, false | "" | 0 | 0n | null | undefined>;Type guard that checks whether a value is falsy (0, null, undefined, false, '', or 0n).
Type Parameters
T
T
Parameters
value
T
Returns
value is Extract<T, false | "" | 0 | 0n | null | undefined>
Call Signature
function isFalsy<T>(value): value is Extract<T, false>;Type guard that checks whether a value is falsy (0, null, undefined, false, '', or 0n).
Type Parameters
T
T extends boolean
Parameters
value
T
Returns
value is Extract<T, false>
Call Signature
function isFalsy<T>(value): value is Extract<T, 0>;Type guard that checks whether a value is falsy (0, null, undefined, false, '', or 0n).
Type Parameters
T
T extends number
Parameters
value
T
Returns
value is Extract<T, 0>
Call Signature
function isFalsy<T>(value): value is Extract<T, 0n>;Type guard that checks whether a value is falsy (0, null, undefined, false, '', or 0n).
Type Parameters
T
T extends bigint
Parameters
value
T
Returns
value is Extract<T, 0n>
Call Signature
function isFalsy<T>(value): value is Extract<T, null>;Type guard that checks whether a value is falsy (0, null, undefined, false, '', or 0n).
Type Parameters
T
T extends null
Parameters
value
T
Returns
value is Extract<T, null>
Call Signature
function isFalsy<T>(value): value is Extract<T, undefined>;Type guard that checks whether a value is falsy (0, null, undefined, false, '', or 0n).
Type Parameters
T
T extends undefined
Parameters
value
T
Returns
value is Extract<T, undefined>
Call Signature
function isFalsy<T>(value): value is Extract<T, "">;Type guard that checks whether a value is falsy (0, null, undefined, false, '', or 0n).
Type Parameters
T
T extends string
Parameters
value
T
Returns
value is Extract<T, "">
### <a id="isFile"></a>isFileCall Signature
function isFile(value): value is File;Type guard that checks whether a value is a File instance.
Parameters
value
unknown
Returns
value is File
Call Signature
function isFile<T>(value): value is Extract<T, File>;Type guard that checks whether a value is a File instance.
Type Parameters
T
T extends File
Parameters
value
T
Returns
value is Extract<T, File>
### <a id="isFunction"></a>isFunctionCall Signature
function isFunction(value): value is AnyFunction;Type guard that checks whether a value is a function.
Parameters
value
unknown
Returns
value is AnyFunction
Call Signature
function isFunction<T>(value): value is Extract<T, AnyFunction>;Type guard that checks whether a value is a function.
Type Parameters
T
T extends AnyFunction
Parameters
value
T
Returns
value is Extract<T, AnyFunction>
### <a id="isMap"></a>isMapCall Signature
function isMap(value): value is Map<unknown, unknown>;Type guard that checks whether a value is a Map instance.
Parameters
value
unknown
Returns
value is Map<unknown, unknown>
Call Signature
function isMap<K, V, T>(value): value is Extract<T, Map<K, V>>;Type guard that checks whether a value is a Map instance.
Type Parameters
K
K
V
V
T
T extends Map<K, V>
Parameters
value
T
Returns
value is Extract<T, Map<K, V>>
### <a id="isNull"></a>isNullCall Signature
function isNull(value): value is null;Type guard that checks whether a value is null.
Parameters
value
unknown
Returns
value is null
Call Signature
function isNull<T>(value): value is Extract<T, null>;Type guard that checks whether a value is null.
Type Parameters
T
T
Parameters
value
T
Returns
value is Extract<T, null>
### <a id="isNumber"></a>isNumberCall Signature
function isNumber(value): value is number;Type guard that checks whether a value is a number.
Parameters
value
unknown
Returns
value is number
Call Signature
function isNumber<T>(value): value is Extract<T, number>;Type guard that checks whether a value is a number.
Type Parameters
T
T extends number
Parameters
value
T
Returns
value is Extract<T, number>
### <a id="isObject"></a>isObjectCall Signature
function isObject(value): value is object;Type guard that checks whether a value is a plain object (not null and not an array).
Parameters
value
unknown
Returns
value is object
Call Signature
function isObject<T>(value): value is Extract<T, object>;Type guard that checks whether a value is a plain object (not null and not an array).
Type Parameters
T
T extends object
Parameters
value
T
Returns
value is Extract<T, object>
### <a id="isPopulatedArray"></a>isPopulatedArrayCall Signature
function isPopulatedArray(value): value is readonly unknown[];Type guard that checks whether a value is a non-empty array.
Parameters
value
unknown
Returns
value is readonly unknown[]
Call Signature
function isPopulatedArray<T>(value): value is Extract<T, readonly unknown[]>;Type guard that checks whether a value is a non-empty array.
Type Parameters
T
T extends unknown[]
Parameters
value
T
Returns
value is Extract<T, readonly unknown[]>
### <a id="isPromise"></a>isPromiseCall Signature
function isPromise(value): value is Promise<unknown>;Type guard that checks whether a value is a Promise instance.
Parameters
value
unknown
Returns
value is Promise<unknown>
Call Signature
function isPromise<T>(value): value is Extract<T, Promise<unknown>>;Type guard that checks whether a value is a Promise instance.
Type Parameters
T
T
Parameters
value
T
Returns
value is Extract<T, Promise<unknown>>
### <a id="isPromiseLike"></a>isPromiseLikeCall Signature
function isPromiseLike(value): value is Promise<unknown>;Type guard that checks whether a value is promise-like (has a then method).
Parameters
value
unknown
Returns
value is Promise<unknown>
Call Signature
function isPromiseLike<T>(value): value is Extract<T, Promise<unknown>>;Type guard that checks whether a value is promise-like (has a then method).
Type Parameters
T
T
Parameters
value
T
Returns
value is Extract<T, Promise<unknown>>
### <a id="isRegExp"></a>isRegExpCall Signature
function isRegExp(value): value is RegExp;Type guard that checks whether a value is a RegExp instance.
Parameters
value
unknown
Returns
value is RegExp
Call Signature
function isRegExp<T>(value): value is Extract<T, RegExp>;Type guard that checks whether a value is a RegExp instance.
Type Parameters
T
T extends RegExp
Parameters
value
T
Returns
value is Extract<T, RegExp>
### <a id="isSet"></a>isSetCall Signature
function isSet(value): value is Set<unknown>;Type guard that checks whether a value is a Set instance.
Parameters
value
unknown
Returns
value is Set<unknown>
Call Signature
function isSet<T>(value): value is Extract<T, Set<unknown>>;Type guard that checks whether a value is a Set instance.
Type Parameters
T
T extends Set<unknown>
Parameters
value
unknown
Returns
value is Extract<T, Set<unknown>>
### <a id="isString"></a>isStringCall Signature
function isString(value): value is string;Type guard that checks whether a value is a string.
Parameters
value
unknown
Returns
value is string
Call Signature
function isString<T>(value): value is Extract<T, string>;Type guard that checks whether a value is a string.
Type Parameters
T
T extends string
Parameters
value
T
Returns
value is Extract<T, string>
### <a id="isSymbol"></a>isSymbolCall Signature
function isSymbol(value): value is symbol;Type guard that checks whether a value is a symbol.
Parameters
value
unknown
Returns
value is symbol
Call Signature
function isSymbol<T>(value): value is Extract<T, symbol>;Type guard that checks whether a value is a symbol.
Type Parameters
T
T extends symbol
Parameters
value
T
Returns
value is Extract<T, symbol>
### <a id="isTruthy"></a>isTruthyCall Signature
function isTruthy<T>(value): value is Exclude<T, false | "" | 0 | 0n | null | undefined>;Type guard that checks whether a value is truthy (not 0, null, undefined, false, '', or 0n).
Type Parameters
T
T
Parameters
value
T
Returns
value is Exclude<T, false | "" | 0 | 0n | null | undefined>
Call Signature
function isTruthy<T>(value): value is Extract<T, true>;Type guard that checks whether a value is truthy (not 0, null, undefined, false, '', or 0n).
Type Parameters
T
T extends boolean
Parameters
value
T
Returns
value is Extract<T, true>
Call Signature
function isTruthy<T>(value): value is Extract<T, number>;Type guard that checks whether a value is truthy (not 0, null, undefined, false, '', or 0n).
Type Parameters
T
T extends number
Parameters
value
T
Returns
value is Extract<T, number>
Call Signature
function isTruthy<T>(value): value is Extract<T, bigint>;Type guard that checks whether a value is truthy (not 0, null, undefined, false, '', or 0n).
Type Parameters
T
T extends bigint
Parameters
value
T
Returns
value is Extract<T, bigint>
Call Signature
function isTruthy<T>(value): value is Extract<T, null>;Type guard that checks whether a value is truthy (not 0, null, undefined, false, '', or 0n).
Type Parameters
T
T extends null
Parameters
value
T
Returns
value is Extract<T, null>
Call Signature
function isTruthy<T>(value): value is Extract<T, undefined>;Type guard that checks whether a value is truthy (not 0, null, undefined, false, '', or 0n).
Type Parameters
T
T extends undefined
Parameters
value
T
Returns
value is Extract<T, undefined>
Call Signature
function isTruthy<T>(value): value is Extract<T, string>;Type guard that checks whether a value is truthy (not 0, null, undefined, false, '', or 0n).
Type Parameters
T
T extends string
Parameters
value
T
Returns
value is Extract<T, string>
### <a id="isType"></a>isTypefunction isType(value, expectedType): boolean;Checks whether a value matches the expected field type, with correct handling for arrays and nulls.
Parameters
value
unknown
The value to check.
expectedType
The expected type string.
Returns
boolean
True if the value matches the expected type.
### <a id="isTypedArray"></a>isTypedArrayfunction isTypedArray(value): value is TypedArray;Type guard that checks whether a value is a TypedArray (an array where every element is a TypedValue).
Parameters
value
unknown
The value to check.
Returns
value is TypedArray
True if the value is an array of TypedValue elements.
### <a id="isTypedKey"></a>isTypedKeyfunction isTypedKey(value): value is string | number | symbol;Type guard that checks whether a value is a valid TypedKey (string, bigint, number, or symbol).
Parameters
value
unknown
The value to check.
Returns
value is string | number | symbol
True if the value is a valid TypedKey.
### <a id="isTypedObject"></a>isTypedObjectfunction isTypedObject(value): value is TypedObject;Type guard that checks whether a value is a TypedObject (an object with TypedKey keys and TypedValue values).
Parameters
value
unknown
The value to check.
Returns
value is TypedObject
True if the value is a valid TypedObject.
### <a id="isTypedValue"></a>isTypedValuefunction isTypedValue(value): value is TypedValue;Type guard that checks whether a value is a valid TypedValue.
Parameters
value
unknown
The value to check.
Returns
value is TypedValue
True if the value is a string, number, boolean, null, TypedObject, or TypedArray.
### <a id="isUndefined"></a>isUndefinedCall Signature
function isUndefined(value): value is undefined;Type guard that checks whether a value is undefined.
Parameters
value
unknown
Returns
value is undefined
Call Signature
function isUndefined<T>(value): value is Extract<T, undefined>;Type guard that checks whether a value is undefined.
Type Parameters
T
T
Parameters
value
T
Returns
value is Extract<T, undefined>
### <a id="isUndefinedOrNull"></a>isUndefinedOrNullCall Signature
function isUndefinedOrNull(value): value is null | undefined;Type guard that checks whether a value is undefined or null.
Parameters
value
unknown
Returns
value is null | undefined
Call Signature
function isUndefinedOrNull<T>(value): value is Extract<T, null | undefined>;Type guard that checks whether a value is undefined or null.
Type Parameters
T
T
Parameters
value
T
Returns
value is Extract<T, null | undefined>
### <a id="isValidTypedFieldPair"></a>isValidTypedFieldPairfunction isValidTypedFieldPair(pair): pair is [key: string | number | symbol, value: TypedValue];Type guard that checks whether a key-value pair has a valid TypedKey and TypedValue.
Parameters
pair
[unknown, unknown]
A tuple of [key, value] to validate.
Returns
pair is [key: string | number | symbol, value: TypedValue]
True if the key is a TypedKey and the value is a TypedValue.
### <a id="isWeakMap"></a>isWeakMapCall Signature
function isWeakMap(value): value is WeakMap<WeakKey, unknown>;Type guard that checks whether a value is a WeakMap instance.
Parameters
value
unknown
Returns
value is WeakMap<WeakKey, unknown>
Call Signature
function isWeakMap<K, V, T>(value): value is Extract<T, WeakMap<K, V>>;Type guard that checks whether a value is a WeakMap instance.
Type Parameters
K
K extends WeakKey
V
V
T
T extends WeakMap<K, V>
Parameters
value
T
Returns
value is Extract<T, WeakMap<K, V>>
### <a id="isWeakSet"></a>isWeakSetCall Signature
function isWeakSet(value): value is WeakSet<WeakKey>;Type guard that checks whether a value is a WeakSet instance.
Parameters
value
unknown
Returns
value is WeakSet<WeakKey>
Call Signature
function isWeakSet<K, T>(value): value is Extract<T, WeakSet<K>>;Type guard that checks whether a value is a WeakSet instance.
Type Parameters
K
K extends WeakKey
T
T extends WeakSet<K>
Parameters
value
T
Returns
value is Extract<T, WeakSet<K>>
### <a id="typeOf"></a>typeOffunction typeOf<T>(item): TypeOfTypes;Extended typeof that distinguishes arrays from objects (unlike native typeof).
Type Parameters
T
T
Parameters
item
T
The value to check.
Returns
The type of the item as a TypeOfTypes string.
### <a id="validateType"></a>validateTypefunction validateType<T>(
typeName,
value,
optional?): [T | undefined, Error[]];Validates that a value matches the expected type, returning the value and any errors.
Type Parameters
T
T
Parameters
typeName
The expected type name.
value
T
The value to validate.
optional?
boolean = false
If true, undefined values are accepted without error.
Returns
[T | undefined, Error[]]
A tuple of [value or undefined, array of errors].
### type-aliases
### <a id="AnyFunction"></a>AnyFunctiontype AnyFunction = (...args) => unknown;A function type that accepts any arguments and returns unknown.
Parameters
args
...unknown[]
Returns
unknown
### <a id="Brand"></a>Brandtype Brand<T, B> = T & { [K in keyof B]: B[K] };Creates a branded type by intersecting base type T with brand type B, enabling nominal typing in TypeScript.
Type Parameters
T
T
B
B
### <a id="FieldType"></a>FieldTypetype FieldType =
| "string"
| "number"
| "object"
| "symbol"
| "undefined"
| "null"
| "array"
| "function";Union of string literals representing the possible types of an object field.
### <a id="IdentityFunction"></a>IdentityFunctiontype IdentityFunction<T> = (value) => value is T;A type guard function that narrows an unknown value to type T.
Type Parameters
T
T
Parameters
value
unknown
Returns
value is T
### <a id="ObjectTypeShape"></a>ObjectTypeShapetype ObjectTypeShape = Record<string | number | symbol, FieldType>;Describes the expected shape of an object by mapping each key to its expected field type.
### <a id="RecordKey"></a>RecordKeytype RecordKey = string | number | symbol;A union of valid object key types.
### <a id="TypeOfTypes"></a>TypeOfTypestype TypeOfTypes =
| "string"
| "number"
| "object"
| "array"
| "buffer"
| "null"
| "undefined"
| "bigint"
| "boolean"
| "function"
| "symbol";Union of string literals representing the possible results of the extended typeOf function.
### <a id="TypedArray"></a>TypedArraytype TypedArray = TypedValue[];An array of TypedValue elements.
### <a id="TypedKey"></a>TypedKeytype TypedKey<T> = T extends string ? T : string | number | symbol;A valid key for a typed object. Defaults to string | number | symbol unless narrowed by T.
Type Parameters
T
T extends string | void = void
### <a id="TypedObject"></a>TypedObjecttype TypedObject =
| {
[key: string | number | symbol]: TypedValue;
}
| object;An object whose keys are TypedKey and whose values are TypedValue.
### <a id="TypedValue"></a>TypedValuetype TypedValue =
| bigint
| string
| number
| boolean
| null
| TypedObject
| TypedArray
| Function
| symbol
| undefined;A value that can appear in a typed object tree (primitives, objects, arrays, functions, and symbols).