shelving 1.236.0 → 1.236.2

package/util/object.d.ts

@@ -1,38 +1,113 @@
 import type { ImmutableArray } from "./array.js";
-/** Any readonly object. */
+/**
+ * Any readonly object.
+ *
+ * @see https://dhoulb.github.io/shelving/util/object/ImmutableObject
+ */
 export type ImmutableObject<K extends PropertyKey = PropertyKey, T = unknown> = {
     readonly [KK in K]: T;
 };
-/** Any writable object. */
+/**
+ * Any writable object.
+ *
+ * @see https://dhoulb.github.io/shelving/util/object/MutableObject
+ */
 export type MutableObject<K extends PropertyKey = PropertyKey, T = unknown> = {
     [KK in K]: T;
 };
-/** Prop for an object. */
+/**
+ * Prop for an object, as a readonly key/value entry tuple.
+ *
+ * @see https://dhoulb.github.io/shelving/util/object/Prop
+ */
 export type Prop<T> = readonly [keyof T, T[keyof T]];
-/** Key for an object prop. */
+/**
+ * Key for an object prop.
+ *
+ * @see https://dhoulb.github.io/shelving/util/object/Key
+ */
 export type Key<T> = keyof T;
-/** Value for an object prop. */
+/**
+ * Value for an object prop.
+ *
+ * @see https://dhoulb.github.io/shelving/util/object/Value
+ */
 export type Value<T> = T[keyof T];
-/** Something that can be converted to an object. */
+/**
+ * Something that can be converted to an object.
+ * - Either the object itself, or an iterable set of key/value entry tuples.
+ *
+ * @see https://dhoulb.github.io/shelving/util/object/PossibleObject
+ */
 export type PossibleObject<T> = T | Iterable<Prop<T>>;
-/** Is an unknown value an unknown object? */
+/**
+ * Is an unknown value an unknown object?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a non-null `object`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/object/isObject
+ */
 export declare function isObject(value: unknown): value is ImmutableObject;
-/** Assert that a value is an object */
+/**
+ * Assert that a value is an object.
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is not an `object`.
+ * @see https://dhoulb.github.io/shelving/util/object/assertObject
+ */
 export declare function assertObject(value: unknown): asserts value is ImmutableObject;
-/** Is an unknown value a plain object? */
+/**
+ * Is an unknown value a plain object?
+ * - A plain object is one whose prototype is `Object.prototype` or `null` (i.e. not a class instance).
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a plain object, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/object/isPlainObject
+ */
 export declare function isPlainObject(value: unknown): value is ImmutableObject;
-/** Assert that an unknown value is a plain object */
+/**
+ * Assert that an unknown value is a plain object.
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is not a plain object.
+ * @see https://dhoulb.github.io/shelving/util/object/assertPlainObject
+ */
 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. */
+/**
+ * Is an unknown value the key for an own prop of an object.
+ *
+ * @param obj The object to test against.
+ * @param key The key to test for.
+ * @returns `true` if `key` is an own prop of `obj`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/object/isProp
+ */
+export declare function 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.
+ *
+ * @param obj The object to assert against.
+ * @param key The key to assert is an own prop.
+ * @throws {RequiredError} If `key` is not an own prop of `obj`.
+ * @see https://dhoulb.github.io/shelving/util/object/assertProp
+ */
 export declare function assertProp<T extends ImmutableObject>(obj: T, key: PropertyKey): asserts key is keyof T;
-/** Turn a possible object into an object. */
+/**
+ * Turn a possible object into an object.
+ * - If the value is iterable it is converted to an object using `Object.fromEntries()`, otherwise it is returned as-is.
+ *
+ * @param obj The object or iterable set of key/value entry tuples to convert.
+ * @returns The corresponding object.
+ * @example
+ * getObject([["a", 1], ["b", 2]]); // { a: 1, b: 2 }
+ * @see https://dhoulb.github.io/shelving/util/object/getObject
+ */
 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>`
+ *
+ * @see https://dhoulb.github.io/shelving/util/object/Mutable
  */
 export type Mutable<T> = {
     -readonly [K in keyof T]: T[K];
@@ -41,6 +116,8 @@ export type Mutable<T> = {
  * 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.
+ *
+ * @see https://dhoulb.github.io/shelving/util/object/DeepPartial
  */
 export type DeepPartial<T> = {
     [K in keyof T]?: DeepPartial<T[K]>;
@@ -49,6 +126,8 @@ export type DeepPartial<T> = {
  * 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.
+ *
+ * @see https://dhoulb.github.io/shelving/util/object/DeepMutable
  */
 export type DeepMutable<T> = {
     -readonly [K in keyof T]: DeepMutable<T[K]>;
@@ -57,59 +136,212 @@ export type DeepMutable<T> = {
  * 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.
+ *
+ * @see https://dhoulb.github.io/shelving/util/object/DeepReadonly
  */
 export type DeepReadonly<T> = {
     +readonly [K in keyof T]: DeepReadonly<T[K]>;
 };
-/** Pick only the properties of an object that match a type. */
+/**
+ * Pick only the properties of an object that match a type.
+ *
+ * @see https://dhoulb.github.io/shelving/util/object/PickProps
+ */
 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. */
+/**
+ * Omit the properties of an object that match a type.
+ *
+ * @see https://dhoulb.github.io/shelving/util/object/OmitProps
+ */
 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. */
+/**
+ * Get the props of an object as a set of entries.
+ *
+ * @param obj The object to read the props from.
+ * @returns Iterable set of key/value entry tuples for the object.
+ * @example
+ * getProps({ a: 1, b: 2 }); // [["a", 1], ["b", 2]]
+ * @see https://dhoulb.github.io/shelving/util/object/getProps
+ */
 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. */
+/**
+ * Get the keys of an object as an array.
+ *
+ * @param obj The object to read the keys from.
+ * @returns Iterable set of keys for the object.
+ * @example
+ * getKeys({ a: 1, b: 2 }); // ["a", "b"]
+ * @see https://dhoulb.github.io/shelving/util/object/getKeys
+ */
 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. */
+/**
+ * Extract the value of a named prop from an object.
+ *
+ * @param obj The object to read the prop from.
+ * @param key The key of the prop to read.
+ * @returns The value of the named prop.
+ * @example
+ * getProp({ a: 1, b: 2 }, "a"); // 1
+ * @see https://dhoulb.github.io/shelving/util/object/getProp
+ */
 export declare function getProp<T, K extends Key<T>>(obj: T, key: K): T[K];
-/** Create an object from a single prop. */
+/**
+ * Create an object from a single prop.
+ *
+ * @param key The key of the prop to set.
+ * @param value The value of the prop to set.
+ * @returns A new object containing only the single prop.
+ * @example
+ * fromProp("a", 1); // { a: 1 }
+ * @see https://dhoulb.github.io/shelving/util/object/fromProp
+ */
 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. */
+/**
+ * Set a prop on an object (immutably) and return a new object including that prop.
+ * - If the value is unchanged the original object is returned unchanged.
+ *
+ * @param input The object to set the prop on.
+ * @param key The key of the prop to set.
+ * @param value The value of the prop to set.
+ * @returns A new object including the set prop, or the original object if the value was unchanged.
+ * @example
+ * withProp({ a: 1 }, "b", 2); // { a: 1, b: 2 }
+ * @see https://dhoulb.github.io/shelving/util/object/withProp
+ */
 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. */
+/**
+ * Set several props on an object (immutably) and return a new object including those props.
+ * - If all values are unchanged the original object is returned unchanged.
+ *
+ * @param input The object to set the props on.
+ * @param props The props to set, as an object or iterable set of key/value entry tuples.
+ * @returns A new object including the set props, or the original object if all values were unchanged.
+ * @example
+ * withProps({ a: 1 }, { b: 2, c: 3 }); // { a: 1, b: 2, c: 3 }
+ * @see https://dhoulb.github.io/shelving/util/object/withProps
+ */
 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. */
+/**
+ * Remove several props from an object (immutably) and return a new object without those props.
+ * - If none of the keys exist the original object is returned unchanged.
+ *
+ * @param input The object to remove the props from.
+ * @param keys The keys of the props to remove.
+ * @returns A new object without the removed props, or the original object if no keys were present.
+ * @example
+ * omitProps({ a: 1, b: 2, c: 3 }, "b", "c"); // { a: 1 }
+ * @see https://dhoulb.github.io/shelving/util/object/omitProps
+ */
 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. */
+/**
+ * Remove a prop from an object (immutably) and return a new object without that prop.
+ * - If the key doesn't exist the original object is returned unchanged.
+ *
+ * @param input The object to remove the prop from.
+ * @param key The key of the prop to remove.
+ * @returns A new object without the removed prop, or the original object if the key was not present.
+ * @example
+ * omitProp({ a: 1, b: 2 }, "b"); // { a: 1 }
+ * @see https://dhoulb.github.io/shelving/util/object/omitProp
+ */
 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. */
+/**
+ * Pick several props from an object and return a new object with only those props.
+ *
+ * @param obj The object to pick the props from.
+ * @param keys The keys of the props to pick.
+ * @returns A new object containing only the picked props.
+ * @example
+ * pickProps({ a: 1, b: 2, c: 3 }, "a", "b"); // { a: 1, b: 2 }
+ * @see https://dhoulb.github.io/shelving/util/object/pickProps
+ */
 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. */
+/**
+ * Set a single named prop on an object (by reference) and return its value.
+ *
+ * @param obj The object to set the prop on (modified by reference).
+ * @param key The key of the prop to set.
+ * @param value The value of the prop to set.
+ * @returns The value that was set.
+ * @example
+ * setProp(obj, "a", 1); // 1
+ * @see https://dhoulb.github.io/shelving/util/object/setProp
+ */
 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). */
+/**
+ * Set several named props on an object (by reference).
+ *
+ * @param obj The object to set the props on (modified by reference).
+ * @param entries The props to set, as an object or iterable set of key/value entry tuples.
+ * @example
+ * setProps(obj, { a: 1, b: 2 });
+ * @see https://dhoulb.github.io/shelving/util/object/setProps
+ */
 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). */
+/**
+ * Remove several key/value entries from an object (by reference).
+ *
+ * @param obj The object to remove the props from (modified by reference).
+ * @param keys The keys of the props to remove.
+ * @example
+ * deleteProps(obj, "a", "b");
+ * @see https://dhoulb.github.io/shelving/util/object/deleteProps
+ */
 export declare function deleteProps<T extends MutableObject>(obj: T, ...keys: Key<T>[]): void;
-/** Remove a key/value entry from an object (by reference). */
+/**
+ * Remove a key/value entry from an object (by reference).
+ *
+ * @param input The object to remove the prop from (modified by reference).
+ * @param key The key of the prop to remove.
+ * @example
+ * deleteProp(obj, "a");
+ * @see https://dhoulb.github.io/shelving/util/object/deleteProp
+ */
 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`.
+ *
+ * @param obj The object to read the prototype from.
+ * @returns The prototype of the object, or `null` if it has none.
+ * @example
+ * getPrototype({ a: 1 }); // Object.prototype
+ * @see https://dhoulb.github.io/shelving/util/object/getPrototype
  */
 export declare function getPrototype<T>(obj: T): Partial<T> | null;
-/** Shallow clone an object with the same prototype. */
+/**
+ * Shallow clone an object with the same prototype.
+ *
+ * @param input The object to clone.
+ * @returns A new object with the same prototype and props as `input`.
+ * @example
+ * cloneObject({ a: 1 }); // { a: 1 }
+ * @see https://dhoulb.github.io/shelving/util/object/cloneObject
+ */
 export declare function cloneObject<T>(input: T): T;
-/** Shallow clone an object with a single changed value. */
+/**
+ * Shallow clone an object with a single changed value.
+ * - If the value is unchanged the original object is returned unchanged.
+ *
+ * @param input The object to clone.
+ * @param key The key of the prop to change.
+ * @param value The value of the prop to change.
+ * @returns A new object with the changed prop, or the original object if the value was unchanged.
+ * @example
+ * cloneObjectWith({ a: 1 }, "a", 2); // { a: 2 }
+ * @see https://dhoulb.github.io/shelving/util/object/cloneObjectWith
+ */
 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;

package/util/object.js

@@ -1,15 +1,34 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { isIterable } from "./iterate.js";
-/** Is an unknown value an unknown object? */
+/**
+ * Is an unknown value an unknown object?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a non-null `object`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/object/isObject
+ */
 export function isObject(value) {
     return typeof value === "object" && value !== null;
 }
-/** Assert that a value is an object */
+/**
+ * Assert that a value is an object.
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is not an `object`.
+ * @see https://dhoulb.github.io/shelving/util/object/assertObject
+ */
 export function assertObject(value) {
     if (!isObject(value))
         throw new RequiredError("Must be object", { received: value, caller: assertObject });
 }
-/** Is an unknown value a plain object? */
+/**
+ * Is an unknown value a plain object?
+ * - A plain object is one whose prototype is `Object.prototype` or `null` (i.e. not a class instance).
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a plain object, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/object/isPlainObject
+ */
 export function isPlainObject(value) {
     if (isObject(value)) {
         const proto = getPrototype(value);
@@ -17,19 +36,50 @@ export function isPlainObject(value) {
     }
     return false;
 }
-/** Assert that an unknown value is a plain object */
+/**
+ * Assert that an unknown value is a plain object.
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is not a plain object.
+ * @see https://dhoulb.github.io/shelving/util/object/assertPlainObject
+ */
 export function assertPlainObject(value) {
     if (!isPlainObject(value))
         throw new RequiredError("Must be plain object", { received: value, caller: assertPlainObject });
 }
-/** Is an unknown value the key for an own prop of an object. */
-export const isProp = (obj, key) => Object.hasOwn(obj, key);
-/** Assert that an unknown value is the key for an own prop of an object. */
+/**
+ * Is an unknown value the key for an own prop of an object.
+ *
+ * @param obj The object to test against.
+ * @param key The key to test for.
+ * @returns `true` if `key` is an own prop of `obj`, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/object/isProp
+ */
+export function isProp(obj, key) {
+    return Object.hasOwn(obj, key);
+}
+/**
+ * Assert that an unknown value is the key for an own prop of an object.
+ *
+ * @param obj The object to assert against.
+ * @param key The key to assert is an own prop.
+ * @throws {RequiredError} If `key` is not an own prop of `obj`.
+ * @see https://dhoulb.github.io/shelving/util/object/assertProp
+ */
 export function assertProp(obj, key) {
     if (!isProp(obj, key))
         throw new RequiredError("Key must exist in object", { key, obj, caller: assertProp });
 }
-/** Turn a possible object into an object. */
+/**
+ * Turn a possible object into an object.
+ * - If the value is iterable it is converted to an object using `Object.fromEntries()`, otherwise it is returned as-is.
+ *
+ * @param obj The object or iterable set of key/value entry tuples to convert.
+ * @returns The corresponding object.
+ * @example
+ * getObject([["a", 1], ["b", 2]]); // { a: 1, b: 2 }
+ * @see https://dhoulb.github.io/shelving/util/object/getObject
+ */
 export function getObject(obj) {
     return isIterable(obj) ? Object.fromEntries(obj) : obj;
 }
@@ -39,15 +89,44 @@ export function getProps(obj) {
 export function getKeys(obj) {
     return isIterable(obj) ? obj : Object.keys(obj);
 }
-/** Extract the value of a named prop from an object. */
+/**
+ * Extract the value of a named prop from an object.
+ *
+ * @param obj The object to read the prop from.
+ * @param key The key of the prop to read.
+ * @returns The value of the named prop.
+ * @example
+ * getProp({ a: 1, b: 2 }, "a"); // 1
+ * @see https://dhoulb.github.io/shelving/util/object/getProp
+ */
 export function getProp(obj, key) {
     return obj[key];
 }
-/** Create an object from a single prop. */
+/**
+ * Create an object from a single prop.
+ *
+ * @param key The key of the prop to set.
+ * @param value The value of the prop to set.
+ * @returns A new object containing only the single prop.
+ * @example
+ * fromProp("a", 1); // { a: 1 }
+ * @see https://dhoulb.github.io/shelving/util/object/fromProp
+ */
 export function fromProp(key, value) {
     return { [key]: value };
 }
-/** Set a prop on an object (immutably) and return a new object including that prop. */
+/**
+ * Set a prop on an object (immutably) and return a new object including that prop.
+ * - If the value is unchanged the original object is returned unchanged.
+ *
+ * @param input The object to set the prop on.
+ * @param key The key of the prop to set.
+ * @param value The value of the prop to set.
+ * @returns A new object including the set prop, or the original object if the value was unchanged.
+ * @example
+ * withProp({ a: 1 }, "b", 2); // { a: 1, b: 2 }
+ * @see https://dhoulb.github.io/shelving/util/object/withProp
+ */
 export function withProp(input, key, value) {
     return input[key] === value ? input : { __proto__: getPrototype(input), ...input, [key]: value };
 }
@@ -68,7 +147,17 @@ export function omitProps(input, ...keys) {
 function _hasntKey([key]) {
     return !this.includes(key);
 }
-/** Remove a prop from an object (immutably) and return a new object without that prop. */
+/**
+ * Remove a prop from an object (immutably) and return a new object without that prop.
+ * - If the key doesn't exist the original object is returned unchanged.
+ *
+ * @param input The object to remove the prop from.
+ * @param key The key of the prop to remove.
+ * @returns A new object without the removed prop, or the original object if the key was not present.
+ * @example
+ * omitProp({ a: 1, b: 2 }, "b"); // { a: 1 }
+ * @see https://dhoulb.github.io/shelving/util/object/omitProp
+ */
 export const omitProp = omitProps;
 export function pickProps(input, ...keys) {
     return Object.fromEntries(Object.entries(input).filter(_hasKey, keys));
@@ -76,31 +165,79 @@ export function pickProps(input, ...keys) {
 function _hasKey([key]) {
     return this.includes(key);
 }
-/** Set a single named prop on an object (by reference) and return its value. */
+/**
+ * Set a single named prop on an object (by reference) and return its value.
+ *
+ * @param obj The object to set the prop on (modified by reference).
+ * @param key The key of the prop to set.
+ * @param value The value of the prop to set.
+ * @returns The value that was set.
+ * @example
+ * setProp(obj, "a", 1); // 1
+ * @see https://dhoulb.github.io/shelving/util/object/setProp
+ */
 export function setProp(obj, key, value) {
     obj[key] = value;
     return value;
 }
-/** Set several named props on an object (by reference). */
+/**
+ * Set several named props on an object (by reference).
+ *
+ * @param obj The object to set the props on (modified by reference).
+ * @param entries The props to set, as an object or iterable set of key/value entry tuples.
+ * @example
+ * setProps(obj, { a: 1, b: 2 });
+ * @see https://dhoulb.github.io/shelving/util/object/setProps
+ */
 export function setProps(obj, entries) {
     for (const [k, v] of getProps(entries))
         obj[k] = v;
 }
-/** Remove several key/value entries from an object (by reference). */
+/**
+ * Remove several key/value entries from an object (by reference).
+ *
+ * @param obj The object to remove the props from (modified by reference).
+ * @param keys The keys of the props to remove.
+ * @example
+ * deleteProps(obj, "a", "b");
+ * @see https://dhoulb.github.io/shelving/util/object/deleteProps
+ */
 export function deleteProps(obj, ...keys) {
     for (const key of keys)
         delete obj[key];
 }
-/** Remove a key/value entry from an object (by reference). */
+/**
+ * Remove a key/value entry from an object (by reference).
+ *
+ * @param input The object to remove the prop from (modified by reference).
+ * @param key The key of the prop to remove.
+ * @example
+ * deleteProp(obj, "a");
+ * @see https://dhoulb.github.io/shelving/util/object/deleteProp
+ */
 export const deleteProp = deleteProps;
 /**
  * Get the prototype of an object instance.
  * - Recommend to use this because Typescript's default lib specifies `Object.getPrototypeOf()` returning `any`.
+ *
+ * @param obj The object to read the prototype from.
+ * @returns The prototype of the object, or `null` if it has none.
+ * @example
+ * getPrototype({ a: 1 }); // Object.prototype
+ * @see https://dhoulb.github.io/shelving/util/object/getPrototype
  */
 export function getPrototype(obj) {
     return Object.getPrototypeOf(obj);
 }
-/** Shallow clone an object with the same prototype. */
+/**
+ * Shallow clone an object with the same prototype.
+ *
+ * @param input The object to clone.
+ * @returns A new object with the same prototype and props as `input`.
+ * @example
+ * cloneObject({ a: 1 }); // { a: 1 }
+ * @see https://dhoulb.github.io/shelving/util/object/cloneObject
+ */
 export function cloneObject(input) {
     return { __proto__: getPrototype(input), ...input };
 }