shelving 1.307.4 → 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 +1 -0
- package/api/index.js +1 -0
- package/api/provider/HydratingAPIProvider.d.ts +28 -0
- package/api/provider/HydratingAPIProvider.js +82 -0
- package/db/collection/Collection.d.ts +24 -1
- package/db/collection/Collection.js +28 -2
- package/db/collection/CollectionItemSchema.d.ts +24 -0
- package/db/collection/CollectionItemSchema.js +23 -0
- package/db/collection/CollectionItemsSchema.d.ts +25 -0
- package/db/collection/CollectionItemsSchema.js +24 -0
- package/db/collection/CollectionQueryItemsSchema.d.ts +27 -0
- package/db/collection/CollectionQueryItemsSchema.js +25 -0
- package/db/collection/CollectionQuerySchema.d.ts +25 -0
- package/db/collection/CollectionQuerySchema.js +28 -0
- package/db/index.d.ts +4 -0
- package/db/index.js +4 -0
- package/db/provider/CacheDBProvider.d.ts +1 -1
- package/db/provider/CacheDBProvider.js +4 -2
- package/db/provider/MemoryDBProvider.d.ts +41 -3
- package/db/provider/MemoryDBProvider.js +72 -5
- package/db/store/ItemStore.d.ts +4 -2
- package/db/store/ItemStore.js +41 -6
- package/db/store/QueryStore.d.ts +4 -2
- package/db/store/QueryStore.js +47 -12
- package/package.json +1 -1
- package/util/query.d.ts +29 -6
- package/util/query.js +33 -6
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:
|
|
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
|
|
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 =
|
|
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)
|
|
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
|
-
* -
|
|
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
|
-
* -
|
|
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
|
-
|
|
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
|
-
* -
|
|
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
|
-
* -
|
|
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
|
-
|
|
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
|
+
}
|
package/db/store/ItemStore.d.ts
CHANGED
|
@@ -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
|
|
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(
|
|
48
|
+
_fetch(signal: AbortSignal): Promise<OptionalItem<I, T>>;
|
|
47
49
|
}
|
package/db/store/ItemStore.js
CHANGED
|
@@ -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
|
|
60
|
-
super(
|
|
61
|
-
if (
|
|
62
|
-
this.starter = store => runSequence(store.through(
|
|
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
|
-
|
|
69
|
-
|
|
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
|
}
|
package/db/store/QueryStore.d.ts
CHANGED
|
@@ -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
|
|
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(
|
|
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.
|
package/db/store/QueryStore.js
CHANGED
|
@@ -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 {
|
|
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
|
|
141
|
-
|
|
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 (
|
|
158
|
-
// Unpaged query: follow the live query result in the memory.
|
|
159
|
-
this.starter = store => runSequence(store.through(
|
|
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
|
-
|
|
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
|
|
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
|
|
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(
|
|
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({ ...
|
|
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
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
|
|
156
|
-
* @see https://shelving.cc/util/query/
|
|
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
|
|
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
|
|
171
|
-
* @see https://shelving.cc/util/query/
|
|
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
|
|
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
|
|
171
|
-
* @see https://shelving.cc/util/query/
|
|
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
|
|
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
|
|
189
|
-
* @see https://shelving.cc/util/query/
|
|
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
|
|
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);
|