shelving 1.307.4 → 1.309.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/cache/CollectionCache.d.ts +1 -7
- package/db/cache/CollectionCache.js +3 -9
- package/db/cache/DBCache.d.ts +1 -7
- package/db/cache/DBCache.js +2 -12
- 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 -1
- package/db/index.js +4 -1
- package/db/provider/MemoryDBProvider.d.ts +42 -4
- package/db/provider/MemoryDBProvider.js +73 -6
- package/db/provider/RecordingDBProvider.d.ts +1 -1
- package/db/provider/RecordingDBProvider.js +1 -1
- package/db/provider/StorageDBProvider.d.ts +1 -1
- package/db/provider/StorageDBProvider.js +1 -1
- package/db/store/ItemStore.d.ts +6 -4
- package/db/store/ItemStore.js +55 -8
- package/db/store/QueryStore.d.ts +9 -99
- package/db/store/QueryStore.js +55 -260
- package/package.json +1 -1
- package/react/createDBContext.d.ts +1 -1
- package/react/createDBContext.js +1 -1
- package/util/query.d.ts +29 -6
- package/util/query.js +33 -6
- package/db/provider/CacheDBProvider.d.ts +0 -56
- package/db/provider/CacheDBProvider.js +0 -105
package/db/store/QueryStore.js
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
1
|
import { RequiredError } from "../../error/RequiredError.js";
|
|
2
|
+
import { UnsupportedError } from "../../error/UnsupportedError.js";
|
|
2
3
|
import { FetchStore } from "../../store/FetchStore.js";
|
|
3
|
-
import { getFirst, getLast
|
|
4
|
+
import { getFirst, getLast } from "../../util/array.js";
|
|
5
|
+
import { awaitAbort, awaitRace } from "../../util/async.js";
|
|
4
6
|
import { getGetter } from "../../util/class.js";
|
|
5
7
|
import { NONE } from "../../util/constants.js";
|
|
6
|
-
import {
|
|
7
|
-
import { isEqual } from "../../util/equal.js";
|
|
8
|
-
import { compareQueryItems, getAfterQuery, getBeforeQuery, getQueryFilters, getQueryLimit, getQueryOrders, matchQueryItem, sortQueryItems, } from "../../util/query.js";
|
|
8
|
+
import { BLACKHOLE } from "../../util/function.js";
|
|
9
9
|
import { runSequence } from "../../util/sequence.js";
|
|
10
|
-
import {
|
|
10
|
+
import { getSource } from "../../util/source.js";
|
|
11
|
+
import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
|
|
11
12
|
/**
|
|
12
13
|
* Store that runs a query against a collection from a database provider and tracks its matching items.
|
|
13
14
|
*
|
|
14
15
|
* - Holds an `Items` value (the array of matching items) and is iterable over those items.
|
|
15
|
-
* -
|
|
16
|
-
* -
|
|
17
|
-
* -
|
|
18
|
-
* - A query without an `$order` follows the live query result in the memory, and cannot page.
|
|
16
|
+
* - When the provider is (or wraps) a `MemoryDBProvider`, the store seeds from the memory at once and follows the live query result. An empty result only counts as loaded when the memory has a time for the query (see `MemoryTable.getQueryTime()`). Until then the store is loading, and a fetch waits until the memory loads the query (e.g. from `HydratingAPIProvider`).
|
|
17
|
+
* - Any other provider is fetched, and its `DBProvider.getQuerySequence()` is followed while the store has subscribers. A provider that throws `UnsupportedError` for subscriptions is only fetched.
|
|
18
|
+
* - The store does not page. To load more items into a memory, call the API with `getQueryItemsAfter()`, and the store shows the new items.
|
|
19
19
|
*
|
|
20
20
|
* @example
|
|
21
21
|
* const store = new QueryStore(collection, query, provider);
|
|
@@ -38,43 +38,6 @@ export class QueryStore extends FetchStore {
|
|
|
38
38
|
* @see https://shelving.cc/db/QueryStore/query
|
|
39
39
|
*/
|
|
40
40
|
query;
|
|
41
|
-
/**
|
|
42
|
-
* The memory provider this store seeds from and follows, if available.
|
|
43
|
-
* @see https://shelving.cc/db/QueryStore/memory
|
|
44
|
-
*/
|
|
45
|
-
memory;
|
|
46
|
-
/**
|
|
47
|
-
* The maximum number of items the query can return, or `Infinity` if unlimited.
|
|
48
|
-
* - For a paged query, this is the size of each page.
|
|
49
|
-
* @see https://shelving.cc/db/QueryStore/limit
|
|
50
|
-
*/
|
|
51
|
-
get limit() {
|
|
52
|
-
return getQueryLimit(this.query) ?? Number.POSITIVE_INFINITY;
|
|
53
|
-
}
|
|
54
|
-
/**
|
|
55
|
-
* Whether more items can be loaded after the last item with `fetchAfter()`.
|
|
56
|
-
* @see https://shelving.cc/db/QueryStore/hasAfter
|
|
57
|
-
*/
|
|
58
|
-
get hasAfter() {
|
|
59
|
-
return this._hasAfter;
|
|
60
|
-
}
|
|
61
|
-
_hasAfter = false;
|
|
62
|
-
/**
|
|
63
|
-
* Whether more items can be loaded before the first item with `fetchBefore()`.
|
|
64
|
-
* - `false` after the first fetch, because the first page starts at the start. It becomes `true` when `fetchBefore()` finds more new items than one page.
|
|
65
|
-
* @see https://shelving.cc/db/QueryStore/hasBefore
|
|
66
|
-
*/
|
|
67
|
-
get hasBefore() {
|
|
68
|
-
return this._hasBefore;
|
|
69
|
-
}
|
|
70
|
-
_hasBefore = false;
|
|
71
|
-
/**
|
|
72
|
-
* Whether more items can be loaded after the last item. Alias of `hasAfter`.
|
|
73
|
-
* @see https://shelving.cc/db/QueryStore/hasMore
|
|
74
|
-
*/
|
|
75
|
-
get hasMore() {
|
|
76
|
-
return this._hasAfter;
|
|
77
|
-
}
|
|
78
41
|
/**
|
|
79
42
|
* The first item in this store, or `undefined` if the query has no items.
|
|
80
43
|
* @see https://shelving.cc/db/QueryStore/optionalFirst
|
|
@@ -129,230 +92,62 @@ export class QueryStore extends FetchStore {
|
|
|
129
92
|
});
|
|
130
93
|
return last;
|
|
131
94
|
}
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
_loaded = false; // Whether any items have been pinned yet.
|
|
138
|
-
_generation = 0; // Increases when a refresh starts.
|
|
139
|
-
constructor(collection, query, provider, memory) {
|
|
140
|
-
const items = memory?.getTable(collection).getQuery(query);
|
|
141
|
-
super(items ?? NONE); // Use the current memory snapshot if available.
|
|
95
|
+
/** The memory table the provider is backed by, if any. */
|
|
96
|
+
_table;
|
|
97
|
+
constructor(collection, query, provider) {
|
|
98
|
+
const table = getSource(MemoryDBProvider, provider)?.getTable(collection);
|
|
99
|
+
super(table && _isLoaded(table, query) ? table.getQuery(query) : NONE); // Use the current memory snapshot if it has loaded.
|
|
142
100
|
this.provider = provider;
|
|
143
101
|
this.collection = collection;
|
|
144
102
|
this.query = query;
|
|
145
|
-
this.
|
|
146
|
-
this.
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
// Paged query: pin the snapshot, and recompose the pinned items whenever the memory changes.
|
|
150
|
-
if (items) {
|
|
151
|
-
this._pin(items);
|
|
152
|
-
this._hasAfter = items.length >= this.limit; // A full snapshot may have more items after it.
|
|
153
|
-
}
|
|
154
|
-
if (memory)
|
|
155
|
-
this.starter = store => runSequence(memory.getQuerySequence(collection), () => store._recompose());
|
|
156
|
-
}
|
|
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)));
|
|
160
|
-
}
|
|
103
|
+
this._table = table;
|
|
104
|
+
this.starter = table
|
|
105
|
+
? store => runSequence(store.through(_getLoadedSequence(table, query)))
|
|
106
|
+
: store => runSequence(store.through(_getSupportedSequence(() => provider.getQuerySequence(collection, query))), undefined, reason => (store.reason = reason));
|
|
161
107
|
}
|
|
162
108
|
// Override to fetch the result from the database provider.
|
|
163
|
-
// - A
|
|
164
|
-
async _fetch(
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
// 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));
|
|
171
|
-
if (generation !== this._generation)
|
|
172
|
-
return this._compose(); // A newer refresh started, so it sets the items.
|
|
173
|
-
this._hasAfter = items.length > limit;
|
|
174
|
-
this._hasBefore = false;
|
|
175
|
-
this._pin(items.slice(0, limit));
|
|
176
|
-
return this._compose();
|
|
177
|
-
}
|
|
178
|
-
/**
|
|
179
|
-
* Load the next page of items after the last item.
|
|
180
|
-
* - Uses the query `$limit` as the page size.
|
|
181
|
-
* - Sets `busy` while the page loads. The items already loaded do not suspend.
|
|
182
|
-
* - Waits for a fetch that is already running, then loads the page.
|
|
183
|
-
* - Does nothing if `hasAfter` is `false`.
|
|
184
|
-
* - Loads the first page if no items have loaded yet.
|
|
185
|
-
* - A failed fetch rejects the promise, and the items already loaded stay. Unlike `refresh()`, it does not set `reason`.
|
|
186
|
-
*
|
|
187
|
-
* @returns Promise that resolves when the page has loaded.
|
|
188
|
-
* @throws {RequiredError} If the query has no `$order`.
|
|
189
|
-
* @throws {unknown} The error from the provider, if the fetch fails.
|
|
190
|
-
* @example if (store.hasAfter) await store.fetchAfter();
|
|
191
|
-
* @see https://shelving.cc/db/QueryStore/fetchAfter
|
|
192
|
-
*/
|
|
193
|
-
async fetchAfter() {
|
|
194
|
-
const { query, limit } = this;
|
|
195
|
-
if (!this._orders.length)
|
|
196
|
-
throw new RequiredError("Query must have $order to fetch more items", { store: this, query, caller: this.fetchAfter });
|
|
197
|
-
if (this.busy.value)
|
|
198
|
-
await this._idle(); // Only await when busy, so `busy` is set at once.
|
|
199
|
-
const last = this._getRow(this._ids.at(-1));
|
|
200
|
-
if (!last) {
|
|
201
|
-
await this.refresh();
|
|
202
|
-
return;
|
|
203
|
-
}
|
|
204
|
-
if (!this._hasAfter)
|
|
205
|
-
return;
|
|
206
|
-
const items = await this._fetchPage(getAfterQuery(query, last, this.fetchAfter), last);
|
|
207
|
-
if (!items)
|
|
208
|
-
return;
|
|
209
|
-
this._hasAfter = items.length > limit;
|
|
210
|
-
this._pin([...this._ids, ...items.slice(0, limit)]);
|
|
211
|
-
this.write(this._compose());
|
|
212
|
-
}
|
|
213
|
-
/**
|
|
214
|
-
* Load the next page of items after the last item. Alias of `fetchAfter()`.
|
|
215
|
-
*
|
|
216
|
-
* @returns Promise that resolves when the page has loaded.
|
|
217
|
-
* @see https://shelving.cc/db/QueryStore/fetchMore
|
|
218
|
-
*/
|
|
219
|
-
fetchMore() {
|
|
220
|
-
return this.fetchAfter();
|
|
221
|
-
}
|
|
222
|
-
/**
|
|
223
|
-
* Load the new items before the first item, e.g. new messages at the start of a newest-first list.
|
|
224
|
-
* - Loads up to one page (the query `$limit`), nearest to the first item. Call again while `hasBefore` is `true` to load more.
|
|
225
|
-
* - Sets `busy` while the items load. The items already loaded do not suspend.
|
|
226
|
-
* - Waits for a fetch that is already running, then loads the items.
|
|
227
|
-
* - Loads the first page if no items have loaded yet.
|
|
228
|
-
* - A failed fetch rejects the promise, and the items already loaded stay. Unlike `refresh()`, it does not set `reason`.
|
|
229
|
-
*
|
|
230
|
-
* @returns Promise that resolves when the new items have loaded.
|
|
231
|
-
* @throws {RequiredError} If the query has no `$order`.
|
|
232
|
-
* @throws {unknown} The error from the provider, if the fetch fails.
|
|
233
|
-
* @example setInterval(() => store.fetchBefore().catch(BLACKHOLE), 10_000); // Poll for new messages.
|
|
234
|
-
* @see https://shelving.cc/db/QueryStore/fetchBefore
|
|
235
|
-
*/
|
|
236
|
-
async fetchBefore() {
|
|
237
|
-
const { query, limit } = this;
|
|
238
|
-
if (!this._orders.length)
|
|
239
|
-
throw new RequiredError("Query must have $order to fetch more items", { store: this, query, caller: this.fetchBefore });
|
|
240
|
-
if (this.busy.value)
|
|
241
|
-
await this._idle(); // Only await when busy, so `busy` is set at once.
|
|
242
|
-
const first = this._getRow(this._ids[0]);
|
|
243
|
-
if (!first) {
|
|
244
|
-
await this.refresh();
|
|
245
|
-
return;
|
|
246
|
-
}
|
|
247
|
-
// 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);
|
|
249
|
-
if (!items)
|
|
250
|
-
return;
|
|
251
|
-
this._hasBefore = items.length > limit;
|
|
252
|
-
this._pin([...items.slice(0, limit).reverse(), ...this._ids]);
|
|
253
|
-
this.write(this._compose());
|
|
254
|
-
}
|
|
255
|
-
/** Wait until no fetch is running. */
|
|
256
|
-
async _idle() {
|
|
257
|
-
while (this.busy.value)
|
|
258
|
-
await this.busy.next;
|
|
259
|
-
}
|
|
260
|
-
/** Fetch one page from an inclusive cursor query, and drop the items already loaded. */
|
|
261
|
-
async _fetchPage(query, cursor) {
|
|
262
|
-
const { _ids, _rows, limit } = this;
|
|
263
|
-
const { key } = requireFirst(this._orders);
|
|
264
|
-
const value = getDataProp(cursor, key);
|
|
265
|
-
// The inclusive range returns the loaded items with the same sort value as the cursor again, so ask for that many more.
|
|
266
|
-
let ties = 0;
|
|
267
|
-
for (const id of _ids) {
|
|
268
|
-
const row = _rows.get(id);
|
|
269
|
-
if (row && isEqual(getDataProp(row, key), value))
|
|
270
|
-
ties++;
|
|
271
|
-
}
|
|
272
|
-
// A refresh that starts while the page loads owns the items and `busy`, so the page is dropped.
|
|
273
|
-
const generation = this._generation;
|
|
274
|
-
this.busy.value = true;
|
|
275
|
-
try {
|
|
276
|
-
const items = await this.provider.getQuery(this.collection, _withLimit(query, limit + ties + 1));
|
|
277
|
-
if (generation !== this._generation)
|
|
278
|
-
return;
|
|
279
|
-
const seen = new Set(_ids);
|
|
280
|
-
return items.filter(({ id }) => !seen.has(id));
|
|
281
|
-
}
|
|
282
|
-
catch (thrown) {
|
|
283
|
-
if (generation === this._generation)
|
|
284
|
-
throw thrown; // Keep the loaded items, so do not set `reason`.
|
|
285
|
-
}
|
|
286
|
-
finally {
|
|
287
|
-
if (generation === this._generation)
|
|
288
|
-
this.busy.value = false;
|
|
289
|
-
}
|
|
290
|
-
}
|
|
291
|
-
/** Pin a list of items (or IDs of items already pinned) as the loaded items, in display order. */
|
|
292
|
-
_pin(items) {
|
|
293
|
-
const rows = new Map();
|
|
294
|
-
const ids = [];
|
|
295
|
-
for (const item of items) {
|
|
296
|
-
const row = typeof item === "object" ? item : this._rows.get(item);
|
|
297
|
-
if (!row || rows.has(row.id))
|
|
298
|
-
continue;
|
|
299
|
-
rows.set(row.id, row);
|
|
300
|
-
ids.push(row.id);
|
|
301
|
-
}
|
|
302
|
-
this._ids = ids;
|
|
303
|
-
this._rows = rows;
|
|
304
|
-
this._loaded = true;
|
|
305
|
-
// Put the fetched items in the memory, so other stores can use them.
|
|
306
|
-
if (this.memory)
|
|
307
|
-
this.memory.getTable(this.collection).setItems(items.filter(item => typeof item === "object"));
|
|
308
|
-
}
|
|
309
|
-
/** Get a pinned item as it was fetched. */
|
|
310
|
-
_getRow(id) {
|
|
311
|
-
return id === undefined ? undefined : this._rows.get(id);
|
|
312
|
-
}
|
|
313
|
-
/**
|
|
314
|
-
* Make the current value of a paged query.
|
|
315
|
-
* - New items in the memory that match the filters and sort before the first pinned item come first.
|
|
316
|
-
* - When the list is complete (`hasAfter` is `false`), new items that sort after the last pinned item come last.
|
|
317
|
-
* - Then each pinned item in its pinned position, with its current data from the memory. Items deleted from the memory are hidden.
|
|
318
|
-
*/
|
|
319
|
-
_compose() {
|
|
320
|
-
const { memory, _ids, _rows, _orders, _filters } = this;
|
|
321
|
-
if (!memory)
|
|
322
|
-
return _ids.map(id => _rows.get(id)).filter(isDefined);
|
|
323
|
-
const table = memory.getTable(this.collection);
|
|
324
|
-
const first = this._getRow(_ids[0]);
|
|
325
|
-
const last = this._hasAfter ? undefined : this._getRow(_ids.at(-1)); // Only a complete list shows new items at the end.
|
|
326
|
-
const head = [];
|
|
327
|
-
const tail = [];
|
|
328
|
-
for (const item of table.getQuery()) {
|
|
329
|
-
if (_rows.has(item.id) || !matchQueryItem(item, _filters))
|
|
330
|
-
continue;
|
|
331
|
-
if (!first || compareQueryItems(item, first, _orders) < 0)
|
|
332
|
-
head.push(item);
|
|
333
|
-
else if (last && compareQueryItems(item, last, _orders) > 0)
|
|
334
|
-
tail.push(item);
|
|
335
|
-
}
|
|
336
|
-
const body = _ids.map(id => table.getItem(id)).filter(isDefined);
|
|
337
|
-
return [...sortQueryItems(head, _orders), ...body, ...sortQueryItems(tail, _orders)];
|
|
338
|
-
}
|
|
339
|
-
/** Recompose the value after the memory changes. */
|
|
340
|
-
_recompose() {
|
|
341
|
-
// Skip while loading, or while a fetch runs (it recomposes when it ends, and a write now would abort a refresh).
|
|
342
|
-
if (!this._loaded || this.busy.value)
|
|
343
|
-
return;
|
|
344
|
-
this.write(this._compose());
|
|
109
|
+
// - A memory waits until it has loaded the query.
|
|
110
|
+
async _fetch(signal) {
|
|
111
|
+
const { provider, collection, query, _table } = this;
|
|
112
|
+
if (_table && !_isLoaded(_table, query))
|
|
113
|
+
await _awaitFirst(_getLoadedSequence(_table, query), signal);
|
|
114
|
+
return provider.getQuery(collection, query);
|
|
345
115
|
}
|
|
346
116
|
// Implement `Iterable`
|
|
347
117
|
[Symbol.iterator]() {
|
|
348
118
|
return this.value.values();
|
|
349
119
|
}
|
|
350
120
|
}
|
|
351
|
-
/**
|
|
352
|
-
function
|
|
353
|
-
return
|
|
121
|
+
/** Whether the memory has loaded a query, i.e. it has items for it, or a time for it. */
|
|
122
|
+
function _isLoaded(table, query) {
|
|
123
|
+
return table.getQueryTime(query) !== undefined || !!table.countQuery(query);
|
|
124
|
+
}
|
|
125
|
+
/** Follow a query in the memory, but skip the results from before it has loaded. */
|
|
126
|
+
async function* _getLoadedSequence(table, query) {
|
|
127
|
+
for await (const items of table.getQuerySequence(query))
|
|
128
|
+
if (items.length || table.getQueryTime(query) !== undefined)
|
|
129
|
+
yield items;
|
|
354
130
|
}
|
|
355
|
-
/**
|
|
356
|
-
function
|
|
357
|
-
|
|
131
|
+
/** Follow a provider's sequence, but end it at once if the provider does not support subscriptions. */
|
|
132
|
+
async function* _getSupportedSequence(getSequence) {
|
|
133
|
+
try {
|
|
134
|
+
yield* getSequence();
|
|
135
|
+
}
|
|
136
|
+
catch (thrown) {
|
|
137
|
+
if (!(thrown instanceof UnsupportedError))
|
|
138
|
+
throw thrown;
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
/** Get the first value of a sequence, or reject when the signal aborts. */
|
|
142
|
+
async function _awaitFirst(sequence, signal) {
|
|
143
|
+
const iterator = sequence[Symbol.asyncIterator]();
|
|
144
|
+
try {
|
|
145
|
+
const result = await awaitRace(iterator.next(), awaitAbort(signal));
|
|
146
|
+
if (result.done)
|
|
147
|
+
throw new RequiredError("Memory closed before the query loaded", { caller: _awaitFirst });
|
|
148
|
+
return result.value;
|
|
149
|
+
}
|
|
150
|
+
finally {
|
|
151
|
+
iterator.return?.().catch(BLACKHOLE);
|
|
152
|
+
}
|
|
358
153
|
}
|
package/package.json
CHANGED
|
@@ -34,7 +34,7 @@ export interface DBContext<I extends Identifier, T extends Data> {
|
|
|
34
34
|
/**
|
|
35
35
|
* Create a data context
|
|
36
36
|
* - Allows React elements to call `useItem()` and `useQuery()` to access items/queries in a database provider.
|
|
37
|
-
* - If the database
|
|
37
|
+
* - If the database is (or wraps) a `MemoryDBProvider`, the returned stores seed from it synchronously.
|
|
38
38
|
*
|
|
39
39
|
* @param provider `DBProvider` the created context resolves item and query stores against.
|
|
40
40
|
*
|
package/react/createDBContext.js
CHANGED
|
@@ -7,7 +7,7 @@ import { useStore } from "./useStore.js";
|
|
|
7
7
|
/**
|
|
8
8
|
* Create a data context
|
|
9
9
|
* - Allows React elements to call `useItem()` and `useQuery()` to access items/queries in a database provider.
|
|
10
|
-
* - If the database
|
|
10
|
+
* - If the database is (or wraps) a `MemoryDBProvider`, the returned stores seed from it synchronously.
|
|
11
11
|
*
|
|
12
12
|
* @param provider `DBProvider` the created context resolves item and query stores against.
|
|
13
13
|
*
|
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);
|
|
@@ -1,56 +0,0 @@
|
|
|
1
|
-
import type { Data } from "../../util/data.js";
|
|
2
|
-
import type { Identifier, Item, Items, ItemsSequence, OptionalItem, OptionalItemSequence } from "../../util/item.js";
|
|
3
|
-
import type { Query } from "../../util/query.js";
|
|
4
|
-
import type { Updates } from "../../util/update.js";
|
|
5
|
-
import type { Collection } from "../collection/Collection.js";
|
|
6
|
-
import type { DBProvider } from "./DBProvider.js";
|
|
7
|
-
import { MemoryDBProvider } from "./MemoryDBProvider.js";
|
|
8
|
-
import { ThroughDBProvider } from "./ThroughDBProvider.js";
|
|
9
|
-
/**
|
|
10
|
-
* Database provider that keeps a copy of asynchronous remote data in a local synchronous cache.
|
|
11
|
-
*
|
|
12
|
-
* - Wraps a `source` provider and mirrors every read and write into an in-memory `MemoryDBProvider`, so subsequent reads can be served synchronously and live subscriptions stay seeded.
|
|
13
|
-
* - Reads fetch from `source`, then refresh the cache; writes hit `source`, then mirror the change into the cache.
|
|
14
|
-
* - Fetch-first item writes: `updateItem()` and `deleteItem()` fetch the item first (caching it) and skip the source write when it doesn't exist. Query writes are inherited two-step, resolving through this provider's own `getQuery()` — so the matched items are cached, and each per-item write mirrors exactly. The fetch and the writes are separate steps, so wrap them in `transact()` when they must be atomic.
|
|
15
|
-
* - Transactions run on `source` via `transact()` with a transaction-scoped mirror — only a committed transaction's writes reach the cache.
|
|
16
|
-
* - Discover the cache from a wrapping layer with `getSource(CacheDBProvider, provider)` to seed stores from `.memory`.
|
|
17
|
-
*
|
|
18
|
-
* @see https://shelving.cc/db/CacheDBProvider
|
|
19
|
-
*/
|
|
20
|
-
export declare class CacheDBProvider<I extends Identifier, T extends Data> extends ThroughDBProvider<I, T> {
|
|
21
|
-
/**
|
|
22
|
-
* The in-memory provider holding the local synchronous cache of `source` data.
|
|
23
|
-
*
|
|
24
|
-
* @see https://shelving.cc/db/CacheDBProvider/memory
|
|
25
|
-
*/
|
|
26
|
-
readonly memory: MemoryDBProvider<I, T>;
|
|
27
|
-
/**
|
|
28
|
-
* @param cache In-memory provider to use as the cache (a fresh `MemoryDBProvider` by default).
|
|
29
|
-
*/
|
|
30
|
-
constructor(source: DBProvider<I, T>, cache?: MemoryDBProvider<I, T>);
|
|
31
|
-
/** Read from `source`, then refresh the cache. */
|
|
32
|
-
getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
|
|
33
|
-
/** Mirror each emission into the cache. */
|
|
34
|
-
getItemSequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): OptionalItemSequence<II, TT>;
|
|
35
|
-
/** Mirror the added item into the cache. */
|
|
36
|
-
addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
|
|
37
|
-
/** Mirror the set item into the cache. */
|
|
38
|
-
setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
|
|
39
|
-
/** Fetch the item first (caching it), then update it only if it exists. */
|
|
40
|
-
updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
|
|
41
|
-
/** Fetch the item first, then delete it only if it exists. */
|
|
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. */
|
|
44
|
-
getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
|
|
45
|
-
/** Mirror each emission into the cache. */
|
|
46
|
-
getQuerySequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
|
|
47
|
-
cloneWith(source: DBProvider<I, T>): this;
|
|
48
|
-
/**
|
|
49
|
-
* Runs the transaction on `source`, recording the callback's operations, then commits the recorded writes into the cache once the source commits.
|
|
50
|
-
* - The callback's provider is this cache over the source's transaction (with its own transaction-scoped mirror), so fetch-first writes and query resolution behave exactly as they do outside a transaction — and the fetch-then-write steps are atomic because both run in the source transaction.
|
|
51
|
-
* - Uncommitted data never touches the cache: a thrown callback commits nothing, and if the backend retries the callback only the committed attempt's writes are mirrored.
|
|
52
|
-
* - Update writes commit to the cache as deltas, so they refresh cached items and skip uncached ones — an item only read inside the transaction stays uncached until its next read.
|
|
53
|
-
*/
|
|
54
|
-
transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
|
|
55
|
-
[Symbol.asyncDispose](): Promise<void>;
|
|
56
|
-
}
|