shelving 1.33.0 → 1.37.0

package/db/Pagination.js

@@ -1,4 +1,4 @@
-import { getLastItem, assertLength, assertNumber, yieldMerged, toMap, LOADING } from "../util/index.js";
+import { getLastItem, assertNumber, yieldMerged, toMap, LOADING, assertMaximum } from "../util/index.js";
 import { State } from "../stream/index.js";
 import { ConditionError } from "../index.js";
 /**
@@ -40,7 +40,7 @@ export class Pagination extends State {
         };
         this.ref = ref;
         assertNumber(ref.limit); // Collection must have a numeric limit to paginate (otherwise you'd be retrieving the entire set of documents).
-        assertLength(ref.sorts, 1, Infinity); // Collection must have at least one sort order to paginate.
+        assertMaximum(ref.sorts.size, 1); // Collection must have at least one sort order to paginate.
         this.limit = ref.limit;
     }
     /**

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.33.0",
+	"version": "1.37.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -63,20 +63,20 @@
 		"@types/jest": "^27.0.3",
 		"@types/react": "^17.0.37",
 		"@types/react-dom": "^17.0.11",
-		"@typescript-eslint/eslint-plugin": "^5.6.0",
-		"@typescript-eslint/parser": "^5.6.0",
-		"eslint": "^8.4.1",
+		"@typescript-eslint/eslint-plugin": "^5.7.0",
+		"@typescript-eslint/parser": "^5.7.0",
+		"eslint": "^8.5.0",
 		"eslint-config-prettier": "^8.3.0",
 		"eslint-plugin-import": "^2.25.3",
 		"eslint-plugin-prettier": "^4.0.0",
 		"firebase": "^9.6.1",
-		"jest": "^27.4.4",
+		"jest": "^27.4.5",
 		"jest-ts-webcompat-resolver": "^1.0.0",
 		"prettier": "^2.5.1",
 		"react": "^17.0.2",
 		"react-dom": "^17.0.2",
-		"ts-jest": "^27.1.1",
-		"typescript": "^4.5.3"
+		"ts-jest": "^27.1.2",
+		"typescript": "^4.5.4"
 	},
 	"peerDependencies": {
 		"@google-cloud/firestore": ">=4.0.0",

package/query/Filters.d.ts

@@ -13,5 +13,6 @@ export declare class Filters<T extends Data> extends Rules<T, Filter<T>> impleme
     gt<K extends QueryKey<T>>(key: K, value: K extends "id" ? string : T[K]): this;
     gte<K extends QueryKey<T>>(key: K, value: K extends "id" ? string : T[K]): this;
     match(entry: Entry<T>): boolean;
+    get unfiltered(): this;
     transform(iterable: Results<T>): Results<T>;
 }

package/query/Filters.js

@@ -3,6 +3,7 @@ import { ArrayContainsFilter, EqualFilter, GreaterThanEqualFilter, GreaterThanFi
 import { Rules } from "./Rules.js";
 /** A set of filters. */
 export class Filters extends Rules {
+    // Implement `Filterable`
     is(key, value) {
         return { __proto__: Object.getPrototypeOf(this), ...this, _rules: [...this._rules, new EqualFilter(key, value)] };
     }
@@ -33,6 +34,10 @@ export class Filters extends Rules {
                 return false;
         return true;
     }
+    get unfiltered() {
+        return { __proto__: Object.getPrototypeOf(this), ...this, _rules: [] };
+    }
+    // Implement `Rule`
     transform(iterable) {
         return this._rules.length ? yieldFiltered(iterable, this) : iterable;
     }

package/query/Query.d.ts

@@ -17,9 +17,11 @@ export declare class Query<T extends Data> extends Rule<T> implements Queryable<
     lte<K extends QueryKey<T>>(key: K, value: K extends "id" ? string : T[K]): this;
     gt<K extends QueryKey<T>>(key: K, value: K extends "id" ? string : T[K]): this;
     gte<K extends QueryKey<T>>(key: K, value: K extends "id" ? string : T[K]): this;
+    get unfiltered(): this;
     match(entry: Entry<T>): boolean;
-    asc(key?: QueryKey<T>): this;
-    desc(key?: QueryKey<T>): this;
+    asc(key: QueryKey<T>): this;
+    desc(key: QueryKey<T>): this;
+    get unsorted(): this;
     rank(left: Entry<T>, right: Entry<T>): number;
     /** Return a new instance of this class with a limit defined. */
     max(limit: number | null): this;

package/query/Query.js

@@ -40,16 +40,22 @@ export class Query extends Rule {
     gte(key, value) {
         return { __proto__: Object.getPrototypeOf(this), ...this, filters: this.filters.gte(key, value) };
     }
+    get unfiltered() {
+        return { __proto__: Object.getPrototypeOf(this), ...this, filters: this.filters.unfiltered };
+    }
     match(entry) {
         return this.filters.match(entry);
     }
     // Implement `Sortable`
-    asc(key = "id") {
+    asc(key) {
         return { __proto__: Object.getPrototypeOf(this), ...this, sorts: this.sorts.asc(key) };
     }
-    desc(key = "id") {
+    desc(key) {
         return { __proto__: Object.getPrototypeOf(this), ...this, sorts: this.sorts.desc(key) };
     }
+    get unsorted() {
+        return { __proto__: Object.getPrototypeOf(this), ...this, sorts: this.sorts.unsorted };
+    }
     rank(left, right) {
         return this.sorts.rank(left, right);
     }

package/query/Rules.d.ts

@@ -8,7 +8,7 @@ export declare abstract class Rules<T extends Data, R extends Rule<T>> extends R
     /** Get the last rule. */
     get last(): R | undefined;
     /** Get the number of rules. */
-    get length(): number;
+    get size(): number;
     constructor(...rules: R[]);
     toString(): string;
     /** Iterate over the rules. */

package/query/Rules.js

@@ -15,7 +15,7 @@ export class Rules extends Rule {
         return this._rules[this._rules.length - 1];
     }
     /** Get the number of rules. */
-    get length() {
+    get size() {
         return this._rules.length;
     }
     toString() {

package/query/Sorts.d.ts

@@ -6,6 +6,7 @@ import { Rules } from "./Rules.js";
 export declare class Sorts<T extends Data> extends Rules<T, Sort<T>> implements Sortable<T> {
     asc(key: QueryKey<T>): this;
     desc(key: QueryKey<T>): this;
+    get unsorted(): this;
     rank(left: Entry<T>, right: Entry<T>): number;
     transform(iterable: Results<T>): Results<T>;
 }

package/query/Sorts.js

@@ -3,20 +3,25 @@ import { AscendingSort, DescendingSort } from "./Sort.js";
 import { Rules } from "./Rules.js";
 /** A set of sorts. */
 export class Sorts extends Rules {
+    // Implement `Sortable`
     asc(key) {
         return { __proto__: Object.getPrototypeOf(this), ...this, _rules: [...this._rules, new AscendingSort(key)] };
     }
     desc(key) {
         return { __proto__: Object.getPrototypeOf(this), ...this, _rules: [...this._rules, new DescendingSort(key)] };
     }
+    get unsorted() {
+        return { __proto__: Object.getPrototypeOf(this), ...this, _rules: [] };
+    }
     rank(left, right) {
-        for (const rule of this) {
+        for (const rule of this._rules) {
             const l = rule.rank(left, right);
             if (l !== 0)
                 return l;
         }
         return 0;
     }
+    // Implement `Rule`
     transform(iterable) {
         return this._rules.length ? sortItems(iterable, this) : iterable;
     }

package/query/types.d.ts

@@ -16,6 +16,9 @@ export interface Filterable<T extends Data> extends Matchable<Entry<T>, void> {
     lte<K extends QueryKey<T>>(key: K, value: K extends "id" ? string : T[K]): this;
     gt<K extends QueryKey<T>>(key: K, value: K extends "id" ? string : T[K]): this;
     gte<K extends QueryKey<T>>(key: K, value: K extends "id" ? string : T[K]): this;
+    /** Return a new instance of this class with no sorts specified. */
+    unfiltered: this;
+    /** Match an entry against the filters specified for this object. */
     match(entry: Entry<T>): boolean;
 }
 /**
@@ -24,9 +27,11 @@ export interface Filterable<T extends Data> extends Matchable<Entry<T>, void> {
  */
 export interface Sortable<T extends Data> extends Rankable<Entry<T>> {
     /** Return a new instance of this class with an ascending order sort defined. */
-    asc(key?: QueryKey<T>): this;
+    asc(key: QueryKey<T>): this;
     /** Return a new instance of this class with a descending order sort defined. */
-    desc(key?: QueryKey<T>): this;
+    desc(key: QueryKey<T>): this;
+    /** Return a new instance of this class with no sorts specified. */
+    unsorted: this;
 }
 /** Possible operator references. */
 export declare type SortDirection = "ASC" | "DESC";

package/stream/ArrayState.d.ts

@@ -3,8 +3,8 @@ import { State } from "./State.js";
 /** State that stores an array and has additional methods to help with that. */
 export declare class ArrayState<T> extends State<ImmutableArray<T>> implements Iterable<T> {
     _value: never[];
-    /** Count the number of entries in this map-like object. */
-    get count(): number;
+    /** Get the length of the current value of this state. */
+    get length(): number;
     /** Add an item to this array. */
     add(item: T): void;
     /** Remove an item from this array. */

package/stream/ArrayState.js

@@ -1,4 +1,4 @@
-import { swapItem, toggleItem, withItem, withoutItem, countItems } from "../util/index.js";
+import { swapItem, toggleItem, withItem, withoutItem } from "../util/index.js";
 import { State } from "./State.js";
 /** State that stores an array and has additional methods to help with that. */
 export class ArrayState extends State {
@@ -7,9 +7,9 @@ export class ArrayState extends State {
         // Set default value to be empty array.
         this._value = [];
     }
-    /** Count the number of entries in this map-like object. */
-    get count() {
-        return countItems(this.value);
+    /** Get the length of the current value of this state. */
+    get length() {
+        return this.value.length;
     }
     /** Add an item to this array. */
     add(item) {

package/util/array.d.ts

@@ -163,3 +163,15 @@ export declare function removeItems<T>(arr: MutableArray<T>, items: Iterable<T>)
 export declare function uniqueArray<T>(input: Iterable<T>): ImmutableArray<T>;
 /** Apply a limit to an array. */
 export declare function limitArray<T>(arr: ImmutableArray<T>, limit: number): ImmutableArray<T>;
+/** Does an array have the specified minimum length.  */
+export declare function isMinimumLength<T>(arr: ImmutableArray<T>, min?: 1): arr is [T, ...T[]];
+export declare function isMinimumLength<T>(arr: ImmutableArray<T>, min: 2): arr is [T, T, ...T[]];
+export declare function isMinimumLength<T>(arr: ImmutableArray<T>, min: 3): arr is [T, T, T, ...T[]];
+export declare function isMinimumLength<T>(arr: ImmutableArray<T>, min: 4): arr is [T, T, T, T, ...T[]];
+export declare function isMinimumLength<T>(arr: ImmutableArray<T>, min: number): arr is [T, T, T, T, T, ...T[]];
+/** Get an array if it has the specified minimum length.  */
+export declare function getMinimumLength<T>(arr: ImmutableArray<T>, min?: 1): [T, ...T[]];
+export declare function getMinimumLength<T>(arr: ImmutableArray<T>, min: 2): [T, T, ...T[]];
+export declare function getMinimumLength<T>(arr: ImmutableArray<T>, min: 3): [T, T, T, ...T[]];
+export declare function getMinimumLength<T>(arr: ImmutableArray<T>, min: 4): [T, T, T, T, ...T[]];
+export declare function getMinimumLength<T>(arr: ImmutableArray<T>, min: number): [T, T, T, T, T, ...T[]];

package/util/array.js

@@ -1,3 +1,4 @@
+import { AssertionError } from "../error/index.js";
 /** Is an unknown value an array? */
 export const isArray = (v) => v instanceof Array;
 /** Is an unknown value an item in a specified array? */
@@ -244,3 +245,11 @@ export function uniqueArray(input) {
 export function limitArray(arr, limit) {
     return limit > arr.length ? arr : arr.slice(0, limit);
 }
+export function isMinimumLength(arr, min = 1) {
+    return arr.length >= min;
+}
+export function getMinimumLength(arr, min = 1) {
+    if (arr.length >= min)
+        return arr;
+    throw new AssertionError(`Must have minimum length ${min}`, arr);
+}

package/util/assert.d.ts

@@ -24,15 +24,21 @@ export declare function assertProp<K extends string | number | symbol, T extends
     [L in K]: unknown;
 }>(value: T | unknown, key: K): asserts value is T;
 /** Assert that a value is an array. */
-export declare function assertArray<T extends ImmutableArray>(value: T | unknown): asserts value is T;
+export declare function assertArray<T>(value: ImmutableArray<T> | unknown): asserts value is ImmutableArray<T>;
 /** Assert that a value has a specific length (or length is in a specific range). */
-export declare function assertLength<T extends {
-    length: number;
-}>(value: T | unknown, min: number, max?: number): asserts value is T;
+export declare function assertMinimumLength<T>(value: ImmutableArray<T> | unknown, min?: 1): asserts value is [T, ...T[]];
+export declare function assertMinimumLength<T>(value: ImmutableArray<T> | unknown, min: 2): asserts value is [T, T, ...T[]];
+export declare function assertMinimumLength<T>(value: ImmutableArray<T> | unknown, min: 3): asserts value is [T, T, T, ...T[]];
+export declare function assertMinimumLength<T>(value: ImmutableArray<T> | unknown, min: 4): asserts value is [T, T, T, T, ...T[]];
+export declare function assertMinimumLength<T>(value: ImmutableArray<T> | unknown, min: number): asserts value is [T, T, T, T, T, ...T[]];
+/** Assert that a value has a specific length (or length is in a specific range). */
+export declare function assertLength<T>(value: ImmutableArray<T> | unknown, min: number, max?: number): asserts value is ImmutableArray<T>;
+/** Assert that a value is a number greater than. */
+export declare function assertBetween(value: number | unknown, min: number, max: number): asserts value is number;
 /** Assert that a value is a number greater than. */
-export declare function assertGreater(value: number | unknown, target: number): asserts value is number;
+export declare function assertMaximum(value: number | unknown, max: number): asserts value is number;
 /** Assert that a value is a number less than. */
-export declare function assertLess(value: number | unknown, target: number): asserts value is number;
+export declare function assertMinimum(value: number | unknown, min: number): asserts value is number;
 /** Assert that a value is an instance of something. */
 export declare function assertInstance<T>(value: T | unknown, type: Class<T>): asserts value is T;
 /** Assert that a value is a function. */
@@ -42,8 +48,8 @@ export declare function assertValue<T>(value: T | typeof NOVALUE): asserts value
 /** Assert that a value is not the `NOVALUE` constant. */
 export declare function assertDefined<T>(value: T | undefined): asserts value is T;
 /** Expect a synchronous value. */
-export declare function assertSync<T>(value: Promise<T> | T): asserts value is T;
+export declare function assertSynchronous<T>(value: Promise<T> | T): asserts value is T;
 /** Expect an asynchronous value. */
-export declare function assertAsync<T>(value: PromiseLike<T> | T): asserts value is PromiseLike<T>;
+export declare function assertAsynchronous<T>(value: PromiseLike<T> | T): asserts value is PromiseLike<T>;
 /** Expect a promise. */
 export declare function assertPromise<T>(value: Promise<T> | T): asserts value is Promise<T>;

package/util/assert.js

@@ -1,6 +1,7 @@
 import { AssertionError } from "../error/index.js";
 import { debug } from "./debug.js";
 import { isObject } from "./object.js";
+import { isArray } from "./array.js";
 import { NOVALUE } from "./constants.js";
 import { isAsync } from "./async.js";
 /** Assert a boolean condition is true. */
@@ -53,20 +54,29 @@ export function assertArray(value) {
     if (!(value instanceof Array))
         throw new AssertionError(`Must be array`, value);
 }
+export function assertMinimumLength(value, min = 1) {
+    if (!isArray(value) || value.length < min)
+        throw new AssertionError(`Must be array with minimum length ${min}`, value);
+}
 /** Assert that a value has a specific length (or length is in a specific range). */
 export function assertLength(value, min, max = min) {
-    if (!isObject(value) || typeof value.length !== "number" || value.length < min || value.length > max)
-        throw new AssertionError(`Must have length ${min}–${max}`, value);
+    if (!isArray(value) || value.length < min || value.length > max)
+        throw new AssertionError(`Must be array with length ${min}-${max}`, value);
+}
+/** Assert that a value is a number greater than. */
+export function assertBetween(value, min, max) {
+    if (typeof value !== "number" || value < min || value > max)
+        throw new AssertionError(`Must be number between ${min}-${max}`, value);
 }
 /** Assert that a value is a number greater than. */
-export function assertGreater(value, target) {
-    if (typeof value !== "number" || value <= target)
-        throw new AssertionError(`Must be greater than ${target}`, value);
+export function assertMaximum(value, max) {
+    if (typeof value !== "number" || value > max)
+        throw new AssertionError(`Must be number with maximum ${max}`, value);
 }
 /** Assert that a value is a number less than. */
-export function assertLess(value, target) {
-    if (typeof value !== "number" || value >= target)
-        throw new AssertionError(`Must be less than ${target}`, value);
+export function assertMinimum(value, min) {
+    if (typeof value !== "number" || value < min)
+        throw new AssertionError(`Must be number with minimum ${min}`, value);
 }
 /** Assert that a value is an instance of something. */
 export function assertInstance(value, type) {
@@ -89,12 +99,12 @@ export function assertDefined(value) {
         throw new AssertionError("Must be defined", value);
 }
 /** Expect a synchronous value. */
-export function assertSync(value) {
+export function assertSynchronous(value) {
     if (isAsync(value))
         throw new AssertionError("Must be synchronous", value);
 }
 /** Expect an asynchronous value. */
-export function assertAsync(value) {
+export function assertAsynchronous(value) {
     if (!isAsync(value))
         throw new AssertionError("Must be asynchronous", value);
 }

package/util/iterate.d.ts

@@ -1,4 +1,3 @@
-import type { ImmutableMap } from "./map.js";
 import type { ImmutableArray } from "./array.js";
 import type { Entry } from "./entry.js";
 import { DONE } from "./constants.js";
@@ -23,8 +22,6 @@ export declare const isIterable: <T extends Iterable<unknown>>(value: unknown) =
  * - Note: Array and Map instances etc will return true because they implement `Symbol.iterator`
  */
 export declare const isAsyncIterable: <T extends AsyncIterable<unknown>>(value: unknown) => value is T;
-/** Get the known size or length of an object (e.g. `Array`, `Map`, and `Set` have known size), or return `undefined` if the size cannot be established. */
-export declare const getSize: (obj: Iterable<unknown> | ImmutableMap | ImmutableArray) => number | undefined;
 /**
  * Count the number items of an iterable.
  * - Checks `items.size` or `items.length` first, or consumes the iterable and counts its iterations.
@@ -35,8 +32,6 @@ export declare function countItems(items: Iterable<unknown>): number;
  * - Note: this consumes the iterable so you won't be able to use it again.
  */
 export declare function countIterations(items: Iterable<unknown>): number;
-/** Sum an iterable set of numbers and return the total. */
-export declare function sumItems(input: Iterable<number>): number;
 /**
  * Yield a range of numbers from `start` to `end`
  * - Yields in descending order if `end` is lower than `start`

package/util/iterate.js

@@ -13,14 +13,14 @@ export const isIterable = (value) => typeof value === "object" && !!value && Sym
  */
 export const isAsyncIterable = (value) => typeof value === "object" && !!value && Symbol.asyncIterator in value;
 /** Get the known size or length of an object (e.g. `Array`, `Map`, and `Set` have known size), or return `undefined` if the size cannot be established. */
-export const getSize = (obj) => ("size" in obj && typeof obj.size === "number" ? obj.size : "length" in obj && typeof obj.length === "number" ? obj.length : undefined);
+const getKnownSize = (obj) => ("size" in obj && typeof obj.size === "number" ? obj.size : "length" in obj && typeof obj.length === "number" ? obj.length : undefined);
 /**
  * Count the number items of an iterable.
  * - Checks `items.size` or `items.length` first, or consumes the iterable and counts its iterations.
  */
 export function countItems(items) {
     var _a;
-    return (_a = getSize(items)) !== null && _a !== void 0 ? _a : countIterations(items);
+    return (_a = getKnownSize(items)) !== null && _a !== void 0 ? _a : countIterations(items);
 }
 /**
  * Count the number of iterations an iterable does.
@@ -32,13 +32,6 @@ export function countIterations(items) {
         count++; // eslint-disable-line @typescript-eslint/no-unused-vars
     return count;
 }
-/** Sum an iterable set of numbers and return the total. */
-export function sumItems(input) {
-    let sum = 0;
-    for (const num of input)
-        sum += num;
-    return sum;
-}
 /**
  * Yield a range of numbers from `start` to `end`
  * - Yields in descending order if `end` is lower than `start`
@@ -57,7 +50,7 @@ export function* yieldRange(start, end) {
  */
 export function limitItems(items, limit) {
     var _a;
-    const size = (_a = getSize(items)) !== null && _a !== void 0 ? _a : Infinity;
+    const size = (_a = getKnownSize(items)) !== null && _a !== void 0 ? _a : Infinity;
     return size <= limit ? items : yieldUntilLimit(items, limit);
 }
 /** Yield items from a source iterable until we hit a maximum iteration count. */

package/util/number.d.ts

@@ -11,6 +11,11 @@ export declare const IS_NUMBER: (v: unknown) => v is number;
  * - Everything else returns `null`
  */
 export declare function toNumber(value: unknown): number | null;
+/**
+ * Assertively convert an unknown value to a finite number.
+ * @throws `AssertionError` if the value cannot be converted.
+ */
+export declare function getNumber(value: unknown): number;
 /**
  * Round numbers to a given step.
  *
@@ -44,10 +49,14 @@ export declare const formatNumber: (num: number, precision?: number) => string;
  */
 export declare const isBetween: (num: number, start: number, end: number) => boolean;
 /**
- *  Apply a min/max to a number to return a number that's definitely in the specified range.
+ * Apply a min/max to a number to return a number that's definitely in the specified range.
  *
  * @param num The number to apply the min/max to, e.g. `17`
  * @param start The start of the range, e.g. `10`
  * @param end The end of the range, e.g. `20`
  */
 export declare const getBetween: (num: number, start: number, end: number) => number;
+/** Sum an iterable set of numbers and return the total. */
+export declare function sumNumbers(nums: Iterable<number>): number;
+/** Find the number that's closest to a target in an iterable set of numbers. */
+export declare function getClosestNumber<T extends number>(nums: Iterable<T>, target: number): T | undefined;

package/util/number.js

@@ -21,6 +21,16 @@ export function toNumber(value) {
     return null;
 }
 const NUMERIC = /[^0-9-.]/g;
+/**
+ * Assertively convert an unknown value to a finite number.
+ * @throws `AssertionError` if the value cannot be converted.
+ */
+export function getNumber(value) {
+    const num = toNumber(value);
+    if (num === null)
+        throw new AssertionError("Must be number", value);
+    return num;
+}
 /**
  * Round numbers to a given step.
  *
@@ -58,10 +68,25 @@ export const formatNumber = (num, precision = 10) => new Intl.NumberFormat(undef
  */
 export const isBetween = (num, start, end) => num >= start && num <= end;
 /**
- *  Apply a min/max to a number to return a number that's definitely in the specified range.
+ * Apply a min/max to a number to return a number that's definitely in the specified range.
  *
  * @param num The number to apply the min/max to, e.g. `17`
  * @param start The start of the range, e.g. `10`
  * @param end The end of the range, e.g. `20`
  */
 export const getBetween = (num, start, end) => Math.max(start, Math.min(end, num));
+/** Sum an iterable set of numbers and return the total. */
+export function sumNumbers(nums) {
+    let sum = 0;
+    for (const num of nums)
+        sum += num;
+    return sum;
+}
+/** Find the number that's closest to a target in an iterable set of numbers. */
+export function getClosestNumber(nums, target) {
+    let closest = undefined;
+    for (const item of nums)
+        if (closest === undefined || Math.abs(item - target) < Math.abs(closest - target))
+            closest = item;
+    return closest;
+}