shelving 1.71.1 → 1.73.1

package/{query/Rule.d.ts → constraint/Constraint.d.ts}

@@ -1,7 +1,7 @@
 import type { Data } from "../util/data.js";
 import type { Transformable } from "../util/transform.js";
-/** Something that can be used to query against a result set or an array of entries. */
-export declare abstract class Rule<T extends Data> implements Transformable<Iterable<T>, Iterable<T>> {
+/** 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

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

package/constraint/Constraints.d.ts

@@ -0,0 +1,20 @@
+import type { Data } from "../util/data.js";
+import { ImmutableArray } from "../util/array.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<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. */
+    without(...constraints: C[]): this;
+    /** Iterate over the constraints. */
+    [Symbol.iterator](): Iterator<C, void>;
+}

package/constraint/Constraints.js

@@ -0,0 +1,35 @@
+import { withItems, withoutItems } from "../util/array.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 class Constraints extends Constraint {
+    constructor(...constraints) {
+        super();
+        this._constraints = constraints;
+    }
+    /** Get the first constraint. */
+    get first() {
+        return this._constraints[0];
+    }
+    /** Get the last constraint. */
+    get last() {
+        return this._constraints[this._constraints.length - 1];
+    }
+    /** Get the number of constraints. */
+    get size() {
+        return this._constraints.length;
+    }
+    /** Clone this set of constraints but add additional constraints. */
+    with(...constraints) {
+        const _constraints = withItems(this._constraints, constraints);
+        return _constraints !== this._constraints ? { __proto__: Object.getPrototypeOf(this), ...this, _constraints: _constraints } : this;
+    }
+    /** Clone this set of constraints but remove specific constraints. */
+    without(...constraints) {
+        const _constraints = withoutItems(this._constraints, constraints);
+        return _constraints !== this._constraints ? { __proto__: Object.getPrototypeOf(this), ...this, _constraints: _constraints } : this;
+    }
+    /** Iterate over the constraints. */
+    [Symbol.iterator]() {
+        return this._constraints.values();
+    }
+}

package/{query/Filter.d.ts → constraint/FilterConstraint.d.ts}

@@ -1,7 +1,8 @@
 import { ArrayType, ImmutableArray } from "../util/array.js";
 import { Data, Key } from "../util/data.js";
 import { Matchable } from "../util/match.js";
-import { Rule } from "./Rule.js";
+import { NotString } from "../util/string.js";
+import { Constraint } from "./Constraint.js";
 /** Possible operator references. */
 export declare type FilterOperator = "IS" | "NOT" | "IN" | "OUT" | "CONTAINS" | "LT" | "LTE" | "GT" | "GTE";
 /** Format that allows filters to be specified as a string, e.g. `!name` means `name is not` and `age>` means `age is more than` and `tags[]` means `tags array contains` */
@@ -14,21 +15,24 @@ export declare type FilterProps<T extends Data> = {
 } & {
     [K in Key<T> as `${K}<` | `${K}<=` | `${K}>` | `${K}>=`]?: T[K];
 };
+/** List of filters in a flexible format. */
+export declare type FilterList<T extends Data> = FilterProps<T> | FilterConstraint<T> | Iterable<FilterList<T> & NotString>;
 /**
- * Filter: filters a list of documents.
+ * Filter: filters a list of data.
  *
- * @param key The name of a property that might exist on documents in the collection.
+ * @param key The name of a property that might exist on data in the collection.
  * @param operator FilterOperator, e.g. `IS` or `CONTAINS`
  * @param value Value the specified property should be matched against.
  */
-export declare class Filter<T extends Data> extends Rule<T> implements Matchable<T, void> {
-    /** Parse a set of FilterProps and return the corresponding array of `Filter` instances. */
-    static on<X extends Data>(key: FilterKey<X>, value: unknown): Filter<X>;
-    readonly key: Key<T>;
+export declare class FilterConstraint<T extends Data = Data> implements Constraint<T>, Matchable<T, void> {
+    readonly key: string;
     readonly operator: FilterOperator;
     readonly value: unknown;
-    constructor(key: Key<T>, operator: FilterOperator, value: unknown);
+    get filterKey(): string;
+    constructor(filterKey: FilterKey<T>, value: unknown);
     match(item: T): boolean;
     transform(items: Iterable<T>): Iterable<T>;
     toString(): string;
 }
+/** Get the separate filters generated from a list of filters. */
+export declare function getFilters<T extends Data>(filters: FilterList<T>): Iterable<FilterConstraint<T>>;

package/constraint/FilterConstraint.js

@@ -0,0 +1,96 @@
+import { isArray } from "../util/array.js";
+import { isArrayWith, isEqual, isEqualGreater, isEqualLess, isGreater, isInArray, isLess, notEqual, notInArray } from "../util/match.js";
+import { filterItems } from "../util/filter.js";
+import { isIterable } from "../util/iterate.js";
+/** Map `FilterOperator` to its corresponding `Match` function. */
+const MATCHERS = {
+    IS: isEqual,
+    NOT: notEqual,
+    IN: isInArray,
+    OUT: notInArray,
+    CONTAINS: isArrayWith,
+    LT: isLess,
+    LTE: isEqualLess,
+    GT: isGreater,
+    GTE: isEqualGreater,
+};
+/**
+ * Filter: filters a list of data.
+ *
+ * @param key The name of a property that might exist on data in the collection.
+ * @param operator FilterOperator, e.g. `IS` or `CONTAINS`
+ * @param value Value the specified property should be matched against.
+ */
+export class FilterConstraint {
+    constructor(filterKey, value) {
+        if (filterKey.startsWith("!")) {
+            this.key = filterKey.slice(1);
+            this.operator = isArray(value) ? "OUT" : "NOT";
+        }
+        else if (filterKey.endsWith(">")) {
+            this.key = filterKey.slice(0, -1);
+            this.operator = "GT";
+        }
+        else if (filterKey.endsWith(">=")) {
+            this.key = filterKey.slice(0, -2);
+            this.operator = "GTE";
+        }
+        else if (filterKey.endsWith("<")) {
+            this.key = filterKey.slice(0, -1);
+            this.operator = "LT";
+        }
+        else if (filterKey.endsWith("<=")) {
+            this.key = filterKey.slice(0, -2);
+            this.operator = "LTE";
+        }
+        else if (filterKey.endsWith("[]")) {
+            this.key = filterKey.slice(0, -2);
+            this.operator = "CONTAINS";
+        }
+        else {
+            this.key = filterKey;
+            this.operator = isArray(value) ? "IN" : "IS";
+        }
+        this.value = value;
+    }
+    get filterKey() {
+        const { operator, key } = this;
+        if (operator === "NOT" || operator === "OUT")
+            return `!${key}`;
+        else if (operator === "CONTAINS")
+            return `${key}[]`;
+        else if (operator === "LT")
+            return `${key}<`;
+        else if (operator === "LTE")
+            return `${key}<=`;
+        else if (operator === "GT")
+            return `${key}>`;
+        else if (operator === "GTE")
+            return `${key}>=`;
+        else
+            return key;
+    }
+    match(item) {
+        return MATCHERS[this.operator](item[this.key], this.value);
+    }
+    transform(items) {
+        return filterItems(items, this);
+    }
+    toString() {
+        return `"${this.filterKey}":${JSON.stringify(this.value)}`;
+    }
+}
+/** Get the separate filters generated from a list of filters. */
+export function* getFilters(filters) {
+    if (filters instanceof FilterConstraint) {
+        yield filters;
+    }
+    else if (isIterable(filters)) {
+        for (const filter of filters)
+            yield* getFilters(filter);
+    }
+    else {
+        for (const [key, value] of Object.entries(filters))
+            yield new FilterConstraint(key, value);
+    }
+}

package/constraint/FilterConstraints.d.ts

@@ -0,0 +1,22 @@
+import type { Data } from "../util/data.js";
+import type { Matchable } from "../util/match.js";
+import { FilterList, FilterProps, FilterConstraint } from "./FilterConstraint.js";
+import { Constraints } from "./Constraints.js";
+/**
+ * Interface to make sure an object implements all matchers.
+ * - Extends `Matchable` so this object itself can be directly be used in `filterItems()` and `filterEntries()`
+ */
+export interface Filterable<T extends Data> extends Matchable<T, void> {
+    /** Add a filter to this filterable. */
+    filter(props: FilterProps<T>): this;
+    /** Match an item against the filters specified for this object. */
+    match(item: T): boolean;
+}
+/** A set of filters. */
+export declare class FilterConstraints<T extends Data = Data> extends Constraints<T, FilterConstraint<T>> implements Filterable<T> {
+    constructor(...filters: FilterList<T>[]);
+    filter(...filters: FilterList<T>[]): this;
+    match(item: T): boolean;
+    transform(items: Iterable<T>): Iterable<T>;
+    toString(): string;
+}

package/constraint/FilterConstraints.js

@@ -0,0 +1,27 @@
+import { filterItems } from "../util/filter.js";
+import { getFilters } from "./FilterConstraint.js";
+import { Constraints } from "./Constraints.js";
+/** A set of filters. */
+export class FilterConstraints extends Constraints {
+    constructor(...filters) {
+        super(...getFilters(filters));
+    }
+    // Implement `Filterable`
+    filter(...filters) {
+        return this.with(...getFilters(filters));
+    }
+    match(item) {
+        for (const rule of this._constraints)
+            if (!rule.match(item))
+                return false;
+        return true;
+    }
+    // Implement `Rule`
+    transform(items) {
+        return this._constraints.length ? filterItems(items, this) : items;
+    }
+    // Stringify as object syntax.
+    toString() {
+        return `{${this._constraints.map(String).join(",")}`;
+    }
+}

package/{query/Query.d.ts → constraint/QueryConstraints.d.ts}

@@ -1,13 +1,13 @@
-import { Data, Key } from "../util/data.js";
-import type { ArrayType, ImmutableArray } from "../util/array.js";
-import { Filterable, Filters } from "./Filters.js";
-import { Sortable, Sorts } from "./Sorts.js";
-import { Rule } from "./Rule.js";
-import { FilterProps } from "./Filter.js";
-import { SortKey, SortKeys } from "./Sort.js";
+import { Data } from "../util/data.js";
+import { Filterable, FilterConstraints } from "./FilterConstraints.js";
+import { Sortable, SortConstraints } from "./SortConstraints.js";
+import { Constraint } from "./Constraint.js";
+import { FilterList } from "./FilterConstraint.js";
+import { SortKeys, SortList } from "./SortConstraint.js";
 /** Set of props for a query defined as an object. */
-export declare type QueryProps<T extends Data> = FilterProps<T> & {
-    readonly sort?: SortKey<T> | ImmutableArray<SortKey<T>>;
+export declare type QueryProps<T extends Data> = {
+    readonly filter?: FilterList<T>;
+    readonly sort?: SortList<T>;
     readonly limit?: number | null;
 };
 /** Interface that combines Filterable, Sortable, Sliceable. */
@@ -24,9 +24,9 @@ export interface Queryable<T extends Data> extends Filterable<T>, Sortable<T> {
     /** Return a new instance of this class with a before offset defined. */
     before(item: T): this;
     /** Return a new instance of this class with no filters specified. */
-    unfilter: this;
+    readonly unfilter: this;
     /** Return a new instance of this class with no sorts specified. */
-    unsort: this;
+    readonly unsort: this;
     /** The maximum number of items allowed by the limit. */
     readonly limit: number | null;
     /** Return a new instance of this class with a limit set. */
@@ -35,17 +35,12 @@ export interface Queryable<T extends Data> extends Filterable<T>, Sortable<T> {
     query(query: QueryProps<T>): this;
 }
 /** Allows filtering, sorting, and limiting on a set of results. */
-export declare class Query<T extends Data> extends Rule<T> implements Queryable<T> {
-    /** Create a new `Query` object from a set of `QueryProps` */
-    static on<X extends Data>({ sort, limit, ...filters }: QueryProps<X>): Query<X>;
-    readonly filters: Filters<T>;
-    readonly sorts: Sorts<T>;
+export declare class QueryConstraints<T extends Data = Data> extends Constraint<T> implements Queryable<T> {
+    readonly filters: FilterConstraints<T>;
+    readonly sorts: SortConstraints<T>;
     readonly limit: number | null;
-    constructor(filters?: Filters<T>, sorts?: Sorts<T>, limit?: number | null);
-    filter(props: FilterProps<T>): this;
-    filter<K extends Key<T>>(key: `${K}` | `!${K}` | `${K}>` | `${K}>=` | `${K}<` | `${K}<=`, value: T[K]): this;
-    filter<K extends Key<T>>(key: `${K}` | `!${K}`, value: ImmutableArray<T[K]>): this;
-    filter<K extends Key<T>>(key: `${K}[]`, value: T[K] extends ImmutableArray ? ArrayType<T[K]> : never): this;
+    constructor({ filter, sort, limit }?: QueryProps<T>);
+    filter(...filters: FilterList<T>[]): this;
     get unfilter(): this;
     match(item: T): boolean;
     sort(...keys: SortKeys<T>[]): this;
@@ -54,7 +49,7 @@ export declare class Query<T extends Data> extends Rule<T> implements Queryable<
     after(item: T): this;
     before(item: T): this;
     max(limit: number | null): this;
-    query({ sort, limit, ...filters }: QueryProps<T>): this;
+    query({ sort, limit, filter }: QueryProps<T>): this;
     transform(items: Iterable<T>): Iterable<T>;
     toString(): string;
 }

package/constraint/QueryConstraints.js

@@ -0,0 +1,120 @@
+import { getProp } from "../util/data.js";
+import { assert } from "../util/assert.js";
+import { limitItems } from "../util/iterate.js";
+import { FilterConstraints } from "./FilterConstraints.js";
+import { SortConstraints } from "./SortConstraints.js";
+import { Constraint } from "./Constraint.js";
+import { FilterConstraint } from "./FilterConstraint.js";
+// Instances to save resources for the default case (empty query).
+const EMPTY_FILTERS = new FilterConstraints(); // eslint-disable-line @typescript-eslint/no-explicit-any
+const EMPTY_SORTS = new SortConstraints(); // eslint-disable-line @typescript-eslint/no-explicit-any
+const EMPTY_PROPS = { filter: EMPTY_FILTERS, sort: EMPTY_SORTS, limit: null }; // eslint-disable-line @typescript-eslint/no-explicit-any
+/** Allows filtering, sorting, and limiting on a set of results. */
+export class QueryConstraints extends Constraint {
+    constructor({ filter = EMPTY_FILTERS, sort = EMPTY_SORTS, limit = null } = EMPTY_PROPS) {
+        super();
+        this.filters = filter instanceof FilterConstraints ? filter : new FilterConstraints(filter);
+        this.sorts = sort instanceof SortConstraints ? sort : new SortConstraints(sort);
+        this.limit = limit;
+    }
+    // Implement `Filterable`
+    filter(...filters) {
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            filters: this.filters.filter(...filters),
+        };
+    }
+    get unfilter() {
+        if (!this.filters.size)
+            return this;
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            filters: EMPTY_FILTERS,
+        };
+    }
+    match(item) {
+        return this.filters.match(item);
+    }
+    // Implement `Sortable`
+    sort(...keys) {
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            sorts: this.sorts.sort(...keys),
+        };
+    }
+    get unsort() {
+        if (!this.sorts.size)
+            return this;
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            sorts: EMPTY_SORTS,
+        };
+    }
+    rank(left, right) {
+        return this.sorts.rank(left, right);
+    }
+    // Implement `Queryable`
+    after(item) {
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            filters: this.filters.with(..._getAfterFilters(this.sorts, item)),
+        };
+    }
+    before(item) {
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            filters: this.filters.with(..._getBeforeFilters(this.sorts, item)),
+        };
+    }
+    max(limit) {
+        if (this.limit === limit)
+            return this;
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            limit,
+        };
+    }
+    query({ sort, limit, filter }) {
+        return {
+            __proto__: Object.getPrototypeOf(this),
+            ...this,
+            filters: filter ? this.filters.filter(filter) : this.filters,
+            sorts: sort ? this.sorts.sort(sort) : this.sorts,
+            limit: limit !== undefined ? limit : this.limit,
+        };
+    }
+    // Implement `Rule`
+    transform(items) {
+        const sorted = this.sorts.transform(this.filters.transform(items));
+        return typeof this.limit === "number" ? limitItems(sorted, this.limit) : sorted;
+    }
+    // Implement toString()
+    toString() {
+        return `{"filter":${this.filters.toString()}},"sort":${this.sorts.toString()},"limit":${this.limit}}`;
+    }
+}
+function* _getAfterFilters(sorts, item) {
+    const lastSort = sorts.last;
+    assert(lastSort);
+    for (const sort of sorts) {
+        const { key, direction } = sort;
+        const filterKey = direction === "ASC" ? (sort === lastSort ? `${key}>` : `${key}>=`) : sort === lastSort ? `${key}<` : `${key}<=`;
+        yield new FilterConstraint(filterKey, getProp(item, key));
+    }
+}
+function* _getBeforeFilters(sorts, item) {
+    const lastSort = sorts.last;
+    assert(lastSort);
+    for (const sort of sorts) {
+        const { key, direction } = sort;
+        const filterKey = direction === "ASC" ? (sort === lastSort ? `${key}<` : `${key}<=`) : sort === lastSort ? `${key}>` : `${key}>=`;
+        yield new FilterConstraint(filterKey, getProp(item, key));
+    }
+}

package/{query/Sort.d.ts → constraint/SortConstraint.d.ts}

@@ -1,21 +1,24 @@
 import type { ImmutableArray } from "../util/array.js";
 import { Data, Key } from "../util/data.js";
 import { Rankable } from "../util/sort.js";
-import { Rule } from "./Rule.js";
+import { Constraint } from "./Constraint.js";
 /** Format that allows sorts to be set as a plain string, e.g. `name` sorts by name in ascending order and `!date` sorts by date in descending order. */
 export declare type SortKey<T extends Data> = Key<T> | `${Key<T>}` | `!${Key<T>}`;
 /** One or more sort keys. */
 export declare type SortKeys<T extends Data> = SortKey<T> | ImmutableArray<SortKey<T>>;
 /** Possible operator references. */
 export declare type SortDirection = "ASC" | "DESC";
+/** List of sorts in a flexible format. */
+export declare type SortList<T extends Data> = SortKeys<T> | SortConstraint<T> | Iterable<SortList<T>>;
 /** Sort a list of values. */
-export declare class Sort<T extends Data> extends Rule<T> implements Rankable<T> {
-    /** Create a sort on a specified field. */
-    static on<X extends Data>(sort: SortKey<X> | Sort<X>): Sort<X>;
-    readonly key: Key<T>;
+export declare class SortConstraint<T extends Data = Data> implements Constraint<T>, Rankable<T> {
+    readonly key: string;
     readonly direction: SortDirection;
-    constructor(key: Key<T>, direction: SortDirection);
+    get sortKey(): string;
+    constructor(sortKey: SortKey<T>);
     rank(left: T, right: T): number;
     transform(items: Iterable<T>): Iterable<T>;
     toString(): string;
 }
+/** Get the separate sorts generated from a list of sorts. */
+export declare function getSorts<T extends Data>(sorts: SortList<T>): Iterable<SortConstraint<T>>;

package/constraint/SortConstraint.js

@@ -0,0 +1,40 @@
+import { getProp } from "../util/data.js";
+import { rank, rankAsc, rankDesc, sortItems } from "../util/sort.js";
+/** Sort a list of values. */
+export class SortConstraint {
+    constructor(sortKey) {
+        if (sortKey.startsWith("!")) {
+            this.key = sortKey.slice(1);
+            this.direction = "DESC";
+        }
+        else {
+            this.key = sortKey;
+            this.direction = "ASC";
+        }
+    }
+    get sortKey() {
+        return `"${this.direction === "DESC" ? "!" : ""}${this.key}"`;
+    }
+    rank(left, right) {
+        return rank(getProp(left, this.key), this.direction === "ASC" ? rankAsc : rankDesc, getProp(right, this.key));
+    }
+    transform(items) {
+        return sortItems(items, this);
+    }
+    toString() {
+        return this.sortKey;
+    }
+}
+/** Get the separate sorts generated from a list of sorts. */
+export function* getSorts(sorts) {
+    if (typeof sorts === "string") {
+        yield new SortConstraint(sorts);
+    }
+    else if (sorts instanceof SortConstraint) {
+        yield sorts;
+    }
+    else {
+        for (const sort of sorts)
+            yield* getSorts(sort);
+    }
+}

package/constraint/SortConstraints.d.ts

@@ -0,0 +1,20 @@
+import type { Data } from "../util/data.js";
+import { Rankable } from "../util/sort.js";
+import { Constraints } from "./Constraints.js";
+import { SortConstraint, SortKeys, SortList } from "./SortConstraint.js";
+/**
+ * Interface to make sure an object implements all directions.
+ * - Extends `Rankable` so this object itself can be directly be used with `filterItems()` and `filterEntries()`
+ */
+export interface Sortable<T extends Data> extends Rankable<T> {
+    /** Add one or more sorts to this sortable. */
+    sort(...keys: SortKeys<T>[]): this;
+}
+/** A set of sorts. */
+export declare class SortConstraints<T extends Data = Data> extends Constraints<T, SortConstraint<T>> implements Sortable<T> {
+    constructor(...sorts: SortList<T>[]);
+    sort(...sorts: SortList<T>[]): this;
+    rank(left: T, right: T): number;
+    transform(items: Iterable<T>): Iterable<T>;
+    toString(): string;
+}

package/constraint/SortConstraints.js

@@ -0,0 +1,29 @@
+import { sortItems } from "../util/sort.js";
+import { Constraints } from "./Constraints.js";
+import { getSorts } from "./SortConstraint.js";
+/** A set of sorts. */
+export class SortConstraints extends Constraints {
+    constructor(...sorts) {
+        super(...getSorts(sorts));
+    }
+    // Implement `Sortable`
+    sort(...sorts) {
+        return this.with(...getSorts(sorts));
+    }
+    rank(left, right) {
+        for (const rule of this._constraints) {
+            const l = rule.rank(left, right);
+            if (l !== 0)
+                return l;
+        }
+        return 0;
+    }
+    // Implement `Rule`
+    transform(items) {
+        return this._constraints.length ? sortItems(items, this) : items;
+    }
+    // Stringify as array syntax.
+    toString() {
+        return `[${this._constraints.map(String).join(",")}]`;
+    }
+}

package/constraint/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./Constraint.js";
+export * from "./Constraints.js";
+export * from "./FilterConstraint.js";
+export * from "./FilterConstraints.js";
+export * from "./SortConstraint.js";
+export * from "./SortConstraints.js";
+export * from "./QueryConstraints.js";

package/constraint/index.js

@@ -0,0 +1,7 @@
+export * from "./Constraint.js";
+export * from "./Constraints.js";
+export * from "./FilterConstraint.js";
+export * from "./FilterConstraints.js";
+export * from "./SortConstraint.js";
+export * from "./SortConstraints.js";
+export * from "./QueryConstraints.js";

package/db/Changes.d.ts

@@ -0,0 +1,22 @@
+import type { Datas, Key } from "../util/data.js";
+import { DataUpdate } from "../update/DataUpdate.js";
+import type { Provider, AsyncProvider } from "../provider/Provider.js";
+import type { Database, AsyncDatabase } from "./Database.js";
+/**
+ * Change set of operations to run against a database in `{ "collection/id": data | DataUpdate | null }`  format.
+ * - If data is an object, sets the item.
+ * - If data is a `DataUpdate` instance, updates the item.
+ * - If data is null, deletes the item.
+ * - If data is undefined, skip the item.
+ */
+export declare type Changes<DB extends Datas> = {
+    [K in Key<DB> as `${K}/${string}`]: DB[K] | DataUpdate<DB[K]> | null | undefined;
+};
+/** Apply a set of changes to a synchronous database. */
+export declare function changeDatabase<T extends Datas>({ provider }: Database<T>, changes: Changes<T>): Changes<T>;
+/** Apply a set of changes to an asynchronous database. */
+export declare function changeAsyncDatabase<T extends Datas>({ provider }: AsyncDatabase<T>, changes: Changes<T>): Promise<Changes<T>>;
+/** Apply a set of changes to a synchronous provider. */
+export declare function changeProvider<T extends Datas>(provider: Provider<T>, changes: Changes<T>): Changes<T>;
+/** Apply a set of changes to an asynchronous provider. */
+export declare function changeAsyncProvider<T extends Datas>(provider: AsyncProvider<T>, changes: Changes<T>): Promise<Changes<T>>;

package/db/Changes.js

@@ -0,0 +1,40 @@
+import { splitString } from "../util/string.js";
+import { DataUpdate } from "../update/DataUpdate.js";
+/** Apply a set of changes to a synchronous database. */
+export function changeDatabase({ provider }, changes) {
+    return changeProvider(provider, changes);
+}
+/** Apply a set of changes to an asynchronous database. */
+export function changeAsyncDatabase({ provider }, changes) {
+    return changeAsyncProvider(provider, changes);
+}
+/** Apply a set of changes to a synchronous provider. */
+export function changeProvider(provider, changes) {
+    for (const [key, change] of Object.entries(changes)) {
+        const [collection, id] = splitString(key, "/", 2);
+        if (change === undefined)
+            continue;
+        else if (change === null)
+            provider.deleteItem(collection, id);
+        else if (change instanceof DataUpdate)
+            provider.updateItem(collection, id, change);
+        else
+            provider.setItem(collection, id, change);
+    }
+    return changes;
+}
+/** Apply a set of changes to an asynchronous provider. */
+export async function changeAsyncProvider(provider, changes) {
+    for (const [key, change] of Object.entries(changes)) {
+        const [collection, id] = splitString(key, "/", 2);
+        if (change === undefined)
+            continue;
+        else if (change === null)
+            await provider.deleteItem(collection, id);
+        else if (change instanceof DataUpdate)
+            await provider.updateItem(collection, id, change);
+        else
+            await provider.setItem(collection, id, change);
+    }
+    return changes;
+}

package/db/Changes.test.d.ts

@@ -0,0 +1 @@
+export {};