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
|
@@ -8,7 +8,7 @@ import { DBProvider } from "./DBProvider.js";
|
|
|
8
8
|
/**
|
|
9
9
|
* Synchronous in-memory database provider, storing each collection in a `MemoryTable`.
|
|
10
10
|
*
|
|
11
|
-
* - Extremely fast (ideal as the
|
|
11
|
+
* - Extremely fast (ideal as the client database that `HydratingAPIProvider` fills), but does not persist data after the process or browser window closes.
|
|
12
12
|
* - Identity-preserving: `getItem()` etc. return the exact same object instance that was passed into `setItem()`.
|
|
13
13
|
* - Supports live subscriptions, so it can back `ItemStore` / `QueryStore` reads.
|
|
14
14
|
* - Supports transactions: `transact()` runs the callback against a snapshot clone, records its operations with `RecordingDBProvider`, and replays the recorded writes onto this provider on success — sequences and nested transactions work inside the callback, scoped to the transaction.
|
|
@@ -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
|
*
|
|
@@ -13,7 +13,7 @@ import { RecordingDBProvider } from "./RecordingDBProvider.js";
|
|
|
13
13
|
/**
|
|
14
14
|
* Synchronous in-memory database provider, storing each collection in a `MemoryTable`.
|
|
15
15
|
*
|
|
16
|
-
* - Extremely fast (ideal as the
|
|
16
|
+
* - Extremely fast (ideal as the client database that `HydratingAPIProvider` fills), but does not persist data after the process or browser window closes.
|
|
17
17
|
* - Identity-preserving: `getItem()` etc. return the exact same object instance that was passed into `setItem()`.
|
|
18
18
|
* - Supports live subscriptions, so it can back `ItemStore` / `QueryStore` reads.
|
|
19
19
|
* - Supports transactions: `transact()` runs the callback against a snapshot clone, records its operations with `RecordingDBProvider`, and replays the recorded writes onto this provider on success — sequences and nested transactions work inside the callback, scoped to the transaction.
|
|
@@ -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
|
+
}
|
|
@@ -106,7 +106,7 @@ export declare class RecordingDBProvider<I extends Identifier, T extends Data> e
|
|
|
106
106
|
* - Applies what each read observed (setting the item, or deleting it when the read confirmed absence) — e.g. warming a cache from a recorded session.
|
|
107
107
|
*
|
|
108
108
|
* @param provider Provider to replay the reads onto.
|
|
109
|
-
* @example await recording.replayReads(
|
|
109
|
+
* @example await recording.replayReads(memory);
|
|
110
110
|
* @see https://shelving.cc/db/RecordingDBProvider/replayReads
|
|
111
111
|
*/
|
|
112
112
|
replayReads(provider: DBProvider<I, T>): Promise<void>;
|
|
@@ -122,7 +122,7 @@ export class RecordingDBProvider extends ThroughDBProvider {
|
|
|
122
122
|
* - Applies what each read observed (setting the item, or deleting it when the read confirmed absence) — e.g. warming a cache from a recorded session.
|
|
123
123
|
*
|
|
124
124
|
* @param provider Provider to replay the reads onto.
|
|
125
|
-
* @example await recording.replayReads(
|
|
125
|
+
* @example await recording.replayReads(memory);
|
|
126
126
|
* @see https://shelving.cc/db/RecordingDBProvider/replayReads
|
|
127
127
|
*/
|
|
128
128
|
replayReads(provider) {
|
|
@@ -5,7 +5,7 @@ import { MemoryDBProvider, MemoryTable } from "./MemoryDBProvider.js";
|
|
|
5
5
|
/**
|
|
6
6
|
* In-memory database provider that persists every collection to a `Storage` — `localStorage`, `sessionStorage`, or anything else with the same interface.
|
|
7
7
|
*
|
|
8
|
-
* - Extends `MemoryDBProvider`, so all reads, queries, and realtime sequences are served synchronously from memory, and it can seed `ItemStore` / `QueryStore` and
|
|
8
|
+
* - Extends `MemoryDBProvider`, so all reads, queries, and realtime sequences are served synchronously from memory, and it can seed `ItemStore` / `QueryStore` and be filled by `HydratingAPIProvider`. The only difference is that collections are backed by `StorageTable` instead of `MemoryTable`.
|
|
9
9
|
* - The storage is a required argument (there is no default), so server code that constructs this provider must reference `localStorage` / `sessionStorage` itself — surfacing the mistake at the callsite instead of deep inside this class.
|
|
10
10
|
* - Treat the persisted data as best-effort: quota is shared across the origin (typically ~5MB) and users can clear it at any time. Data read back from storage is unvalidated — wrap this provider in `ValidationDBProvider` if it may have been written by an older version of your app.
|
|
11
11
|
* - If the storage is unusable (writes blocked by browser settings, or private browsing with zero quota), the provider degrades to memory-only operation — check the `persistent` flag to warn users their changes won't be saved.
|
|
@@ -7,7 +7,7 @@ import { MemoryDBProvider, MemoryTable } from "./MemoryDBProvider.js";
|
|
|
7
7
|
/**
|
|
8
8
|
* In-memory database provider that persists every collection to a `Storage` — `localStorage`, `sessionStorage`, or anything else with the same interface.
|
|
9
9
|
*
|
|
10
|
-
* - Extends `MemoryDBProvider`, so all reads, queries, and realtime sequences are served synchronously from memory, and it can seed `ItemStore` / `QueryStore` and
|
|
10
|
+
* - Extends `MemoryDBProvider`, so all reads, queries, and realtime sequences are served synchronously from memory, and it can seed `ItemStore` / `QueryStore` and be filled by `HydratingAPIProvider`. The only difference is that collections are backed by `StorageTable` instead of `MemoryTable`.
|
|
11
11
|
* - The storage is a required argument (there is no default), so server code that constructs this provider must reference `localStorage` / `sessionStorage` itself — surfacing the mistake at the callsite instead of deep inside this class.
|
|
12
12
|
* - Treat the persisted data as best-effort: quota is shared across the origin (typically ~5MB) and users can clear it at any time. Data read back from storage is unvalidated — wrap this provider in `ValidationDBProvider` if it may have been written by an older version of your app.
|
|
13
13
|
* - If the storage is unusable (writes blocked by browser settings, or private browsing with zero quota), the provider degrades to memory-only operation — check the `persistent` flag to warn users their changes won't be saved.
|
package/db/store/ItemStore.d.ts
CHANGED
|
@@ -3,12 +3,12 @@ import type { Data } from "../../util/data.js";
|
|
|
3
3
|
import type { Identifier, Item, OptionalItem } from "../../util/item.js";
|
|
4
4
|
import type { Collection } from "../collection/Collection.js";
|
|
5
5
|
import type { DBProvider } from "../provider/DBProvider.js";
|
|
6
|
-
import type { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
|
|
7
6
|
/**
|
|
8
7
|
* Store that fetches and tracks a single item by ID in a collection from a database provider.
|
|
9
8
|
*
|
|
10
9
|
* - Holds an `OptionalItem` value: the item if it exists, or `undefined` if it doesn't.
|
|
11
|
-
* -
|
|
10
|
+
* - When the provider is (or wraps) a `MemoryDBProvider`, the store seeds from the memory at once and follows its changes. A missing item only counts as loaded when the memory has a time for it (see `MemoryTable.getItemTime()`). Until then the store is loading, and a fetch waits until the memory loads the item (e.g. from `HydratingAPIProvider`).
|
|
11
|
+
* - Any other provider is fetched, and its `DBProvider.getItemSequence()` is followed while the store has subscribers. A provider that throws `UnsupportedError` for subscriptions is only fetched.
|
|
12
12
|
*
|
|
13
13
|
* @example
|
|
14
14
|
* const store = new ItemStore(collection, "abc", provider);
|
|
@@ -42,6 +42,8 @@ export declare class ItemStore<I extends Identifier, T extends Data> extends Fet
|
|
|
42
42
|
*/
|
|
43
43
|
get item(): Item<I, T>;
|
|
44
44
|
set item(data: T | Item<I, T>);
|
|
45
|
-
|
|
46
|
-
|
|
45
|
+
/** The memory table the provider is backed by, if any. */
|
|
46
|
+
private readonly _table;
|
|
47
|
+
constructor(collection: Collection<string, I, T>, id: I, provider: DBProvider<I>);
|
|
48
|
+
_fetch(signal: AbortSignal): Promise<OptionalItem<I, T>>;
|
|
47
49
|
}
|
package/db/store/ItemStore.js
CHANGED
|
@@ -1,14 +1,20 @@
|
|
|
1
1
|
import { RequiredError } from "../../error/RequiredError.js";
|
|
2
|
+
import { UnsupportedError } from "../../error/UnsupportedError.js";
|
|
2
3
|
import { FetchStore } from "../../store/FetchStore.js";
|
|
4
|
+
import { awaitAbort, awaitRace } from "../../util/async.js";
|
|
3
5
|
import { getGetter } from "../../util/class.js";
|
|
4
6
|
import { NONE } from "../../util/constants.js";
|
|
7
|
+
import { BLACKHOLE } from "../../util/function.js";
|
|
5
8
|
import { getItem } from "../../util/item.js";
|
|
6
9
|
import { runSequence } from "../../util/sequence.js";
|
|
10
|
+
import { getSource } from "../../util/source.js";
|
|
11
|
+
import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
|
|
7
12
|
/**
|
|
8
13
|
* Store that fetches and tracks a single item by ID in a collection from a database provider.
|
|
9
14
|
*
|
|
10
15
|
* - Holds an `OptionalItem` value: the item if it exists, or `undefined` if it doesn't.
|
|
11
|
-
* -
|
|
16
|
+
* - When the provider is (or wraps) a `MemoryDBProvider`, the store seeds from the memory at once and follows its changes. A missing item only counts as loaded when the memory has a time for it (see `MemoryTable.getItemTime()`). Until then the store is loading, and a fetch waits until the memory loads the item (e.g. from `HydratingAPIProvider`).
|
|
17
|
+
* - Any other provider is fetched, and its `DBProvider.getItemSequence()` is followed while the store has subscribers. A provider that throws `UnsupportedError` for subscriptions is only fetched.
|
|
12
18
|
*
|
|
13
19
|
* @example
|
|
14
20
|
* const store = new ItemStore(collection, "abc", provider);
|
|
@@ -55,17 +61,58 @@ export class ItemStore extends FetchStore {
|
|
|
55
61
|
set item(data) {
|
|
56
62
|
this.value = getItem(this.id, data);
|
|
57
63
|
}
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
64
|
+
/** The memory table the provider is backed by, if any. */
|
|
65
|
+
_table;
|
|
66
|
+
constructor(collection, id, provider) {
|
|
67
|
+
const table = getSource(MemoryDBProvider, provider)?.getTable(collection);
|
|
68
|
+
super(table && _isLoaded(table, id) ? table.getItem(id) : NONE); // Use the current memory snapshot if it has loaded.
|
|
63
69
|
this.provider = provider;
|
|
64
70
|
this.collection = collection;
|
|
65
71
|
this.id = id;
|
|
72
|
+
this._table = table;
|
|
73
|
+
this.starter = table
|
|
74
|
+
? store => runSequence(store.through(_getLoadedSequence(table, id)))
|
|
75
|
+
: store => runSequence(store.through(_getSupportedSequence(() => provider.getItemSequence(collection, id))), undefined, reason => (store.reason = reason));
|
|
66
76
|
}
|
|
67
77
|
// Override to get the item from the provider.
|
|
68
|
-
|
|
69
|
-
|
|
78
|
+
// - A memory waits until it has loaded the item.
|
|
79
|
+
async _fetch(signal) {
|
|
80
|
+
const { provider, collection, id, _table } = this;
|
|
81
|
+
if (_table && !_isLoaded(_table, id))
|
|
82
|
+
await _awaitFirst(_getLoadedSequence(_table, id), signal);
|
|
83
|
+
return provider.getItem(collection, id);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
/** Whether the memory has loaded an item, i.e. it has the item, or a time for it. */
|
|
87
|
+
function _isLoaded(table, id) {
|
|
88
|
+
return !!table.getItem(id) || table.getItemTime(id) !== undefined;
|
|
89
|
+
}
|
|
90
|
+
/** Follow an item in the memory, but skip the values from before it has loaded. */
|
|
91
|
+
async function* _getLoadedSequence(table, id) {
|
|
92
|
+
for await (const item of table.getItemSequence(id))
|
|
93
|
+
if (_isLoaded(table, id))
|
|
94
|
+
yield item;
|
|
95
|
+
}
|
|
96
|
+
/** Follow a provider's sequence, but end it at once if the provider does not support subscriptions. */
|
|
97
|
+
async function* _getSupportedSequence(getSequence) {
|
|
98
|
+
try {
|
|
99
|
+
yield* getSequence();
|
|
100
|
+
}
|
|
101
|
+
catch (thrown) {
|
|
102
|
+
if (!(thrown instanceof UnsupportedError))
|
|
103
|
+
throw thrown;
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
/** Get the first value of a sequence, or reject when the signal aborts. */
|
|
107
|
+
async function _awaitFirst(sequence, signal) {
|
|
108
|
+
const iterator = sequence[Symbol.asyncIterator]();
|
|
109
|
+
try {
|
|
110
|
+
const result = await awaitRace(iterator.next(), awaitAbort(signal));
|
|
111
|
+
if (result.done)
|
|
112
|
+
throw new RequiredError("Memory closed before the item loaded", { caller: _awaitFirst });
|
|
113
|
+
return result.value;
|
|
114
|
+
}
|
|
115
|
+
finally {
|
|
116
|
+
iterator.return?.().catch(BLACKHOLE);
|
|
70
117
|
}
|
|
71
118
|
}
|
package/db/store/QueryStore.d.ts
CHANGED
|
@@ -1,18 +1,16 @@
|
|
|
1
1
|
import { FetchStore } from "../../store/FetchStore.js";
|
|
2
|
-
import {
|
|
2
|
+
import type { Data } from "../../util/data.js";
|
|
3
3
|
import type { Identifier, Item, Items } from "../../util/item.js";
|
|
4
|
-
import {
|
|
4
|
+
import type { Query } from "../../util/query.js";
|
|
5
5
|
import type { Collection } from "../collection/Collection.js";
|
|
6
6
|
import type { DBProvider } from "../provider/DBProvider.js";
|
|
7
|
-
import type { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
|
|
8
7
|
/**
|
|
9
8
|
* Store that runs a query against a collection from a database provider and tracks its matching items.
|
|
10
9
|
*
|
|
11
10
|
* - Holds an `Items` value (the array of matching items) and is iterable over those items.
|
|
12
|
-
* -
|
|
13
|
-
* -
|
|
14
|
-
* -
|
|
15
|
-
* - A query without an `$order` follows the live query result in the memory, and cannot page.
|
|
11
|
+
* - 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`).
|
|
12
|
+
* - 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.
|
|
13
|
+
* - The store does not page. To load more items into a memory, call the API with `getQueryItemsAfter()`, and the store shows the new items.
|
|
16
14
|
*
|
|
17
15
|
* @example
|
|
18
16
|
* const store = new QueryStore(collection, query, provider);
|
|
@@ -35,35 +33,6 @@ export declare class QueryStore<I extends Identifier, T extends Data> extends Fe
|
|
|
35
33
|
* @see https://shelving.cc/db/QueryStore/query
|
|
36
34
|
*/
|
|
37
35
|
readonly query: Query<Item<I, T>>;
|
|
38
|
-
/**
|
|
39
|
-
* The memory provider this store seeds from and follows, if available.
|
|
40
|
-
* @see https://shelving.cc/db/QueryStore/memory
|
|
41
|
-
*/
|
|
42
|
-
readonly memory: MemoryDBProvider<I> | undefined;
|
|
43
|
-
/**
|
|
44
|
-
* The maximum number of items the query can return, or `Infinity` if unlimited.
|
|
45
|
-
* - For a paged query, this is the size of each page.
|
|
46
|
-
* @see https://shelving.cc/db/QueryStore/limit
|
|
47
|
-
*/
|
|
48
|
-
get limit(): number;
|
|
49
|
-
/**
|
|
50
|
-
* Whether more items can be loaded after the last item with `fetchAfter()`.
|
|
51
|
-
* @see https://shelving.cc/db/QueryStore/hasAfter
|
|
52
|
-
*/
|
|
53
|
-
get hasAfter(): boolean;
|
|
54
|
-
private _hasAfter;
|
|
55
|
-
/**
|
|
56
|
-
* Whether more items can be loaded before the first item with `fetchBefore()`.
|
|
57
|
-
* - `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.
|
|
58
|
-
* @see https://shelving.cc/db/QueryStore/hasBefore
|
|
59
|
-
*/
|
|
60
|
-
get hasBefore(): boolean;
|
|
61
|
-
private _hasBefore;
|
|
62
|
-
/**
|
|
63
|
-
* Whether more items can be loaded after the last item. Alias of `hasAfter`.
|
|
64
|
-
* @see https://shelving.cc/db/QueryStore/hasMore
|
|
65
|
-
*/
|
|
66
|
-
get hasMore(): boolean;
|
|
67
36
|
/**
|
|
68
37
|
* The first item in this store, or `undefined` if the query has no items.
|
|
69
38
|
* @see https://shelving.cc/db/QueryStore/optionalFirst
|
|
@@ -92,68 +61,9 @@ export declare class QueryStore<I extends Identifier, T extends Data> extends Fe
|
|
|
92
61
|
* @see https://shelving.cc/db/QueryStore/last
|
|
93
62
|
*/
|
|
94
63
|
get last(): Item<I, T>;
|
|
95
|
-
|
|
96
|
-
private readonly
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
private _loaded;
|
|
100
|
-
private _generation;
|
|
101
|
-
constructor(collection: Collection<string, I, T>, query: Query<Item<I, T>>, provider: DBProvider<I>, memory?: MemoryDBProvider<I>);
|
|
102
|
-
_fetch(_signal: AbortSignal): Promise<Items<I, T>>;
|
|
103
|
-
/**
|
|
104
|
-
* Load the next page of items after the last item.
|
|
105
|
-
* - Uses the query `$limit` as the page size.
|
|
106
|
-
* - Sets `busy` while the page loads. The items already loaded do not suspend.
|
|
107
|
-
* - Waits for a fetch that is already running, then loads the page.
|
|
108
|
-
* - Does nothing if `hasAfter` is `false`.
|
|
109
|
-
* - Loads the first page if no items have loaded yet.
|
|
110
|
-
* - A failed fetch rejects the promise, and the items already loaded stay. Unlike `refresh()`, it does not set `reason`.
|
|
111
|
-
*
|
|
112
|
-
* @returns Promise that resolves when the page has loaded.
|
|
113
|
-
* @throws {RequiredError} If the query has no `$order`.
|
|
114
|
-
* @throws {unknown} The error from the provider, if the fetch fails.
|
|
115
|
-
* @example if (store.hasAfter) await store.fetchAfter();
|
|
116
|
-
* @see https://shelving.cc/db/QueryStore/fetchAfter
|
|
117
|
-
*/
|
|
118
|
-
fetchAfter(): Promise<void>;
|
|
119
|
-
/**
|
|
120
|
-
* Load the next page of items after the last item. Alias of `fetchAfter()`.
|
|
121
|
-
*
|
|
122
|
-
* @returns Promise that resolves when the page has loaded.
|
|
123
|
-
* @see https://shelving.cc/db/QueryStore/fetchMore
|
|
124
|
-
*/
|
|
125
|
-
fetchMore(): Promise<void>;
|
|
126
|
-
/**
|
|
127
|
-
* Load the new items before the first item, e.g. new messages at the start of a newest-first list.
|
|
128
|
-
* - Loads up to one page (the query `$limit`), nearest to the first item. Call again while `hasBefore` is `true` to load more.
|
|
129
|
-
* - Sets `busy` while the items load. The items already loaded do not suspend.
|
|
130
|
-
* - Waits for a fetch that is already running, then loads the items.
|
|
131
|
-
* - Loads the first page if no items have loaded yet.
|
|
132
|
-
* - A failed fetch rejects the promise, and the items already loaded stay. Unlike `refresh()`, it does not set `reason`.
|
|
133
|
-
*
|
|
134
|
-
* @returns Promise that resolves when the new items have loaded.
|
|
135
|
-
* @throws {RequiredError} If the query has no `$order`.
|
|
136
|
-
* @throws {unknown} The error from the provider, if the fetch fails.
|
|
137
|
-
* @example setInterval(() => store.fetchBefore().catch(BLACKHOLE), 10_000); // Poll for new messages.
|
|
138
|
-
* @see https://shelving.cc/db/QueryStore/fetchBefore
|
|
139
|
-
*/
|
|
140
|
-
fetchBefore(): Promise<void>;
|
|
141
|
-
/** Wait until no fetch is running. */
|
|
142
|
-
private _idle;
|
|
143
|
-
/** Fetch one page from an inclusive cursor query, and drop the items already loaded. */
|
|
144
|
-
private _fetchPage;
|
|
145
|
-
/** Pin a list of items (or IDs of items already pinned) as the loaded items, in display order. */
|
|
146
|
-
private _pin;
|
|
147
|
-
/** Get a pinned item as it was fetched. */
|
|
148
|
-
private _getRow;
|
|
149
|
-
/**
|
|
150
|
-
* Make the current value of a paged query.
|
|
151
|
-
* - New items in the memory that match the filters and sort before the first pinned item come first.
|
|
152
|
-
* - When the list is complete (`hasAfter` is `false`), new items that sort after the last pinned item come last.
|
|
153
|
-
* - Then each pinned item in its pinned position, with its current data from the memory. Items deleted from the memory are hidden.
|
|
154
|
-
*/
|
|
155
|
-
private _compose;
|
|
156
|
-
/** Recompose the value after the memory changes. */
|
|
157
|
-
private _recompose;
|
|
64
|
+
/** The memory table the provider is backed by, if any. */
|
|
65
|
+
private readonly _table;
|
|
66
|
+
constructor(collection: Collection<string, I, T>, query: Query<Item<I, T>>, provider: DBProvider<I>);
|
|
67
|
+
_fetch(signal: AbortSignal): Promise<Items<I, T>>;
|
|
158
68
|
[Symbol.iterator](): Iterator<Item<I, T>>;
|
|
159
69
|
}
|