shelving 1.76.0 → 1.76.1

package/db/Change.d.ts

@@ -1,35 +1,36 @@
-import type { Data, Datas, Key } from "../util/data.js";
+import type { Data, Datas, Key, Value } from "../util/data.js";
 import type { ImmutableArray } from "../util/array.js";
 import type { Provider, AsyncProvider } from "../provider/Provider.js";
 import { DataUpdate } from "../update/DataUpdate.js";
 import { Nullish } from "../util/null.js";
+import { DeepIterable } from "../util/iterate.js";
 import type { ItemConstraints, ItemData } from "./Item.js";
-export interface Change<T extends Datas, K extends Key<T>> {
+export interface Change<T extends Datas> {
     readonly action: string;
-    readonly collection: K;
+    readonly collection: Key<T>;
 }
 /** Add on an item. */
-export interface AddChange<T extends Datas, K extends Key<T>> extends Change<T, K> {
+export interface AddChange<T extends Datas, K extends Key<T> = Key<T>> extends Change<T> {
     readonly action: "ADD";
     readonly collection: K;
     readonly data: T[K];
 }
 /** Set on an item. */
-export interface SetChange<T extends Datas, K extends Key<T>> extends Change<T, K> {
+export interface SetChange<T extends Datas, K extends Key<T> = Key<T>> extends Change<T> {
     readonly action: "SET";
     readonly collection: K;
     readonly id: string;
     readonly data: T[K];
 }
 /** Update change on an item. */
-export interface UpdateChange<T extends Datas, K extends Key<T>> extends Change<T, K> {
+export interface UpdateChange<T extends Datas, K extends Key<T> = Key<T>> extends Change<T> {
     readonly action: "UPDATE";
     readonly collection: K;
     readonly id: string;
-    readonly update: DataUpdate<T[K]>;
+    readonly update: DataUpdate<Value<T>>;
 }
 /** Delete change on an item. */
-export interface DeleteChange<T extends Datas, K extends Key<T>> extends Change<T, K> {
+export interface DeleteChange<T extends Datas, K extends Key<T> = Key<T>> extends Change<T> {
     readonly action: "DELETE";
     readonly collection: K;
     readonly id: string;
@@ -43,7 +44,7 @@ export declare type WriteChange<T extends Datas, K extends Key<T> = Key<T>> = It
 /** Array of write changes. */
 export declare type WriteChanges<T extends Datas, K extends Key<T> = Key<T>> = ImmutableArray<WriteChange<T, K>>;
 /** Apply a set of changes to a synchronous provider. */
-export declare function changeProvider<T extends Datas, K extends Key<T> = Key<T>>(provider: Provider<T>, changes: ImmutableArray<Nullish<WriteChange<T, K>>>): ItemChanges<T, K>;
+export declare function changeProvider<T extends Datas, K extends Key<T>>(provider: Provider<T>, ...changes: DeepIterable<Nullish<WriteChange<T, K>>>[]): ItemChanges<T, K>;
 /** Apply a set of changes to an asynchronous provider. */
-export declare function changeAsyncProvider<T extends Datas, K extends Key<T>>(provider: AsyncProvider<T>, changes: ImmutableArray<Nullish<WriteChange<T, K>>>): Promise<ItemChanges<T, K>>;
+export declare function changeAsyncProvider<T extends Datas, K extends Key<T>>(provider: AsyncProvider<T>, ...changes: DeepIterable<Nullish<WriteChange<T, K>>>[]): Promise<ItemChanges<T, K>>;
 export declare function _getItemConstraint<T extends Data>(id: string): ItemConstraints<ItemData<T>>;

package/db/Change.js

@@ -1,9 +1,10 @@
 import { QueryConstraints } from "../constraint/QueryConstraints.js";
 import { FilterConstraint } from "../constraint/FilterConstraint.js";
 import { notNullish } from "../util/null.js";
+import { flattenDeepIterable } from "../util/iterate.js";
 /** Apply a set of changes to a synchronous provider. */
-export function changeProvider(provider, changes) {
-    return changes.filter(notNullish).map(_changeItem, provider);
+export function changeProvider(provider, ...changes) {
+    return Array.from(flattenDeepIterable(changes)).filter(notNullish).map(_changeItem, provider);
 }
 function _changeItem(change) {
     const { action, collection } = change;
@@ -18,8 +19,8 @@ function _changeItem(change) {
     return change;
 }
 /** Apply a set of changes to an asynchronous provider. */
-export function changeAsyncProvider(provider, changes) {
-    return Promise.all(changes.filter(notNullish).map(_changeAsyncItem, provider));
+export function changeAsyncProvider(provider, ...changes) {
+    return Promise.all(Array.from(flattenDeepIterable(changes)).filter(notNullish).map(_changeAsyncItem, provider));
 }
 async function _changeAsyncItem(change) {
     const { collection, action } = change;

package/db/Collection.d.ts

@@ -2,10 +2,11 @@ import type { Datas, Key } from "../util/data.js";
 import type { Nullish } from "../util/null.js";
 import type { FilterList } from "../constraint/FilterConstraint.js";
 import type { SortList } from "../constraint/SortConstraint.js";
-import type { ItemData, AsyncItem, Item } from "./Item.js";
+import type { DeepIterable } from "../util/iterate.js";
 import type { AsyncDatabase, Database } from "./Database.js";
-import type { AsyncQuery, Query } from "./Query.js";
-import type { AddChange, ItemChanges, WriteChange } from "./Change.js";
+import { ItemData, AsyncItem, Item } from "./Item.js";
+import { AsyncQuery, Query } from "./Query.js";
+import { AddChange, ItemChanges, WriteChange } from "./Change.js";
 /** Reference to a collection in a synchronous or asynchronous provider. */
 declare abstract class BaseCollection<T extends Datas = Datas, K extends Key<T> = Key<T>> {
     abstract readonly db: Database<T> | AsyncDatabase<T>;
@@ -17,7 +18,7 @@ declare abstract class BaseCollection<T extends Datas = Datas, K extends Key<T>
     /** Add an item to this collection. */
     abstract add(data: T[K]): string | Promise<string>;
     /** Run a set of changes on this database. */
-    abstract change(...changes: Nullish<WriteChange<T, K>>[]): ItemChanges<T, K> | Promise<ItemChanges<T, K>>;
+    abstract change(...changes: DeepIterable<Nullish<WriteChange<T, K>>>[]): ItemChanges<T, K> | Promise<ItemChanges<T, K>>;
     /** Get an add change for this collection. */
     getAdd(data: T[K]): AddChange<T, K>;
     toString(): K;
@@ -30,7 +31,7 @@ export declare class Collection<T extends Datas = Datas, K extends Key<T> = Key<
     query(filters?: FilterList<ItemData<T[K]>>, sorts?: SortList<ItemData<T[K]>>, limit?: number | null): Query<T, K>;
     item(id: string): Item<T, K>;
     add(data: T[K]): string;
-    change(...changes: Nullish<WriteChange<T, K>>[]): ItemChanges<T, K>;
+    change(...changes: DeepIterable<Nullish<WriteChange<T, K>>>[]): ItemChanges<T, K>;
 }
 /** Reference to a collection in an asynchronous provider. */
 export declare class AsyncCollection<T extends Datas = Datas, K extends Key<T> = Key<T>> extends BaseCollection<T, K> {
@@ -40,6 +41,6 @@ export declare class AsyncCollection<T extends Datas = Datas, K extends Key<T> =
     query(filters?: FilterList<ItemData<T[K]>>, sorts?: SortList<ItemData<T[K]>>, limit?: number | null): AsyncQuery<T, K>;
     item(id: string): AsyncItem<T, K>;
     add(data: T[K]): Promise<string>;
-    change(...changes: Nullish<WriteChange<T, K>>[]): Promise<ItemChanges<T, K>>;
+    change(...changes: DeepIterable<Nullish<WriteChange<T, K>>>[]): Promise<ItemChanges<T, K>>;
 }
 export {};

package/db/Collection.js

@@ -1,3 +1,6 @@
+import { AsyncItem, Item } from "./Item.js";
+import { AsyncQuery, Query } from "./Query.js";
+import { changeAsyncProvider, changeProvider } from "./Change.js";
 /** Reference to a collection in a synchronous or asynchronous provider. */
 class BaseCollection {
     /** Get an add change for this collection. */
@@ -17,16 +20,16 @@ export class Collection extends BaseCollection {
         this.collection = collection;
     }
     query(filters, sorts, limit) {
-        return this.db.query(this.collection, filters, sorts, limit);
+        return new Query(this.db, this.collection, filters, sorts, limit);
     }
     item(id) {
-        return this.db.item(this.collection, id);
+        return new Item(this.db, this.collection, id);
     }
     add(data) {
         return this.db.provider.addItem(this.collection, data);
     }
     change(...changes) {
-        return this.db.change(...changes);
+        return changeProvider(this.db.provider, changes);
     }
 }
 /** Reference to a collection in an asynchronous provider. */
@@ -37,15 +40,15 @@ export class AsyncCollection extends BaseCollection {
         this.collection = collection;
     }
     query(filters, sorts, limit) {
-        return this.db.query(this.collection, filters, sorts, limit);
+        return new AsyncQuery(this.db, this.collection, filters, sorts, limit);
     }
     item(id) {
-        return this.db.item(this.collection, id);
+        return new AsyncItem(this.db, this.collection, id);
     }
     add(data) {
         return this.db.provider.addItem(this.collection, data);
     }
     change(...changes) {
-        return this.db.change(...changes);
+        return changeAsyncProvider(this.db.provider, changes);
     }
 }

package/db/Database.d.ts

@@ -4,6 +4,7 @@ import type { FilterList } from "../constraint/FilterConstraint.js";
 import type { SortList } from "../constraint/SortConstraint.js";
 import type { ItemData } from "../db/Item.js";
 import type { Nullish } from "../util/null.js";
+import { DeepIterable } from "../util/iterate.js";
 import { Item, AsyncItem } from "./Item.js";
 import { Query, AsyncQuery } from "./Query.js";
 import { Collection, AsyncCollection } from "./Collection.js";
@@ -12,30 +13,30 @@ import { ItemChanges, WriteChange } from "./Change.js";
 declare abstract class BaseDatabase<T extends Datas> {
     abstract readonly provider: Provider<T> | AsyncProvider<T>;
     /** Create a query on a collection in this database. */
-    abstract collection<K extends Key<T>>(collection: K): Collection<T, K> | AsyncCollection<T, K>;
+    abstract collection<K extends Key<T>>(collection: K): Collection<Pick<T, K>, K> | AsyncCollection<Pick<T, K>, K>;
     /** Create a query on a collection in this database. */
-    abstract query<K extends Key<T>>(collection: K, filters?: FilterList<ItemData<T[K]>>, sorts?: SortList<ItemData<T[K]>>, limit?: number | null): Query<T, K> | AsyncQuery<T, K>;
+    abstract query<K extends Key<T>>(collection: K, filters?: FilterList<ItemData<T[K]>>, sorts?: SortList<ItemData<T[K]>>, limit?: number | null): Query<Pick<T, K>, K> | AsyncQuery<Pick<T, K>, K>;
     /** Reference an item in a collection in this database. */
-    abstract item<K extends Key<T>>(collection: K, id: string): Item<T, K> | AsyncItem<T, K>;
+    abstract item<K extends Key<T>>(collection: K, id: string): Item<Pick<T, K>, K> | AsyncItem<Pick<T, K>, K>;
     /** Run a set of changes on this database. */
-    abstract change<K extends Key<T>>(...changes: Nullish<WriteChange<T, K>>[]): ItemChanges<T, K> | Promise<ItemChanges<T, K>>;
+    abstract change<K extends Key<T>>(...changes: DeepIterable<Nullish<WriteChange<Pick<T, K>, K>>>[]): ItemChanges<Pick<T, K>, K> | Promise<ItemChanges<Pick<T, K>, K>>;
 }
 /** Database with a synchronous provider. */
 export declare class Database<T extends Datas = Datas> implements BaseDatabase<T> {
     readonly provider: Provider<T>;
     constructor(provider: Provider<T>);
-    collection<K extends Key<T>>(collection: K): Collection<T, K>;
-    query<K extends Key<T>>(collection: K, filters?: FilterList<ItemData<T[K]>>, sorts?: SortList<ItemData<T[K]>>, limit?: number | null): Query<T, K>;
-    item<K extends Key<T>>(collection: K, id: string): Item<T, K>;
-    change<K extends Key<T>>(...changes: Nullish<WriteChange<T, K>>[]): ItemChanges<T, K>;
+    collection<K extends Key<T>>(collection: K): Collection<Pick<T, K>, K>;
+    query<K extends Key<T>>(collection: K, filters?: FilterList<ItemData<T[K]>>, sorts?: SortList<ItemData<T[K]>>, limit?: number | null): Query<Pick<T, K>, K>;
+    item<K extends Key<T>>(collection: K, id: string): Item<Pick<T, K>, K>;
+    change<K extends Key<T>>(...changes: DeepIterable<Nullish<WriteChange<Pick<T, K>, K>>>[]): ItemChanges<Pick<T, K>, K>;
 }
 /** Database with a synchronous provider. */
 export declare class AsyncDatabase<T extends Datas = Datas> implements BaseDatabase<T> {
     readonly provider: AsyncProvider<T>;
     constructor(provider: AsyncProvider<T>);
-    collection<K extends Key<T>>(collection: K): AsyncCollection<T, K>;
-    query<K extends Key<T>>(collection: K, filters?: FilterList<ItemData<T[K]>>, sorts?: SortList<ItemData<T[K]>>, limit?: number | null): AsyncQuery<T, K>;
-    item<K extends Key<T>>(collection: K, id: string): AsyncItem<T, K>;
-    change<K extends Key<T>>(...changes: Nullish<WriteChange<T, K>>[]): Promise<ItemChanges<T, K>>;
+    collection<K extends Key<T>>(collection: K): AsyncCollection<Pick<T, K>, K>;
+    query<K extends Key<T>>(collection: K, filters?: FilterList<ItemData<T[K]>>, sorts?: SortList<ItemData<T[K]>>, limit?: number | null): AsyncQuery<Pick<T, K>, K>;
+    item<K extends Key<T>>(collection: K, id: string): AsyncItem<Pick<T, K>, K>;
+    change<K extends Key<T>>(...changes: DeepIterable<Nullish<WriteChange<Pick<T, K>, K>>>[]): Promise<ItemChanges<Pick<T, K>, K>>;
 }
 export {};

package/package.json

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

package/react/useItem.d.ts

@@ -1,17 +1,17 @@
 import type { Unsubscribe } from "../observe/Observable.js";
-import { Key, Datas } from "../util/data.js";
+import { Datas, Value } from "../util/data.js";
 import { ItemValue, ItemData, AsyncItem, Item } from "../db/Item.js";
 import { State } from "../state/State.js";
 import { BooleanState } from "../state/BooleanState.js";
 /** Hold the current state of a item. */
-export declare class ItemState<T extends Datas, K extends Key<T>> extends State<ItemValue<T[K]>> {
-    readonly ref: Item<T, K> | AsyncItem<T, K>;
+export declare class ItemState<T extends Datas> extends State<ItemValue<Value<T>>> {
+    readonly ref: Item<T> | AsyncItem<T>;
     readonly busy: BooleanState;
     /** Get the data of the item (throws `RequiredError` if item doesn't exist). */
-    get data(): ItemData<T[K]>;
+    get data(): ItemData<Value<T>>;
     /** Does the item exist (i.e. its value isn't `null`)? */
     get exists(): boolean;
-    constructor(ref: Item<T, K> | AsyncItem<T, K>);
+    constructor(ref: Item<T> | AsyncItem<T>);
     /** Refresh this state from the source provider. */
     readonly refresh: () => void;
     _refresh(): Promise<void>;
@@ -28,5 +28,5 @@ export declare class ItemState<T extends Datas, K extends Key<T>> extends State<
  * Use an item in a React component.
  * - Uses the default cache, so will error if not used inside `<Cache>`
  */
-export declare function useItem<T extends Datas, K extends Key<T>>(ref: Item<T, K> | AsyncItem<T, K>): ItemState<T, K>;
-export declare function useItem<T extends Datas, K extends Key<T>>(ref?: Item<T, K> | AsyncItem<T, K>): ItemState<T, K> | undefined;
+export declare function useItem<T extends Datas>(ref: Item<T> | AsyncItem<T>): ItemState<T>;
+export declare function useItem<T extends Datas>(ref?: Item<T> | AsyncItem<T>): ItemState<T> | undefined;

package/react/useQuery.d.ts

@@ -1,30 +1,30 @@
 import type { Unsubscribe } from "../observe/Observable.js";
-import type { Key, Datas } from "../util/data.js";
+import type { Datas, Value } from "../util/data.js";
 import type { ItemArray, ItemValue, ItemData } from "../db/Item.js";
 import { AsyncQuery, Query } from "../db/Query.js";
 import { State } from "../state/State.js";
 import { BooleanState } from "../state/BooleanState.js";
 /** Hold the current state of a query. */
-export declare class QueryState<T extends Datas, K extends Key<T>> extends State<ItemArray<T[K]>> {
-    readonly ref: Query<T, K> | AsyncQuery<T, K>;
+export declare class QueryState<T extends Datas> extends State<ItemArray<Value<T>>> {
+    readonly ref: Query<T> | AsyncQuery<T>;
     readonly busy: BooleanState;
     readonly limit: number;
     /** Can more items be loaded after the current result. */
     get hasMore(): boolean;
     private _hasMore;
     /** Get the first document matched by this query or `null` if this query has no items. */
-    get firstValue(): ItemValue<T[K]>;
+    get firstValue(): ItemValue<Value<T>>;
     /** Get the first document matched by this query. */
-    get firstData(): ItemData<T[K]>;
+    get firstData(): ItemData<Value<T>>;
     /** Get the last document matched by this query or `null` if this query has no items. */
-    get lastValue(): ItemValue<T[K]>;
+    get lastValue(): ItemValue<Value<T>>;
     /** Get the last document matched by this query. */
-    get lastData(): ItemData<T[K]>;
+    get lastData(): ItemData<Value<T>>;
     /** Does the document have at least one result. */
     get exists(): boolean;
     /** Get the number of items matching this query. */
     get count(): number;
-    constructor(ref: Query<T, K> | AsyncQuery<T, K>);
+    constructor(ref: Query<T> | AsyncQuery<T>);
     /** Refresh this state from the source provider. */
     readonly refresh: () => void;
     _refresh(): Promise<void>;
@@ -47,5 +47,5 @@ export declare class QueryState<T extends Datas, K extends Key<T>> extends State
  * Use a query in a React component.
  * - Uses the default cache, so will error if not used inside `<Cache>`
  */
-export declare function useQuery<T extends Datas, K extends Key<T>>(ref: Query<T, K> | AsyncQuery<T, K>): QueryState<T, K>;
-export declare function useQuery<T extends Datas, K extends Key<T>>(ref?: Query<T, K> | AsyncQuery<T, K>): QueryState<T, K> | undefined;
+export declare function useQuery<T extends Datas>(ref: Query<T> | AsyncQuery<T>): QueryState<T>;
+export declare function useQuery<T extends Datas>(ref?: Query<T> | AsyncQuery<T>): QueryState<T> | undefined;

package/util/iterate.d.ts

@@ -20,6 +20,10 @@ export declare const isAsyncIterable: <T extends AsyncIterable<unknown>>(value:
  * - Checks `items.size` or `items.length` first, or consumes the iterable and counts its iterations.
  */
 export declare function countItems(items: Iterable<unknown>): number;
+/** An iterable possibly containing multiple other iterables. */
+export declare type DeepIterable<T> = T | Iterable<DeepIterable<T>>;
+/** Flatten one or more iterables. */
+export declare function flattenDeepIterable<T>(items: DeepIterable<T>): Iterable<T>;
 /**
  * Does an iterable have one or more items.
  * - Checks `items.size` or `items.length` first, or consumes the iterable and counts its iterations.

package/util/iterate.js

@@ -31,6 +31,14 @@ function _countItems(items) {
         count++;
     return count;
 }
+/** Flatten one or more iterables. */
+export function* flattenDeepIterable(items) {
+    if (isIterable(items))
+        for (const item of items)
+            yield* flattenDeepIterable(item);
+    else
+        yield items;
+}
 /**
  * Does an iterable have one or more items.
  * - Checks `items.size` or `items.length` first, or consumes the iterable and counts its iterations.