shelving 1.91.2 → 1.92.0

package/util/query.d.ts

@@ -0,0 +1,83 @@
+import type { ImmutableArray } from "./array.js";
+import type { Data, FlatData, FlatDataKey } from "./data.js";
+/** Query that can be applied to a list of data objects. */
+export type Query<T extends Data> = {
+    readonly [K in FlatDataKey<T> as K | `${K}` | `!${K}`]?: FlatData<T>[K] | ImmutableArray<FlatData<T>[K]> | undefined;
+} & {
+    readonly [K in FlatDataKey<T> as `${K}<` | `${K}<=` | `${K}>` | `${K}>=`]?: FlatData<T>[K] | undefined;
+} & {
+    readonly [K in FlatDataKey<T> as `${K}[]`]?: FlatData<T>[K] extends ImmutableArray<infer X> ? X | undefined : never;
+} & {
+    readonly $order?: FlatDataKey<T> | `${FlatDataKey<T>}` | `!${FlatDataKey<T>}` | ImmutableArray<`${FlatDataKey<T>}` | `!${FlatDataKey<T>}`>;
+    readonly $limit?: number | undefined;
+};
+/** A single filter that can be applied to a list of data objects. */
+export type Filter = {
+    keys: readonly [string, ...string[]];
+    operator: "is";
+    value: unknown;
+} | {
+    keys: readonly [string, ...string[]];
+    operator: "not";
+    value: unknown;
+} | {
+    keys: readonly [string, ...string[]];
+    operator: "in";
+    value: ImmutableArray;
+} | {
+    keys: readonly [string, ...string[]];
+    operator: "out";
+    value: ImmutableArray;
+} | {
+    keys: readonly [string, ...string[]];
+    operator: "contains";
+    value: unknown;
+} | {
+    keys: readonly [string, ...string[]];
+    operator: "lt";
+    value: unknown;
+} | {
+    keys: readonly [string, ...string[]];
+    operator: "lte";
+    value: unknown;
+} | {
+    keys: readonly [string, ...string[]];
+    operator: "gt";
+    value: unknown;
+} | {
+    keys: readonly [string, ...string[]];
+    operator: "gte";
+    value: unknown;
+};
+/** A single sort that can be applied to a list of data objects. */
+export type Sort = {
+    keys: readonly [string, ...string[]];
+    direction: "asc" | "desc";
+};
+/** Get the `Filter` objects for a query. */
+export declare function getFilters<T extends Data>(query: Query<T>): ImmutableArray<Filter>;
+/** Get the `Sort` objects for a query. */
+export declare function getSorts<T extends Data>({ $order }: Query<T>): ImmutableArray<Sort>;
+/** Get the limit for a query. */
+export declare const getLimit: <T extends Data>({ $limit }: Query<T>) => number | undefined;
+/** Query a set of data items using a query. */
+export declare function queryItems<T extends Data>(items: Iterable<T>, query: Query<T>): Iterable<T>;
+/**
+ * Query a set of data items for writing using a query.
+ * - If no limit is set on the data sorting can be avoided too for performance reasons.
+ */
+export declare function queryWritableItems<T extends Data>(items: Iterable<T>, query: Query<T>): Iterable<T>;
+/** Match a single data item againt a set of filters. */
+export declare function matchQueryItem<T extends Data>(item: T, filters: ImmutableArray<Filter>): boolean;
+/**  Filter a set of data items using a set of filters. */
+export declare function filterQueryItems<T extends Data>(items: Iterable<T>, filters: ImmutableArray<Filter>): Iterable<T>;
+/** Compare two data items using a set of sorts. */
+export declare function compareQueryItems<T extends Data>(left: T, right: T, sorts: ImmutableArray<Sort>): number;
+/**  Sort a set of data items using a set of sorts. */
+export declare function sortQueryItems<T extends Data>(items: Iterable<T>, sorts: ImmutableArray<Sort>): Iterable<T>;
+/** LImit a set of data items using a set of limit. */
+export declare function limitQueryItems<T extends Data>(items: ImmutableArray<T> | Iterable<T>, limit: number | undefined): Iterable<T>;
+/** Get a query for items that appear before a specified item. */
+export declare function getBeforeQuery<T extends Data>(query: Query<T>, item: T): Query<T>;
+/** Get a query for items that appear after a specified item. */
+export declare function getAfterQuery<T extends Data>(query: Query<T>, item: T): Query<T>;

package/util/query.js

@@ -0,0 +1,129 @@
+import { getLastItem, isArray, limitArray } from "./array.js";
+import { isArrayWith, isEqual, isEqualGreater, isEqualLess, isGreater, isInArray, isLess, notEqual, notInArray } from "./equal.js";
+import { limitItems } from "./iterate.js";
+import { getProp, getProps } from "./object.js";
+import { compareAscending, compareDescending, sortArray } from "./sort.js";
+import { splitString } from "./string.js";
+import { isDefined } from "./undefined.js";
+/** Map `Filter` operators to corresponding `Match` function. */
+const MATCHERS = {
+    is: isEqual,
+    not: notEqual,
+    in: isInArray,
+    out: notInArray,
+    contains: isArrayWith,
+    lt: isLess,
+    lte: isEqualLess,
+    gt: isGreater,
+    gte: isEqualGreater,
+};
+/** Get the `Filter` objects for a query. */
+export function getFilters(query) {
+    return getProps(query).map(_getFilters).filter(isDefined);
+}
+function _getFilters([key, value]) {
+    if (key === "$order" || key === "$limit")
+        return;
+    else if (key.startsWith("!"))
+        return isArray(value) ? { keys: splitString(key.slice(1), "."), operator: "out", value } : { keys: splitString(key.slice(1), "."), operator: "not", value };
+    else if (key.endsWith("[]"))
+        return { keys: splitString(key.slice(0, -2), "."), operator: "contains", value };
+    else if (key.endsWith(">"))
+        return { keys: splitString(key.slice(0, -1), "."), operator: "gt", value };
+    else if (key.endsWith(">="))
+        return { keys: splitString(key.slice(0, -2), "."), operator: "gte", value };
+    else if (key.endsWith("<"))
+        return { keys: splitString(key.slice(0, -1), "."), operator: "lt", value };
+    else if (key.endsWith("<="))
+        return { keys: splitString(key.slice(0, -2), "."), operator: "lte", value };
+    else
+        return isArray(value) ? { keys: splitString(key, "."), operator: "in", value } : { keys: splitString(key, "."), operator: "is", value };
+}
+/** Get the `Sort` objects for a query. */
+export function getSorts({ $order }) {
+    return !$order ? [] : isArray($order) ? $order.map(_getSort) : [_getSort($order)];
+}
+function _getSort(key) {
+    if (key.startsWith("!"))
+        return { keys: splitString(key.slice(1), "."), direction: "desc" };
+    else
+        return { keys: splitString(key, "."), direction: "asc" };
+}
+/** Get the limit for a query. */
+export const getLimit = ({ $limit }) => $limit;
+/** Query a set of data items using a query. */
+export function queryItems(items, query) {
+    return limitQueryItems(sortQueryItems(filterQueryItems(items, getFilters(query)), getSorts(query)), getLimit(query));
+}
+/**
+ * Query a set of data items for writing using a query.
+ * - If no limit is set on the data sorting can be avoided too for performance reasons.
+ */
+export function queryWritableItems(items, query) {
+    return getLimit(query) === undefined ? filterQueryItems(items, getFilters(query)) : queryItems(items, query);
+}
+/** Match a single data item againt a set of filters. */
+export function matchQueryItem(item, filters) {
+    for (const { keys, operator, value } of filters) {
+        const matcher = MATCHERS[operator];
+        if (!matcher(getProp(item, ...keys), value))
+            return false;
+    }
+    return true;
+}
+/**  Filter a set of data items using a set of filters. */
+export function* filterQueryItems(items, filters) {
+    if (filters.length) {
+        for (const item of items)
+            if (matchQueryItem(item, filters))
+                yield item;
+    }
+    else {
+        yield* items;
+    }
+}
+/** Compare two data items using a set of sorts. */
+export function compareQueryItems(left, right, sorts) {
+    for (const { keys, direction } of sorts) {
+        const l = getProp(left, ...keys);
+        const r = getProp(right, ...keys);
+        const c = direction === "asc" ? compareAscending(l, r) : compareDescending(l, r);
+        if (c !== 0)
+            return c;
+    }
+    return 0;
+}
+/**  Sort a set of data items using a set of sorts. */
+export function sortQueryItems(items, sorts) {
+    return sorts.length ? sortArray(items, compareQueryItems, sorts) : items;
+}
+/** LImit a set of data items using a set of limit. */
+export function limitQueryItems(items, limit) {
+    return typeof limit !== "number" ? items : isArray(items) ? limitArray(items, limit) : limitItems(items, limit);
+}
+/** Get a query for items that appear before a specified item. */
+export function getBeforeQuery(query, item) {
+    const sorts = getSorts(query);
+    const lastSort = getLastItem(sorts);
+    const newQuery = { ...query };
+    for (const sort of sorts) {
+        const { keys, direction } = sort;
+        const key = keys.join(".");
+        const value = getProp(item, ...keys);
+        newQuery[direction === "asc" ? (sort === lastSort ? `${key}>` : `${key}>=`) : sort === lastSort ? `${key}<` : `${key}<=`] = value;
+    }
+    return newQuery;
+}
+/** Get a query for items that appear after a specified item. */
+export function getAfterQuery(query, item) {
+    const sorts = getSorts(query);
+    const lastSort = getLastItem(sorts);
+    const newQuery = { ...query };
+    for (const sort of sorts) {
+        const { keys, direction } = sort;
+        const key = keys.join(".");
+        const value = getProp(item, ...keys);
+        newQuery[direction === "asc" ? (sort === lastSort ? `${key}<` : `${key}<=`) : sort === lastSort ? `${key}>` : `${key}>=`] = value;
+    }
+    return newQuery;
+}

package/util/sort.d.ts

@@ -1,16 +1,9 @@
 import type { ImmutableArray } from "./array.js";
-/** Object that can rank two values using its `rank()` function. */
-export interface Rankable<T> {
-    rank(left: T, right: T): number;
-}
-/** Function that can rank two values. */
-export type Rank<T> = (left: T, right: T) => number;
-/** Something that can rank two values. */
-export type Ranker<T> = Rankable<T> | Rank<T>;
-/** Rank two values with a `Ranker`. */
-export declare function rank<T>(left: T, ranker: Ranker<T>, right: T): number;
+import type { Arguments } from "./function.js";
+/** Function that can compare two values for sorting. */
+export type Compare<T, A extends Arguments = []> = (left: T, right: T, ...args: A) => number;
 /**
- * Rank two values in ascending order.
+ * Compare two unknown values in ascending order.
  * - Allows values of different types to be ranked for sorting.
  *
  * 1. Numbers and dates (ascending order: -Infinity, negative, zero, positive, Infinity, NaN)
@@ -26,8 +19,8 @@ export declare function rank<T>(left: T, ranker: Ranker<T>, right: T): number;
  *
  * @returns Number below zero if `a` is higher, number above zero if `b` is higher, or `0` if they're equally sorted.
  */
-export declare function rankAsc(left: unknown, right: unknown): number;
-/** Rank two values in descending order. */
-export declare const rankDesc: (left: unknown, right: unknown) => number;
+export declare function compareAscending(left: unknown, right: unknown): number;
+/** Compare two unknown values in descending order. */
+export declare const compareDescending: (left: unknown, right: unknown) => number;
 /** Sort an iterable set of items using a ranker (defaults to sorting in ascending order). */
-export declare function sortItems<T>(input: ImmutableArray<T> | Iterable<T>, ranker?: Ranker<T>): ImmutableArray<T>;
+export declare function sortArray<T, A extends Arguments = []>(input: ImmutableArray<T> | Iterable<T>, compare?: Compare<T, A>, ...args: A): ImmutableArray<T>;

package/util/sort.js

@@ -1,10 +1,6 @@
 import { isArray } from "./array.js";
-/** Rank two values with a `Ranker`. */
-export function rank(left, ranker, right) {
-    return typeof ranker === "function" ? ranker(left, right) : ranker.rank(left, right);
-}
 /**
- * Rank two values in ascending order.
+ * Compare two unknown values in ascending order.
  * - Allows values of different types to be ranked for sorting.
  *
  * 1. Numbers and dates (ascending order: -Infinity, negative, zero, positive, Infinity, NaN)
@@ -20,7 +16,7 @@ export function rank(left, ranker, right) {
  *
  * @returns Number below zero if `a` is higher, number above zero if `b` is higher, or `0` if they're equally sorted.
  */
-export function rankAsc(left, right) {
+export function compareAscending(left, right) {
     // Exactly equal is easy.
     if (left === right)
         return 0;
@@ -72,8 +68,8 @@ export function rankAsc(left, right) {
     // Otherwise a is higher.
     return -1;
 }
-/** Rank two values in descending order. */
-export const rankDesc = (left, right) => 0 - rankAsc(left, right);
+/** Compare two unknown values in descending order. */
+export const compareDescending = (left, right) => 0 - compareAscending(left, right);
 /**
  * Quick sort algorithm.
  * DH: We implement our own sorting algorithm so that:
@@ -81,13 +77,13 @@ export const rankDesc = (left, right) => 0 - rankAsc(left, right);
  *     2. We can use our own comparison function by default.
  *
  * @param items The actual list of items that's sorted in place.
- * @param ranker A rank function that takes a left/right value and returns 1/0/-1 (like `Array.prototype.sort()`).
+ * @param compare A rank function that takes a left/right value and returns 1/0/-1 (like `Array.prototype.sort()`).
  * @param leftPointer Index in the set of items to start sorting on.
  * @param rightPointer Index in the set of items to stop sorting on.
  *
  * @return `true` if the array order changed, and `false` otherwise.
  */
-function _quicksort(items, ranker, leftPointer = 0, rightPointer = items.length - 1) {
+function _quicksort(items, compare, args, leftPointer = 0, rightPointer = items.length - 1) {
     // Have any swaps been made?
     let changed = false;
     // Calculate the middle value.
@@ -97,9 +93,9 @@ function _quicksort(items, ranker, leftPointer = 0, rightPointer = items.length
     let l = leftPointer;
     let r = rightPointer;
     while (l <= r) {
-        while (rank(items[l], ranker, middle) < 0)
+        while (compare(items[l], middle, ...args) < 0)
             l++; // eslint-disable-line @typescript-eslint/no-non-null-assertion
-        while (rank(items[r], ranker, middle) > 0)
+        while (compare(items[r], middle, ...args) > 0)
             r--; // eslint-disable-line @typescript-eslint/no-non-null-assertion
         if (l <= r) {
             if (l < r) {
@@ -111,22 +107,22 @@ function _quicksort(items, ranker, leftPointer = 0, rightPointer = items.length
         }
     }
     // Sort the lower and upper segments.
-    if (leftPointer < l - 1 && _quicksort(items, ranker, leftPointer, l - 1))
+    if (leftPointer < l - 1 && _quicksort(items, compare, args, leftPointer, l - 1))
         changed = true;
-    if (l < rightPointer && _quicksort(items, ranker, l, rightPointer))
+    if (l < rightPointer && _quicksort(items, compare, args, l, rightPointer))
         changed = true;
     // Changes were made.
     return changed;
 }
 /** Sort an iterable set of items using a ranker (defaults to sorting in ascending order). */
-export function sortItems(input, ranker = rankAsc) {
+export function sortArray(input, compare = compareAscending, ...args) {
     if (isArray(input)) {
         if (input.length < 2)
             return input;
         const output = Array.from(input);
-        return _quicksort(output, ranker) ? output : input;
+        return _quicksort(output, compare, args) ? output : input;
     }
-    const array = Array.from(input);
-    _quicksort(array, ranker);
-    return array;
+    const output = Array.from(input);
+    _quicksort(output, compare, args);
+    return output;
 }

package/util/transform.d.ts

@@ -3,57 +3,38 @@ import type { ImmutableDictionary, PossibleDictionary } from "./dictionary.js";
 import type { Entry } from "./entry.js";
 import type { Arguments } from "./function.js";
 import type { ImmutableObject, ObjectValue } from "./object.js";
-/** Object that transforms an input value into an output value with its `transform()` method. */
-export interface Transformable<I, O, A extends Arguments = []> {
-    transform(input: I, ...args: A): O;
-}
-/** Object that transforms an input value into an output value with its `transform()` method. */
-export interface AsyncTransformable<I, O, A extends Arguments = []> {
-    transform(input: I, ...args: A): O | PromiseLike<O>;
-}
-/** Is an unknown value a transformable. */
-export declare const isTransformable: <T extends Transformable<unknown, unknown, Arguments>>(value: unknown) => value is T;
 /** Function that can transform an input value into an output value. */
 export type Transform<I, O, A extends Arguments = []> = (input: I, ...args: A) => O;
 /** Function that can transform an input value into an output value. */
 export type AsyncTransform<I, O, A extends Arguments = []> = (input: I, ...args: A) => O | PromiseLike<O>;
-/** Something that can transform an input value into an output value (or a plain value). */
-export type Transformer<I, O, A extends Arguments = []> = Transformable<I, O, A> | Transform<I, O, A> | O;
-/** Something that can transform an input value into an output value (or a plain value). */
-export type AsyncTransformer<I, O, A extends Arguments = []> = AsyncTransformable<I, O, A> | AsyncTransform<I, O, A> | O;
-/** Set of named transformers for a data object (or `undefined` to skip the transform). */
-export type Transformers<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []> = {
-    readonly [K in keyof I]?: Transformer<I[K], O[K], A>;
+/** Set of named transforms for a data object (or `undefined` to skip the transform). */
+export type Transforms<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []> = {
+    readonly [K in keyof I]?: Transform<I[K], O[K], A>;
 };
-/** Transform a value using a transformer. */
-export declare function transform<I, O, A extends Arguments = []>(input: I, transformer: (v: I) => O, ...args: A): O;
-export declare function transform<I, O, A extends Arguments = []>(input: I, transformer: (v: I) => O | PromiseLike<O>, ...args: A): O | PromiseLike<O>;
-export declare function transform<I, O, A extends Arguments = []>(input: I, transformer: Transformer<I, O, A>, ...args: A): O;
-export declare function transform<I, O, A extends Arguments = []>(input: I, transformer: AsyncTransformer<I, O, A>, ...args: A): O;
-/** Modify a set of items using a transformer. */
-export declare function mapItems<I, O, A extends Arguments = []>(items: Iterable<I>, transformer: (v: I, ...args: A) => O, ...args: A): Iterable<O>;
-export declare function mapItems<I, O, A extends Arguments = []>(items: Iterable<I>, transformer: Transformer<I, O, A>, ...args: A): Iterable<O>;
-/** Modify the items of an array using a transformer. */
-export declare function mapArray<T extends ImmutableArray>(arr: T, transformer: Transformer<ArrayItem<T>, ArrayItem<T>>): T;
-export declare function mapArray<I, O, A extends Arguments = []>(arr: Iterable<I>, transformer: (v: I, ...args: A) => O, ...args: A): ImmutableArray<O>;
-export declare function mapArray<I, O, A extends Arguments = []>(arr: Iterable<I>, transformer: Transformer<I, O, A>, ...args: A): ImmutableArray<O>;
-/** Modify the values of the props of an object using a transformer. */
-export declare function mapObject<T extends ImmutableObject>(obj: T, transformer: Transformer<ObjectValue<T>, ObjectValue<T>>): T;
-export declare function mapObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I, transformer: (v: ObjectValue<I>, ...args: A) => ObjectValue<O>, ...args: A): O;
-export declare function mapObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I, transformer: Transformer<ObjectValue<I>, ObjectValue<O>>, ...args: A): O;
-/** Modify the values of a dictionary using a transformer. */
-export declare const mapDictionary: <I, O, A extends Arguments = []>(dictionary: PossibleDictionary<I>, transformer: Transformer<I, O, A>, ...args: A) => ImmutableDictionary<O>;
-/** Modify the values of a set of entries using a transformer. */
-export declare function mapEntries<K, I, O, A extends Arguments = []>(entries: Iterable<Entry<K, I>>, transformer: Transformer<I, O, A>, ...args: A): Iterable<Entry<K, O>>;
+/** Modify a set of items using a transform. */
+export declare function mapItems<I, O, A extends Arguments = []>(items: Iterable<I>, transform: (v: I, ...args: A) => O, ...args: A): Iterable<O>;
+export declare function mapItems<I, O, A extends Arguments = []>(items: Iterable<I>, transform: Transform<I, O, A>, ...args: A): Iterable<O>;
+/** Modify the items of an array using a transform. */
+export declare function mapArray<T extends ImmutableArray>(arr: T, transform: Transform<ArrayItem<T>, ArrayItem<T>>): T;
+export declare function mapArray<I, O, A extends Arguments = []>(arr: Iterable<I>, transform: (v: I, ...args: A) => O, ...args: A): ImmutableArray<O>;
+export declare function mapArray<I, O, A extends Arguments = []>(arr: Iterable<I>, transform: Transform<I, O, A>, ...args: A): ImmutableArray<O>;
+/** Modify the values of the props of an object using a transform. */
+export declare function mapObject<T extends ImmutableObject>(obj: T, transform: Transform<ObjectValue<T>, ObjectValue<T>>): T;
+export declare function mapObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I, transform: (v: ObjectValue<I>, ...args: A) => ObjectValue<O>, ...args: A): O;
+export declare function mapObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I, transform: Transform<ObjectValue<I>, ObjectValue<O>, A>, ...args: A): O;
+/** Modify the values of a dictionary using a transform. */
+export declare const mapDictionary: <I, O, A extends Arguments = []>(dictionary: PossibleDictionary<I>, transform: Transform<I, O, A>, ...args: A) => ImmutableDictionary<O>;
+/** Modify the values of a set of entries using a transform. */
+export declare function mapEntries<K, I, O, A extends Arguments = []>(entries: Iterable<Entry<K, I>>, transform: Transform<I, O, A>, ...args: A): Iterable<Entry<K, O>>;
 /**
- * Transform an object using a set of named transformers.
+ * Transform an object using a set of named transforms.
  *
  * @returns Transformed object (or same object if no changes were made).
  */
-export declare function transformObject<T extends ImmutableObject, A extends Arguments = []>(obj: T, transforms: Transformers<T, T | Partial<T>, A>, ...args: A): T;
-export declare function transformObject<T extends ImmutableObject, A extends Arguments = []>(obj: T | Partial<T>, transforms: Transformers<T, T | Partial<T>, A>, ...args: A): Partial<T>;
-export declare function transformObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I, transforms: Transformers<I, O | Partial<O>, A>, ...args: A): O;
-export declare function transformObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I | Partial<I>, transforms: Transformers<I, O | Partial<O>, A>, ...args: A): Partial<O>;
-/** Transform items in a sequence as they are yielded using a (potentially async) transformer. */
-export declare function mapSequence<I, O, A extends Arguments = []>(sequence: AsyncIterable<I>, transformer: (input: I, ...args: A) => O | PromiseLike<O>, ...args: A): AsyncIterable<O>;
-export declare function mapSequence<I, O, A extends Arguments = []>(sequence: AsyncIterable<I>, transformer: AsyncTransformer<I, O, A>, ...args: A): AsyncIterable<O>;
+export declare function transformObject<T extends ImmutableObject, A extends Arguments = []>(obj: T, transforms: Transforms<T, T | Partial<T>, A>, ...args: A): T;
+export declare function transformObject<T extends ImmutableObject, A extends Arguments = []>(obj: T | Partial<T>, transforms: Transforms<T, T | Partial<T>, A>, ...args: A): Partial<T>;
+export declare function transformObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I, transforms: Transforms<I, O | Partial<O>, A>, ...args: A): O;
+export declare function transformObject<I extends ImmutableObject, O extends ImmutableObject, A extends Arguments = []>(obj: I | Partial<I>, transforms: Transforms<I, O | Partial<O>, A>, ...args: A): Partial<O>;
+/** Transform items in a sequence as they are yielded using a (potentially async) transform. */
+export declare function mapSequence<I, O, A extends Arguments = []>(sequence: AsyncIterable<I>, transform: (input: I, ...args: A) => O | PromiseLike<O>, ...args: A): AsyncIterable<O>;
+export declare function mapSequence<I, O, A extends Arguments = []>(sequence: AsyncIterable<I>, transform: AsyncTransform<I, O, A>, ...args: A): AsyncIterable<O>;

package/util/transform.js

@@ -1,46 +1,41 @@
-import { isFunction } from "./function.js";
-import { getProps, isObject } from "./object.js";
-/** Is an unknown value a transformable. */
-export const isTransformable = (value) => isObject(value) && typeof value.transform === "function";
-export function transform(input, transformer, ...args) {
-    return isFunction(transformer) ? transformer(input, ...args) : isTransformable(transformer) ? transformer.transform(input, ...args) : transformer;
-}
-export function* mapItems(items, transformer, ...args) {
+import { getProps } from "./object.js";
+export function* mapItems(items, transform, ...args) {
     for (const item of items)
-        yield transform(item, transformer, ...args);
+        yield transform(item, ...args);
 }
-export function mapArray(arr, transformer, ...args) {
-    return Array.from(mapItems(arr, transformer, ...args));
+export function mapArray(arr, transform, ...args) {
+    return Array.from(mapItems(arr, transform, ...args));
 }
-export function mapObject(obj, transformer, ...args) {
-    return Object.fromEntries(mapEntries(getProps(obj), transformer, ...args));
+export function mapObject(obj, transform, ...args) {
+    return Object.fromEntries(mapEntries(getProps(obj), transform, ...args));
 }
-/** Modify the values of a dictionary using a transformer. */
+/** Modify the values of a dictionary using a transform. */
 export const mapDictionary = mapObject;
-/** Modify the values of a set of entries using a transformer. */
-export function* mapEntries(entries, transformer, ...args) {
+/** Modify the values of a set of entries using a transform. */
+export function* mapEntries(entries, transform, ...args) {
     for (const [k, v] of entries)
-        yield [k, transform(v, transformer, ...args)];
+        yield [k, transform(v, ...args)];
 }
 export function transformObject(input, transforms, ...args) {
     let changed = false;
     const output = { ...input };
     for (const [k, t] of getProps(transforms)) {
-        // if (t !== undefined) {
-        const i = input[k];
-        const o = transform(i, t, ...args);
-        if (t === undefined) {
-            delete output[k];
-        }
-        else {
-            output[k] = o;
-            if (!changed && i !== o)
-                changed = true;
+        if (t) {
+            const i = input[k];
+            const o = t(i, ...args);
+            if (t === undefined) {
+                delete output[k];
+            }
+            else {
+                output[k] = o;
+                if (!changed && i !== o)
+                    changed = true;
+            }
         }
     }
     return changed ? output : input;
 }
-export async function* mapSequence(sequence, transformer, ...args) {
+export async function* mapSequence(sequence, transform, ...args) {
     for await (const item of sequence)
-        yield transform(item, transformer, ...args);
+        yield transform(item, ...args);
 }

package/util/update.d.ts

@@ -0,0 +1,22 @@
+import type { ImmutableArray } from "./array.js";
+import type { Data, FlatData, FlatDataKey } from "./data.js";
+/** Set of named updates for a data object. */
+export type Updates<T extends Data = Data> = {
+    readonly [K in FlatDataKey<T> as K | `${K}`]?: FlatData<T>[K];
+} & {
+    readonly [K in FlatDataKey<T> as `${K}+=` | `${K}-=`]?: FlatData<T>[K] extends number ? FlatData<T>[K] : never;
+};
+/** A single update to a keyed property in an object. */
+export type Update = {
+    action: "set";
+    keys: ImmutableArray<string>;
+    value: unknown;
+} | {
+    action: "sum";
+    keys: ImmutableArray<string>;
+    value: number;
+};
+/** Yield the prop updates in an `Updates` object as a set of `Update` objects. */
+export declare function getUpdates<T extends Data>(data: Updates<T>): ImmutableArray<Update>;
+/** Update a data object with a set of updates. */
+export declare function updateData<T extends Data>(data: T, updates: Updates<T>): T;

package/util/update.js

@@ -0,0 +1,42 @@
+import { AssertionError } from "../error/AssertionError.js";
+import { reduceItems } from "./iterate.js";
+import { getNumber } from "./number.js";
+import { getProps, isObject } from "./object.js";
+/** Yield the prop updates in an `Updates` object as a set of `Update` objects. */
+export function getUpdates(data) {
+    return getProps(data).map(_getUpdate);
+}
+function _getUpdate([keys, value]) {
+    if (keys.endsWith("+="))
+        return { action: "sum", keys: keys.slice(0, -2).split("."), value: getNumber(value) };
+    else if (keys.endsWith("-="))
+        return { action: "sum", keys: keys.slice(0, -2).split("."), value: 0 - getNumber(value) };
+    else
+        return { action: "set", keys: keys.split("."), value };
+}
+/** Update a data object with a set of updates. */
+export function updateData(data, updates) {
+    return reduceItems(getUpdates(updates), _updateProp, data);
+}
+function _updateProp(obj, update, i = 0) {
+    const { action, keys, value } = update;
+    const key = keys[i];
+    if (!key)
+        return obj; // Shouldn't happen.
+    const oldValue = obj[key];
+    let newValue = oldValue;
+    if (i === keys.length - 1) {
+        if (action === "sum")
+            newValue = typeof oldValue === "number" ? oldValue + value : value;
+        else if (action === "set")
+            newValue = value;
+        else
+            return action; // Never happens.
+    }
+    else {
+        if (!isObject(oldValue))
+            throw new AssertionError(`Prop "${keys.slice(0, i + 1).join(".")}" is not an object`);
+        newValue = _updateProp(oldValue, update, i + 1);
+    }
+    return oldValue === newValue ? obj : { ...obj, [key]: newValue };
+}

package/util/validate.js

@@ -105,10 +105,10 @@ export function validateDictionary(unsafeDictionary, validator) {
  * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
  */
 export function validateData(unsafeData, validators) {
-    const { partial = false } = getValidationContext();
+    const { partial = false, id = false } = getValidationContext();
     let valid = true;
     let changed = true;
-    const safeData = {};
+    const safeData = id && typeof unsafeData.id === "string" ? { id: unsafeData.id } : {};
     const feedbacks = {};
     for (const [key, validator] of getDataProps(validators)) {
         const unsafeValue = unsafeData[key];

package/constraint/Constraint.d.ts

@@ -1,7 +0,0 @@
-import type { Data } from "../util/data.js";
-import type { Transformable } from "../util/transform.js";
-/** Something that can be used to constrain a query. */
-export declare abstract class Constraint<T extends Data> implements Transformable<Iterable<T>, Iterable<T>> {
-    abstract transform(items: Iterable<T>): Iterable<T>;
-    abstract toString(): string;
-}

package/constraint/Constraint.js

@@ -1,3 +0,0 @@
-/** Something that can be used to constrain a query. */
-export class Constraint {
-}

package/constraint/Constraints.d.ts

@@ -1,20 +0,0 @@
-import type { ImmutableArray } from "../util/array.js";
-import type { Data } from "../util/data.js";
-import { Constraint } from "./Constraint.js";
-/** Type of Rule that is powered by several sub-constraints (e.g. `Filters` and `Sorts` and `Query` itself extend this). */
-export declare abstract class Constraints<T extends Data, C extends Constraint<Partial<T>>> extends Constraint<T> implements Iterable<C> {
-    protected readonly _constraints: ImmutableArray<C>;
-    /** Get the first constraint. */
-    get first(): C | undefined;
-    /** Get the last constraint. */
-    get last(): C | undefined;
-    /** Get the number of constraints. */
-    get size(): number;
-    constructor(...constraints: C[]);
-    /** Clone this set of constraints but add additional constraints. */
-    with(...constraints: C[]): this;
-    /** Clone this set of constraints but remove specific constraints. */
-    omit(...constraints: C[]): this;
-    /** Iterate over the constraints. */
-    [Symbol.iterator](): Iterator<C, void>;
-}