shelving/util/object.d.ts

Toolkit for using data in JavaScript.

import type { ImmutableArray } from "./array.js";
/** Any readonly object. */
export type ImmutableObject<K extends PropertyKey = PropertyKey, T = unknown> = {
    readonly [KK in K]: T;
};
/** Any writable object. */
export type MutableObject<K extends PropertyKey = PropertyKey, T = unknown> = {
    [KK in K]: T;
};
/** Prop for an object. */
export type Prop<T> = readonly [keyof T, T[keyof T]];
/** Key for an object prop. */
export type Key<T> = keyof T;
/** Value for an object prop. */
export type Value<T> = T[keyof T];
/** Something that can be converted to an object. */
export type PossibleObject<T> = T | Iterable<Prop<T>>;
/** Is an unknown value an unknown object? */
export declare function isObject(value: unknown): value is ImmutableObject;
/** Assert that a value is an object */
export declare function assertObject(value: unknown): asserts value is ImmutableObject;
/** Is an unknown value a plain object? */
export declare function isPlainObject(value: unknown): value is ImmutableObject;
/** Assert that an unknown value is a plain object */
export declare function assertPlainObject(value: unknown): asserts value is ImmutableObject;
/** Is an unknown value the key for an own prop of an object. */
export declare const isProp: <T extends ImmutableObject>(obj: T, key: PropertyKey) => key is keyof T;
/** Assert that an unknown value is the key for an own prop of an object. */
export declare function assertProp<T extends ImmutableObject>(obj: T, key: PropertyKey): asserts key is keyof T;
/** Turn a possible object into an object. */
export declare function getObject<T extends ImmutableObject>(obj: PossibleObject<T>): T;
/**
 * Mutable type is the opposite of `Readonly<T>` helper type.
 * - See https://github.com/microsoft/TypeScript/issues/24509
 * - Consistency with `Readonly<T>`
 */
export type Mutable<T> = {
    -readonly [K in keyof T]: T[K];
};
/**
 * Deep partial object: deeply convert an object to its partial version.
 * - Any value that extends `UnknownObject` has its props made partial.
 * - Works deeply on nested objects too.
 */
export type DeepPartial<T> = {
    [K in keyof T]?: DeepPartial<T[K]>;
};
/**
 * Deep mutable object: deeply convert an object to its mutable version.
 * - Any value that extends `UnknownObject` has its props made mutable.
 * - Works deeply on nested objects too.
 */
export type DeepMutable<T> = {
    -readonly [K in keyof T]: DeepMutable<T[K]>;
};
/**
 * Deep readonly object: deeply convert an object to its readonly version.
 * - Any value that extends `UnknownObject` has its props made readonly.
 * - Works deeply on nested objects too.
 */
export type DeepReadonly<T> = {
    +readonly [K in keyof T]: DeepReadonly<T[K]>;
};
/** Pick only the properties of an object that match a type. */
export type PickProps<T, TT> = Pick<T, {
    [K in keyof T]: T[K] extends TT ? K : never;
}[keyof T]>;
/** Omit the properties of an object that match a type. */
export type OmitProps<T, TT> = Omit<T, {
    [K in keyof T]: T[K] extends TT ? K : never;
}[keyof T]>;
/** Get the props of an object as a set of entries. */
export declare function getProps<T>(obj: T): ImmutableArray<Prop<T>>;
export declare function getProps<T>(obj: T | Partial<T>): ImmutableArray<Prop<T>>;
export declare function getProps<T>(obj: T | Partial<T> | Iterable<Prop<T>>): Iterable<Prop<T>>;
/** Get the keys of an object as an array. */
export declare function getKeys<T>(obj: T): ImmutableArray<Key<T>>;
export declare function getKeys<T>(obj: T | Partial<T>): ImmutableArray<Key<T>>;
export declare function getKeys<T>(obj: T | Partial<T> | Iterable<Key<T>>): Iterable<Key<T>>;
/** Extract the value of a named prop from an object. */
export declare function getProp<T, K extends Key<T>>(obj: T, key: K): T[K];
/** Create an object from a single prop. */
export declare function fromProp<K extends PropertyKey, V>(key: K, value: V): {
    readonly [KK in K]: V;
};
/** Set a prop on an object (immutably) and return a new object including that prop. */
export declare function withProp<T extends ImmutableObject, K extends Key<T>>(input: T, key: K, value: T[K]): T;
/** Set several props on an object (immutably) and return a new object including those props. */
export declare function withProps<T>(input: T, props: Partial<T>): T;
export declare function withProps<T>(input: T, props: T | Partial<T> | Iterable<Prop<T>>): T;
/** Remove several props from an object (immutably) and return a new object without those props. */
export declare function omitProps<T, K extends Key<T>>(input: T, ...keys: K[]): Omit<T, K>;
/** Remove a prop from an object (immutably) and return a new object without that prop. */
export declare const omitProp: <T, K extends Key<T>>(input: T, key: K) => Omit<T, K>;
/** Pick several props from an object and return a new object with only thos props. */
export declare function pickProps<T, K extends Key<T>>(obj: T, ...keys: K[]): Pick<T, K>;
/** Set a single named prop on an object (by reference) and return its value. */
export declare function setProp<T extends MutableObject, K extends Key<T>>(obj: T, key: K, value: T[K]): T[K];
/** Set several named props on an object (by reference). */
export declare function setProps<T extends MutableObject>(obj: T, entries: T | Partial<T> | Iterable<Prop<T>>): void;
/** Remove several key/value entries from an object (by reference). */
export declare function deleteProps<T extends MutableObject>(obj: T, ...keys: Key<T>[]): void;
/** Remove a key/value entry from an object (by reference). */
export declare const deleteProp: <T extends MutableObject>(input: T, key: Key<T>) => void;
/**
 * Get the prototype of an object instance.
 * - Recommend to use this because Typescript's default lib specifies `Object.getPrototypeOf()` returning `any`.
 */
export declare function getPrototype<T>(obj: T): Partial<T> | null;
/** Shallow clone an object with the same prototype. */
export declare function cloneObject<T>(input: T): T;
/** Shallow clone an object with a single changed value. */
export declare function cloneObjectWith<T, K extends Key<T>>(input: T, key: K, value: T[K]): T;
export declare function cloneObjectWith<T, K extends string, V>(input: T, key: K, value: V): T & {
    [KK in K]: V;
};