shelving 1.86.7 → 1.87.0

package/util/assert.js

@@ -5,12 +5,12 @@ export function assert(condition, ...received) {
         throw new AssertionError(`Must assert`, ...received);
 }
 /** Assert two values are equal. */
-export function assertEqual(v, target) {
-    if (v !== target)
-        throw new AssertionError(`Must be equal`, v, target);
+export function assertEqual(left, right) {
+    if (left !== right)
+        throw new AssertionError(`Must be equal`, left, right);
 }
 /** Assert two values are equal. */
-export function assertNot(v, target) {
-    if (v === target)
-        throw new AssertionError(`Must not be equal`, v, target);
+export function assertNot(left, right) {
+    if (left === right)
+        throw new AssertionError(`Must not be equal`, left, right);
 }

package/util/async.d.ts

@@ -1,9 +1,9 @@
 import { SIGNAL } from "./constants.js";
 import type { Handler, Dispatch } from "./function.js";
 /** Is a value an asynchronous value implementing a `then()` function. */
-export declare const isAsync: <T>(v: T | PromiseLike<T>) => v is PromiseLike<T>;
+export declare const isAsync: <T>(value: T | PromiseLike<T>) => value is PromiseLike<T>;
 /** Is a value a synchronous value. */
-export declare const notAsync: <T>(v: T | PromiseLike<T>) => v is T;
+export declare const notAsync: <T>(value: T | PromiseLike<T>) => value is T;
 /**
  * Throw the value if it's an async (promised) value.
  * @returns Synchronous (not promised) value.

package/util/async.js

@@ -1,9 +1,9 @@
 import { AssertionError } from "../error/AssertionError.js";
 import { SIGNAL } from "./constants.js";
 /** Is a value an asynchronous value implementing a `then()` function. */
-export const isAsync = (v) => typeof v === "object" && v !== null && typeof v.then === "function";
+export const isAsync = (value) => typeof value === "object" && value !== null && typeof value.then === "function";
 /** Is a value a synchronous value. */
-export const notAsync = (v) => !isAsync(v);
+export const notAsync = (value) => !isAsync(value);
 /**
  * Throw the value if it's an async (promised) value.
  * @returns Synchronous (not promised) value.
@@ -78,7 +78,7 @@ export class Delay extends AbstractPromise {
     }
 }
 /** Resolve to `SIGNAL` on a specific signal. */
-export class Signal extends AbstractPromise {
+class Signal extends AbstractPromise {
     constructor() {
         super(...arguments);
         /** Send this signal now. */
@@ -87,3 +87,4 @@ export class Signal extends AbstractPromise {
 }
 /** The `SIGNAL` symbol indicates a signal. */
 Signal.SIGNAL = SIGNAL;
+export { Signal };

package/util/boolean.d.ts

@@ -1,20 +1,20 @@
 /** Is a value a boolean? */
-export declare const isBoolean: (v: unknown) => v is boolean;
+export declare const isBoolean: (value: unknown) => value is boolean;
 /** Is a value true? */
-export declare const isTrue: (v: unknown) => v is true;
+export declare const isTrue: (value: unknown) => value is true;
 /** Is a value false? */
-export declare const isFalse: (v: unknown) => v is false;
+export declare const isFalse: (value: unknown) => value is false;
 /** Is a value truthy? */
-export declare const isTruthy: (v: unknown) => boolean;
+export declare const isTruthy: (value: unknown) => boolean;
 /** Is a value falsey? */
-export declare const isFalsey: (v: unknown) => boolean;
+export declare const isFalsey: (value: unknown) => boolean;
 /** Assert that a value is a boolean. */
-export declare function assertBoolean(v: unknown): asserts v is boolean;
+export declare function assertBoolean(value: unknown): asserts value is boolean;
 /** Assert that a value is true. */
-export declare function assertTrue(v: unknown): asserts v is true;
+export declare function assertTrue(value: unknown): asserts value is true;
 /** Assert that a value is false. */
-export declare function assertFalse(v: unknown): asserts v is false;
+export declare function assertFalse(value: unknown): asserts value is false;
 /** Assert that a value is truthy. */
-export declare function assertTruthy(v: unknown): asserts v is true;
+export declare function assertTruthy(value: unknown): asserts value is true;
 /** Assert that a value is falsy. */
-export declare function assertFalsy(v: unknown): asserts v is false;
+export declare function assertFalsy(value: unknown): asserts value is false;

package/util/boolean.js

@@ -1,36 +1,36 @@
 import { AssertionError } from "../error/AssertionError.js";
 /** Is a value a boolean? */
-export const isBoolean = (v) => typeof v === "boolean";
+export const isBoolean = (value) => typeof value === "boolean";
 /** Is a value true? */
-export const isTrue = (v) => v === true;
+export const isTrue = (value) => value === true;
 /** Is a value false? */
-export const isFalse = (v) => v === false;
+export const isFalse = (value) => value === false;
 /** Is a value truthy? */
-export const isTruthy = (v) => !!v;
+export const isTruthy = (value) => !!value;
 /** Is a value falsey? */
-export const isFalsey = (v) => !v;
+export const isFalsey = (value) => !value;
 /** Assert that a value is a boolean. */
-export function assertBoolean(v) {
-    if (typeof v !== "boolean")
-        throw new AssertionError(`Must be boolean`, v);
+export function assertBoolean(value) {
+    if (typeof value !== "boolean")
+        throw new AssertionError(`Must be boolean`, value);
 }
 /** Assert that a value is true. */
-export function assertTrue(v) {
-    if (v !== true)
-        throw new AssertionError(`Must be true`, v);
+export function assertTrue(value) {
+    if (value !== true)
+        throw new AssertionError(`Must be true`, value);
 }
 /** Assert that a value is false. */
-export function assertFalse(v) {
-    if (v !== false)
-        throw new AssertionError(`Must be false`, v);
+export function assertFalse(value) {
+    if (value !== false)
+        throw new AssertionError(`Must be false`, value);
 }
 /** Assert that a value is truthy. */
-export function assertTruthy(v) {
-    if (!v)
-        throw new AssertionError(`Must be truthy`, v);
+export function assertTruthy(value) {
+    if (!value)
+        throw new AssertionError(`Must be truthy`, value);
 }
 /** Assert that a value is falsy. */
-export function assertFalsy(v) {
-    if (v)
-        throw new AssertionError(`Must be falsy`, v);
+export function assertFalsy(value) {
+    if (value)
+        throw new AssertionError(`Must be falsy`, value);
 }

package/util/class.d.ts

@@ -7,11 +7,11 @@ export type AnyConstructor = new (...args: any) => any;
 export type Class<T> = new (...args: any) => T;
 export declare const abc: Class<String>;
 /** Is a given value a class constructor? */
-export declare const isConstructor: <T extends AnyConstructor>(v: unknown) => v is T;
+export declare const isConstructor: <T extends AnyConstructor>(value: unknown) => value is T;
 /** Is a value an instance of a class? */
-export declare const isInstance: <T>(v: unknown, type: Class<T>) => v is T;
+export declare const isInstance: <T>(value: unknown, type: Class<T>) => value is T;
 /** Assert that a value is an instance of something. */
-export declare function assertInstance<T>(v: T | unknown, type: Class<T>): asserts v is T;
+export declare function assertInstance<T>(value: T | unknown, type: Class<T>): asserts value is T;
 /** Decorator to bind a class method lazily on first access. */
 export declare function bindMethod<O, T, A>(target: O, key: string, { value: method }: TypedPropertyDescriptor<(...args: A[]) => T>): TypedPropertyDescriptor<(...args: A[]) => T>;
 /**

package/util/class.js

@@ -4,13 +4,13 @@ import { assertFunction } from "./function.js";
 import { debug } from "./debug.js";
 export const abc = String;
 /** Is a given value a class constructor? */
-export const isConstructor = (v) => typeof v === "function" && v.toString().startsWith("class");
+export const isConstructor = (value) => typeof value === "function" && value.toString().startsWith("class");
 /** Is a value an instance of a class? */
-export const isInstance = (v, type) => v instanceof type;
+export const isInstance = (value, type) => value instanceof type;
 /** Assert that a value is an instance of something. */
-export function assertInstance(v, type) {
-    if (!(v instanceof type))
-        throw new AssertionError(`Must be instance of ${debug(type)}`, v);
+export function assertInstance(value, type) {
+    if (!(value instanceof type))
+        throw new AssertionError(`Must be instance of ${debug(type)}`, value);
 }
 /** Decorator to bind a class method lazily on first access. */
 export function bindMethod(target, key, { value: method }) {

package/util/clone.d.ts

@@ -5,7 +5,7 @@ export interface Cloneable {
     clone(): this;
 }
 /** Does an object implement `Cloneable` */
-export declare const isCloneable: <T extends Cloneable>(v: unknown) => v is T;
+export declare const isCloneable: <T extends Cloneable>(value: unknown) => value is T;
 /** Shallow clone a value. */
 export declare const shallowClone: <T>(value: T) => T;
 /** Deep clone a value. */

package/util/clone.js

@@ -3,7 +3,7 @@ import { isData } from "./data.js";
 import { mapArray, mapObject } from "./transform.js";
 import { getPrototype } from "./object.js";
 /** Does an object implement `Cloneable` */
-export const isCloneable = (v) => isData(v) && typeof v.clone === "function";
+export const isCloneable = (value) => isData(value) && typeof value.clone === "function";
 /** Shallow clone a value. */
 export const shallowClone = (value) => value;
 /** Deep clone a value. */

package/util/color.d.ts

@@ -27,9 +27,9 @@ export declare class Color {
     toString(): string;
 }
 /** Is an unknown value a `Color` instance. */
-export declare const isColor: (v: Color | unknown) => v is Color;
+export declare const isColor: (value: Color | unknown) => value is Color;
 /** Assert that an unknown value is a `Color` instance. */
-export declare function assertColor(v: Color | unknown): asserts v is Color;
+export declare function assertColor(value: Color | unknown): asserts value is Color;
 /** Convert a possible color to a `Color` instance or `null` */
 export declare function getOptionalColor(possible: unknown): Color | null;
 /** Convert a possible color to a `Color` instance */

package/util/color.js

@@ -53,11 +53,11 @@ export class Color {
 const _parse = (hex) => parseInt(hex.padStart(2, "00"), 16);
 const _hex = (channel) => channel.toString(16).padStart(2, "00");
 /** Is an unknown value a `Color` instance. */
-export const isColor = (v) => v instanceof Color;
+export const isColor = (value) => value instanceof Color;
 /** Assert that an unknown value is a `Color` instance. */
-export function assertColor(v) {
-    if (!isColor(v))
-        throw new AssertionError("Invalid color", v);
+export function assertColor(value) {
+    if (!isColor(value))
+        throw new AssertionError("Invalid color", value);
 }
 /** Convert a possible color to a `Color` instance or `null` */
 export function getOptionalColor(possible) {

package/util/data.d.ts

@@ -1,26 +1,39 @@
 import type { ImmutableArray } from "./array.js";
+import type { EntryObject } from "./entry.js";
 /** Data object. */
 export type Data = {
     readonly [K in string]: unknown;
 };
-/** Prop for a data object. */
-export type DataProp<T extends Data> = readonly [keyof T & string, T[keyof T & string]];
 /** Key for a data object prop. */
 export type DataKey<T extends Data> = keyof T & string;
 /** Value for a data object prop. */
 export type DataValue<T extends Data> = T[keyof T & string];
+/** Prop for a data object. */
+export type DataProp<T extends Data> = {
+    readonly [K in DataKey<T>]: [K, T[K]];
+}[DataKey<T>];
 /** Data or `null` to indicate the data doesn't exist. */
 export type OptionalData<T extends Data> = T | null;
 /** Set of named data objects. */
 export type Datas = {
     readonly [K in string]: Data;
 };
+/** Flattened data object with deep keys flattened into `a.c.b` format. */
+export type FlatData<T extends Data> = EntryObject<FlatDataProp<T>>;
+/** Key for a flattened data object with deep keys flattened into `a.c.b` format. */
+export type FlatDataKey<T extends Data> = FlatDataProp<T>[0];
+/** Value for a flattened data object with deep keys flattened into `a.c.b` format. */
+export type FlatDataValue<T extends Data> = FlatDataProp<T>[1];
+/** Prop for a flattened data object with deep keys flattened into `a.c.b` format. */
+export type FlatDataProp<T extends Data> = {
+    readonly [K in DataKey<T>]: (T[K] extends Data ? FlatDataProp<T[K]> : [null, T[K]]) extends infer E ? E extends [infer KK, infer VV] ? [KK extends string ? `${K}.${KK}` : K, VV] : never : never;
+}[DataKey<T>];
 /** Is an unknown value a data object? */
 export declare const isData: <T extends Data>(value: unknown) => value is T;
 /** Assert that an unknown value is a data object. */
 export declare function assertData<T extends Data>(value: T | unknown): asserts value is T;
 /** Is an unknown value the key for an own prop of a data object. */
-export declare const isDataKey: <T extends Data>(obj: T, key: unknown) => key is DataKey<T>;
+export declare const isDataProp: <T extends Data>(obj: T, key: unknown) => key is DataKey<T>;
 /** Get the data of a result (returns data or throws `RequiredError` if value is `null` or `undefined`). */
 export declare function getData<T extends Data>(result: OptionalData<T>): T;
 /** Get the props of a data object. */

package/util/data.js

@@ -9,7 +9,7 @@ export function assertData(value) {
         throw new AssertionError("Must be data", value);
 }
 /** Is an unknown value the key for an own prop of a data object. */
-export const isDataKey = (obj, key) => typeof key === "string" && Object.prototype.hasOwnProperty.call(obj, key);
+export const isDataProp = (obj, key) => typeof key === "string" && Object.prototype.hasOwnProperty.call(obj, key);
 /** Get the data of a result (returns data or throws `RequiredError` if value is `null` or `undefined`). */
 export function getData(result) {
     if (!result)

package/util/date.d.ts

@@ -3,9 +3,9 @@ export type PossibleDate = Date | number | string;
 /** Things that converted to dates or `null` */
 export type PossibleOptionalDate = Date | number | string | null;
 /** Is a value a date? */
-export declare const isDate: (v: Date | unknown) => v is Date;
+export declare const isDate: (value: Date | unknown) => value is Date;
 /** Assert that a value is a `Date` instance. */
-export declare function assertDate(v: Date | unknown): asserts v is Date;
+export declare function assertDate(value: Date | unknown): asserts value is Date;
 /**
  * Convert an unknown value to a valid `Date` instance, or `null` if it couldn't be converted.
  * - Note: `Date` instances can be invalid (e.g. `new Date("blah blah").getTime()` returns `NaN`). These are detected and will always return `null`

package/util/date.js

@@ -1,10 +1,10 @@
 import { AssertionError } from "../error/AssertionError.js";
 /** Is a value a date? */
-export const isDate = (v) => v instanceof Date;
+export const isDate = (value) => value instanceof Date;
 /** Assert that a value is a `Date` instance. */
-export function assertDate(v) {
-    if (!isDate(v))
-        throw new AssertionError(`Must be date`, v);
+export function assertDate(value) {
+    if (!isDate(value))
+        throw new AssertionError(`Must be date`, value);
 }
 /**
  * Convert an unknown value to a valid `Date` instance, or `null` if it couldn't be converted.

package/util/duration.d.ts

@@ -1,8 +1,8 @@
 import { PossibleDate } from "./date.js";
 /** Format a full format of a duration of time using the most reasonable units e.g. `5 years` or `1 week` or `4 minutes` or `12 milliseconds`. */
-export declare function formatFullDuration(ms: number, precision?: number): string;
+export declare function formatFullDuration(ms: number): string;
 /** Format a description of a duration of time using the most reasonable units e.g. `5y` or `4m` or `12ms`. */
-export declare function formatDuration(ms: number, precision?: number): string;
+export declare function formatDuration(ms: number): string;
 /** Full when a date happens/happened, e.g. `in 10 days` or `2 hours ago` */
 export declare const formatFullWhen: (target: PossibleDate, current?: PossibleDate) => string;
 /** Compact when a date happens/happened, e.g. `in 10d` or `2h ago` or `in 1w` */

package/util/duration.js

@@ -1,35 +1,34 @@
 import { MONTH, WEEK, DAY, HOUR, SECOND } from "./constants.js";
 import { getDuration } from "./date.js";
-import { getMapItem } from "./map.js";
 import { TIME_UNITS } from "./units.js";
-/** Get the ID for a time unit based on the amount in milliseconds. */
-function _getTimeUnitKey(ms) {
+/** Get an appropriate time unit based on an amount in milliseconds. */
+function _getTimeUnit(ms) {
     const abs = Math.abs(ms);
     if (abs > 18 * MONTH)
-        return "year";
+        return TIME_UNITS.unit("year");
     if (abs > 10 * WEEK)
-        return "month";
+        return TIME_UNITS.unit("month");
     if (abs > 2 * WEEK)
-        return "week";
+        return TIME_UNITS.unit("week");
     if (abs > DAY)
-        return "day";
+        return TIME_UNITS.unit("day");
     if (abs > HOUR)
-        return "hour";
+        return TIME_UNITS.unit("hour");
     if (abs > 9949)
-        return "minute";
+        return TIME_UNITS.unit("minute");
     if (abs > SECOND)
-        return "second";
-    return "millisecond";
+        return TIME_UNITS.unit("second");
+    return TIME_UNITS.unit("millisecond");
 }
 /** Format a full format of a duration of time using the most reasonable units e.g. `5 years` or `1 week` or `4 minutes` or `12 milliseconds`. */
-export function formatFullDuration(ms, precision) {
-    const unit = getMapItem(TIME_UNITS, _getTimeUnitKey(ms));
-    return unit.formatFull(unit.from(ms), precision);
+export function formatFullDuration(ms) {
+    const unit = _getTimeUnit(ms);
+    return unit.formatFull(unit.from(ms), 0);
 }
 /** Format a description of a duration of time using the most reasonable units e.g. `5y` or `4m` or `12ms`. */
-export function formatDuration(ms, precision) {
-    const unit = getMapItem(TIME_UNITS, _getTimeUnitKey(ms));
-    return unit.format(unit.from(ms), precision);
+export function formatDuration(ms) {
+    const unit = _getTimeUnit(ms);
+    return unit.format(unit.from(ms), 0);
 }
 /** format when a data happens/happened. */
 function _formatWhen(formatter, target, current) {

package/util/entry.d.ts

@@ -11,6 +11,10 @@ export type Entry<K = unknown, T = unknown> = readonly [K, T];
 export type EntryKey<X> = X extends Entry<infer Y, unknown> ? Y : never;
 /** Extract the type for the value of an entry. */
 export type EntryValue<X> = X extends Entry<unknown, infer Y> ? Y : never;
+/** Convert an entry back into an object. */
+export type EntryObject<T extends Entry<PropertyKey, unknown>> = {
+    readonly [E in T as E[0]]: E[1];
+};
 /** Extract the key from an object entry. */
 export declare const getEntryKey: <K, T>([k]: Entry<K, T>) => K;
 /** Extract the value from an object entry. */

package/util/equal.d.ts

@@ -2,36 +2,73 @@ import type { Match } from "./match.js";
 import { ImmutableArray } from "./array.js";
 import { ImmutableObject } from "./object.js";
 import { ImmutableMap } from "./map.js";
-/** Are two unknown values exactly equal? */
-export declare const isExactlyEqual: <L extends unknown>(left: L, right: unknown) => right is L;
+/** Is unknown value `left` exactly equal to `right`? */
+export declare const isEqual: <T>(left: unknown, right: T) => left is T;
+/** Is unknown value `left` not exactly equal to `right`? */
+export declare const notEqual: <T, N>(left: T | N, right: N) => left is T;
+/** Is unknown value `left` less than `right`? */
+export declare const isLess: (left: unknown, right: unknown) => boolean;
+/** Is unknown value `left` less than or equal to `right`? */
+export declare const isEqualLess: (left: unknown, right: unknown) => boolean;
+/** Is unknown value `left` greater than `right`? */
+export declare const isGreater: (left: unknown, right: unknown) => boolean;
+/** Is unknown value `left` greater than or equal to `right`? */
+export declare const isEqualGreater: (left: unknown, right: unknown) => boolean;
 /**
- * Are two unknown values shallow equal?
- * - If the values are both arrays/objects, see if the items/properties are **exactly** equal with each other.
+ * Are two unknown values shallowly equal?
+ * - If the values are both arrays/objects, see if the items/properties are **shallowly** equal with each other.
  */
-export declare const isShallowEqual: <L extends unknown>(left: L, right: unknown) => right is L;
+export declare const isShallowEqual: <T extends unknown>(left: unknown, right: T) => left is T;
+/** Are two unknown values not shallowly equal? */
+export declare const notShallowEqual: <T extends unknown>(left: unknown, right: T) => left is T;
 /**
  * Are two unknown values deeply equal?
  * - If the values are both arrays/objects, see if the items/properties are **deeply** equal with each other.
  */
-export declare const isDeepEqual: <L extends unknown>(left: L, right: unknown) => right is L;
+export declare const isDeepEqual: <T extends unknown>(left: unknown, right: T) => left is T;
+/** Are two unknown values not deeply equal? */
+export declare const notDeepEqual: <T extends unknown>(left: unknown, right: T) => left is T;
 /**
  * Are two maps equal (based on their items).
  */
-export declare function isMapEqual<L extends ImmutableMap>(left: L, right: ImmutableMap, recursor?: Match): right is L;
+export declare function isMapEqual<T extends ImmutableMap>(left: ImmutableMap, right: T, recursor?: Match): left is T;
 /**
- * Are two arrays equal (based on their items)?
+ * Are two arrays equal based on their items?
  *
- * @param recursor Function that checks each property of the object.
- * - Defaults to `isExactlyEqual()` to check strict equality of the items.
+ * @param recursor Function that checks each item of the array.
+ * - Defaults to `isEqual()` to check strict equality of the items.
  * - Use `isDeepEqual()` as the recursor to check to check deep equality of the items.
  */
-export declare function isArrayEqual<L extends ImmutableArray>(left: L, right: ImmutableArray, recursor?: Match): right is L;
+export declare function isArrayEqual<T extends ImmutableArray>(left: ImmutableArray, right: T, recursor?: Match): left is T;
+/** Is unknown value `left` in array `right`? */
+export declare const isInArray: <R>(left: unknown, right: ImmutableArray<R>) => left is R;
+/** Is unknown value `left` not in array `right`? */
+export declare const notInArray: (left: unknown, right: ImmutableArray) => boolean;
+/** Is unknown value `left` an array including `right`? */
+export declare const isArrayWith: <T>(left: unknown, right: T) => left is ImmutableArray<T>;
+/** Is unknown value `left` not an array or does not include `right`? */
+export declare const notArrayWith: (left: unknown, right: unknown) => boolean;
 /**
- * Are two objects equal?
- * - Only checks constructor and enumerable own keys (as returned by `Object.keys()`).
+ * Are two objects equal based on their own props?
+ * - `left` must have every property present in `right`
+ * - `left` must not have excess properties not present in `right`
  *
- * @param recursor Function that checks each property of the object.
- * - Defaults to `isExactlyEqual()` to check strict equality of the properties.
+ * @param recursor Function that checks each prop of the object.
+ * - Defaults to `isEqual()` to check strict equality of the properties.
  * - Use `isDeepEqual()` as the recursor to check to check deep equality of the properties.
  */
-export declare function isObjectEqual<L extends ImmutableObject>(left: L, right: ImmutableObject, recursor?: Match): right is L;
+export declare function isObjectEqual<T extends ImmutableObject>(left: ImmutableObject, right: T, recursor?: Match): left is T;
+/**
+ * Are two objects partially equal based on their own props?
+ * - `left` must have every property present in `right`
+ * - `left` may have have excess properties not present in `right`
+ *
+ * @param recursor Function that checks each prop of the object.
+ * - Defaults to `isEqual()` to check strict equality of the properties.
+ * - Use `isDeepEqual()` as the recursor to check to check deep equality of the properties.
+ */
+export declare function isObjectMatch<L extends ImmutableObject, R extends ImmutableObject>(left: L | R, right: R, recursor?: Match): left is L & R;
+/** Is unknown value `left` an object with every prop from `right`? */
+export declare const isObjectWith: (left: unknown, right: ImmutableObject) => boolean;
+/** Is unknown value `left` not an object or missing one or more props from `right`? */
+export declare const notObjectWith: (left: unknown, right: ImmutableObject) => boolean;