@xylabs/object
Advanced tools
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
Using npm:
npm install {{name}}
Using yarn:
yarn add {{name}}
Using pnpm:
pnpm add {{name}}
Using bun:
bun add {{name}}
See the LICENSE file for license rights and limitations (LGPL-3.0-only).
### .temp-typedoc
### index
### index-deprecated
### functions
### <a id="isType"></a>isType
function isType(value, expectedType): boolean;
unknown
FieldType
boolean
use from @xylabs/typeof instead
### index-un-deprecated
### classes
### <a id="IsObjectFactory"></a>IsObjectFactory
Factory class for creating type-guard functions that validate objects against a given shape and optional additional checks.
T extends TypedObject
new IsObjectFactory<T>(): IsObjectFactory<T>;
IsObjectFactory<T>
create(shape?, additionalChecks?): TypeCheck<T>;
Creates a type-guard function that validates an object matches the given shape and passes additional checks.
ObjectTypeShape
An optional map of property names to expected types.
TypeCheck<TypedObject>[]
Optional extra type-check functions to run after shape validation.
TypeCheck<T>
A type-guard function for type T.
### <a id="ObjectWrapper"></a>ObjectWrapper
Abstract base class that wraps an object and provides typed access to it.
T extends EmptyObject = EmptyObject
new ObjectWrapper<T>(obj): ObjectWrapper<T>;
T
ObjectWrapper<T>
readonly obj: T;
get protected stringKeyObj(): StringKeyObject;
### <a id="ValidatorBase"></a>ValidatorBase
Abstract base class for validators that wraps a partial object and provides a validation method.
ObjectWrapper<Partial<T>>T extends EmptyObject = AnyObject
Validator<T>new ValidatorBase<T>(obj): ValidatorBase<T>;
T
ValidatorBase<T>
readonly obj: T;
get protected stringKeyObj(): StringKeyObject;
abstract validate(payload): Promisable<Error[]>;
T
Promisable<Error[]>
### functions
### <a id="createDeepMerge"></a>createDeepMerge
function createDeepMerge(options): <T>(...objects) => MergeAll<T>;
Creates a deep merge function with the specified options.
MergeOptions
Options for merging.
A deep merge function configured for the specified options.
<T>(...objects) => MergeAll<T>
### <a id="omitBy"></a>omitBy
function omitBy<T>(
obj,
predicate,
maxDepth?): Partial<T>;
Creates a new object excluding properties that satisfy the predicate, with optional recursive depth.
T extends object
T
The source object to omit properties from.
A function that returns true for properties to exclude.
number = 1
Maximum recursion depth for nested objects.
Partial<T>
A partial copy of the object without matching properties.
### <a id="omitByPrefix"></a>omitByPrefix
function omitByPrefix<T, P>(
payload,
prefix,
maxDepth?): DeepOmitStartsWith<T, P>;
Omits all properties whose keys start with the given prefix, recursively through nested objects.
T extends object
P extends string
T
The source object.
P
The string prefix to match keys against.
number = 100
Maximum recursion depth.
DeepOmitStartsWith<T, P>
A new object without properties that have matching prefixed keys.
### <a id="pickBy"></a>pickBy
function pickBy<T>(
obj,
predicate,
maxDepth?): Partial<T>;
Creates a new object containing only the properties that satisfy the predicate, with optional recursive depth.
T extends object
T
The source object to pick properties from.
A function that returns true for properties to include.
number = 1
Maximum recursion depth for nested objects.
Partial<T>
A partial copy of the object with only matching properties.
### <a id="pickByPrefix"></a>pickByPrefix
function pickByPrefix<T, P>(
payload,
prefix,
maxDepth?): DeepPickStartsWith<T, P>;
Picks all properties whose keys start with the given prefix, recursively through nested objects.
T extends object
P extends string
T
The source object.
P
The string prefix to match keys against.
number = 100
Maximum recursion depth.
DeepPickStartsWith<T, P>
A new object containing only properties with matching prefixed keys.
### <a id="removeFields"></a>removeFields
function removeFields<T, K>(obj, fields): Omit<T, K>;
Returns a shallow copy of the object with the specified fields removed.
T extends object
K extends string | number | symbol
T
The source object.
K[]
An array of keys to remove.
Omit<T, K>
A new object without the specified fields.
### <a id="toSafeJson"></a>toSafeJson
function toSafeJson(value, maxDepth?): unknown;
Converts a value to a JSON-safe representation, handling circular references and non-serializable types.
unknown
The value to convert.
number = 3
Maximum recursion depth.
unknown
A JSON-safe value.
### <a id="toSafeJsonArray"></a>toSafeJsonArray
function toSafeJsonArray(
value,
cycleList?,
maxDepth?): unknown[];
Converts an array to a JSON-safe array, handling circular references and depth limits.
unknown[]
The array to convert.
unknown[]
Tracks visited objects to detect circular references.
number = 3
Maximum recursion depth before truncating.
unknown[]
A JSON-safe array representation.
### <a id="toSafeJsonObject"></a>toSafeJsonObject
function toSafeJsonObject(
value,
cycleList?,
maxDepth?): JsonObject;
Converts an object to a JSON-safe object, handling circular references and depth limits.
object
The object to convert.
unknown[]
Tracks visited objects to detect circular references.
number = 3
Maximum recursion depth before truncating.
A JSON-safe object representation.
### <a id="toSafeJsonString"></a>toSafeJsonString
function toSafeJsonString(value, maxDepth?): string;
Converts a value to a pretty-printed JSON string, safely handling circular references and non-JSON types.
unknown
The value to serialize.
number = 3
Maximum recursion depth.
string
A formatted JSON string.
### <a id="toSafeJsonValue"></a>toSafeJsonValue
function toSafeJsonValue(
value,
cycleList?,
maxDepth?): unknown;
Converts an unknown value to a JSON-safe value, replacing circular references with '[Circular]' and non-JSON types with descriptive placeholder strings.
unknown
The value to convert.
unknown[]
Tracks visited objects to detect circular references.
number = 3
Maximum recursion depth before truncating with '[MaxDepth]'.
unknown
A JSON-safe representation of the value.
### interfaces
### <a id="AsTypeFunction"></a>AsTypeFunction
A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.
T extends AnyNonPromise = AnyNonPromise
AsTypeFunction<TType>(value): TType | undefined;
A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.
TType extends AnyNonPromise
AnyNonPromise
TType | undefined
AsTypeFunction<TType>(value, config): TType;
A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.
TType extends AnyNonPromise
AnyNonPromise
TType
AsTypeFunction<TType>(value, config): TType | undefined;
A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.
TType extends AnyNonPromise
AnyNonPromise
| TypeCheckConfig
| TypeCheckOptionalConfig
TType | undefined
AsTypeFunction<TType>(value, assert): TType | undefined;
A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.
TType extends AnyNonPromise
AnyNonPromise
StringOrAlertFunction<TType>
TType | undefined
AsTypeFunction<TType>(
value,
assert,
config): TType;
A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.
TType extends AnyNonPromise
AnyNonPromise
StringOrAlertFunction<TType>
TType
AsTypeFunction<TType>(
value,
assert,
config): TType | undefined;
A type-narrowing function that attempts to cast a value to T, with optional assertion and configuration overloads.
TType extends AnyNonPromise
AnyNonPromise
StringOrAlertFunction<TType>
| TypeCheckConfig
| TypeCheckOptionalConfig
TType | undefined
### <a id="ObjectTypeConfig"></a>ObjectTypeConfig
Configuration options for object type checking.
optional log?: boolean | Logger;
### <a id="TypeCheck"></a>TypeCheck
A type guard function that checks whether a value conforms to type T, with optional configuration.
T extends TypedValue
TypeCheck(obj): obj is T;
A type guard function that checks whether a value conforms to type T, with optional configuration.
AnyNonPromise
obj is T
TypeCheck(obj, config): obj is T;
A type guard function that checks whether a value conforms to type T, with optional configuration.
AnyNonPromise
obj is T
TypeCheck(obj, config): obj is T;
A type guard function that checks whether a value conforms to type T, with optional configuration.
AnyNonPromise
number | TypeCheckConfig | undefined
obj is T
### <a id="TypeCheckConfig"></a>TypeCheckConfig
Configuration options for type check functions, with optional logging.
optional log?: boolean | Logger;
### <a id="TypeCheckOptionalConfig"></a>TypeCheckOptionalConfig
Type check configuration that marks the value as optional, returning undefined on failure.
optional log?: boolean | Logger;
required: false;
### <a id="TypeCheckRequiredConfig"></a>TypeCheckRequiredConfig
Type check configuration that marks the value as required, causing assertions on failure.
optional log?: boolean | Logger;
required: true;
### <a id="Validator"></a>Validator
Interface for validating objects and returning any errors found.
T extends EmptyObject = AnyObject
validate(payload): Promisable<Error[]>;
T
Promisable<Error[]>
### type-aliases
### <a id="AnyObject"></a>AnyObject
type AnyObject = EmptyObject & Partial<Record<TypedKey, unknown>>;
Any object, which means that it does not enforce the set of fields that it has. Extending from AnyObject will result in a type that includes the universal set of field names
### <a id="AsOptionalTypeFunction"></a>AsOptionalTypeFunction
type AsOptionalTypeFunction<T> = <TType>(value) => TType | undefined;
A simplified type-narrowing function that returns T or undefined, without assertion support.
T extends AnyNonPromise = AnyNonPromise
TType extends T
AnyNonPromise
TType | undefined
### <a id="Compare"></a>Compare
type Compare<T> = (a, b) => number;
A comparator function that returns a negative number if a < b, zero if a == b, and a positive number if a > b.
T
T
T
number
### <a id="DeepOmitStartsWith"></a>DeepOmitStartsWith
type DeepOmitStartsWith<T, Prefix> = T extends infer U[] ? DeepOmitStartsWith<U, Prefix>[] : T extends object ? { [K in keyof T as K extends string ? K extends `${Prefix}${string}` ? never : K : K]: DeepOmitStartsWith<T[K], Prefix> } : T;
Recursively omits keys that start with the given prefix, including in nested objects and arrays.
T
Prefix extends string
### <a id="DeepPickStartsWith"></a>DeepPickStartsWith
type DeepPickStartsWith<T, Prefix> = T extends infer U[] ? DeepPickStartsWith<U, Prefix>[] : T extends object ? { [K in keyof T as K extends string ? K extends `${Prefix}${string}` ? K : never : K]: DeepPickStartsWith<T[K], Prefix> } : T;
Recursively picks only the keys that start with the given prefix, including in nested objects and arrays.
T
Prefix extends string
### <a id="DeepRestrictToJson"></a>DeepRestrictToJson
type DeepRestrictToJson<T> = { [K in keyof T as K extends string ? K : never]: T[K] extends (infer U)[] ? DeepRestrictToJson<U>[] : T[K] extends object ? DeepRestrictToJson<T[K]> : T[K] extends JsonValue ? T[K] : never };
Recursively restricts an object type to only JSON-compatible values, excluding non-serializable types.
T
### <a id="DeepRestrictToStringKeys"></a>DeepRestrictToStringKeys
type DeepRestrictToStringKeys<T> = { [K in keyof T as K extends string ? K : never]: T[K] extends (infer U)[] ? DeepRestrictToStringKeys<U>[] : T[K] extends object ? DeepRestrictToStringKeys<T[K]> : T[K] };
Recursively removes all non-string keys from an object type, including in nested objects and arrays.
T
### <a id="EmptyObject"></a>EmptyObject
type EmptyObject<T> = Exclude<{ [K in keyof T]?: never }, unknown[] | ((...args) => unknown) | null>;
An empty object, which means that it does enforce the set of field names, defaulting to an empty set until extended from, which then adds only those additional fields
T extends object = object
### <a id="JsonArray"></a>JsonArray
type JsonArray = z.infer<typeof JsonArrayZod>;
A JSON array containing JSON values.
### <a id="JsonObject"></a>JsonObject
type JsonObject = z.infer<typeof JsonObjectZod>;
A JSON object with string keys and JSON values.
### <a id="JsonValue"></a>JsonValue
type JsonValue = z.infer<typeof JsonValueZod>;
A recursive JSON value: string, number, boolean, null, array, or object.
### <a id="OmitByPredicate"></a>OmitByPredicate
type OmitByPredicate<T> = (value, key) => boolean;
A predicate function used to determine which properties to omit from an object.
T extends EmptyObject = Record<string, unknown>
T[keyof T]
keyof T
boolean
### <a id="OmitStartsWith"></a>OmitStartsWith
type OmitStartsWith<T, Prefix> = { [K in keyof T as K extends `${Prefix}${string}` ? never : K]: T[K] };
Omits the keys of T that start with the given prefix.
T
Prefix extends string
### <a id="Optional"></a>Optional
type Optional<T, F> = Omit<T, F> & Partial<Pick<T, F>>;
Makes the specified fields of T optional while keeping the rest required.
T extends object
F extends keyof T
### <a id="Override"></a>Override
type Override<T1, T2> = Omit<T1, keyof T2> & T2;
Overrides properties of T1 with those from T2.
T1
T2
### <a id="PartialRecord"></a>PartialRecord
type PartialRecord<K, T> = Partial<Record<K, T>>;
K extends keyof any
T
use Partial<Record<>> instead
### <a id="PickByPredicate"></a>PickByPredicate
type PickByPredicate<T> = (value, key) => boolean;
A predicate function used to determine which properties to pick from an object.
T extends EmptyObject = Record<string, unknown>
T[keyof T]
keyof T
boolean
### <a id="PickStartsWith"></a>PickStartsWith
type PickStartsWith<T, Prefix> = { [K in keyof T as K extends `${Prefix}${string}` ? K : never]: T[K] };
Picks only the keys of T that start with the given prefix.
T
Prefix extends string
### <a id="Simplify"></a>Simplify
type Simplify<T> = { [K in keyof T]: T[K] } & object;
Flattens an intersection or complex mapped type into a single object type for better readability.
T
### <a id="StringKeyObject"></a>StringKeyObject
type StringKeyObject<T> = Record<string, T>;
An object type with string keys and values of type T.
T = unknown
### <a id="StringOrAlertFunction"></a>StringOrAlertFunction
type StringOrAlertFunction<T> = string | AssertExMessageFunc<T>;
A string message or function that produces an assertion error message for a failed type check.
T extends AnyNonPromise
### <a id="WithAdditional"></a>WithAdditional
type WithAdditional<T, TAdditional> = TAdditional extends EmptyObject ? T & TAdditional : T;
Intersects T with TAdditional if TAdditional is an object, otherwise returns T unchanged.
T extends EmptyObject | void
TAdditional extends EmptyObject | void = void
### variables
### <a id="AsObjectFactory"></a>AsObjectFactory
const AsObjectFactory: object;
Factory for creating type-narrowing functions for TypedObject types.
create: <T>(typeCheck) => AsTypeFunction<T>;
T extends TypedObject
TypeCheck<T>
createOptional: <T>(typeCheck) => (value) => T | undefined;
T extends TypedObject
TypeCheck<T>
(value) => T | undefined
### <a id="AsTypeFactory"></a>AsTypeFactory
const AsTypeFactory: object;
Factory for creating type-narrowing 'as' functions that cast a value to T or return undefined. Supports optional assertion messages and configuration for required/optional behavior.
create: <T>(typeCheck) => AsTypeFunction<T>;
T extends AnyNonPromise
TypeCheck<T>
createOptional: <T>(typeCheck) => (value) => T | undefined;
T extends AnyNonPromise
TypeCheck<T>
(value) => T | undefined
### <a id="JsonObjectZod"></a>JsonObjectZod
const JsonObjectZod: ZodRecord<ZodString, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>;
Zod schema for a JSON object with string keys and recursive JSON values.
### <a id="asAnyObject"></a>asAnyObject
const asAnyObject: AsTypeFunction<AnyObject>;
Type-narrowing function that casts a value to AnyObject if it is a plain object, or returns undefined.
### <a id="asJsonArray"></a>asJsonArray
const asJsonArray: {
<T> (value): T & unknown[] | undefined;
<T> (value, assert): T & unknown[];
};
Casts a value to JsonArray or returns undefined if it does not conform.
<T>(value): T & unknown[] | undefined;
T
T
T & unknown[] | undefined
<T>(value, assert): T & unknown[];
T
T
ZodFactoryConfig
T & unknown[]
### <a id="asJsonObject"></a>asJsonObject
const asJsonObject: {
<T> (value): T & Record<string, unknown> | undefined;
<T> (value, assert): T & Record<string, unknown>;
};
Casts a value to JsonObject or returns undefined if it does not conform.
<T>(value): T & Record<string, unknown> | undefined;
T
T
T & Record<string, unknown> | undefined
<T>(value, assert): T & Record<string, unknown>;
T
T
ZodFactoryConfig
T & Record<string, unknown>
### <a id="asJsonValue"></a>asJsonValue
const asJsonValue: {
<T> (value): T | undefined;
<T> (value, assert): T;
};
Casts a value to JsonValue or returns undefined if it does not conform.
<T>(value): T | undefined;
T
T
T | undefined
<T>(value, assert): T;
T
T
ZodFactoryConfig
T
### <a id="deepMerge"></a>deepMerge
const deepMerge: <T>(...objects) => MergeAll<T>;
Deeply merges multiple objects into a new object.
T extends AnyObject[]
...T
Multiple objects to merge deeply. The function merges properties from all objects into a new object. If a property exists in multiple objects, the last object's value will be used. If a property is an object, it will be merged recursively. If a property is an array, it will be overwritten by the last object's value. If a property is a primitive value, it will be overwritten by the last object's value. If a property is undefined in the source, it will be skipped. If a property is a symbol, it will be merged as well.
MergeAll<T>
A new object with the merged properties.
### <a id="isJsonArray"></a>isJsonArray
const isJsonArray: <T>(value) => value is T & unknown[];
Type guard that checks if a value is a valid JSON array.
T
T
value is T & unknown[]
### <a id="isJsonObject"></a>isJsonObject
const isJsonObject: <T>(value) => value is T & Record<string, unknown>;
Type guard that checks if a value is a valid JSON object.
T
T
value is T & Record<string, unknown>
### <a id="isJsonValue"></a>isJsonValue
const isJsonValue: <T>(value) => value is T;
Type guard that checks if a value is a valid JSON value.
T
T
value is T
### <a id="toJsonArray"></a>toJsonArray
const toJsonArray: {
<T> (value): T & unknown[] | undefined;
<T> (value, assert): T & unknown[];
};
Parses a value into a JsonArray, throwing if it does not conform.
<T>(value): T & unknown[] | undefined;
T
T
T & unknown[] | undefined
<T>(value, assert): T & unknown[];
T
T
ZodFactoryConfig
T & unknown[]
### <a id="toJsonObject"></a>toJsonObject
const toJsonObject: {
<T> (value): T & Record<string, unknown> | undefined;
<T> (value, assert): T & Record<string, unknown>;
};
Parses a value into a JsonObject, throwing if it does not conform.
<T>(value): T & Record<string, unknown> | undefined;
T
T
T & Record<string, unknown> | undefined
<T>(value, assert): T & Record<string, unknown>;
T
T
ZodFactoryConfig
T & Record<string, unknown>
### <a id="toJsonValue"></a>toJsonValue
const toJsonValue: {
<T> (value): T | undefined;
<T> (value, assert): T;
};
Parses a value into a JsonValue, throwing if it does not conform.
<T>(value): T | undefined;
T
T
T | undefined
<T>(value, assert): T;
T
T
ZodFactoryConfig
T
FAQs
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
The npm package @xylabs/object receives a total of 1,537 weekly downloads. As such, @xylabs/object popularity was classified as popular.
We found that @xylabs/object demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Malicious Namastex.ai npm packages appear to replicate TeamPCP-style Canister Worm tradecraft, including exfiltration and self-propagation.
Product
Explore exportable charts for vulnerabilities, dependencies, and usage with Reports, Socket’s new extensible reporting framework.
Product
Socket for Jira lets teams turn alerts into Jira tickets with manual creation, automated ticketing rules, and two-way sync.