shelving 1.78.0 → 1.80.1

package/util/object.d.ts

@@ -1,5 +1,6 @@
 import type { ImmutableArray } from "./array.js";
-import type { NotString } from "./string.js";
+import type { Data, Prop } from "./data.js";
+import type { Entry } from "./entry.js";
 /** Readonly object with string keys. */
 export declare type ImmutableObject<T = unknown> = {
     readonly [key: string | number]: T;
@@ -8,8 +9,6 @@ export declare type ImmutableObject<T = unknown> = {
 export declare type MutableObject<T = unknown> = {
     [key: string | number]: T;
 };
-/** Extract the type for the values of an object. */
-export declare type ObjectType<T extends ImmutableObject> = T[keyof T];
 /**
  * Is a value an unknown object?
  * - This is a TypeScript assertion object that asserts the value extends `ImmutableObject`
@@ -23,75 +22,84 @@ export declare function isPlainObject<T extends ImmutableObject>(value: T | unkn
 /** Assert that a value is a plain object */
 export declare function assertPlainObject<T extends ImmutableObject>(value: T | unknown): asserts value is T;
 /** Is an unknown string an own prop of an object. */
-export declare const isEntry: <T extends ImmutableObject<unknown>>(obj: T, key: unknown) => key is keyof T;
+export declare const isProp: <T extends ImmutableObject<unknown>>(obj: T, key: unknown) => key is keyof T;
+/** Turn a data object into an array of props. */
+export declare function getProps<T extends Data>(data: T): ImmutableArray<Prop<T>>;
+export declare function getProps<T extends Data>(data: T | Partial<T>): ImmutableArray<Prop<T>>;
+export declare function getProps<T extends ImmutableObject>(data: T): ImmutableArray<Entry<keyof T, T[keyof T]>>;
+export declare function getProps<T extends ImmutableObject>(data: T | Partial<T>): ImmutableArray<Entry<keyof T, T[keyof T]>>;
 /**
- * Add a key/value entry to a map-like object (immutably).
+ * Extract the value of a named prop from a data object.
+ * - Extraction is possibly deep if deeper keys are specified.
  *
- * @param input The input object.
+ * @param obj The target object to get from.
+ * @param k1 The key of the prop in the object to get.
+ * @param k2 The sub-key of the prop in the object to get.
+ * @param k3 The sub-sub-key of the prop in the object to get.
+ * @param k4 The sub-sub-sub-key of the prop in the object to get.
+ */
+export declare function getProp<T extends ImmutableObject, K1 extends keyof T, K2 extends keyof T[K1], K3 extends keyof T[K1][K2], K4 extends keyof T[K1][K2][K3]>(obj: T, k1: K1, k2: K2, k3: K3, k4: K4): T[K1][K2][K3][K4];
+export declare function getProp<T extends ImmutableObject, K1 extends keyof T, K2 extends keyof T[K1], K3 extends keyof T[K1][K2]>(obj: T, k1: K1, k2: K2, k3: K3): T[K1][K2][K3];
+export declare function getProp<T extends ImmutableObject, K1 extends keyof T, K2 extends keyof T[K1]>(obj: T, k1: K1, k2: K2): T[K1][K2];
+export declare function getProp<T extends ImmutableObject, K1 extends keyof T>(obj: T, k1: K1): T[K1];
+/**
+ * Set a prop on an object (immutably).
+ *
+ * @param input The input data object.
  * @param key The key of the entry to add.
  * @param value The value of the entry to add. If set, the entry will only be added if its current value is not `value`
  *
- * @return New object without the specified entry (or same object if entry value didn't change).
+ * @return New object without the specified prop (or same object if prop value didn't change).
  */
-export declare const withEntry: <T>(input: ImmutableObject<T>, key: string, value: T) => ImmutableObject<T>;
+export declare function withProp<T extends ImmutableObject, K extends keyof T>(input: T, key: K, value: T[K]): T;
 /**
- * Add several key/value entries on a map-like object (immutably).
+ * Set several props on an object (immutably).
  *
- * @param input The input object.
- * @return New object with the specified entries added (or same object if no entries changed).
+ * @param input The input data object.
+ * @param props Set of props to add to the object.
+ * @return New object with the specified prop added (or same object if no props changed).
  */
-export declare const withEntries: <T>(input: ImmutableObject<T>, entries: ImmutableObject<T>) => ImmutableObject<T>;
+export declare function withProps<T extends ImmutableObject>(input: T, props: T | Partial<T>): T;
 /**
- * Remove a key/value entry from a map-like object (immutably).
+ * Remove several key/value entries from an object (immutably).
  *
  * @param input The input object.
- * @param key The key of the entry to remove.
- * @param value The value of the entry to remove. If not undefined, the entry will only be removed if its current value is exactly `value`
+ * @param keys Set of keys for props to remove.
  *
- * @return New object without the specified entries (or same object if the entry didn't exist).
- * - If `key` doesn't already exist in `obj` then the exact same input object will be returned.
+ * @return New object without the specified entries (or same object if none of the entries existed).
  */
-export declare function withoutEntry<T>(input: ImmutableObject<T>, key: string, value?: T): ImmutableObject<T>;
+export declare function withoutProps<T extends ImmutableObject, K extends keyof T>(input: T, ...keys: K[]): Omit<T, K>;
 /**
- * Remove several key/value entries from a map-like object (immutably).
+ * Pick several props from an object (immutably).
  *
  * @param input The input object.
- * @param keys Set of keys or entries to remove.
+ * @param keys Set of keys for props to pick.
  *
- * @return New object without the specified entries (or same object if none of the entries existed).
- * - If every entry already exists and has the exact same input object will be returned.
+ * @return New object with only the specified props.
  */
-export declare function withoutEntries<T>(input: ImmutableObject<T>, keys: Iterable<string> & NotString): ImmutableObject<T>;
+export declare function pickProps<T extends ImmutableObject, K extends keyof T>(input: T, ...keys: (keyof T)[]): Pick<T, K>;
 /**
- * Set a key/value entry on a map-like object (by reference).
+ * Set a single named prop on an object (by reference).
  *
- * @param obj The target object to modify.
+ * @param data The target data object to modify.
  * @param key The key of the prop in the object to set.
  * @param value The value to set the prop to.
  */
-export declare const setEntry: <T>(obj: MutableObject<T>, key: string, value: T) => T;
-/**
- * Set several key/value entries on a map-like object (by reference).
- *
- * @param obj The target object to modify.
- * @param entries An object containing new props to set on the object.
- */
-export declare const setEntries: <T>(obj: MutableObject<T>, entries: ImmutableObject<T>) => void;
+export declare function setProp<T extends MutableObject, K extends keyof T>(data: T, key: K, value: T[K]): T[K];
 /**
- * Remove a key/value entry from a map-like object (by reference).
+ * Set several named props on an object (by reference).
  *
  * @param obj The target object to modify.
- * @param key The key of the entry to remove.
- * @param value The value of the entry to remove. If set, the entry will only be removed if its current value is exactly `value`
+ * @param props An object containing new props to set on the object.
  */
-export declare function deleteEntry<T>(obj: MutableObject<T>, key: string, value?: T): void;
+export declare function setProps<T extends MutableObject>(obj: T, props: Partial<T>): void;
 /**
- * Remove several key/value entries from a map-like object (by reference).
+ * Remove several key/value entries from an object (by reference).
  *
  * @param obj The target object to modify.
- * @param entries Set of keys or entries to remove.
+ * @param keys Set of keys or keys to remove.
  */
-export declare function deleteEntries<T>(obj: MutableObject<T>, keys: ImmutableArray<string>): void;
+export declare function deleteProps<T extends MutableObject>(obj: T, ...keys: (keyof T)[]): void;
 /** Type that represents an empty object. */
 export declare type EmptyObject = {
     readonly [K in never]: never;
@@ -99,4 +107,4 @@ export declare type EmptyObject = {
 /** An empty object. */
 export declare const EMPTY_OBJECT: EmptyObject;
 /** Function that returns an an empty object. */
-export declare const GET_EMPTY_OBJECT: () => EmptyObject;
+export declare const getEmptyObject: () => EmptyObject;

package/util/object.js

@@ -1,5 +1,4 @@
 import { AssertionError } from "../error/AssertionError.js";
-import { setProp, setProps, withProp, withProps } from "./data.js";
 /**
  * Is a value an unknown object?
  * - This is a TypeScript assertion object that asserts the value extends `ImmutableObject`
@@ -25,97 +24,101 @@ export function assertPlainObject(value) {
         throw new AssertionError(`Must be plain object`, value);
 }
 /** Is an unknown string an own prop of an object. */
-export const isEntry = (obj, key) => (typeof key === "string" || typeof key === "number" || typeof key === "symbol") && Object.prototype.hasOwnProperty.call(obj, key);
+export const isProp = (obj, key) => (typeof key === "string" || typeof key === "number" || typeof key === "symbol") && Object.prototype.hasOwnProperty.call(obj, key);
+export function getProps(data) {
+    return Object.entries(data);
+}
+export function getProp(data, k1, k2, k3, k4) {
+    return k2 === undefined ? data[k1] : k3 === undefined ? data[k1][k2] : k4 === undefined ? data[k1][k2][k3] : data[k1][k2][k3][k4];
+}
 /**
- * Add a key/value entry to a map-like object (immutably).
+ * Set a prop on an object (immutably).
  *
- * @param input The input object.
+ * @param input The input data object.
  * @param key The key of the entry to add.
  * @param value The value of the entry to add. If set, the entry will only be added if its current value is not `value`
  *
- * @return New object without the specified entry (or same object if entry value didn't change).
+ * @return New object without the specified prop (or same object if prop value didn't change).
  */
-export const withEntry = withProp;
+export function withProp(input, key, value) {
+    return input[key] === value ? input : { ...input, [key]: value };
+}
 /**
- * Add several key/value entries on a map-like object (immutably).
+ * Set several props on an object (immutably).
  *
- * @param input The input object.
- * @return New object with the specified entries added (or same object if no entries changed).
+ * @param input The input data object.
+ * @param props Set of props to add to the object.
+ * @return New object with the specified prop added (or same object if no props changed).
  */
-export const withEntries = withProps;
+export function withProps(input, props) {
+    for (const [k, v] of Object.entries(props))
+        if (input[k] !== v)
+            return { ...input, ...props };
+    return input;
+}
 /**
- * Remove a key/value entry from a map-like object (immutably).
+ * Remove several key/value entries from an object (immutably).
  *
  * @param input The input object.
- * @param key The key of the entry to remove.
- * @param value The value of the entry to remove. If not undefined, the entry will only be removed if its current value is exactly `value`
+ * @param keys Set of keys for props to remove.
  *
- * @return New object without the specified entries (or same object if the entry didn't exist).
- * - If `key` doesn't already exist in `obj` then the exact same input object will be returned.
+ * @return New object without the specified entries (or same object if none of the entries existed).
  */
-export function withoutEntry(input, key, value) {
-    if (isEntry(input, key) && (value === undefined || input[key] === value)) {
-        const { [key]: unused, ...output } = input;
-        return output;
-    }
+export function withoutProps(input, ...keys) {
+    for (const key of keys)
+        if (key in input)
+            return Object.fromEntries(Object.entries(input).filter(_doesntHaveKey, keys));
     return input;
 }
+function _doesntHaveKey([key]) {
+    return !this.includes(key);
+}
 /**
- * Remove several key/value entries from a map-like object (immutably).
+ * Pick several props from an object (immutably).
  *
  * @param input The input object.
- * @param keys Set of keys or entries to remove.
+ * @param keys Set of keys for props to pick.
  *
- * @return New object without the specified entries (or same object if none of the entries existed).
- * - If every entry already exists and has the exact same input object will be returned.
+ * @return New object with only the specified props.
  */
-export function withoutEntries(input, keys) {
-    let changed = false;
-    const output = { ...input };
-    for (const key of keys)
-        if (isEntry(input, key)) {
-            delete output[key];
-            changed = true;
-        }
-    return changed ? output : input;
+export function pickProps(input, ...keys) {
+    return Object.fromEntries(Object.entries(input).filter(_doesHaveKey, keys));
+}
+function _doesHaveKey([key]) {
+    return this.includes(key);
 }
 /**
- * Set a key/value entry on a map-like object (by reference).
+ * Set a single named prop on an object (by reference).
  *
- * @param obj The target object to modify.
+ * @param data The target data object to modify.
  * @param key The key of the prop in the object to set.
  * @param value The value to set the prop to.
  */
-export const setEntry = setProp;
-/**
- * Set several key/value entries on a map-like object (by reference).
- *
- * @param obj The target object to modify.
- * @param entries An object containing new props to set on the object.
- */
-export const setEntries = setProps;
+export function setProp(data, key, value) {
+    data[key] = value;
+    return value;
+}
 /**
- * Remove a key/value entry from a map-like object (by reference).
+ * Set several named props on an object (by reference).
  *
  * @param obj The target object to modify.
- * @param key The key of the entry to remove.
- * @param value The value of the entry to remove. If set, the entry will only be removed if its current value is exactly `value`
+ * @param props An object containing new props to set on the object.
  */
-export function deleteEntry(obj, key, value) {
-    if (value === undefined || obj[key] === value)
-        delete obj[key];
+export function setProps(obj, props) {
+    for (const [k, v] of getProps(props))
+        obj[k] = v;
 }
 /**
- * Remove several key/value entries from a map-like object (by reference).
+ * Remove several key/value entries from an object (by reference).
  *
  * @param obj The target object to modify.
- * @param entries Set of keys or entries to remove.
+ * @param keys Set of keys or keys to remove.
  */
-export function deleteEntries(obj, keys) {
+export function deleteProps(obj, ...keys) {
     for (const key of keys)
         delete obj[key];
 }
 /** An empty object. */
 export const EMPTY_OBJECT = {};
 /** Function that returns an an empty object. */
-export const GET_EMPTY_OBJECT = () => EMPTY_OBJECT;
+export const getEmptyObject = () => EMPTY_OBJECT;

package/util/transform.d.ts

@@ -1,7 +1,7 @@
-import { Data, Value, Prop } from "./data.js";
-import { Entry } from "./entry.js";
-import type { ImmutableObject } from "./object.js";
 import type { ArrayType, ImmutableArray } from "./array.js";
+import type { Data, Prop, Value } from "./data.js";
+import { Entry } from "./entry.js";
+import { ImmutableObject } from "./object.js";
 /** Object that transforms an input value into an output value with its `transform()` method. */
 export interface Transformable<I, O> {
     transform(input: I): O;
@@ -20,26 +20,24 @@ export declare type Transformers<T extends Data> = {
     readonly [K in keyof T]?: Transformer<T[K], T[K]>;
 };
 /**
- * Transform the props of a data object using a set of transformers for its props.
- * @returns New object with changed props (or the same object if no changes were made).
+ * Transform the props of a data object using a set of named transformers.
+ * @returns New object with changed props.
  */
 export declare function transformData<T extends Data>(data: T, transforms: Transformers<T>): T;
 /**
- * Transform the props of a data object using a set of prop transformers.
- * @yield Transformed prop entry after calling the corresponding prop transformer.
+ * Transform the props of a data object using a set of named transformers.
+ * @yield Transformed prop entries after calling the corresponding transformer.
  */
-export declare function transformProps<T extends Data>(data: T, transforms: Transformers<T>): Iterable<Prop<T>>;
+export declare function transformProps<T extends Data>(obj: T, transforms: Transformers<T>): Iterable<Prop<T>>;
 /**
  * Transform the _values_ of an iterable set of entries using a transformer.
  * @yield Transformed entry after calling transforming the new value for each entry.
  */
-export declare function mapEntries<K, I, O>(entries: Iterable<Entry<K, I>>, transformer: (v: I) => O): Iterable<Entry<K, O>>;
 export declare function mapEntries<K, I, O>(entries: Iterable<Entry<K, I>>, transformer: Transformer<I, O>): Iterable<Entry<K, O>>;
 /**
  * Transform the _values_ of a map-like object using a transformer.
  * @return New object after transforming its entries.
  */
-export declare function mapObject<I, O>(obj: ImmutableObject<I>, transformer: (v: I) => O): ImmutableObject<O>;
 export declare function mapObject<I, O>(obj: ImmutableObject<I>, transformer: Transformer<I, O>): ImmutableObject<O>;
 /**
  * Transform the _values_ of an data object using a transformer.
@@ -53,12 +51,10 @@ export declare function mapData<I extends Data, O extends {
  * Map an iterable set of items using a transformer.
  * @yield Transformed items after calling `transformer()` on each.
  */
-export declare function mapItems<I, O>(items: Iterable<I>, transformer: (input: I) => O): Iterable<O>;
 export declare function mapItems<I, O>(items: Iterable<I>, transformer: Transformer<I, O>): Iterable<O>;
 /**
  * Apply a transformer to each item in an array and return the transformed array.
  * @return The transformed array.
  */
 export declare function mapArray<T extends ImmutableArray>(arr: T, transformer: Transformer<ArrayType<T>, ArrayType<T>>): T;
-export declare function mapArray<I, O>(arr: Iterable<I>, transformer: (v: I) => O): ImmutableArray<O>;
 export declare function mapArray<I, O>(arr: Iterable<I>, transformer: Transformer<I, O>): ImmutableArray<O>;

package/util/transform.js

@@ -1,36 +1,48 @@
 import { isFunction } from "./function.js";
-import { getProps, isData } from "./data.js";
 import { getEntries } from "./entry.js";
+import { getProps, isObject } from "./object.js";
 /** Is an unknown value a transformable. */
-export const isTransformable = (v) => isData(v) && typeof v.transform === "function";
+export const isTransformable = (v) => isObject(v) && typeof v.transform === "function";
 export function transform(input, transformer) {
     return isFunction(transformer) ? transformer(input) : isTransformable(transformer) ? transformer.transform(input) : transformer;
 }
 /**
- * Transform the props of a data object using a set of transformers for its props.
- * @returns New object with changed props (or the same object if no changes were made).
+ * Transform the props of a data object using a set of named transformers.
+ * @returns New object with changed props.
  */
 export function transformData(data, transforms) {
     return { ...data, ...Object.fromEntries(transformProps(data, transforms)) };
 }
 /**
- * Transform the props of a data object using a set of prop transformers.
- * @yield Transformed prop entry after calling the corresponding prop transformer.
+ * Transform the props of a data object using a set of named transformers.
+ * @yield Transformed prop entries after calling the corresponding transformer.
  */
-export function* transformProps(data, transforms) {
+export function* transformProps(obj, transforms) {
     for (const [k, v] of getProps(transforms))
-        yield [k, transform(data[k], v)];
+        yield [k, transform(obj[k], v)];
 }
+/**
+ * Transform the _values_ of an iterable set of entries using a transformer.
+ * @yield Transformed entry after calling transforming the new value for each entry.
+ */
 export function* mapEntries(entries, transformer) {
     for (const [k, v] of entries)
         yield [k, transform(v, transformer)];
 }
+/**
+ * Transform the _values_ of a map-like object using a transformer.
+ * @return New object after transforming its entries.
+ */
 export function mapObject(obj, transformer) {
     return Object.fromEntries(mapEntries(getEntries(obj), transformer));
 }
 export function mapData(data, transformer) {
     return mapObject(data, transformer);
 }
+/**
+ * Map an iterable set of items using a transformer.
+ * @yield Transformed items after calling `transformer()` on each.
+ */
 export function* mapItems(items, transformer) {
     for (const item of items)
         yield transform(item, transformer);

package/util/validate.d.ts

@@ -1,6 +1,6 @@
 import type { Entry } from "./entry.js";
-import type { ImmutableObject } from "./object.js";
-import { Data, Prop } from "./data.js";
+import type { Data, Prop } from "./data.js";
+import { ImmutableObject } from "./object.js";
 import { ImmutableArray } from "./array.js";
 /** Object that can validate an unknown value with its `validate()` method. */
 export interface Validatable<T> {

package/util/validate.js

@@ -1,6 +1,6 @@
 import { isFeedback } from "../feedback/Feedback.js";
 import { InvalidFeedback } from "../feedback/InvalidFeedback.js";
-import { getProps } from "./data.js";
+import { getProps } from "./object.js";
 import { getArray } from "./array.js";
 /** Validate an unknown value with a validator. */
 export function validate(unsafeValue, validator) {