shelving 1.307.3 → 1.308.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/api/index.d.ts CHANGED
@@ -6,6 +6,7 @@ export * from "./provider/APIProvider.js";
6
6
  export * from "./provider/CachedAPIProvider.js";
7
7
  export * from "./provider/ClientAPIProvider.js";
8
8
  export * from "./provider/DebugAPIProvider.js";
9
+ export * from "./provider/HydratingAPIProvider.js";
9
10
  export * from "./provider/JSONAPIProvider.js";
10
11
  export * from "./provider/LoggingAPIProvider.js";
11
12
  export * from "./provider/MockAPIProvider.js";
package/api/index.js CHANGED
@@ -6,6 +6,7 @@ export * from "./provider/APIProvider.js";
6
6
  export * from "./provider/CachedAPIProvider.js";
7
7
  export * from "./provider/ClientAPIProvider.js";
8
8
  export * from "./provider/DebugAPIProvider.js";
9
+ export * from "./provider/HydratingAPIProvider.js";
9
10
  export * from "./provider/JSONAPIProvider.js";
10
11
  export * from "./provider/LoggingAPIProvider.js";
11
12
  export * from "./provider/MockAPIProvider.js";
@@ -0,0 +1,28 @@
1
+ import type { MemoryDBProvider } from "../../db/provider/MemoryDBProvider.js";
2
+ import type { AnyCaller } from "../../util/function.js";
3
+ import type { RequestOptions } from "../../util/http.js";
4
+ import type { Endpoint } from "../endpoint/Endpoint.js";
5
+ import type { APIProvider } from "./APIProvider.js";
6
+ import { ValidationAPIProvider } from "./ValidationAPIProvider.js";
7
+ /**
8
+ * API provider that validates every result, then writes the collection items in it into a local database.
9
+ *
10
+ * - Only results that use a collection's own schemas hydrate: `Collection.item`, `Collection.items` and `Collection.queryItems`, or a `DataSchema` whose props use them (one level deep). Every other result passes through with no change.
11
+ * - `Collection.item` sets the item. A `null` or `undefined` result (e.g. `NULLABLE(USERS.item)`) deletes the item with the `id` from the payload (the payload itself, or its `id` prop).
12
+ * - `Collection.items` sets each item. It never deletes items.
13
+ * - `Collection.queryItems` sets each item, then marks the query as loaded (see `MemoryTable.setQueryTime()`).
14
+ * - Writes happen synchronously before `call()` resolves, so no store sees half of a result.
15
+ * - Extends `ValidationAPIProvider`, so it only ever writes validated items.
16
+ *
17
+ * @see https://shelving.cc/api/HydratingAPIProvider
18
+ */
19
+ export declare class HydratingAPIProvider<P, R> extends ValidationAPIProvider<P, R> {
20
+ /**
21
+ * The local database the items are written into.
22
+ * @see https://shelving.cc/api/HydratingAPIProvider/db
23
+ */
24
+ readonly db: MemoryDBProvider;
25
+ constructor(source: APIProvider<P, R>, db: MemoryDBProvider);
26
+ /** Calls the endpoint, then writes the collection items in the result into `db`. */
27
+ call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
28
+ }
@@ -0,0 +1,82 @@
1
+ import { CollectionItemSchema } from "../../db/collection/CollectionItemSchema.js";
2
+ import { CollectionItemsSchema } from "../../db/collection/CollectionItemsSchema.js";
3
+ import { CollectionQueryItemsSchema } from "../../db/collection/CollectionQueryItemsSchema.js";
4
+ import { DataSchema } from "../../schema/DataSchema.js";
5
+ import { isArray } from "../../util/array.js";
6
+ import { isData } from "../../util/data.js";
7
+ import { getSource } from "../../util/source.js";
8
+ import { ValidationAPIProvider } from "./ValidationAPIProvider.js";
9
+ /**
10
+ * API provider that validates every result, then writes the collection items in it into a local database.
11
+ *
12
+ * - Only results that use a collection's own schemas hydrate: `Collection.item`, `Collection.items` and `Collection.queryItems`, or a `DataSchema` whose props use them (one level deep). Every other result passes through with no change.
13
+ * - `Collection.item` sets the item. A `null` or `undefined` result (e.g. `NULLABLE(USERS.item)`) deletes the item with the `id` from the payload (the payload itself, or its `id` prop).
14
+ * - `Collection.items` sets each item. It never deletes items.
15
+ * - `Collection.queryItems` sets each item, then marks the query as loaded (see `MemoryTable.setQueryTime()`).
16
+ * - Writes happen synchronously before `call()` resolves, so no store sees half of a result.
17
+ * - Extends `ValidationAPIProvider`, so it only ever writes validated items.
18
+ *
19
+ * @see https://shelving.cc/api/HydratingAPIProvider
20
+ */
21
+ export class HydratingAPIProvider extends ValidationAPIProvider {
22
+ /**
23
+ * The local database the items are written into.
24
+ * @see https://shelving.cc/api/HydratingAPIProvider/db
25
+ */
26
+ db;
27
+ constructor(source, db) {
28
+ super(source);
29
+ this.db = db;
30
+ }
31
+ /** Calls the endpoint, then writes the collection items in the result into `db`. */
32
+ async call(endpoint, payload, options, caller = this.call) {
33
+ const result = await super.call(endpoint, payload, options, caller);
34
+ const { db } = this;
35
+ if (!_hydrate(db, endpoint.result, result, payload) && isData(result)) {
36
+ // Go one level deep into a data result, so one endpoint can return several collections.
37
+ const data = getSource(DataSchema, endpoint.result);
38
+ if (data)
39
+ for (const [k, schema] of Object.entries(data.props))
40
+ _hydrate(db, schema, result[k]);
41
+ }
42
+ return result;
43
+ }
44
+ }
45
+ /** Write a value into the database if its schema is a collection schema, and return whether it was. */
46
+ function _hydrate(db, schema, value, payload) {
47
+ const queryItems = getSource(CollectionQueryItemsSchema, schema);
48
+ if (queryItems) {
49
+ if (isData(value)) {
50
+ const { query, items } = value;
51
+ const table = db.getTable(queryItems.source);
52
+ table.setItems(items);
53
+ table.setQueryTime(query);
54
+ }
55
+ return true;
56
+ }
57
+ const items = getSource(CollectionItemsSchema, schema);
58
+ if (items) {
59
+ if (isArray(value))
60
+ db.getTable(items.source).setItems(value);
61
+ return true;
62
+ }
63
+ const item = getSource(CollectionItemSchema, schema);
64
+ if (item) {
65
+ const table = db.getTable(item.source);
66
+ if (isData(value))
67
+ table.setItem(value.id, value);
68
+ else if (value === null || value === undefined) {
69
+ const id = _getPayloadID(payload);
70
+ if (id !== undefined)
71
+ table.deleteItem(id);
72
+ }
73
+ return true;
74
+ }
75
+ return false;
76
+ }
77
+ /** Get the item `id` from a payload: the payload itself, or its `id` prop. */
78
+ function _getPayloadID(payload) {
79
+ const id = isData(payload) ? payload.id : payload;
80
+ if (typeof id === "string" || typeof id === "number")
81
+ return id;
82
+ }
@@ -4,6 +4,10 @@ import type { Schema, Schemas } from "../../schema/Schema.js";
4
4
  import type { ImmutableArray } from "../../util/array.js";
5
5
  import type { Data } from "../../util/data.js";
6
6
  import type { Identifier, Item, Items, OptionalItem } from "../../util/item.js";
7
+ import { CollectionItemSchema } from "./CollectionItemSchema.js";
8
+ import { CollectionItemsSchema } from "./CollectionItemsSchema.js";
9
+ import { CollectionQueryItemsSchema } from "./CollectionQueryItemsSchema.js";
10
+ import { CollectionQuerySchema } from "./CollectionQuerySchema.js";
7
11
  /**
8
12
  * Default identifier schema (integer) used when a collection doesn't supply its own.
9
13
  *
@@ -15,6 +19,7 @@ export declare const ID: NumberSchema;
15
19
  *
16
20
  * - Pairs a collection name with an identifier schema and a data schema, so providers can validate and address items.
17
21
  * - Extends `DataSchema<T>`, so the collection itself validates an item's data, while `.item` validates the complete `id + data` item.
22
+ * - `.item`, `.items`, `.query` and `.queryItems` point back at the collection with `source`, so an endpoint result that uses them can hydrate a database (see `HydratingAPIProvider`).
18
23
  *
19
24
  * @example
20
25
  * const users = new Collection("users", ID, { name: STRING, age: NUMBER });
@@ -40,7 +45,25 @@ export declare class Collection<N extends string = string, I extends Identifier
40
45
  *
41
46
  * @see https://shelving.cc/db/Collection/item
42
47
  */
43
- readonly item: DataSchema<Item<I, T>>;
48
+ readonly item: CollectionItemSchema<I, T>;
49
+ /**
50
+ * Schema for a list of complete items (id + data).
51
+ *
52
+ * @see https://shelving.cc/db/Collection/items
53
+ */
54
+ readonly items: CollectionItemsSchema<I, T>;
55
+ /**
56
+ * Schema for a query on the items. It only checks that the query is an object, so do not trust the query it validates.
57
+ *
58
+ * @see https://shelving.cc/db/Collection/query
59
+ */
60
+ readonly query: CollectionQuerySchema<I, T>;
61
+ /**
62
+ * Schema for a query and the complete list of items that answer it.
63
+ *
64
+ * @see https://shelving.cc/db/Collection/queryItems
65
+ */
66
+ readonly queryItems: CollectionQueryItemsSchema<I, T>;
44
67
  constructor(name: N, id: Schema<I>, data: Schemas<T> | DataSchema<T>);
45
68
  /** Returns the collection name. */
46
69
  toString(): string;
@@ -1,5 +1,9 @@
1
- import { DataSchema, ITEM } from "../../schema/DataSchema.js";
1
+ import { DataSchema } from "../../schema/DataSchema.js";
2
2
  import { NumberSchema } from "../../schema/NumberSchema.js";
3
+ import { CollectionItemSchema } from "./CollectionItemSchema.js";
4
+ import { CollectionItemsSchema } from "./CollectionItemsSchema.js";
5
+ import { CollectionQueryItemsSchema } from "./CollectionQueryItemsSchema.js";
6
+ import { CollectionQuerySchema } from "./CollectionQuerySchema.js";
3
7
  /**
4
8
  * Default identifier schema (integer) used when a collection doesn't supply its own.
5
9
  *
@@ -18,6 +22,7 @@ export const ID = new NumberSchema({
18
22
  *
19
23
  * - Pairs a collection name with an identifier schema and a data schema, so providers can validate and address items.
20
24
  * - Extends `DataSchema<T>`, so the collection itself validates an item's data, while `.item` validates the complete `id + data` item.
25
+ * - `.item`, `.items`, `.query` and `.queryItems` point back at the collection with `source`, so an endpoint result that uses them can hydrate a database (see `HydratingAPIProvider`).
21
26
  *
22
27
  * @example
23
28
  * const users = new Collection("users", ID, { name: STRING, age: NUMBER });
@@ -44,12 +49,33 @@ export class Collection extends DataSchema {
44
49
  * @see https://shelving.cc/db/Collection/item
45
50
  */
46
51
  item;
52
+ /**
53
+ * Schema for a list of complete items (id + data).
54
+ *
55
+ * @see https://shelving.cc/db/Collection/items
56
+ */
57
+ items;
58
+ /**
59
+ * Schema for a query on the items. It only checks that the query is an object, so do not trust the query it validates.
60
+ *
61
+ * @see https://shelving.cc/db/Collection/query
62
+ */
63
+ query;
64
+ /**
65
+ * Schema for a query and the complete list of items that answer it.
66
+ *
67
+ * @see https://shelving.cc/db/Collection/queryItems
68
+ */
69
+ queryItems;
47
70
  constructor(name, id, data) {
48
71
  const dataSchema = data instanceof DataSchema ? data : new DataSchema({ props: data });
49
72
  super({ ...dataSchema, props: dataSchema.props });
50
73
  this.name = name;
51
74
  this.id = id;
52
- this.item = ITEM(id, dataSchema);
75
+ this.item = new CollectionItemSchema(this);
76
+ this.items = new CollectionItemsSchema(this);
77
+ this.query = new CollectionQuerySchema(this);
78
+ this.queryItems = new CollectionQueryItemsSchema(this);
53
79
  }
54
80
  /** Returns the collection name. */
55
81
  toString() {
@@ -0,0 +1,24 @@
1
+ import { DataSchema } from "../../schema/DataSchema.js";
2
+ import type { Data } from "../../util/data.js";
3
+ import type { Identifier, Item } from "../../util/item.js";
4
+ import type { Sourceable } from "../../util/source.js";
5
+ import type { Collection } from "./Collection.js";
6
+ /**
7
+ * Schema for one complete item (`id` + data) of a `Collection`.
8
+ *
9
+ * - Built by `Collection` as `Collection.item`. Use that instance, and do not make your own.
10
+ * - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema (e.g. through `NULLABLE(USERS.item)`).
11
+ * - `HydratingAPIProvider` writes an endpoint result that uses this schema into its database. A `null` or `undefined` result deletes the item with the `id` from the payload.
12
+ *
13
+ * @example
14
+ * const GET_USER = GET("/user/{id}", DATA({ id: USERS.id }), NULLABLE(USERS.item));
15
+ * @see https://shelving.cc/db/CollectionItemSchema
16
+ */
17
+ export declare class CollectionItemSchema<I extends Identifier = Identifier, T extends Data = Data> extends DataSchema<Item<I, T>> implements Sourceable<Collection<string, I, T>> {
18
+ /**
19
+ * The collection this schema validates items of.
20
+ * @see https://shelving.cc/db/CollectionItemSchema/source
21
+ */
22
+ readonly source: Collection<string, I, T>;
23
+ constructor(collection: Collection<string, I, T>);
24
+ }
@@ -0,0 +1,23 @@
1
+ import { DataSchema } from "../../schema/DataSchema.js";
2
+ /**
3
+ * Schema for one complete item (`id` + data) of a `Collection`.
4
+ *
5
+ * - Built by `Collection` as `Collection.item`. Use that instance, and do not make your own.
6
+ * - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema (e.g. through `NULLABLE(USERS.item)`).
7
+ * - `HydratingAPIProvider` writes an endpoint result that uses this schema into its database. A `null` or `undefined` result deletes the item with the `id` from the payload.
8
+ *
9
+ * @example
10
+ * const GET_USER = GET("/user/{id}", DATA({ id: USERS.id }), NULLABLE(USERS.item));
11
+ * @see https://shelving.cc/db/CollectionItemSchema
12
+ */
13
+ export class CollectionItemSchema extends DataSchema {
14
+ /**
15
+ * The collection this schema validates items of.
16
+ * @see https://shelving.cc/db/CollectionItemSchema/source
17
+ */
18
+ source;
19
+ constructor(collection) {
20
+ super({ props: { id: collection.id, ...collection.props } });
21
+ this.source = collection;
22
+ }
23
+ }
@@ -0,0 +1,25 @@
1
+ import { ArraySchema } from "../../schema/ArraySchema.js";
2
+ import type { Data } from "../../util/data.js";
3
+ import type { Identifier, Item } from "../../util/item.js";
4
+ import type { Sourceable } from "../../util/source.js";
5
+ import type { Collection } from "./Collection.js";
6
+ /**
7
+ * Schema for a list of complete items (`id` + data) of a `Collection`.
8
+ *
9
+ * - Built by `Collection` as `Collection.items`. Use that instance, and do not make your own.
10
+ * - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
11
+ * - `HydratingAPIProvider` writes an endpoint result that uses this schema into its database. It only adds and replaces items, and never deletes them.
12
+ * - `ARRAY(USERS.item)` validates the same value, but it does not point at the collection, so it does not hydrate. Use `USERS.items`.
13
+ *
14
+ * @example
15
+ * const LIST_USERS = GET("/user", undefined, USERS.items);
16
+ * @see https://shelving.cc/db/CollectionItemsSchema
17
+ */
18
+ export declare class CollectionItemsSchema<I extends Identifier = Identifier, T extends Data = Data> extends ArraySchema<Item<I, T>> implements Sourceable<Collection<string, I, T>> {
19
+ /**
20
+ * The collection this schema validates items of.
21
+ * @see https://shelving.cc/db/CollectionItemsSchema/source
22
+ */
23
+ readonly source: Collection<string, I, T>;
24
+ constructor(collection: Collection<string, I, T>);
25
+ }
@@ -0,0 +1,24 @@
1
+ import { ArraySchema } from "../../schema/ArraySchema.js";
2
+ /**
3
+ * Schema for a list of complete items (`id` + data) of a `Collection`.
4
+ *
5
+ * - Built by `Collection` as `Collection.items`. Use that instance, and do not make your own.
6
+ * - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
7
+ * - `HydratingAPIProvider` writes an endpoint result that uses this schema into its database. It only adds and replaces items, and never deletes them.
8
+ * - `ARRAY(USERS.item)` validates the same value, but it does not point at the collection, so it does not hydrate. Use `USERS.items`.
9
+ *
10
+ * @example
11
+ * const LIST_USERS = GET("/user", undefined, USERS.items);
12
+ * @see https://shelving.cc/db/CollectionItemsSchema
13
+ */
14
+ export class CollectionItemsSchema extends ArraySchema {
15
+ /**
16
+ * The collection this schema validates items of.
17
+ * @see https://shelving.cc/db/CollectionItemsSchema/source
18
+ */
19
+ source;
20
+ constructor(collection) {
21
+ super({ items: collection.item });
22
+ this.source = collection;
23
+ }
24
+ }
@@ -0,0 +1,27 @@
1
+ import { DataSchema } from "../../schema/DataSchema.js";
2
+ import type { Data } from "../../util/data.js";
3
+ import type { Identifier } from "../../util/item.js";
4
+ import type { QueryItems } from "../../util/query.js";
5
+ import type { Sourceable } from "../../util/source.js";
6
+ import type { Collection } from "./Collection.js";
7
+ /**
8
+ * Schema for `QueryItems` of a `Collection`, i.e. a query and the complete list of items that answer it.
9
+ *
10
+ * - Built by `Collection` as `Collection.queryItems`, from `Collection.query` and `Collection.items`. Use that instance, and do not make your own.
11
+ * - **Do not trust the `query` in a value that this schema validates.** `Collection.query` only checks that it is an object. The `items` are validated in full.
12
+ * - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
13
+ * - `HydratingAPIProvider` writes an endpoint result that uses this schema into its database, and marks the query as loaded (see `MemoryTable.getQueryTime()`), so a store for the same query shows the items without loading.
14
+ * - Only use it when `items` is the complete answer to `query` (with its `$limit`).
15
+ *
16
+ * @example
17
+ * const MY_CHALLENGES = GET("/challenge/me", undefined, DATA({ challenges: CHALLENGES.queryItems }));
18
+ * @see https://shelving.cc/db/CollectionQueryItemsSchema
19
+ */
20
+ export declare class CollectionQueryItemsSchema<I extends Identifier = Identifier, T extends Data = Data> extends DataSchema<QueryItems<I, T>> implements Sourceable<Collection<string, I, T>> {
21
+ /**
22
+ * The collection this schema validates items of.
23
+ * @see https://shelving.cc/db/CollectionQueryItemsSchema/source
24
+ */
25
+ readonly source: Collection<string, I, T>;
26
+ constructor(collection: Collection<string, I, T>);
27
+ }
@@ -0,0 +1,25 @@
1
+ import { DataSchema } from "../../schema/DataSchema.js";
2
+ /**
3
+ * Schema for `QueryItems` of a `Collection`, i.e. a query and the complete list of items that answer it.
4
+ *
5
+ * - Built by `Collection` as `Collection.queryItems`, from `Collection.query` and `Collection.items`. Use that instance, and do not make your own.
6
+ * - **Do not trust the `query` in a value that this schema validates.** `Collection.query` only checks that it is an object. The `items` are validated in full.
7
+ * - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
8
+ * - `HydratingAPIProvider` writes an endpoint result that uses this schema into its database, and marks the query as loaded (see `MemoryTable.getQueryTime()`), so a store for the same query shows the items without loading.
9
+ * - Only use it when `items` is the complete answer to `query` (with its `$limit`).
10
+ *
11
+ * @example
12
+ * const MY_CHALLENGES = GET("/challenge/me", undefined, DATA({ challenges: CHALLENGES.queryItems }));
13
+ * @see https://shelving.cc/db/CollectionQueryItemsSchema
14
+ */
15
+ export class CollectionQueryItemsSchema extends DataSchema {
16
+ /**
17
+ * The collection this schema validates items of.
18
+ * @see https://shelving.cc/db/CollectionQueryItemsSchema/source
19
+ */
20
+ source;
21
+ constructor(collection) {
22
+ super({ one: "result", title: "Result", props: { query: collection.query, items: collection.items } });
23
+ this.source = collection;
24
+ }
25
+ }
@@ -0,0 +1,25 @@
1
+ import { Schema } from "../../schema/Schema.js";
2
+ import type { Data } from "../../util/data.js";
3
+ import type { Identifier, Item } from "../../util/item.js";
4
+ import type { Query } from "../../util/query.js";
5
+ import type { Sourceable } from "../../util/source.js";
6
+ import type { Collection } from "./Collection.js";
7
+ /**
8
+ * Schema for a `Query` on the items of a `Collection`.
9
+ *
10
+ * - Built by `Collection` as `Collection.query`. Use that instance, and do not make your own.
11
+ * - **Do not trust a query that this schema validates.** It only checks that the value is an object. It does not check the keys or the values against the collection, so a query from outside (e.g. an API response) can have any keys and values.
12
+ * - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
13
+ *
14
+ * @see https://shelving.cc/db/CollectionQuerySchema
15
+ */
16
+ export declare class CollectionQuerySchema<I extends Identifier = Identifier, T extends Data = Data> extends Schema<Query<Item<I, T>>> implements Sourceable<Collection<string, I, T>> {
17
+ /**
18
+ * The collection this schema validates queries for.
19
+ * @see https://shelving.cc/db/CollectionQuerySchema/source
20
+ */
21
+ readonly source: Collection<string, I, T>;
22
+ constructor(collection: Collection<string, I, T>);
23
+ /** Checks that the value is an object, and does nothing more. Do not trust the result. */
24
+ validate(unsafeValue?: unknown): Query<Item<I, T>>;
25
+ }
@@ -0,0 +1,28 @@
1
+ import { Schema } from "../../schema/Schema.js";
2
+ import { isData } from "../../util/data.js";
3
+ /**
4
+ * Schema for a `Query` on the items of a `Collection`.
5
+ *
6
+ * - Built by `Collection` as `Collection.query`. Use that instance, and do not make your own.
7
+ * - **Do not trust a query that this schema validates.** It only checks that the value is an object. It does not check the keys or the values against the collection, so a query from outside (e.g. an API response) can have any keys and values.
8
+ * - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
9
+ *
10
+ * @see https://shelving.cc/db/CollectionQuerySchema
11
+ */
12
+ export class CollectionQuerySchema extends Schema {
13
+ /**
14
+ * The collection this schema validates queries for.
15
+ * @see https://shelving.cc/db/CollectionQuerySchema/source
16
+ */
17
+ source;
18
+ constructor(collection) {
19
+ super({ one: "query", title: "Query", value: {} });
20
+ this.source = collection;
21
+ }
22
+ /** Checks that the value is an object, and does nothing more. Do not trust the result. */
23
+ validate(unsafeValue = this.value) {
24
+ if (!isData(unsafeValue))
25
+ throw "Must be object";
26
+ return unsafeValue;
27
+ }
28
+ }
package/db/index.d.ts CHANGED
@@ -1,6 +1,10 @@
1
1
  export * from "./cache/CollectionCache.js";
2
2
  export * from "./cache/DBCache.js";
3
3
  export * from "./collection/Collection.js";
4
+ export * from "./collection/CollectionItemSchema.js";
5
+ export * from "./collection/CollectionItemsSchema.js";
6
+ export * from "./collection/CollectionQueryItemsSchema.js";
7
+ export * from "./collection/CollectionQuerySchema.js";
4
8
  export * from "./migrate/DBMigrator.js";
5
9
  export * from "./migrate/PostgresMigrator.js";
6
10
  export * from "./migrate/SQLiteMigrator.js";
package/db/index.js CHANGED
@@ -1,6 +1,10 @@
1
1
  export * from "./cache/CollectionCache.js";
2
2
  export * from "./cache/DBCache.js";
3
3
  export * from "./collection/Collection.js";
4
+ export * from "./collection/CollectionItemSchema.js";
5
+ export * from "./collection/CollectionItemsSchema.js";
6
+ export * from "./collection/CollectionQueryItemsSchema.js";
7
+ export * from "./collection/CollectionQuerySchema.js";
4
8
  export * from "./migrate/DBMigrator.js";
5
9
  export * from "./migrate/PostgresMigrator.js";
6
10
  export * from "./migrate/SQLiteMigrator.js";
@@ -40,7 +40,7 @@ export declare class CacheDBProvider<I extends Identifier, T extends Data> exten
40
40
  updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
41
41
  /** Fetch the item first, then delete it only if it exists. */
42
42
  deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
43
- /** Read from `source`, then refresh the cache. */
43
+ /** Read from `source`, then refresh the cache and mark the query as loaded. */
44
44
  getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
45
45
  /** Mirror each emission into the cache. */
46
46
  getQuerySequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
@@ -65,10 +65,12 @@ export class CacheDBProvider extends ThroughDBProvider {
65
65
  await super.deleteItem(collection, id);
66
66
  this.memory.getTable(collection).deleteItem(id);
67
67
  }
68
- /** Read from `source`, then refresh the cache. */
68
+ /** Read from `source`, then refresh the cache and mark the query as loaded. */
69
69
  async getQuery(collection, query) {
70
70
  const items = await super.getQuery(collection, query);
71
- this.memory.getTable(collection).setItems(items);
71
+ const table = this.memory.getTable(collection);
72
+ table.setItems(items);
73
+ table.setQueryTime(query);
72
74
  return items;
73
75
  }
74
76
  /** Mirror each emission into the cache. */
@@ -94,6 +94,10 @@ export declare class MemoryDBProvider<I extends Identifier = Identifier, T exten
94
94
  export declare class MemoryTable<I extends Identifier, T extends Data> implements AsyncDisposable {
95
95
  /** Actual data in this table. */
96
96
  protected readonly _data: Map<I, Item<I, T>>;
97
+ /** Time each item was last set or deleted. */
98
+ protected readonly _times: Map<I, number>;
99
+ /** Time each query (by `JSON.stringify(query)`) was last marked as loaded. */
100
+ protected readonly _queryTimes: Map<string, number>;
97
101
  /** Deferred sequence that resolves on every change to this table — `false` for a change, or `true` once when the table is disposed and its sequences should end. */
98
102
  protected readonly _next: DeferredSequence<boolean, void, void>;
99
103
  /**
@@ -124,6 +128,16 @@ export declare class MemoryTable<I extends Identifier, T extends Data> implement
124
128
  * @see https://shelving.cc/db/MemoryTable/getItemSequence
125
129
  */
126
130
  getItemSequence(id: I): AsyncIterable<OptionalItem<I, T>>;
131
+ /**
132
+ * Get the time an item was last set or deleted in this table, or `undefined` if it never was.
133
+ * - Use it to tell an item that does not exist (a time and no item) from an item that has not loaded yet (no time).
134
+ *
135
+ * @param id Identifier of the item.
136
+ * @returns The time in milliseconds, or `undefined` if the item was never set or deleted.
137
+ * @example table.getItemTime(123) // 1700000000000
138
+ * @see https://shelving.cc/db/MemoryTable/getItemTime
139
+ */
140
+ getItemTime(id: I): number | undefined;
127
141
  /**
128
142
  * Generate a unique id for a new item in this table.
129
143
  * - Uses a random string for `StringSchema` ids, otherwise a random number, regenerating until it doesn't collide.
@@ -144,7 +158,8 @@ export declare class MemoryTable<I extends Identifier, T extends Data> implement
144
158
  addItem(data: T): I;
145
159
  /**
146
160
  * Set (insert or overwrite) an item by its id.
147
- * - Only resolves `next` when the stored instance actually changes.
161
+ * - Sets the item's time (see `getItemTime()`).
162
+ * - Only resolves `next` when the stored instance actually changes, or the item had no time.
148
163
  *
149
164
  * @param id Identifier of the item to set.
150
165
  * @param data Full item, or data to combine with `id` into an item.
@@ -175,7 +190,8 @@ export declare class MemoryTable<I extends Identifier, T extends Data> implement
175
190
  updateItem(id: I, updates: Updates<Item<I, T>>): void;
176
191
  /**
177
192
  * Delete an item by its id.
178
- * - Only resolves `next` when an item was actually removed.
193
+ * - Sets the item's time (see `getItemTime()`), even when the item does not exist, so the table knows the item is missing.
194
+ * - Only resolves `next` when an item was actually removed, or the item had no time.
179
195
  *
180
196
  * @param id Identifier of the item to delete.
181
197
  * @example table.deleteItem(123);
@@ -203,7 +219,7 @@ export declare class MemoryTable<I extends Identifier, T extends Data> implement
203
219
  /**
204
220
  * Subscribe to the live result of a query.
205
221
  * - Emits the current query result immediately, even if empty.
206
- * - Wakes on every table change, but only yields when the computed query result changed.
222
+ * - Wakes on every table change, but only yields when the computed query result changed, or the query was first marked as loaded (see `getQueryTime()`).
207
223
  *
208
224
  * @param query Query to filter, sort, and limit the items.
209
225
  * @returns Async sequence yielding the matching items on every change.
@@ -211,6 +227,28 @@ export declare class MemoryTable<I extends Identifier, T extends Data> implement
211
227
  * @see https://shelving.cc/db/MemoryTable/getQuerySequence
212
228
  */
213
229
  getQuerySequence(query?: Query<Item<I, T>>): AsyncIterable<Items<I, T>>;
230
+ /**
231
+ * Get the time a query was last marked as loaded in this table, or `undefined` if it never was.
232
+ * - Use it to tell a query with no items (a time and no items) from a query that has not loaded yet (no time).
233
+ * - Queries match by `JSON.stringify(query)`, so the same filters in a different key order are a different query.
234
+ *
235
+ * @param query The query, including its `$order` and `$limit`.
236
+ * @returns The time in milliseconds, or `undefined` if the query was never marked as loaded.
237
+ * @example table.getQueryTime({ user: "dave", $limit: 20 }) // 1700000000000
238
+ * @see https://shelving.cc/db/MemoryTable/getQueryTime
239
+ */
240
+ getQueryTime(query?: Query<Item<I, T>>): number | undefined;
241
+ /**
242
+ * Mark a query as loaded, i.e. the items in this table are the complete answer to the query.
243
+ * - Set the items first (e.g. with `setItems()`), then mark the query.
244
+ * - Resolves `next` when the query was not marked before, so live query sequences see the change.
245
+ *
246
+ * @param query The query, including its `$order` and `$limit`.
247
+ * @param time The time to mark the query with, in milliseconds.
248
+ * @example table.setQueryTime({ user: "dave", $limit: 20 });
249
+ * @see https://shelving.cc/db/MemoryTable/setQueryTime
250
+ */
251
+ setQueryTime(query?: Query<Item<I, T>>, time?: number): void;
214
252
  /**
215
253
  * Set (overwrite) the data for every item matching a query.
216
254
  *
@@ -148,6 +148,10 @@ export class MemoryDBProvider extends DBProvider {
148
148
  export class MemoryTable {
149
149
  /** Actual data in this table. */
150
150
  _data;
151
+ /** Time each item was last set or deleted. */
152
+ _times = new Map();
153
+ /** Time each query (by `JSON.stringify(query)`) was last marked as loaded. */
154
+ _queryTimes = new Map();
151
155
  /** Deferred sequence that resolves on every change to this table — `false` for a change, or `true` once when the table is disposed and its sequences should end. */
152
156
  _next = new DeferredSequence();
153
157
  /**
@@ -184,18 +188,33 @@ export class MemoryTable {
184
188
  */
185
189
  async *getItemSequence(id) {
186
190
  let lastValue = this.getItem(id);
191
+ let lastLoaded = this._times.has(id);
187
192
  yield lastValue;
188
193
  while (true) {
189
194
  const done = await this._next;
190
195
  if (done)
191
196
  return;
192
197
  const nextValue = this.getItem(id);
193
- if (nextValue !== lastValue) {
198
+ const nextLoaded = this._times.has(id);
199
+ if (nextValue !== lastValue || nextLoaded !== lastLoaded) {
194
200
  yield nextValue;
195
201
  lastValue = nextValue;
202
+ lastLoaded = nextLoaded;
196
203
  }
197
204
  }
198
205
  }
206
+ /**
207
+ * Get the time an item was last set or deleted in this table, or `undefined` if it never was.
208
+ * - Use it to tell an item that does not exist (a time and no item) from an item that has not loaded yet (no time).
209
+ *
210
+ * @param id Identifier of the item.
211
+ * @returns The time in milliseconds, or `undefined` if the item was never set or deleted.
212
+ * @example table.getItemTime(123) // 1700000000000
213
+ * @see https://shelving.cc/db/MemoryTable/getItemTime
214
+ */
215
+ getItemTime(id) {
216
+ return this._times.get(id);
217
+ }
199
218
  /**
200
219
  * Generate a unique id for a new item in this table.
201
220
  * - Uses a random string for `StringSchema` ids, otherwise a random number, regenerating until it doesn't collide.
@@ -226,7 +245,8 @@ export class MemoryTable {
226
245
  }
227
246
  /**
228
247
  * Set (insert or overwrite) an item by its id.
229
- * - Only resolves `next` when the stored instance actually changes.
248
+ * - Sets the item's time (see `getItemTime()`).
249
+ * - Only resolves `next` when the stored instance actually changes, or the item had no time.
230
250
  *
231
251
  * @param id Identifier of the item to set.
232
252
  * @param data Full item, or data to combine with `id` into an item.
@@ -235,10 +255,14 @@ export class MemoryTable {
235
255
  */
236
256
  setItem(id, data) {
237
257
  const item = getItem(id, data);
258
+ const loaded = this._times.has(id);
259
+ this._times.set(id, Date.now());
238
260
  if (this._data.get(id) !== item) {
239
261
  this._data.set(id, item);
240
262
  this._next.resolve(false);
241
263
  }
264
+ else if (!loaded)
265
+ this._next.resolve(false);
242
266
  }
243
267
  /**
244
268
  * Mirror an async sequence of item values into this table, passing each value through.
@@ -273,17 +297,22 @@ export class MemoryTable {
273
297
  }
274
298
  /**
275
299
  * Delete an item by its id.
276
- * - Only resolves `next` when an item was actually removed.
300
+ * - Sets the item's time (see `getItemTime()`), even when the item does not exist, so the table knows the item is missing.
301
+ * - Only resolves `next` when an item was actually removed, or the item had no time.
277
302
  *
278
303
  * @param id Identifier of the item to delete.
279
304
  * @example table.deleteItem(123);
280
305
  * @see https://shelving.cc/db/MemoryTable/deleteItem
281
306
  */
282
307
  deleteItem(id) {
308
+ const loaded = this._times.has(id);
309
+ this._times.set(id, Date.now());
283
310
  if (this._data.has(id)) {
284
311
  this._data.delete(id);
285
312
  this._next.resolve(false);
286
313
  }
314
+ else if (!loaded)
315
+ this._next.resolve(false);
287
316
  }
288
317
  /**
289
318
  * Count the items in this table matching an optional query.
@@ -310,7 +339,7 @@ export class MemoryTable {
310
339
  /**
311
340
  * Subscribe to the live result of a query.
312
341
  * - Emits the current query result immediately, even if empty.
313
- * - Wakes on every table change, but only yields when the computed query result changed.
342
+ * - Wakes on every table change, but only yields when the computed query result changed, or the query was first marked as loaded (see `getQueryTime()`).
314
343
  *
315
344
  * @param query Query to filter, sort, and limit the items.
316
345
  * @returns Async sequence yielding the matching items on every change.
@@ -318,19 +347,53 @@ export class MemoryTable {
318
347
  * @see https://shelving.cc/db/MemoryTable/getQuerySequence
319
348
  */
320
349
  async *getQuerySequence(query) {
350
+ const key = _getQueryKey(query);
321
351
  let lastItems = this.getQuery(query);
352
+ let lastLoaded = this._queryTimes.has(key);
322
353
  yield lastItems;
323
354
  while (true) {
324
355
  const done = await this._next;
325
356
  if (done)
326
357
  return;
327
358
  const nextItems = this.getQuery(query);
328
- if (!isArrayEqual(lastItems, nextItems)) {
359
+ const nextLoaded = this._queryTimes.has(key);
360
+ if (!isArrayEqual(lastItems, nextItems) || nextLoaded !== lastLoaded) {
329
361
  yield nextItems;
330
362
  lastItems = nextItems;
363
+ lastLoaded = nextLoaded;
331
364
  }
332
365
  }
333
366
  }
367
+ /**
368
+ * Get the time a query was last marked as loaded in this table, or `undefined` if it never was.
369
+ * - Use it to tell a query with no items (a time and no items) from a query that has not loaded yet (no time).
370
+ * - Queries match by `JSON.stringify(query)`, so the same filters in a different key order are a different query.
371
+ *
372
+ * @param query The query, including its `$order` and `$limit`.
373
+ * @returns The time in milliseconds, or `undefined` if the query was never marked as loaded.
374
+ * @example table.getQueryTime({ user: "dave", $limit: 20 }) // 1700000000000
375
+ * @see https://shelving.cc/db/MemoryTable/getQueryTime
376
+ */
377
+ getQueryTime(query) {
378
+ return this._queryTimes.get(_getQueryKey(query));
379
+ }
380
+ /**
381
+ * Mark a query as loaded, i.e. the items in this table are the complete answer to the query.
382
+ * - Set the items first (e.g. with `setItems()`), then mark the query.
383
+ * - Resolves `next` when the query was not marked before, so live query sequences see the change.
384
+ *
385
+ * @param query The query, including its `$order` and `$limit`.
386
+ * @param time The time to mark the query with, in milliseconds.
387
+ * @example table.setQueryTime({ user: "dave", $limit: 20 });
388
+ * @see https://shelving.cc/db/MemoryTable/setQueryTime
389
+ */
390
+ setQueryTime(query, time = Date.now()) {
391
+ const key = _getQueryKey(query);
392
+ const loaded = this._queryTimes.has(key);
393
+ this._queryTimes.set(key, time);
394
+ if (!loaded)
395
+ this._next.resolve(false);
396
+ }
334
397
  /**
335
398
  * Set (overwrite) the data for every item matching a query.
336
399
  *
@@ -386,3 +449,7 @@ export class MemoryTable {
386
449
  await awaitDispose(() => this._next.resolve(true));
387
450
  }
388
451
  }
452
+ /** Get the key that `MemoryTable` stores a query's time under. */
453
+ function _getQueryKey(query) {
454
+ return JSON.stringify(query ?? {});
455
+ }
@@ -3,12 +3,14 @@ import type { Data } from "../../util/data.js";
3
3
  import type { Identifier, Item, OptionalItem } from "../../util/item.js";
4
4
  import type { Collection } from "../collection/Collection.js";
5
5
  import type { DBProvider } from "../provider/DBProvider.js";
6
- import type { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
6
+ import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
7
7
  /**
8
8
  * Store that fetches and tracks a single item by ID in a collection from a database provider.
9
9
  *
10
10
  * - Holds an `OptionalItem` value: the item if it exists, or `undefined` if it doesn't.
11
11
  * - Seeds from a `MemoryDBProvider` snapshot when available, and subscribes to realtime updates.
12
+ * - A missing item in the memory only counts as loaded when the memory has a time for it (see `MemoryTable.getItemTime()`). Until then the store is loading.
13
+ * - When the provider is a `MemoryDBProvider`, a fetch waits until the memory has loaded the item (e.g. from `HydratingAPIProvider`).
12
14
  *
13
15
  * @example
14
16
  * const store = new ItemStore(collection, "abc", provider);
@@ -43,5 +45,5 @@ export declare class ItemStore<I extends Identifier, T extends Data> extends Fet
43
45
  get item(): Item<I, T>;
44
46
  set item(data: T | Item<I, T>);
45
47
  constructor(collection: Collection<string, I, T>, id: I, provider: DBProvider<I>, memory?: MemoryDBProvider<I>);
46
- _fetch(_signal: AbortSignal): Promise<OptionalItem<I, T>>;
48
+ _fetch(signal: AbortSignal): Promise<OptionalItem<I, T>>;
47
49
  }
@@ -1,14 +1,19 @@
1
1
  import { RequiredError } from "../../error/RequiredError.js";
2
2
  import { FetchStore } from "../../store/FetchStore.js";
3
+ import { awaitAbort, awaitRace } from "../../util/async.js";
3
4
  import { getGetter } from "../../util/class.js";
4
5
  import { NONE } from "../../util/constants.js";
6
+ import { BLACKHOLE } from "../../util/function.js";
5
7
  import { getItem } from "../../util/item.js";
6
8
  import { runSequence } from "../../util/sequence.js";
9
+ import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
7
10
  /**
8
11
  * Store that fetches and tracks a single item by ID in a collection from a database provider.
9
12
  *
10
13
  * - Holds an `OptionalItem` value: the item if it exists, or `undefined` if it doesn't.
11
14
  * - Seeds from a `MemoryDBProvider` snapshot when available, and subscribes to realtime updates.
15
+ * - A missing item in the memory only counts as loaded when the memory has a time for it (see `MemoryTable.getItemTime()`). Until then the store is loading.
16
+ * - When the provider is a `MemoryDBProvider`, a fetch waits until the memory has loaded the item (e.g. from `HydratingAPIProvider`).
12
17
  *
13
18
  * @example
14
19
  * const store = new ItemStore(collection, "abc", provider);
@@ -56,16 +61,46 @@ export class ItemStore extends FetchStore {
56
61
  this.value = getItem(this.id, data);
57
62
  }
58
63
  constructor(collection, id, provider, memory) {
59
- const item = memory?.getTable(collection).getItem(id);
60
- super(item ?? NONE); // Use the current memory snapshot if available.
61
- if (memory)
62
- this.starter = store => runSequence(store.through(memory.getItemSequence(collection, id)));
64
+ const table = memory?.getTable(collection);
65
+ super(table && _isLoaded(table, id) ? table.getItem(id) : NONE); // Use the current memory snapshot if it has loaded.
66
+ if (table)
67
+ this.starter = store => runSequence(store.through(_getLoadedSequence(table, id)));
63
68
  this.provider = provider;
64
69
  this.collection = collection;
65
70
  this.id = id;
66
71
  }
67
72
  // Override to get the item from the provider.
68
- _fetch(_signal) {
69
- return this.provider.getItem(this.collection, this.id);
73
+ // - A `MemoryDBProvider` waits until it has loaded the item.
74
+ async _fetch(signal) {
75
+ const { provider, collection, id } = this;
76
+ if (provider instanceof MemoryDBProvider) {
77
+ const table = provider.getTable(collection);
78
+ if (!_isLoaded(table, id))
79
+ await _awaitFirst(_getLoadedSequence(table, id), signal);
80
+ }
81
+ return provider.getItem(collection, id);
82
+ }
83
+ }
84
+ /** Whether the memory has loaded an item, i.e. it has the item, or a time for it. */
85
+ function _isLoaded(table, id) {
86
+ return !!table.getItem(id) || table.getItemTime(id) !== undefined;
87
+ }
88
+ /** Follow an item in the memory, but skip the values from before it has loaded. */
89
+ async function* _getLoadedSequence(table, id) {
90
+ for await (const item of table.getItemSequence(id))
91
+ if (_isLoaded(table, id))
92
+ yield item;
93
+ }
94
+ /** Get the first value of a sequence, or reject when the signal aborts. */
95
+ async function _awaitFirst(sequence, signal) {
96
+ const iterator = sequence[Symbol.asyncIterator]();
97
+ try {
98
+ const result = await awaitRace(iterator.next(), awaitAbort(signal));
99
+ if (result.done)
100
+ throw new RequiredError("Memory closed before the item loaded", { caller: _awaitFirst });
101
+ return result.value;
102
+ }
103
+ finally {
104
+ iterator.return?.().catch(BLACKHOLE);
70
105
  }
71
106
  }
@@ -4,12 +4,14 @@ import type { Identifier, Item, Items } from "../../util/item.js";
4
4
  import { type Query } from "../../util/query.js";
5
5
  import type { Collection } from "../collection/Collection.js";
6
6
  import type { DBProvider } from "../provider/DBProvider.js";
7
- import type { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
7
+ import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
8
8
  /**
9
9
  * Store that runs a query against a collection from a database provider and tracks its matching items.
10
10
  *
11
11
  * - Holds an `Items` value (the array of matching items) and is iterable over those items.
12
12
  * - Seeds from a `MemoryDBProvider` snapshot when available, and follows changes in the memory.
13
+ * - An empty result in the memory only counts as loaded when the memory has a time for the query (see `MemoryTable.getQueryTime()`). Until then the store is loading.
14
+ * - When the provider is a `MemoryDBProvider`, a fetch waits until the memory has loaded the query (e.g. from `HydratingAPIProvider`).
13
15
  * - A query with an `$order` loads in pages: `fetchAfter()` loads the next page at the end, and `fetchBefore()` loads new items at the start.
14
16
  * - A query with an `$order` pins its items: each item keeps its position after a fetch, so an edit never moves an item or removes it from view. A deleted item is hidden. New items in the memory that sort before the first item show at the start at once (e.g. an optimistic preview).
15
17
  * - A query without an `$order` follows the live query result in the memory, and cannot page.
@@ -99,7 +101,7 @@ export declare class QueryStore<I extends Identifier, T extends Data> extends Fe
99
101
  private _loaded;
100
102
  private _generation;
101
103
  constructor(collection: Collection<string, I, T>, query: Query<Item<I, T>>, provider: DBProvider<I>, memory?: MemoryDBProvider<I>);
102
- _fetch(_signal: AbortSignal): Promise<Items<I, T>>;
104
+ _fetch(signal: AbortSignal): Promise<Items<I, T>>;
103
105
  /**
104
106
  * Load the next page of items after the last item.
105
107
  * - Uses the query `$limit` as the page size.
@@ -1,18 +1,23 @@
1
1
  import { RequiredError } from "../../error/RequiredError.js";
2
2
  import { FetchStore } from "../../store/FetchStore.js";
3
3
  import { getFirst, getLast, requireFirst } from "../../util/array.js";
4
+ import { awaitAbort, awaitRace } from "../../util/async.js";
4
5
  import { getGetter } from "../../util/class.js";
5
6
  import { NONE } from "../../util/constants.js";
6
7
  import { getDataProp, joinDataPath } from "../../util/data.js";
7
8
  import { isEqual } from "../../util/equal.js";
8
- import { compareQueryItems, getAfterQuery, getBeforeQuery, getQueryFilters, getQueryLimit, getQueryOrders, matchQueryItem, sortQueryItems, } from "../../util/query.js";
9
+ import { BLACKHOLE } from "../../util/function.js";
10
+ import { compareQueryItems, getQueryAfter, getQueryBefore, getQueryFilters, getQueryLimit, getQueryOrders, matchQueryItem, sortQueryItems, } from "../../util/query.js";
9
11
  import { runSequence } from "../../util/sequence.js";
10
12
  import { isDefined } from "../../util/undefined.js";
13
+ import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
11
14
  /**
12
15
  * Store that runs a query against a collection from a database provider and tracks its matching items.
13
16
  *
14
17
  * - Holds an `Items` value (the array of matching items) and is iterable over those items.
15
18
  * - Seeds from a `MemoryDBProvider` snapshot when available, and follows changes in the memory.
19
+ * - An empty result in the memory only counts as loaded when the memory has a time for the query (see `MemoryTable.getQueryTime()`). Until then the store is loading.
20
+ * - When the provider is a `MemoryDBProvider`, a fetch waits until the memory has loaded the query (e.g. from `HydratingAPIProvider`).
16
21
  * - A query with an `$order` loads in pages: `fetchAfter()` loads the next page at the end, and `fetchBefore()` loads new items at the start.
17
22
  * - A query with an `$order` pins its items: each item keeps its position after a fetch, so an edit never moves an item or removes it from view. A deleted item is hidden. New items in the memory that sort before the first item show at the start at once (e.g. an optimistic preview).
18
23
  * - A query without an `$order` follows the live query result in the memory, and cannot page.
@@ -137,8 +142,9 @@ export class QueryStore extends FetchStore {
137
142
  _loaded = false; // Whether any items have been pinned yet.
138
143
  _generation = 0; // Increases when a refresh starts.
139
144
  constructor(collection, query, provider, memory) {
140
- const items = memory?.getTable(collection).getQuery(query);
141
- super(items ?? NONE); // Use the current memory snapshot if available.
145
+ const table = memory?.getTable(collection);
146
+ const items = table && _isLoaded(table, query) ? table.getQuery(query) : undefined;
147
+ super(items ?? NONE); // Use the current memory snapshot if it has loaded.
142
148
  this.provider = provider;
143
149
  this.collection = collection;
144
150
  this.query = query;
@@ -154,20 +160,26 @@ export class QueryStore extends FetchStore {
154
160
  if (memory)
155
161
  this.starter = store => runSequence(memory.getQuerySequence(collection), () => store._recompose());
156
162
  }
157
- else if (memory) {
158
- // Unpaged query: follow the live query result in the memory.
159
- this.starter = store => runSequence(store.through(memory.getQuerySequence(collection, query)));
163
+ else if (table) {
164
+ // Unpaged query: follow the live query result in the memory, once it has loaded.
165
+ this.starter = store => runSequence(store.through(_getLoadedSequence(table, query)));
160
166
  }
161
167
  }
162
168
  // Override to fetch the result from the database provider.
163
169
  // - A paged query loads the first page again, and drops any other loaded pages.
164
- async _fetch(_signal) {
170
+ // - A `MemoryDBProvider` waits until it has loaded the query.
171
+ async _fetch(signal) {
172
+ const { provider, collection, query, limit } = this;
173
+ if (provider instanceof MemoryDBProvider) {
174
+ const table = provider.getTable(collection);
175
+ if (!_isLoaded(table, query))
176
+ await _awaitFirst(_getLoadedSequence(table, query), signal);
177
+ }
165
178
  if (!this._orders.length)
166
- return this.provider.getQuery(this.collection, this.query);
167
- const { collection, query, limit } = this;
179
+ return provider.getQuery(collection, query);
168
180
  const generation = ++this._generation; // Makes any page fetch that is still running drop its result.
169
181
  // Load one more item than the page, to see if there are more.
170
- const items = await this.provider.getQuery(collection, _withLimit(query, limit + 1));
182
+ const items = await provider.getQuery(collection, _withLimit(query, limit + 1));
171
183
  if (generation !== this._generation)
172
184
  return this._compose(); // A newer refresh started, so it sets the items.
173
185
  this._hasAfter = items.length > limit;
@@ -203,7 +215,7 @@ export class QueryStore extends FetchStore {
203
215
  }
204
216
  if (!this._hasAfter)
205
217
  return;
206
- const items = await this._fetchPage(getAfterQuery(query, last, this.fetchAfter), last);
218
+ const items = await this._fetchPage(getQueryAfter(query, last, this.fetchAfter), last);
207
219
  if (!items)
208
220
  return;
209
221
  this._hasAfter = items.length > limit;
@@ -245,7 +257,7 @@ export class QueryStore extends FetchStore {
245
257
  return;
246
258
  }
247
259
  // Reverse the order so the items nearest to the first item come first.
248
- const items = await this._fetchPage({ ...getBeforeQuery(query, first, this.fetchBefore), $order: _reverseOrders(this._orders) }, first);
260
+ const items = await this._fetchPage({ ...getQueryBefore(query, first, this.fetchBefore), $order: _reverseOrders(this._orders) }, first);
249
261
  if (!items)
250
262
  return;
251
263
  this._hasBefore = items.length > limit;
@@ -356,3 +368,26 @@ function _withLimit(query, limit) {
356
368
  function _reverseOrders(orders) {
357
369
  return orders.map(({ key, direction }) => `${direction === "asc" ? "!" : ""}${joinDataPath(key)}`);
358
370
  }
371
+ /** Whether the memory has loaded a query, i.e. it has items for it, or a time for it. */
372
+ function _isLoaded(table, query) {
373
+ return table.getQueryTime(query) !== undefined || !!table.countQuery(query);
374
+ }
375
+ /** Follow a query in the memory, but skip the results from before it has loaded. */
376
+ async function* _getLoadedSequence(table, query) {
377
+ for await (const items of table.getQuerySequence(query))
378
+ if (items.length || table.getQueryTime(query) !== undefined)
379
+ yield items;
380
+ }
381
+ /** Get the first value of a sequence, or reject when the signal aborts. */
382
+ async function _awaitFirst(sequence, signal) {
383
+ const iterator = sequence[Symbol.asyncIterator]();
384
+ try {
385
+ const result = await awaitRace(iterator.next(), awaitAbort(signal));
386
+ if (result.done)
387
+ throw new RequiredError("Memory closed before the query loaded", { caller: _awaitFirst });
388
+ return result.value;
389
+ }
390
+ finally {
391
+ iterator.return?.().catch(BLACKHOLE);
392
+ }
393
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.307.3",
3
+ "version": "1.308.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -18,6 +18,7 @@ export interface DialogProps extends OptionalChildProps {
18
18
  * - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
19
19
  * - A tap on a control (button, input, select, textarea, label) or inside a `<Modal>` panel does not close it. A tap on a link or a `<nav>` button always closes it.
20
20
  * - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
21
+ * - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
21
22
  * - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
22
23
  * - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
23
24
  * - Wraps content in `<Suspense>` so lazy children can stream in.
@@ -12,6 +12,7 @@ import modalStyles from "./Modal.module.css";
12
12
  * - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
13
13
  * - A tap on a control (button, input, select, textarea, label) or inside a `<Modal>` panel does not close it. A tap on a link or a `<nav>` button always closes it.
14
14
  * - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
15
+ * - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
15
16
  * - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
16
17
  * - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
17
18
  * - Wraps content in `<Suspense>` so lazy children can stream in.
@@ -20,7 +21,7 @@ import modalStyles from "./Modal.module.css";
20
21
  * @see https://shelving.cc/ui/Dialog
21
22
  */
22
23
  export const Dialog = memo(({ children, onClose, ...props }) => {
23
- return (_jsx(Suspense, { fallback: null, children: _jsx(ViewTransition, { enter: "fade", exit: "fade", children: _jsxs("dialog", { ref: _showModal, className: getModuleClass(styles, "dialog"), onClick: _closeOnClick, onCancel: e => {
24
+ return (_jsx(Suspense, { fallback: null, children: _jsx(ViewTransition, { default: "none", enter: "fade", exit: "fade", children: _jsxs("dialog", { ref: _showModal, className: getModuleClass(styles, "dialog"), onClick: _closeOnClick, onCancel: e => {
24
25
  // Keep the dialog open and let the parent unmount it in a transition. An uncancelable request closes natively and fires `onClose` from the `close` event.
25
26
  if (!onClose || !e.cancelable)
26
27
  return;
@@ -12,6 +12,7 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
12
12
  - `Dialog` only dims the page. Its text is white (`--tint-100`) so it reads on the dark overlay. Wrap the content in `<Modal>` to give it a panel with dark text on a light surface.
13
13
  - `onClose` fires when the user closes the dialog. It must unmount the `Dialog`: clear the React state that mounts it, or (when pushed via a store) remove it from the list. `Dialog` calls `onClose` inside `startTransition()`, and the dialog stays open until it unmounts.
14
14
  - The dialog animates with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). The whole dialog fades in and out as one layer. A `<Modal>` pinned to an edge takes its own layer and slides.
15
+ - A change inside an open dialog (new content, a Suspense reveal) runs no view transition, so the dialog never ignores a tap while its content changes. The page ignores taps while a view transition runs.
15
16
  - A view transition only runs for a React transition update. `DialogsStore` and `onClose` do this for you. To animate a declarative `Dialog` as it opens, set the state that mounts it inside `startTransition()`.
16
17
  - A browser without view transitions shows and hides the dialog at once.
17
18
  - Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app.
@@ -24,6 +24,7 @@ export interface DialogProps extends OptionalChildProps {
24
24
  * - Opens via `showModal()` when mounted, and closes on a tap anywhere on it, the close button, or the Escape key.
25
25
  * - A tap on a control (button, input, select, textarea, label) or inside a `<Modal>` panel does not close it. A tap on a link or a `<nav>` button always closes it.
26
26
  * - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
27
+ * - A change inside an open dialog (new content, a Suspense reveal) runs no view transition. The page ignores taps while one runs.
27
28
  * - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
28
29
  * - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
29
30
  * - Wraps content in `<Suspense>` so lazy children can stream in.
@@ -34,8 +35,8 @@ export interface DialogProps extends OptionalChildProps {
34
35
  export const Dialog = memo(({ children, onClose, ...props }: DialogProps) => {
35
36
  return (
36
37
  <Suspense fallback={null}>
37
- {/* The transition must wrap the `<dialog>`: React only animates a `<ViewTransition>` that comes before any DOM element in the inserted or deleted tree. Fade only on enter and exit, so an open dialog stays still while another dialog opens or closes. */}
38
- <ViewTransition enter="fade" exit="fade">
38
+ {/* The transition must wrap the `<dialog>`: React only animates a `<ViewTransition>` that comes before any DOM element in the inserted or deleted tree. Fade only on enter and exit, so an open dialog stays still while another dialog opens or closes. No update transition: the page ignores taps while a view transition runs, so a change inside an open dialog must not start one. */}
39
+ <ViewTransition default="none" enter="fade" exit="fade">
39
40
  {/** biome-ignore lint/a11y/useKeyWithClickEvents: Dialogs also show a close button. */}
40
41
  <dialog
41
42
  ref={_showModal}
package/util/query.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import type { ImmutableArray } from "./array.js";
2
2
  import type { Data, LeafData, LeafDataPath } from "./data.js";
3
3
  import type { AnyCaller } from "./function.js";
4
+ import type { Identifier, Item, Items } from "./item.js";
4
5
  import type { Segments } from "./string.js";
5
6
  /**
6
7
  * Query that can be applied to a list of data objects.
@@ -152,10 +153,10 @@ export declare function limitQueryItems<T extends Data>(items: ImmutableArray<T>
152
153
  * @param item The item to page from (normally the first item already loaded).
153
154
  * @returns A new query with the range added.
154
155
  * @throws {RequiredError} If the query has no `$order`, or `item` has no value for the first `$order` key.
155
- * @example getBeforeQuery({ $order: "!when" }, { id: "a", when: 5 }) // { $order: "!when", "when>=": 5 }
156
- * @see https://shelving.cc/util/query/getBeforeQuery
156
+ * @example getQueryBefore({ $order: "!when" }, { id: "a", when: 5 }) // { $order: "!when", "when>=": 5 }
157
+ * @see https://shelving.cc/util/query/getQueryBefore
157
158
  */
158
- export declare function getBeforeQuery<T extends Data>(query: Query<T>, item: T, caller?: AnyCaller): Query<T>;
159
+ export declare function getQueryBefore<T extends Data>(query: Query<T>, item: T, caller?: AnyCaller): Query<T>;
159
160
  /**
160
161
  * Get a query for the items that sort at or after a specified item.
161
162
  * - For cursor-based paging towards the end of a result set.
@@ -167,7 +168,29 @@ export declare function getBeforeQuery<T extends Data>(query: Query<T>, item: T,
167
168
  * @param item The item to page from (normally the last item already loaded).
168
169
  * @returns A new query with the range added.
169
170
  * @throws {RequiredError} If the query has no `$order`, or `item` has no value for the first `$order` key.
170
- * @example getAfterQuery({ $order: "!when" }, { id: "a", when: 5 }) // { $order: "!when", "when<=": 5 }
171
- * @see https://shelving.cc/util/query/getAfterQuery
171
+ * @example getQueryAfter({ $order: "!when" }, { id: "a", when: 5 }) // { $order: "!when", "when<=": 5 }
172
+ * @see https://shelving.cc/util/query/getQueryAfter
172
173
  */
173
- export declare function getAfterQuery<T extends Data>(query: Query<T>, item: T, caller?: AnyCaller): Query<T>;
174
+ export declare function getQueryAfter<T extends Data>(query: Query<T>, item: T, caller?: AnyCaller): Query<T>;
175
+ /**
176
+ * A query and the items that answer it, e.g. one page of results from an API endpoint.
177
+ *
178
+ * @see https://shelving.cc/util/query/QueryItems
179
+ */
180
+ export type QueryItems<I extends Identifier = Identifier, T extends Data = Data> = {
181
+ readonly query: Query<Item<I, T>>;
182
+ readonly items: Items<I, T>;
183
+ };
184
+ /**
185
+ * Get the query for the next page after a page of `QueryItems`, or `undefined` if there are no more items.
186
+ * - There are no more items when the query has no `$limit`, or the page has fewer items than the `$limit`.
187
+ * - The cursor is the last item of the page, so it comes from the page itself and never from a cache.
188
+ * - The range is inclusive (see `getQueryAfter()`), so the `$limit` grows by the number of items with the same sort value as the last item. The next page repeats those items.
189
+ *
190
+ * @param queryItems The page to continue from. Its query must have an `$order`.
191
+ * @returns The query for the next page, or `undefined` if there are no more items.
192
+ * @throws {RequiredError} If the query has no `$order`, or the last item has no value for the first `$order` key.
193
+ * @example getQueryItemsAfter({ query: { $order: "when", $limit: 2 }, items: [a, b] }) // { $order: "when", $limit: 3, "when>=": b.when }
194
+ * @see https://shelving.cc/util/query/getQueryItemsAfter
195
+ */
196
+ export declare function getQueryItemsAfter<I extends Identifier, T extends Data>({ query, items }: QueryItems<I, T>, caller?: AnyCaller): Query<Item<I, T>> | undefined;
package/util/query.js CHANGED
@@ -167,10 +167,10 @@ export function limitQueryItems(items, limit) {
167
167
  * @param item The item to page from (normally the first item already loaded).
168
168
  * @returns A new query with the range added.
169
169
  * @throws {RequiredError} If the query has no `$order`, or `item` has no value for the first `$order` key.
170
- * @example getBeforeQuery({ $order: "!when" }, { id: "a", when: 5 }) // { $order: "!when", "when>=": 5 }
171
- * @see https://shelving.cc/util/query/getBeforeQuery
170
+ * @example getQueryBefore({ $order: "!when" }, { id: "a", when: 5 }) // { $order: "!when", "when>=": 5 }
171
+ * @see https://shelving.cc/util/query/getQueryBefore
172
172
  */
173
- export function getBeforeQuery(query, item, caller = getBeforeQuery) {
173
+ export function getQueryBefore(query, item, caller = getQueryBefore) {
174
174
  const { key, direction } = requireFirst(getQueryOrders(query), caller);
175
175
  return _withRange(query, key, direction === "asc" ? "<=" : ">=", _requireCursor(item, key, caller));
176
176
  }
@@ -185,13 +185,40 @@ export function getBeforeQuery(query, item, caller = getBeforeQuery) {
185
185
  * @param item The item to page from (normally the last item already loaded).
186
186
  * @returns A new query with the range added.
187
187
  * @throws {RequiredError} If the query has no `$order`, or `item` has no value for the first `$order` key.
188
- * @example getAfterQuery({ $order: "!when" }, { id: "a", when: 5 }) // { $order: "!when", "when<=": 5 }
189
- * @see https://shelving.cc/util/query/getAfterQuery
188
+ * @example getQueryAfter({ $order: "!when" }, { id: "a", when: 5 }) // { $order: "!when", "when<=": 5 }
189
+ * @see https://shelving.cc/util/query/getQueryAfter
190
190
  */
191
- export function getAfterQuery(query, item, caller = getAfterQuery) {
191
+ export function getQueryAfter(query, item, caller = getQueryAfter) {
192
192
  const { key, direction } = requireFirst(getQueryOrders(query), caller);
193
193
  return _withRange(query, key, direction === "asc" ? ">=" : "<=", _requireCursor(item, key, caller));
194
194
  }
195
+ /**
196
+ * Get the query for the next page after a page of `QueryItems`, or `undefined` if there are no more items.
197
+ * - There are no more items when the query has no `$limit`, or the page has fewer items than the `$limit`.
198
+ * - The cursor is the last item of the page, so it comes from the page itself and never from a cache.
199
+ * - The range is inclusive (see `getQueryAfter()`), so the `$limit` grows by the number of items with the same sort value as the last item. The next page repeats those items.
200
+ *
201
+ * @param queryItems The page to continue from. Its query must have an `$order`.
202
+ * @returns The query for the next page, or `undefined` if there are no more items.
203
+ * @throws {RequiredError} If the query has no `$order`, or the last item has no value for the first `$order` key.
204
+ * @example getQueryItemsAfter({ query: { $order: "when", $limit: 2 }, items: [a, b] }) // { $order: "when", $limit: 3, "when>=": b.when }
205
+ * @see https://shelving.cc/util/query/getQueryItemsAfter
206
+ */
207
+ export function getQueryItemsAfter({ query, items }, caller = getQueryItemsAfter) {
208
+ const limit = getQueryLimit(query);
209
+ if (limit === undefined || items.length < limit)
210
+ return;
211
+ const last = items.at(-1);
212
+ if (!last)
213
+ return;
214
+ const { key } = requireFirst(getQueryOrders(query), caller);
215
+ const value = _requireCursor(last, key, caller);
216
+ let ties = 0;
217
+ for (const item of items)
218
+ if (isEqual(getDataProp(item, key), value))
219
+ ties++;
220
+ return { ...getQueryAfter(query, last, caller), $limit: limit + ties };
221
+ }
195
222
  /** Get the cursor value of an item, or throw if it has none (a range on `undefined` would be dropped). */
196
223
  function _requireCursor(item, key, caller) {
197
224
  const value = getDataProp(item, key);