shelving 1.150.14 → 1.151.0

package/firestore/server/FirestoreServerProvider.d.ts

@@ -1,25 +1,26 @@
 import { Firestore } from "@google-cloud/firestore";
 import { AsyncProvider } from "../../db/Provider.js";
 import type { DataKey, Database } from "../../util/data.js";
-import type { ItemQuery, Items, OptionalItem } from "../../util/item.js";
+import type { Items, OptionalItem } from "../../util/item.js";
+import type { ItemQuery } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 /**
  * Firestore server database provider.
  * - Works with the Firebase Admin SDK for Node.JS
  */
-export declare class FirestoreServerProvider<T extends Database> extends AsyncProvider<T> {
+export declare class FirestoreServerProvider<T extends Database> extends AsyncProvider<string, T> {
     private readonly _firestore;
     constructor(firestore?: Firestore);
-    getItem<K extends DataKey<T>>(c: K, id: string): Promise<OptionalItem<T[K]>>;
-    getItemSequence<K extends DataKey<T>>(c: K, id: string): AsyncIterable<OptionalItem<T[K]>>;
+    getItem<K extends DataKey<T>>(c: K, id: string): Promise<OptionalItem<string, T[K]>>;
+    getItemSequence<K extends DataKey<T>>(c: K, id: string): AsyncIterable<OptionalItem<string, T[K]>>;
     addItem<K extends DataKey<T>>(c: K, data: T[K]): Promise<string>;
     setItem<K extends DataKey<T>>(c: K, id: string, data: T[K]): Promise<void>;
     updateItem<K extends DataKey<T>>(c: K, id: string, updates: Updates<T[K]>): Promise<void>;
     deleteItem<K extends DataKey<T>>(c: K, id: string): Promise<void>;
-    countQuery<K extends DataKey<T>>(c: K, q?: ItemQuery<T[K]>): Promise<number>;
-    getQuery<K extends DataKey<T>>(c: K, q?: ItemQuery<T[K]>): Promise<Items<T[K]>>;
-    getQuerySequence<K extends DataKey<T>>(c: K, q?: ItemQuery<T[K]>): AsyncIterable<Items<T[K]>>;
-    setQuery<K extends DataKey<T>>(c: K, q: ItemQuery<T[K]>, data: T[K]): Promise<void>;
-    updateQuery<K extends DataKey<T>>(c: K, q: ItemQuery<T[K]>, updates: Updates): Promise<void>;
-    deleteQuery<K extends DataKey<T>>(c: K, q: ItemQuery<T[K]>): Promise<void>;
+    countQuery<K extends DataKey<T>>(c: K, q?: ItemQuery<string, T[K]>): Promise<number>;
+    getQuery<K extends DataKey<T>>(c: K, q?: ItemQuery<string, T[K]>): Promise<Items<string, T[K]>>;
+    getQuerySequence<K extends DataKey<T>>(c: K, q?: ItemQuery<string, T[K]>): AsyncIterable<Items<string, T[K]>>;
+    setQuery<K extends DataKey<T>>(c: K, q: ItemQuery<string, T[K]>, data: T[K]): Promise<void>;
+    updateQuery<K extends DataKey<T>>(c: K, q: ItemQuery<string, T[K]>, updates: Updates): Promise<void>;
+    deleteQuery<K extends DataKey<T>>(c: K, q: ItemQuery<string, T[K]>): Promise<void>;
 }

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.150.14",
+	"version": "1.151.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/react/createDataContext.d.ts

@@ -3,15 +3,16 @@ import { ItemStore } from "../db/ItemStore.js";
 import type { AbstractProvider } from "../db/Provider.js";
 import { QueryStore } from "../db/QueryStore.js";
 import type { DataKey, Database } from "../util/data.js";
-import type { ItemQuery } from "../util/item.js";
+import type { Identifier } from "../util/item.js";
 import type { Nullish } from "../util/null.js";
-export interface DataContext<T extends Database> {
+import type { ItemQuery } from "../util/query.js";
+export interface DataContext<I extends Identifier, T extends Database> {
     /** Get an `ItemStore` for the specified collection item in the current `DataProvider` context and subscribe to any changes in it. */
-    useItem<K extends DataKey<T>>(this: void, collection: K, id: string): ItemStore<T, K>;
-    useItem<K extends DataKey<T>>(this: void, collection: Nullish<K>, id: Nullish<string>): ItemStore<T, K> | undefined;
+    useItem<K extends DataKey<T>>(this: void, collection: K, id: I): ItemStore<I, T, K>;
+    useItem<K extends DataKey<T>>(this: void, collection: Nullish<K>, id: Nullish<I>): ItemStore<I, T, K> | undefined;
     /** Get an `QueryStore` for the specified collection query in the current `DataProvider` context and subscribe to any changes in it. */
-    useQuery<K extends DataKey<T>>(this: void, collection: K, query: ItemQuery<T[K]>): QueryStore<T, K>;
-    useQuery<K extends DataKey<T>>(this: void, collection: Nullish<K>, query: Nullish<ItemQuery<T[K]>>): QueryStore<T, K> | undefined;
+    useQuery<K extends DataKey<T>>(this: void, collection: K, query: ItemQuery<I, T[K]>): QueryStore<I, T, K>;
+    useQuery<K extends DataKey<T>>(this: void, collection: Nullish<K>, query: Nullish<ItemQuery<I, T[K]>>): QueryStore<I, T, K> | undefined;
     readonly DataContext: ({ children }: {
         children: ReactNode;
     }) => ReactElement;
@@ -21,4 +22,4 @@ export interface DataContext<T extends Database> {
  * - Allows React elements to call `useItem()` and `useQuery()` to access items/queries in a database provider.
  * - If the database has a `CacheProvider` in its chain then in-memory data will be used in the returned stores.
  */
-export declare function createDataContext<T extends Database>(provider: AbstractProvider<T>): DataContext<T>;
+export declare function createDataContext<I extends Identifier, T extends Database>(provider: AbstractProvider<I, T>): DataContext<I, T>;

package/schema/DataSchema.d.ts

@@ -1,5 +1,5 @@
 import type { Data, Database } from "../util/data.js";
-import type { Item } from "../util/item.js";
+import type { Identifier, Item } from "../util/item.js";
 import type { Validator, Validators } from "../util/validate.js";
 import type { NullableSchema } from "./NullableSchema.js";
 import type { SchemaOptions } from "./Schema.js";
@@ -27,5 +27,5 @@ export declare const DATA: <T extends Data>(props: Validators<T>) => DataSchema<
 export declare const NULLABLE_DATA: <T extends Data>(props: Validators<T>) => NullableSchema<T>;
 /** Create a `DataSchema` that validates partially, i.e. properties can be their value, or `undefined` */
 export declare function PARTIAL<T extends Data>(source: Validators<T> | DataSchema<T>): DataSchema<Partial<T>>;
-/** Create a `DataSchema` that validates a data item, i.e. it has a string `.id` property. */
-export declare function ITEM<T extends Data>(validators: Validators<T> | DataSchema<T>, id?: Validator<string>): DataSchema<Item<T>>;
+/** Create a `DataSchema` that validates a data item, i.e. it has a string or number `.id` identifier property. */
+export declare function ITEM<I extends Identifier, T extends Data>(id: Validator<I>, validators: Validators<T> | DataSchema<T>): DataSchema<Item<I, T>>;

package/schema/DataSchema.js

@@ -2,7 +2,6 @@ import { ValueFeedback } from "../feedback/Feedback.js";
 import { isData } from "../util/data.js";
 import { mapObject } from "../util/transform.js";
 import { validateData } from "../util/validate.js";
-import { KEY } from "./KeySchema.js";
 import { NULLABLE } from "./NullableSchema.js";
 import { OPTIONAL } from "./OptionalSchema.js";
 import { Schema } from "./Schema.js";
@@ -30,8 +29,8 @@ export function PARTIAL(source) {
         props: mapObject(props, OPTIONAL),
     });
 }
-/** Create a `DataSchema` that validates a data item, i.e. it has a string `.id` property. */
-export function ITEM(validators, id = KEY) {
+/** Create a `DataSchema` that validates a data item, i.e. it has a string or number `.id` identifier property. */
+export function ITEM(id, validators) {
     const props = validators instanceof DataSchema ? validators.props : validators;
     return new DataSchema({
         props: { id, ...props },

package/schema/EntitySchema.js

@@ -1,5 +1,5 @@
 import { ValueFeedback } from "../feedback/Feedback.js";
-import { isItem } from "../util/array.js";
+import { isArrayItem } from "../util/array.js";
 import { getEntity } from "../util/entity.js";
 import { NULLABLE } from "./NullableSchema.js";
 import { StringSchema } from "./StringSchema.js";
@@ -15,7 +15,7 @@ export class EntitySchema extends StringSchema {
         const [type] = getEntity(entity);
         if (!type)
             throw new ValueFeedback("Must be entity", unsafeValue);
-        if (this.types && !isItem(this.types, type))
+        if (this.types && !isArrayItem(this.types, type))
             throw new ValueFeedback("Invalid entity type", type);
         return entity;
     }

package/sequence/DeferredSequence.d.ts

@@ -20,6 +20,8 @@ export declare class DeferredSequence<T = void> extends AbstractSequence<T, void
     /** Reject the current deferred in the sequence. */
     reject(reason: unknown): void;
     private _nextReason;
+    /** Cancel the current resolution or rejection. */
+    cancel(): void;
     /** Fulfill the current deferred by resolving or rejecting it. */
     private _fulfill;
     next(): Promise<IteratorResult<T, void>>;

package/sequence/DeferredSequence.js

@@ -33,17 +33,25 @@ export class DeferredSequence extends AbstractSequence {
         queueMicrotask(() => this._fulfill());
     }
     _nextReason = _NOVALUE;
+    /** Cancel the current resolution or rejection. */
+    cancel() {
+        this._nextValue = _NOVALUE;
+        this._nextReason = _NOVALUE;
+    }
     /** Fulfill the current deferred by resolving or rejecting it. */
     _fulfill() {
         const { _deferred, _nextReason, _nextValue } = this;
-        this._deferred = undefined;
         this._nextReason = _NOVALUE;
         this._nextValue = _NOVALUE;
         if (_deferred) {
-            if (_nextReason !== _NOVALUE)
+            if (_nextReason !== _NOVALUE) {
+                this._deferred = undefined;
                 _deferred.reject(_nextReason);
-            else if (_nextValue !== _NOVALUE)
+            }
+            else if (_nextValue !== _NOVALUE) {
+                this._deferred = undefined;
                 _deferred.resolve(_nextValue);
+            }
         }
     }
     // Implement `AsyncIterator`

package/store/Store.d.ts

@@ -18,7 +18,7 @@ export declare class Store<T> implements AsyncIterable<T> {
     readonly next: DeferredSequence<T>;
     /** Current value of the store (or throw a promise that resolves when this store receives its next value or error). */
     get value(): T;
-    set value(value: T);
+    set value(value: T | typeof NONE);
     private _value;
     /** Is there a current value, or is it still loading. */
     get loading(): boolean;

package/store/Store.js

@@ -25,7 +25,12 @@ export class Store {
     }
     set value(value) {
         this._reason = undefined;
-        if (this._value === NONE || !this.equal(value, this._value)) {
+        if (value === NONE) {
+            this._time = undefined;
+            this._value = value;
+            this.next.cancel();
+        }
+        else if (this._value === NONE || !this.equal(value, this._value)) {
             this._time = Date.now();
             this._value = value;
             this.next.resolve(value);

package/test/basics.d.ts

@@ -15,14 +15,15 @@ export declare const BASIC_SCHEMA: import("../schema/DataSchema.js").DataSchema<
     };
 }>;
 export type BasicData = ValidatorType<typeof BASIC_SCHEMA>;
-export declare const basic1: Item<BasicData>;
-export declare const basic2: Item<BasicData>;
-export declare const basic3: Item<BasicData>;
-export declare const basic4: Item<BasicData>;
-export declare const basic5: Item<BasicData>;
-export declare const basic6: Item<BasicData>;
-export declare const basic7: Item<BasicData>;
-export declare const basic8: Item<BasicData>;
-export declare const basic9: Item<BasicData>;
-export declare const basics: ReadonlyArray<Item<BasicData>>;
+export type BasicItem = Item<string, BasicData>;
+export declare const basic1: BasicItem;
+export declare const basic2: BasicItem;
+export declare const basic3: BasicItem;
+export declare const basic4: BasicItem;
+export declare const basic5: BasicItem;
+export declare const basic6: BasicItem;
+export declare const basic7: BasicItem;
+export declare const basic8: BasicItem;
+export declare const basic9: BasicItem;
+export declare const basics: ReadonlyArray<BasicItem>;
 export declare const basic999: BasicData;

package/test/people.d.ts

@@ -8,9 +8,10 @@ export declare const PERSON_SCHEMA: import("../schema/DataSchema.js").DataSchema
     birthday: string | null;
 }>;
 export type PersonData = ValidatorType<typeof PERSON_SCHEMA>;
-export declare const person1: Item<PersonData>;
-export declare const person2: Item<PersonData>;
-export declare const person3: Item<PersonData>;
-export declare const person4: Item<PersonData>;
-export declare const person5: Item<PersonData>;
-export declare const people: ReadonlyArray<Item<PersonData>>;
+export type PersonItem = Item<string, PersonData>;
+export declare const person1: PersonItem;
+export declare const person2: PersonItem;
+export declare const person3: PersonItem;
+export declare const person4: PersonItem;
+export declare const person5: PersonItem;
+export declare const people: ReadonlyArray<PersonItem>;

package/test/util.d.ts

@@ -1,9 +1,9 @@
 import type { Data } from "../util/data.js";
-import type { Item } from "../util/item.js";
+import type { Identifier, Item } from "../util/item.js";
 import type { NotString } from "../util/string.js";
 /** Expect that an object matches `PromiseLike` */
 export declare const EXPECT_PROMISELIKE: any;
 /** Expect `Item` objects with an `.id` prop in any order. */
-export declare function expectUnorderedItems<T extends Data>(items: Iterable<Item<T>>, keys: Iterable<string> & NotString): void;
+export declare function expectUnorderedItems<I extends Identifier, T extends Data>(items: Iterable<Item<I, T>>, keys: Iterable<string> & NotString): void;
 /** Expect `Item` objects with an `.id` prop in a specified order. */
-export declare function expectOrderedItems<T extends Data>(items: Iterable<Item<T>>, keys: Iterable<string> & NotString): void;
+export declare function expectOrderedItems<I extends Identifier, T extends Data>(items: Iterable<Item<I, T>>, keys: Iterable<string> & NotString): void;

package/test/util.js

@@ -1,5 +1,5 @@
 import { expect } from "bun:test";
-import { getItemIDs } from "../util/item.js";
+import { getIdentifiers } from "../util/item.js";
 /** Expect that an object matches `PromiseLike` */
 export const EXPECT_PROMISELIKE = expect.objectContaining({
     // biome-ignore lint/suspicious/noThenProperty: On purpose.
@@ -9,7 +9,7 @@ export const EXPECT_PROMISELIKE = expect.objectContaining({
 export function expectUnorderedItems(items, keys) {
     try {
         expect(items).toBeInstanceOf(Object);
-        expect(Array.from(getItemIDs(items)).sort()).toEqual(Array.from(keys).sort());
+        expect(Array.from(getIdentifiers(items)).sort()).toEqual(Array.from(keys).sort());
     }
     catch (thrown) {
         if (thrown instanceof Error)
@@ -21,7 +21,7 @@ export function expectUnorderedItems(items, keys) {
 export function expectOrderedItems(items, keys) {
     try {
         expect(items).toBeInstanceOf(Object);
-        expect(Array.from(getItemIDs(items))).toEqual(Array.from(keys));
+        expect(Array.from(getIdentifiers(items))).toEqual(Array.from(keys));
     }
     catch (thrown) {
         if (thrown instanceof Error)

package/util/array.d.ts

@@ -61,9 +61,9 @@ export declare function requireArray<T>(arr: ImmutableArray<T>, min: 2, max?: nu
 export declare function requireArray<T>(arr: ImmutableArray<T>, min: 3, max?: number, caller?: AnyCaller): readonly [T, T, T, ...T[]];
 export declare function requireArray<T>(list: PossibleArray<T>, min?: number, max?: number, caller?: AnyCaller): ImmutableArray<T>;
 /** Is an unknown value an item in a specified array or iterable? */
-export declare function isItem<T>(list: PossibleArray<T>, item: unknown): item is T;
+export declare function isArrayItem<T>(list: PossibleArray<T>, item: unknown): item is T;
 /** Assert that an unknown value is an item in a specified array. */
-export declare function assertItem<T>(arr: PossibleArray<T>, item: unknown, caller?: AnyCaller): asserts item is T;
+export declare function assertArrayItem<T>(arr: PossibleArray<T>, item: unknown, caller?: AnyCaller): asserts item is T;
 /** Add multiple items to an array (immutably) and return a new array with those items (or the same array if no changes were made). */
 export declare function withArrayItems<T>(list: PossibleArray<T>, ...add: T[]): ImmutableArray<T>;
 /** Pick multiple items from an array (immutably) and return a new array without those items (or the same array if no changes were made). */

package/util/array.js

@@ -20,7 +20,7 @@ export function requireArray(list, min, max, caller = requireArray) {
     return arr;
 }
 /** Is an unknown value an item in a specified array or iterable? */
-export function isItem(list, item) {
+export function isArrayItem(list, item) {
     if (isArray(list))
         list.includes(item);
     for (const i of list)
@@ -29,8 +29,8 @@ export function isItem(list, item) {
     return false;
 }
 /** Assert that an unknown value is an item in a specified array. */
-export function assertItem(arr, item, caller = assertItem) {
-    if (!isItem(arr, item))
+export function assertArrayItem(arr, item, caller = assertArrayItem) {
+    if (!isArrayItem(arr, item))
         throw new RequiredError("Item must exist in array", { item, array: arr, caller });
 }
 /** Add multiple items to an array (immutably) and return a new array with those items (or the same array if no changes were made). */

package/util/error.d.ts

@@ -25,4 +25,4 @@ export declare function splitMessage(input: PossibleMessage): ImmutableDictionar
  * Name a message by applying a `name: ` prefix to it.
  * - Assumes each line in the message is a separate error, so each line has the same prefix applied.
  */
-export declare function getNamedMessage(name: string, message: string): string;
+export declare function getNamedMessage(name: string | number, message: string): string;

package/util/item.d.ts

@@ -1,21 +1,20 @@
 import type { ImmutableArray } from "./array.js";
 import type { Data } from "./data.js";
-import type { Query } from "./query.js";
-/** Item data with a string ID that uniquely identifies it. */
-export type Item<T extends Data = Data> = T & {
-    id: string;
-};
+/** Allowed types for the "id" property (identifier) for an item. */
+export type Identifier = string | number;
+/** An item object is a data object that includes an "id" identifier property that is either a string or number. */
+export type Item<I extends Identifier, T extends Data> = {
+    id: I;
+} & T;
 /** Entity or `undefined` to indicate the item doesn't exist. */
-export type OptionalItem<T extends Data = Data> = Item<T> | undefined;
-/** Get the ID from item data. */
-export declare function getItemID<T extends Data>({ id }: Item<T>): string;
-/** Get the IDs of an iterable set item data. */
-export declare function getItemIDs<T extends Data>(entities: Iterable<Item<T>>): Iterable<string>;
+export type OptionalItem<I extends Identifier, T extends Data> = Item<I, T> | undefined;
+/** Get the identifier from an item object. */
+export declare function getIdentifier<I extends Identifier, T extends Data>({ id }: Item<I, T>): I;
+/** Get the identifiers from an iterable set item objects. */
+export declare function getIdentifiers<I extends Identifier, T extends Data>(entities: Iterable<Item<I, T>>): Iterable<I>;
+/** Does a data object or data item object. */
+export declare function hasIdentifier<I extends Identifier, T extends Data>(item: T | Item<I, T>, id: I): item is Item<I, T>;
 /** Merge an ID into a set of data to make an `ItemData` */
-export declare function getItem<T extends Data>(id: string, data: T | Item<T>): Item<T>;
+export declare function getItem<I extends Identifier, T extends Data>(id: I, data: T | Item<I, T>): Item<I, T>;
 /** An array of item data. */
-export type Items<T extends Data = Data> = ImmutableArray<Item<T>>;
-/** A set of query constraints for item data. */
-export type ItemQuery<T extends Data = Data> = Query<Item<T>>;
-/** Get query that targets a single database item by its ID. */
-export declare function getItemQuery<T extends Data>(id: string): Query<Item<T>>;
+export type Items<I extends Identifier, T extends Data> = ImmutableArray<Item<I, T>>;

package/util/item.js

@@ -1,16 +1,17 @@
-/** Get the ID from item data. */
-export function getItemID({ id }) {
+/** Get the identifier from an item object. */
+export function getIdentifier({ id }) {
     return id;
 }
-/** Get the IDs of an iterable set item data. */
-export function* getItemIDs(entities) {
+/** Get the identifiers from an iterable set item objects. */
+export function* getIdentifiers(entities) {
     for (const { id } of entities)
         yield id;
 }
+/** Does a data object or data item object. */
+export function hasIdentifier(item, id) {
+    return item.id === id;
+}
 /** Merge an ID into a set of data to make an `ItemData` */
 export function getItem(id, data) {
-    return data.id === id ? data : { ...data, id };
-}
-export function getItemQuery(id) {
-    return { id, $limit: 1 };
+    return hasIdentifier(data, id) ? data : { ...data, id };
 }

package/util/query.d.ts

@@ -1,5 +1,6 @@
 import type { ImmutableArray } from "./array.js";
 import type { Data, LeafData, LeafKey } from "./data.js";
+import type { Item } from "./item.js";
 /** Query that can be applied to a list of data objects. */
 export type Query<T extends Data> = {
     readonly [K in LeafKey<T> as `${K}` | `!${K}`]?: LeafData<T>[K] | ImmutableArray<LeafData<T>[K]> | undefined;
@@ -11,6 +12,8 @@ export type Query<T extends Data> = {
     readonly $order?: `${LeafKey<T>}` | `!${LeafKey<T>}` | undefined | ImmutableArray<`${LeafKey<T>}` | `!${LeafKey<T>}` | undefined>;
     readonly $limit?: number | undefined;
 };
+/** A set of query constraints for item data. */
+export type ItemQuery<I extends string | number, T extends Data> = Query<Item<I, T>>;
 /** A single filter that can be applied to a list of data objects. */
 export type Filter = {
     key: string;

package/util/random.d.ts

@@ -13,4 +13,4 @@ export declare function getRandomKey(length?: number): string;
 /** Get a random character from a string. */
 export declare function getRandomCharacter(str: string): string;
 /** Get a random item from an array or random character from a string string. */
-export declare function getRandomItem<T>(arr: ImmutableArray<T>): T;
+export declare function getRandomItem<I, T>(arr: ImmutableArray<T>): T;

package/util/set.d.ts

@@ -16,11 +16,11 @@ export declare function getSet<T>(value: PossibleSet<T>): ImmutableSet;
 /** Apply a limit to a set. */
 export declare function limitSet<T>(set: ImmutableSet<T>, limit: number): ImmutableSet<T>;
 /** Is an unknown value an item in a set? */
-export declare function isSetItem<T>(set: ImmutableSet<T>, item: unknown): item is T;
+export declare function isSetItem<I, T>(set: ImmutableSet<T>, item: unknown): item is T;
 /** Assert that an unknown value is an item in a set. */
-export declare function assertSetItem<T>(set: ImmutableSet<T>, item: unknown, caller?: AnyCaller): asserts item is T;
+export declare function assertSetItem<I, T>(set: ImmutableSet<T>, item: unknown, caller?: AnyCaller): asserts item is T;
 /** Add an item to a set (by reference) and return the set item. */
-export declare function addSetItem<T>(set: MutableSet<T>, item: T): T;
+export declare function addSetItem<I, T>(set: MutableSet<T>, item: T): T;
 /** Add multiple items to a set (by reference). */
 export declare function addSetItems<T>(set: MutableSet<T>, ...items: T[]): void;
 /** Remove multiple items from a set (by reference). */