shelving 1.308.0 → 1.310.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/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/index.d.ts +0 -1
- package/db/index.js +0 -1
- package/db/provider/MemoryDBProvider.d.ts +1 -1
- package/db/provider/MemoryDBProvider.js +1 -1
- 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 +5 -5
- package/db/store/ItemStore.js +26 -14
- package/db/store/QueryStore.d.ts +8 -100
- package/db/store/QueryStore.js +30 -270
- package/package.json +1 -1
- package/react/createDBContext.d.ts +1 -1
- package/react/createDBContext.js +1 -1
- package/util/string.d.ts +9 -4
- package/util/string.js +31 -6
- package/db/provider/CacheDBProvider.d.ts +0 -56
- package/db/provider/CacheDBProvider.js +0 -107
|
@@ -3,7 +3,6 @@ import type { Identifier, Item } from "../../util/item.js";
|
|
|
3
3
|
import type { Query } from "../../util/query.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
|
import { ItemStore } from "../store/ItemStore.js";
|
|
8
7
|
import { QueryStore } from "../store/QueryStore.js";
|
|
9
8
|
/**
|
|
@@ -29,12 +28,7 @@ export declare class CollectionCache<I extends Identifier, T extends Data> imple
|
|
|
29
28
|
* @see https://shelving.cc/db/CollectionCache/provider
|
|
30
29
|
*/
|
|
31
30
|
readonly provider: DBProvider<I>;
|
|
32
|
-
|
|
33
|
-
* Optional memory provider used to seed stores and drive realtime updates.
|
|
34
|
-
* @see https://shelving.cc/db/CollectionCache/memory
|
|
35
|
-
*/
|
|
36
|
-
readonly memory: MemoryDBProvider<I> | undefined;
|
|
37
|
-
constructor(collection: Collection<string, I, T>, provider: DBProvider<I>, memory?: MemoryDBProvider<I>);
|
|
31
|
+
constructor(collection: Collection<string, I, T>, provider: DBProvider<I>);
|
|
38
32
|
/**
|
|
39
33
|
* Get (or create) the `ItemStore` for the given id.
|
|
40
34
|
*
|
|
@@ -26,15 +26,9 @@ export class CollectionCache {
|
|
|
26
26
|
* @see https://shelving.cc/db/CollectionCache/provider
|
|
27
27
|
*/
|
|
28
28
|
provider;
|
|
29
|
-
|
|
30
|
-
* Optional memory provider used to seed stores and drive realtime updates.
|
|
31
|
-
* @see https://shelving.cc/db/CollectionCache/memory
|
|
32
|
-
*/
|
|
33
|
-
memory;
|
|
34
|
-
constructor(collection, provider, memory) {
|
|
29
|
+
constructor(collection, provider) {
|
|
35
30
|
this.collection = collection;
|
|
36
31
|
this.provider = provider;
|
|
37
|
-
this.memory = memory;
|
|
38
32
|
}
|
|
39
33
|
/**
|
|
40
34
|
* Get (or create) the `ItemStore` for the given id.
|
|
@@ -45,7 +39,7 @@ export class CollectionCache {
|
|
|
45
39
|
* @see https://shelving.cc/db/CollectionCache/getItem
|
|
46
40
|
*/
|
|
47
41
|
getItem(id) {
|
|
48
|
-
return this._items.get(id) || setMapItem(this._items, id, new ItemStore(this.collection, id, this.provider
|
|
42
|
+
return this._items.get(id) || setMapItem(this._items, id, new ItemStore(this.collection, id, this.provider));
|
|
49
43
|
}
|
|
50
44
|
/**
|
|
51
45
|
* Get (or create) the `QueryStore` for the given query.
|
|
@@ -57,7 +51,7 @@ export class CollectionCache {
|
|
|
57
51
|
*/
|
|
58
52
|
getQuery(query) {
|
|
59
53
|
const key = this._queryKey(query);
|
|
60
|
-
return this._queries.get(key) || setMapItem(this._queries, key, new QueryStore(this.collection, query, this.provider
|
|
54
|
+
return this._queries.get(key) || setMapItem(this._queries, key, new QueryStore(this.collection, query, this.provider));
|
|
61
55
|
}
|
|
62
56
|
/**
|
|
63
57
|
* Refresh a specific item store.
|
package/db/cache/DBCache.d.ts
CHANGED
|
@@ -3,7 +3,6 @@ import type { Identifier, Item } from "../../util/item.js";
|
|
|
3
3
|
import type { Query } from "../../util/query.js";
|
|
4
4
|
import type { Collection } from "../collection/Collection.js";
|
|
5
5
|
import type { DBProvider } from "../provider/DBProvider.js";
|
|
6
|
-
import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
|
|
7
6
|
import type { ItemStore } from "../store/ItemStore.js";
|
|
8
7
|
import type { QueryStore } from "../store/QueryStore.js";
|
|
9
8
|
import { CollectionCache } from "./CollectionCache.js";
|
|
@@ -11,7 +10,7 @@ import { CollectionCache } from "./CollectionCache.js";
|
|
|
11
10
|
* Cache of `CollectionCache` objects for multiple collections.
|
|
12
11
|
* - Use `get(collection)` to retrieve or create the `CollectionCache` for a given collection,
|
|
13
12
|
* then `getItem(id)` / `getQuery(query)` on that to get a specific store.
|
|
14
|
-
* - If the provider
|
|
13
|
+
* - If the provider is (or wraps) a `MemoryDBProvider`, the stores seed from it synchronously.
|
|
15
14
|
*
|
|
16
15
|
* @example
|
|
17
16
|
* const cache = new DBCache(provider);
|
|
@@ -25,11 +24,6 @@ export declare class DBCache<I extends Identifier = Identifier, T extends Data =
|
|
|
25
24
|
* @see https://shelving.cc/db/DBCache/provider
|
|
26
25
|
*/
|
|
27
26
|
readonly provider: DBProvider<I, T>;
|
|
28
|
-
/**
|
|
29
|
-
* Memory provider reused from the provider chain to seed stores synchronously, if available.
|
|
30
|
-
* @see https://shelving.cc/db/DBCache/memory
|
|
31
|
-
*/
|
|
32
|
-
readonly memory: MemoryDBProvider<I, T> | undefined;
|
|
33
27
|
constructor(provider: DBProvider<I, T>);
|
|
34
28
|
private _get;
|
|
35
29
|
/**
|
package/db/cache/DBCache.js
CHANGED
|
@@ -1,14 +1,11 @@
|
|
|
1
1
|
import { awaitDispose } from "../../util/dispose.js";
|
|
2
2
|
import { setMapItem } from "../../util/map.js";
|
|
3
|
-
import { getSource } from "../../util/source.js";
|
|
4
|
-
import { CacheDBProvider } from "../provider/CacheDBProvider.js";
|
|
5
|
-
import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
|
|
6
3
|
import { CollectionCache } from "./CollectionCache.js";
|
|
7
4
|
/**
|
|
8
5
|
* Cache of `CollectionCache` objects for multiple collections.
|
|
9
6
|
* - Use `get(collection)` to retrieve or create the `CollectionCache` for a given collection,
|
|
10
7
|
* then `getItem(id)` / `getQuery(query)` on that to get a specific store.
|
|
11
|
-
* - If the provider
|
|
8
|
+
* - If the provider is (or wraps) a `MemoryDBProvider`, the stores seed from it synchronously.
|
|
12
9
|
*
|
|
13
10
|
* @example
|
|
14
11
|
* const cache = new DBCache(provider);
|
|
@@ -22,21 +19,14 @@ export class DBCache {
|
|
|
22
19
|
* @see https://shelving.cc/db/DBCache/provider
|
|
23
20
|
*/
|
|
24
21
|
provider;
|
|
25
|
-
/**
|
|
26
|
-
* Memory provider reused from the provider chain to seed stores synchronously, if available.
|
|
27
|
-
* @see https://shelving.cc/db/DBCache/memory
|
|
28
|
-
*/
|
|
29
|
-
memory;
|
|
30
22
|
constructor(provider) {
|
|
31
23
|
this.provider = provider;
|
|
32
|
-
// If the provider is itself in-memory (e.g. `MemoryDBProvider` or `StorageDBProvider`), or the chain contains a `CacheDBProvider`, reuse its memory so we can seed stores synchronously.
|
|
33
|
-
this.memory = provider instanceof MemoryDBProvider ? provider : getSource(CacheDBProvider, provider)?.memory;
|
|
34
24
|
}
|
|
35
25
|
_get(collection) {
|
|
36
26
|
return this._collections.get(collection);
|
|
37
27
|
}
|
|
38
28
|
get(collection) {
|
|
39
|
-
return this._get(collection) || setMapItem(this._collections, collection, new CollectionCache(collection, this.provider
|
|
29
|
+
return this._get(collection) || setMapItem(this._collections, collection, new CollectionCache(collection, this.provider));
|
|
40
30
|
}
|
|
41
31
|
/**
|
|
42
32
|
* Get (or create) an `ItemStore` for a collection/id in one hop.
|
package/db/index.d.ts
CHANGED
|
@@ -9,7 +9,6 @@ export * from "./migrate/DBMigrator.js";
|
|
|
9
9
|
export * from "./migrate/PostgresMigrator.js";
|
|
10
10
|
export * from "./migrate/SQLiteMigrator.js";
|
|
11
11
|
export * from "./migrate/SQLMigrator.js";
|
|
12
|
-
export * from "./provider/CacheDBProvider.js";
|
|
13
12
|
export * from "./provider/DBProvider.js";
|
|
14
13
|
export * from "./provider/DebugDBProvider.js";
|
|
15
14
|
export * from "./provider/MemoryDBProvider.js";
|
package/db/index.js
CHANGED
|
@@ -9,7 +9,6 @@ export * from "./migrate/DBMigrator.js";
|
|
|
9
9
|
export * from "./migrate/PostgresMigrator.js";
|
|
10
10
|
export * from "./migrate/SQLiteMigrator.js";
|
|
11
11
|
export * from "./migrate/SQLMigrator.js";
|
|
12
|
-
export * from "./provider/CacheDBProvider.js";
|
|
13
12
|
export * from "./provider/DBProvider.js";
|
|
14
13
|
export * from "./provider/DebugDBProvider.js";
|
|
15
14
|
export * from "./provider/MemoryDBProvider.js";
|
|
@@ -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.
|
|
@@ -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.
|
|
@@ -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,14 +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 { 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
|
-
* -
|
|
12
|
-
* -
|
|
13
|
-
* - When the provider is a `MemoryDBProvider`, a fetch waits until the memory has loaded the item (e.g. from `HydratingAPIProvider`).
|
|
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.
|
|
14
12
|
*
|
|
15
13
|
* @example
|
|
16
14
|
* const store = new ItemStore(collection, "abc", provider);
|
|
@@ -44,6 +42,8 @@ export declare class ItemStore<I extends Identifier, T extends Data> extends Fet
|
|
|
44
42
|
*/
|
|
45
43
|
get item(): Item<I, T>;
|
|
46
44
|
set item(data: T | Item<I, T>);
|
|
47
|
-
|
|
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
48
|
_fetch(signal: AbortSignal): Promise<OptionalItem<I, T>>;
|
|
49
49
|
}
|
package/db/store/ItemStore.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { RequiredError } from "../../error/RequiredError.js";
|
|
2
|
+
import { UnsupportedError } from "../../error/UnsupportedError.js";
|
|
2
3
|
import { FetchStore } from "../../store/FetchStore.js";
|
|
3
4
|
import { awaitAbort, awaitRace } from "../../util/async.js";
|
|
4
5
|
import { getGetter } from "../../util/class.js";
|
|
@@ -6,14 +7,14 @@ import { NONE } from "../../util/constants.js";
|
|
|
6
7
|
import { BLACKHOLE } from "../../util/function.js";
|
|
7
8
|
import { getItem } from "../../util/item.js";
|
|
8
9
|
import { runSequence } from "../../util/sequence.js";
|
|
10
|
+
import { getSource } from "../../util/source.js";
|
|
9
11
|
import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
|
|
10
12
|
/**
|
|
11
13
|
* Store that fetches and tracks a single item by ID in a collection from a database provider.
|
|
12
14
|
*
|
|
13
15
|
* - Holds an `OptionalItem` value: the item if it exists, or `undefined` if it doesn't.
|
|
14
|
-
* -
|
|
15
|
-
* -
|
|
16
|
-
* - When the provider is a `MemoryDBProvider`, a fetch waits until the memory has loaded the item (e.g. from `HydratingAPIProvider`).
|
|
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.
|
|
17
18
|
*
|
|
18
19
|
* @example
|
|
19
20
|
* const store = new ItemStore(collection, "abc", provider);
|
|
@@ -60,24 +61,25 @@ export class ItemStore extends FetchStore {
|
|
|
60
61
|
set item(data) {
|
|
61
62
|
this.value = getItem(this.id, data);
|
|
62
63
|
}
|
|
63
|
-
|
|
64
|
-
|
|
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);
|
|
65
68
|
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)));
|
|
68
69
|
this.provider = provider;
|
|
69
70
|
this.collection = collection;
|
|
70
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));
|
|
71
76
|
}
|
|
72
77
|
// Override to get the item from the provider.
|
|
73
|
-
// - A
|
|
78
|
+
// - A memory waits until it has loaded the item.
|
|
74
79
|
async _fetch(signal) {
|
|
75
|
-
const { provider, collection, id } = this;
|
|
76
|
-
if (
|
|
77
|
-
|
|
78
|
-
if (!_isLoaded(table, id))
|
|
79
|
-
await _awaitFirst(_getLoadedSequence(table, id), signal);
|
|
80
|
-
}
|
|
80
|
+
const { provider, collection, id, _table } = this;
|
|
81
|
+
if (_table && !_isLoaded(_table, id))
|
|
82
|
+
await _awaitFirst(_getLoadedSequence(_table, id), signal);
|
|
81
83
|
return provider.getItem(collection, id);
|
|
82
84
|
}
|
|
83
85
|
}
|
|
@@ -91,6 +93,16 @@ async function* _getLoadedSequence(table, id) {
|
|
|
91
93
|
if (_isLoaded(table, id))
|
|
92
94
|
yield item;
|
|
93
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
|
+
}
|
|
94
106
|
/** Get the first value of a sequence, or reject when the signal aborts. */
|
|
95
107
|
async function _awaitFirst(sequence, signal) {
|
|
96
108
|
const iterator = sequence[Symbol.asyncIterator]();
|
package/db/store/QueryStore.d.ts
CHANGED
|
@@ -1,20 +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 { 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 with an `$order` loads in pages: `fetchAfter()` loads the next page at the end, and `fetchBefore()` loads new items at the start.
|
|
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).
|
|
17
|
-
* - 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.
|
|
18
14
|
*
|
|
19
15
|
* @example
|
|
20
16
|
* const store = new QueryStore(collection, query, provider);
|
|
@@ -37,35 +33,6 @@ export declare class QueryStore<I extends Identifier, T extends Data> extends Fe
|
|
|
37
33
|
* @see https://shelving.cc/db/QueryStore/query
|
|
38
34
|
*/
|
|
39
35
|
readonly query: Query<Item<I, T>>;
|
|
40
|
-
/**
|
|
41
|
-
* The memory provider this store seeds from and follows, if available.
|
|
42
|
-
* @see https://shelving.cc/db/QueryStore/memory
|
|
43
|
-
*/
|
|
44
|
-
readonly memory: MemoryDBProvider<I> | undefined;
|
|
45
|
-
/**
|
|
46
|
-
* The maximum number of items the query can return, or `Infinity` if unlimited.
|
|
47
|
-
* - For a paged query, this is the size of each page.
|
|
48
|
-
* @see https://shelving.cc/db/QueryStore/limit
|
|
49
|
-
*/
|
|
50
|
-
get limit(): number;
|
|
51
|
-
/**
|
|
52
|
-
* Whether more items can be loaded after the last item with `fetchAfter()`.
|
|
53
|
-
* @see https://shelving.cc/db/QueryStore/hasAfter
|
|
54
|
-
*/
|
|
55
|
-
get hasAfter(): boolean;
|
|
56
|
-
private _hasAfter;
|
|
57
|
-
/**
|
|
58
|
-
* Whether more items can be loaded before the first item with `fetchBefore()`.
|
|
59
|
-
* - `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.
|
|
60
|
-
* @see https://shelving.cc/db/QueryStore/hasBefore
|
|
61
|
-
*/
|
|
62
|
-
get hasBefore(): boolean;
|
|
63
|
-
private _hasBefore;
|
|
64
|
-
/**
|
|
65
|
-
* Whether more items can be loaded after the last item. Alias of `hasAfter`.
|
|
66
|
-
* @see https://shelving.cc/db/QueryStore/hasMore
|
|
67
|
-
*/
|
|
68
|
-
get hasMore(): boolean;
|
|
69
36
|
/**
|
|
70
37
|
* The first item in this store, or `undefined` if the query has no items.
|
|
71
38
|
* @see https://shelving.cc/db/QueryStore/optionalFirst
|
|
@@ -94,68 +61,9 @@ export declare class QueryStore<I extends Identifier, T extends Data> extends Fe
|
|
|
94
61
|
* @see https://shelving.cc/db/QueryStore/last
|
|
95
62
|
*/
|
|
96
63
|
get last(): Item<I, T>;
|
|
97
|
-
|
|
98
|
-
private readonly
|
|
99
|
-
|
|
100
|
-
private _rows;
|
|
101
|
-
private _loaded;
|
|
102
|
-
private _generation;
|
|
103
|
-
constructor(collection: Collection<string, I, T>, query: Query<Item<I, T>>, provider: DBProvider<I>, memory?: MemoryDBProvider<I>);
|
|
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>);
|
|
104
67
|
_fetch(signal: AbortSignal): Promise<Items<I, T>>;
|
|
105
|
-
/**
|
|
106
|
-
* Load the next page of items after the last item.
|
|
107
|
-
* - Uses the query `$limit` as the page size.
|
|
108
|
-
* - Sets `busy` while the page loads. The items already loaded do not suspend.
|
|
109
|
-
* - Waits for a fetch that is already running, then loads the page.
|
|
110
|
-
* - Does nothing if `hasAfter` is `false`.
|
|
111
|
-
* - Loads the first page if no items have loaded yet.
|
|
112
|
-
* - A failed fetch rejects the promise, and the items already loaded stay. Unlike `refresh()`, it does not set `reason`.
|
|
113
|
-
*
|
|
114
|
-
* @returns Promise that resolves when the page has loaded.
|
|
115
|
-
* @throws {RequiredError} If the query has no `$order`.
|
|
116
|
-
* @throws {unknown} The error from the provider, if the fetch fails.
|
|
117
|
-
* @example if (store.hasAfter) await store.fetchAfter();
|
|
118
|
-
* @see https://shelving.cc/db/QueryStore/fetchAfter
|
|
119
|
-
*/
|
|
120
|
-
fetchAfter(): Promise<void>;
|
|
121
|
-
/**
|
|
122
|
-
* Load the next page of items after the last item. Alias of `fetchAfter()`.
|
|
123
|
-
*
|
|
124
|
-
* @returns Promise that resolves when the page has loaded.
|
|
125
|
-
* @see https://shelving.cc/db/QueryStore/fetchMore
|
|
126
|
-
*/
|
|
127
|
-
fetchMore(): Promise<void>;
|
|
128
|
-
/**
|
|
129
|
-
* Load the new items before the first item, e.g. new messages at the start of a newest-first list.
|
|
130
|
-
* - Loads up to one page (the query `$limit`), nearest to the first item. Call again while `hasBefore` is `true` to load more.
|
|
131
|
-
* - Sets `busy` while the items load. The items already loaded do not suspend.
|
|
132
|
-
* - Waits for a fetch that is already running, then loads the items.
|
|
133
|
-
* - Loads the first page if no items have loaded yet.
|
|
134
|
-
* - A failed fetch rejects the promise, and the items already loaded stay. Unlike `refresh()`, it does not set `reason`.
|
|
135
|
-
*
|
|
136
|
-
* @returns Promise that resolves when the new items have loaded.
|
|
137
|
-
* @throws {RequiredError} If the query has no `$order`.
|
|
138
|
-
* @throws {unknown} The error from the provider, if the fetch fails.
|
|
139
|
-
* @example setInterval(() => store.fetchBefore().catch(BLACKHOLE), 10_000); // Poll for new messages.
|
|
140
|
-
* @see https://shelving.cc/db/QueryStore/fetchBefore
|
|
141
|
-
*/
|
|
142
|
-
fetchBefore(): Promise<void>;
|
|
143
|
-
/** Wait until no fetch is running. */
|
|
144
|
-
private _idle;
|
|
145
|
-
/** Fetch one page from an inclusive cursor query, and drop the items already loaded. */
|
|
146
|
-
private _fetchPage;
|
|
147
|
-
/** Pin a list of items (or IDs of items already pinned) as the loaded items, in display order. */
|
|
148
|
-
private _pin;
|
|
149
|
-
/** Get a pinned item as it was fetched. */
|
|
150
|
-
private _getRow;
|
|
151
|
-
/**
|
|
152
|
-
* Make the current value of a paged query.
|
|
153
|
-
* - New items in the memory that match the filters and sort before the first pinned item come first.
|
|
154
|
-
* - When the list is complete (`hasAfter` is `false`), new items that sort after the last pinned item come last.
|
|
155
|
-
* - Then each pinned item in its pinned position, with its current data from the memory. Items deleted from the memory are hidden.
|
|
156
|
-
*/
|
|
157
|
-
private _compose;
|
|
158
|
-
/** Recompose the value after the memory changes. */
|
|
159
|
-
private _recompose;
|
|
160
68
|
[Symbol.iterator](): Iterator<Item<I, T>>;
|
|
161
69
|
}
|
package/db/store/QueryStore.js
CHANGED
|
@@ -1,26 +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";
|
|
4
5
|
import { awaitAbort, awaitRace } from "../../util/async.js";
|
|
5
6
|
import { getGetter } from "../../util/class.js";
|
|
6
7
|
import { NONE } from "../../util/constants.js";
|
|
7
|
-
import { getDataProp, joinDataPath } from "../../util/data.js";
|
|
8
|
-
import { isEqual } from "../../util/equal.js";
|
|
9
8
|
import { BLACKHOLE } from "../../util/function.js";
|
|
10
|
-
import { compareQueryItems, getQueryAfter, getQueryBefore, getQueryFilters, getQueryLimit, getQueryOrders, matchQueryItem, sortQueryItems, } from "../../util/query.js";
|
|
11
9
|
import { runSequence } from "../../util/sequence.js";
|
|
12
|
-
import {
|
|
10
|
+
import { getSource } from "../../util/source.js";
|
|
13
11
|
import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
|
|
14
12
|
/**
|
|
15
13
|
* Store that runs a query against a collection from a database provider and tracks its matching items.
|
|
16
14
|
*
|
|
17
15
|
* - Holds an `Items` value (the array of matching items) and is iterable over those items.
|
|
18
|
-
* -
|
|
19
|
-
* -
|
|
20
|
-
* -
|
|
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.
|
|
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).
|
|
23
|
-
* - 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.
|
|
24
19
|
*
|
|
25
20
|
* @example
|
|
26
21
|
* const store = new QueryStore(collection, query, provider);
|
|
@@ -43,43 +38,6 @@ export class QueryStore extends FetchStore {
|
|
|
43
38
|
* @see https://shelving.cc/db/QueryStore/query
|
|
44
39
|
*/
|
|
45
40
|
query;
|
|
46
|
-
/**
|
|
47
|
-
* The memory provider this store seeds from and follows, if available.
|
|
48
|
-
* @see https://shelving.cc/db/QueryStore/memory
|
|
49
|
-
*/
|
|
50
|
-
memory;
|
|
51
|
-
/**
|
|
52
|
-
* The maximum number of items the query can return, or `Infinity` if unlimited.
|
|
53
|
-
* - For a paged query, this is the size of each page.
|
|
54
|
-
* @see https://shelving.cc/db/QueryStore/limit
|
|
55
|
-
*/
|
|
56
|
-
get limit() {
|
|
57
|
-
return getQueryLimit(this.query) ?? Number.POSITIVE_INFINITY;
|
|
58
|
-
}
|
|
59
|
-
/**
|
|
60
|
-
* Whether more items can be loaded after the last item with `fetchAfter()`.
|
|
61
|
-
* @see https://shelving.cc/db/QueryStore/hasAfter
|
|
62
|
-
*/
|
|
63
|
-
get hasAfter() {
|
|
64
|
-
return this._hasAfter;
|
|
65
|
-
}
|
|
66
|
-
_hasAfter = false;
|
|
67
|
-
/**
|
|
68
|
-
* Whether more items can be loaded before the first item with `fetchBefore()`.
|
|
69
|
-
* - `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.
|
|
70
|
-
* @see https://shelving.cc/db/QueryStore/hasBefore
|
|
71
|
-
*/
|
|
72
|
-
get hasBefore() {
|
|
73
|
-
return this._hasBefore;
|
|
74
|
-
}
|
|
75
|
-
_hasBefore = false;
|
|
76
|
-
/**
|
|
77
|
-
* Whether more items can be loaded after the last item. Alias of `hasAfter`.
|
|
78
|
-
* @see https://shelving.cc/db/QueryStore/hasMore
|
|
79
|
-
*/
|
|
80
|
-
get hasMore() {
|
|
81
|
-
return this._hasAfter;
|
|
82
|
-
}
|
|
83
41
|
/**
|
|
84
42
|
* The first item in this store, or `undefined` if the query has no items.
|
|
85
43
|
* @see https://shelving.cc/db/QueryStore/optionalFirst
|
|
@@ -134,240 +92,32 @@ export class QueryStore extends FetchStore {
|
|
|
134
92
|
});
|
|
135
93
|
return last;
|
|
136
94
|
}
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
_loaded = false; // Whether any items have been pinned yet.
|
|
143
|
-
_generation = 0; // Increases when a refresh starts.
|
|
144
|
-
constructor(collection, query, provider, memory) {
|
|
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.
|
|
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.
|
|
148
100
|
this.provider = provider;
|
|
149
101
|
this.collection = collection;
|
|
150
102
|
this.query = query;
|
|
151
|
-
this.
|
|
152
|
-
this.
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
// Paged query: pin the snapshot, and recompose the pinned items whenever the memory changes.
|
|
156
|
-
if (items) {
|
|
157
|
-
this._pin(items);
|
|
158
|
-
this._hasAfter = items.length >= this.limit; // A full snapshot may have more items after it.
|
|
159
|
-
}
|
|
160
|
-
if (memory)
|
|
161
|
-
this.starter = store => runSequence(memory.getQuerySequence(collection), () => store._recompose());
|
|
162
|
-
}
|
|
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)));
|
|
166
|
-
}
|
|
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));
|
|
167
107
|
}
|
|
168
108
|
// Override to fetch the result from the database provider.
|
|
169
|
-
// - A
|
|
170
|
-
// - A `MemoryDBProvider` waits until it has loaded the query.
|
|
109
|
+
// - A memory waits until it has loaded the query.
|
|
171
110
|
async _fetch(signal) {
|
|
172
|
-
const { provider, collection, query,
|
|
173
|
-
if (
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
await _awaitFirst(_getLoadedSequence(table, query), signal);
|
|
177
|
-
}
|
|
178
|
-
if (!this._orders.length)
|
|
179
|
-
return provider.getQuery(collection, query);
|
|
180
|
-
const generation = ++this._generation; // Makes any page fetch that is still running drop its result.
|
|
181
|
-
// Load one more item than the page, to see if there are more.
|
|
182
|
-
const items = await provider.getQuery(collection, _withLimit(query, limit + 1));
|
|
183
|
-
if (generation !== this._generation)
|
|
184
|
-
return this._compose(); // A newer refresh started, so it sets the items.
|
|
185
|
-
this._hasAfter = items.length > limit;
|
|
186
|
-
this._hasBefore = false;
|
|
187
|
-
this._pin(items.slice(0, limit));
|
|
188
|
-
return this._compose();
|
|
189
|
-
}
|
|
190
|
-
/**
|
|
191
|
-
* Load the next page of items after the last item.
|
|
192
|
-
* - Uses the query `$limit` as the page size.
|
|
193
|
-
* - Sets `busy` while the page loads. The items already loaded do not suspend.
|
|
194
|
-
* - Waits for a fetch that is already running, then loads the page.
|
|
195
|
-
* - Does nothing if `hasAfter` is `false`.
|
|
196
|
-
* - Loads the first page if no items have loaded yet.
|
|
197
|
-
* - A failed fetch rejects the promise, and the items already loaded stay. Unlike `refresh()`, it does not set `reason`.
|
|
198
|
-
*
|
|
199
|
-
* @returns Promise that resolves when the page has loaded.
|
|
200
|
-
* @throws {RequiredError} If the query has no `$order`.
|
|
201
|
-
* @throws {unknown} The error from the provider, if the fetch fails.
|
|
202
|
-
* @example if (store.hasAfter) await store.fetchAfter();
|
|
203
|
-
* @see https://shelving.cc/db/QueryStore/fetchAfter
|
|
204
|
-
*/
|
|
205
|
-
async fetchAfter() {
|
|
206
|
-
const { query, limit } = this;
|
|
207
|
-
if (!this._orders.length)
|
|
208
|
-
throw new RequiredError("Query must have $order to fetch more items", { store: this, query, caller: this.fetchAfter });
|
|
209
|
-
if (this.busy.value)
|
|
210
|
-
await this._idle(); // Only await when busy, so `busy` is set at once.
|
|
211
|
-
const last = this._getRow(this._ids.at(-1));
|
|
212
|
-
if (!last) {
|
|
213
|
-
await this.refresh();
|
|
214
|
-
return;
|
|
215
|
-
}
|
|
216
|
-
if (!this._hasAfter)
|
|
217
|
-
return;
|
|
218
|
-
const items = await this._fetchPage(getQueryAfter(query, last, this.fetchAfter), last);
|
|
219
|
-
if (!items)
|
|
220
|
-
return;
|
|
221
|
-
this._hasAfter = items.length > limit;
|
|
222
|
-
this._pin([...this._ids, ...items.slice(0, limit)]);
|
|
223
|
-
this.write(this._compose());
|
|
224
|
-
}
|
|
225
|
-
/**
|
|
226
|
-
* Load the next page of items after the last item. Alias of `fetchAfter()`.
|
|
227
|
-
*
|
|
228
|
-
* @returns Promise that resolves when the page has loaded.
|
|
229
|
-
* @see https://shelving.cc/db/QueryStore/fetchMore
|
|
230
|
-
*/
|
|
231
|
-
fetchMore() {
|
|
232
|
-
return this.fetchAfter();
|
|
233
|
-
}
|
|
234
|
-
/**
|
|
235
|
-
* Load the new items before the first item, e.g. new messages at the start of a newest-first list.
|
|
236
|
-
* - Loads up to one page (the query `$limit`), nearest to the first item. Call again while `hasBefore` is `true` to load more.
|
|
237
|
-
* - Sets `busy` while the items load. The items already loaded do not suspend.
|
|
238
|
-
* - Waits for a fetch that is already running, then loads the items.
|
|
239
|
-
* - Loads the first page if no items have loaded yet.
|
|
240
|
-
* - A failed fetch rejects the promise, and the items already loaded stay. Unlike `refresh()`, it does not set `reason`.
|
|
241
|
-
*
|
|
242
|
-
* @returns Promise that resolves when the new items have loaded.
|
|
243
|
-
* @throws {RequiredError} If the query has no `$order`.
|
|
244
|
-
* @throws {unknown} The error from the provider, if the fetch fails.
|
|
245
|
-
* @example setInterval(() => store.fetchBefore().catch(BLACKHOLE), 10_000); // Poll for new messages.
|
|
246
|
-
* @see https://shelving.cc/db/QueryStore/fetchBefore
|
|
247
|
-
*/
|
|
248
|
-
async fetchBefore() {
|
|
249
|
-
const { query, limit } = this;
|
|
250
|
-
if (!this._orders.length)
|
|
251
|
-
throw new RequiredError("Query must have $order to fetch more items", { store: this, query, caller: this.fetchBefore });
|
|
252
|
-
if (this.busy.value)
|
|
253
|
-
await this._idle(); // Only await when busy, so `busy` is set at once.
|
|
254
|
-
const first = this._getRow(this._ids[0]);
|
|
255
|
-
if (!first) {
|
|
256
|
-
await this.refresh();
|
|
257
|
-
return;
|
|
258
|
-
}
|
|
259
|
-
// Reverse the order so the items nearest to the first item come first.
|
|
260
|
-
const items = await this._fetchPage({ ...getQueryBefore(query, first, this.fetchBefore), $order: _reverseOrders(this._orders) }, first);
|
|
261
|
-
if (!items)
|
|
262
|
-
return;
|
|
263
|
-
this._hasBefore = items.length > limit;
|
|
264
|
-
this._pin([...items.slice(0, limit).reverse(), ...this._ids]);
|
|
265
|
-
this.write(this._compose());
|
|
266
|
-
}
|
|
267
|
-
/** Wait until no fetch is running. */
|
|
268
|
-
async _idle() {
|
|
269
|
-
while (this.busy.value)
|
|
270
|
-
await this.busy.next;
|
|
271
|
-
}
|
|
272
|
-
/** Fetch one page from an inclusive cursor query, and drop the items already loaded. */
|
|
273
|
-
async _fetchPage(query, cursor) {
|
|
274
|
-
const { _ids, _rows, limit } = this;
|
|
275
|
-
const { key } = requireFirst(this._orders);
|
|
276
|
-
const value = getDataProp(cursor, key);
|
|
277
|
-
// The inclusive range returns the loaded items with the same sort value as the cursor again, so ask for that many more.
|
|
278
|
-
let ties = 0;
|
|
279
|
-
for (const id of _ids) {
|
|
280
|
-
const row = _rows.get(id);
|
|
281
|
-
if (row && isEqual(getDataProp(row, key), value))
|
|
282
|
-
ties++;
|
|
283
|
-
}
|
|
284
|
-
// A refresh that starts while the page loads owns the items and `busy`, so the page is dropped.
|
|
285
|
-
const generation = this._generation;
|
|
286
|
-
this.busy.value = true;
|
|
287
|
-
try {
|
|
288
|
-
const items = await this.provider.getQuery(this.collection, _withLimit(query, limit + ties + 1));
|
|
289
|
-
if (generation !== this._generation)
|
|
290
|
-
return;
|
|
291
|
-
const seen = new Set(_ids);
|
|
292
|
-
return items.filter(({ id }) => !seen.has(id));
|
|
293
|
-
}
|
|
294
|
-
catch (thrown) {
|
|
295
|
-
if (generation === this._generation)
|
|
296
|
-
throw thrown; // Keep the loaded items, so do not set `reason`.
|
|
297
|
-
}
|
|
298
|
-
finally {
|
|
299
|
-
if (generation === this._generation)
|
|
300
|
-
this.busy.value = false;
|
|
301
|
-
}
|
|
302
|
-
}
|
|
303
|
-
/** Pin a list of items (or IDs of items already pinned) as the loaded items, in display order. */
|
|
304
|
-
_pin(items) {
|
|
305
|
-
const rows = new Map();
|
|
306
|
-
const ids = [];
|
|
307
|
-
for (const item of items) {
|
|
308
|
-
const row = typeof item === "object" ? item : this._rows.get(item);
|
|
309
|
-
if (!row || rows.has(row.id))
|
|
310
|
-
continue;
|
|
311
|
-
rows.set(row.id, row);
|
|
312
|
-
ids.push(row.id);
|
|
313
|
-
}
|
|
314
|
-
this._ids = ids;
|
|
315
|
-
this._rows = rows;
|
|
316
|
-
this._loaded = true;
|
|
317
|
-
// Put the fetched items in the memory, so other stores can use them.
|
|
318
|
-
if (this.memory)
|
|
319
|
-
this.memory.getTable(this.collection).setItems(items.filter(item => typeof item === "object"));
|
|
320
|
-
}
|
|
321
|
-
/** Get a pinned item as it was fetched. */
|
|
322
|
-
_getRow(id) {
|
|
323
|
-
return id === undefined ? undefined : this._rows.get(id);
|
|
324
|
-
}
|
|
325
|
-
/**
|
|
326
|
-
* Make the current value of a paged query.
|
|
327
|
-
* - New items in the memory that match the filters and sort before the first pinned item come first.
|
|
328
|
-
* - When the list is complete (`hasAfter` is `false`), new items that sort after the last pinned item come last.
|
|
329
|
-
* - Then each pinned item in its pinned position, with its current data from the memory. Items deleted from the memory are hidden.
|
|
330
|
-
*/
|
|
331
|
-
_compose() {
|
|
332
|
-
const { memory, _ids, _rows, _orders, _filters } = this;
|
|
333
|
-
if (!memory)
|
|
334
|
-
return _ids.map(id => _rows.get(id)).filter(isDefined);
|
|
335
|
-
const table = memory.getTable(this.collection);
|
|
336
|
-
const first = this._getRow(_ids[0]);
|
|
337
|
-
const last = this._hasAfter ? undefined : this._getRow(_ids.at(-1)); // Only a complete list shows new items at the end.
|
|
338
|
-
const head = [];
|
|
339
|
-
const tail = [];
|
|
340
|
-
for (const item of table.getQuery()) {
|
|
341
|
-
if (_rows.has(item.id) || !matchQueryItem(item, _filters))
|
|
342
|
-
continue;
|
|
343
|
-
if (!first || compareQueryItems(item, first, _orders) < 0)
|
|
344
|
-
head.push(item);
|
|
345
|
-
else if (last && compareQueryItems(item, last, _orders) > 0)
|
|
346
|
-
tail.push(item);
|
|
347
|
-
}
|
|
348
|
-
const body = _ids.map(id => table.getItem(id)).filter(isDefined);
|
|
349
|
-
return [...sortQueryItems(head, _orders), ...body, ...sortQueryItems(tail, _orders)];
|
|
350
|
-
}
|
|
351
|
-
/** Recompose the value after the memory changes. */
|
|
352
|
-
_recompose() {
|
|
353
|
-
// Skip while loading, or while a fetch runs (it recomposes when it ends, and a write now would abort a refresh).
|
|
354
|
-
if (!this._loaded || this.busy.value)
|
|
355
|
-
return;
|
|
356
|
-
this.write(this._compose());
|
|
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);
|
|
357
115
|
}
|
|
358
116
|
// Implement `Iterable`
|
|
359
117
|
[Symbol.iterator]() {
|
|
360
118
|
return this.value.values();
|
|
361
119
|
}
|
|
362
120
|
}
|
|
363
|
-
/** Set the limit of a query, or remove it when the limit is infinite. */
|
|
364
|
-
function _withLimit(query, limit) {
|
|
365
|
-
return { ...query, $limit: Number.isFinite(limit) ? limit : undefined }; // Not `withProp()`, because it cannot infer `$limit` on a generic `Query<T>`.
|
|
366
|
-
}
|
|
367
|
-
/** Reverse every order of a query. */
|
|
368
|
-
function _reverseOrders(orders) {
|
|
369
|
-
return orders.map(({ key, direction }) => `${direction === "asc" ? "!" : ""}${joinDataPath(key)}`);
|
|
370
|
-
}
|
|
371
121
|
/** Whether the memory has loaded a query, i.e. it has items for it, or a time for it. */
|
|
372
122
|
function _isLoaded(table, query) {
|
|
373
123
|
return table.getQueryTime(query) !== undefined || !!table.countQuery(query);
|
|
@@ -378,6 +128,16 @@ async function* _getLoadedSequence(table, query) {
|
|
|
378
128
|
if (items.length || table.getQueryTime(query) !== undefined)
|
|
379
129
|
yield items;
|
|
380
130
|
}
|
|
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
|
+
}
|
|
381
141
|
/** Get the first value of a sequence, or reject when the signal aborts. */
|
|
382
142
|
async function _awaitFirst(sequence, signal) {
|
|
383
143
|
const iterator = sequence[Symbol.asyncIterator]();
|
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/string.d.ts
CHANGED
|
@@ -157,14 +157,19 @@ export declare function sanitizeWord(str: string): string;
|
|
|
157
157
|
export declare function sanitizeMultilineText(str: string): string;
|
|
158
158
|
/**
|
|
159
159
|
* Simplify a string by removing anything that isn't a number, letter, or space.
|
|
160
|
-
* -
|
|
161
|
-
* -
|
|
160
|
+
* - Useful when you're running a query against a string entered by a user, or making a slug from a title.
|
|
161
|
+
* - Uses `NFKD` normalisation to convert styled letters to plain letters, e.g. circled `Ⓒ`, italic `𝐶`, script `𝒞`, fraktur `ℭ`, double-struck `ℂ`, fullwidth `C`, and superscript `ᶜ` all become `c`.
|
|
162
|
+
* - `NFKD` also splits ligatures (e.g. `ff` becomes `ff`) and removes accents (e.g. `é` becomes `e`).
|
|
163
|
+
* - Converts a small set of letterlike characters that `NFKD` does not cover: small capitals (e.g. `ᴄ`), negative circled and squared letters (e.g. `🅒` and `🅲`), regional indicators (e.g. `🇨`), and the estimate symbol `℮`.
|
|
164
|
+
* - Keeps letters from other scripts (e.g. `ж`, `π`, `ℵ` alef becomes `א`), and does not convert them to Latin letters that look the same.
|
|
165
|
+
* - Removes symbols, punctuation, and emoji (e.g. `©`, `!`, `😂`).
|
|
166
|
+
* - Removes marks that annotate text (`™`, `℠`, `🅪`, `🅫`, `🅬`), so `Acme™` becomes `acme`, not `acmetm`.
|
|
167
|
+
* - Keeps the letters of units and abbreviations, because they are part of the meaning (e.g. `㎏` becomes `kg`, `№` becomes `no`, `℃` becomes `c`).
|
|
168
|
+
* - Converts runs of spaces, tabs, newlines, underscores, and dashes to a single space, then trims and lowercases the result.
|
|
162
169
|
*
|
|
163
170
|
* @param str The string to simplify.
|
|
164
171
|
* @returns The simplified, lowercased string containing only numbers, letters, and single spaces.
|
|
165
172
|
* @see https://shelving.cc/util/string/simplifyString
|
|
166
|
-
*
|
|
167
|
-
* @todo Convert confusables (e.g. `ℵ` alef symbol or `℮` estimate symbol) to their letterlike equivalent (e.g. `N` and `e`).
|
|
168
173
|
*/
|
|
169
174
|
export declare function simplifyString(str: string): string;
|
|
170
175
|
/**
|
package/util/string.js
CHANGED
|
@@ -187,22 +187,47 @@ export function sanitizeMultilineText(str) {
|
|
|
187
187
|
.replace(/[^\S\t\n]{4}/g, "\t") // Normalise leading ` ` four whitespace characters to a single `\t` tab.
|
|
188
188
|
.replace(/(^|\t|\n)[^\S\t\n]+/g, "$1"); // Remove leading whitespace that isn't a tab.
|
|
189
189
|
}
|
|
190
|
+
// Characters where `NFKD` normalisation does not give the plain letter we want.
|
|
191
|
+
const _LETTERS = "abcdefghijklmnopqrstuvwxyz";
|
|
192
|
+
const _LETTERLIKE = new Map([
|
|
193
|
+
["℮", "e"], // Estimate symbol.
|
|
194
|
+
...Array.from("™℠🅪🅫🅬", char => [char, ""]), // Marks that annotate text are removed (these are every multi-letter symbol with a `<super>` decomposition, e.g. `NFKD` converts `™` to `TM`).
|
|
195
|
+
...Array.from("ᴀʙᴄᴅᴇꜰɢʜɪᴊᴋʟᴍɴᴏᴘꞯʀꜱᴛᴜᴠᴡxʏᴢ", (char, i) => [char, _LETTERS.charAt(i)]), // Small capitals `ᴀ` to `ᴢ` (no small capital `x` exists).
|
|
196
|
+
..._getLetterRange(0x1f150), // Negative circled capitals `🅐` to `🅩`.
|
|
197
|
+
..._getLetterRange(0x1f170), // Negative squared capitals `🅰` to `🆉`.
|
|
198
|
+
..._getLetterRange(0x1f1e6), // Regional indicators `🇦` to `🇿` (pairs show as flags, e.g. `🇬🇧` becomes `gb`).
|
|
199
|
+
]);
|
|
200
|
+
const _LETTERLIKE_REGEXP = new RegExp(`[${Array.from(_LETTERLIKE.keys()).join("")}]`, "gu");
|
|
201
|
+
/** Get the 26 `[char, letter]` pairs for a run of letterlike characters that starts at `start` and runs `A` to `Z`. */
|
|
202
|
+
function _getLetterRange(start) {
|
|
203
|
+
return Array.from(_LETTERS, (letter, i) => [String.fromCodePoint(start + i), letter]);
|
|
204
|
+
}
|
|
205
|
+
/** Replace a letterlike character with its plain letter. */
|
|
206
|
+
function _replaceLetterlike(char) {
|
|
207
|
+
return _LETTERLIKE.get(char) ?? char;
|
|
208
|
+
}
|
|
190
209
|
/**
|
|
191
210
|
* Simplify a string by removing anything that isn't a number, letter, or space.
|
|
192
|
-
* -
|
|
193
|
-
* -
|
|
211
|
+
* - Useful when you're running a query against a string entered by a user, or making a slug from a title.
|
|
212
|
+
* - Uses `NFKD` normalisation to convert styled letters to plain letters, e.g. circled `Ⓒ`, italic `𝐶`, script `𝒞`, fraktur `ℭ`, double-struck `ℂ`, fullwidth `C`, and superscript `ᶜ` all become `c`.
|
|
213
|
+
* - `NFKD` also splits ligatures (e.g. `ff` becomes `ff`) and removes accents (e.g. `é` becomes `e`).
|
|
214
|
+
* - Converts a small set of letterlike characters that `NFKD` does not cover: small capitals (e.g. `ᴄ`), negative circled and squared letters (e.g. `🅒` and `🅲`), regional indicators (e.g. `🇨`), and the estimate symbol `℮`.
|
|
215
|
+
* - Keeps letters from other scripts (e.g. `ж`, `π`, `ℵ` alef becomes `א`), and does not convert them to Latin letters that look the same.
|
|
216
|
+
* - Removes symbols, punctuation, and emoji (e.g. `©`, `!`, `😂`).
|
|
217
|
+
* - Removes marks that annotate text (`™`, `℠`, `🅪`, `🅫`, `🅬`), so `Acme™` becomes `acme`, not `acmetm`.
|
|
218
|
+
* - Keeps the letters of units and abbreviations, because they are part of the meaning (e.g. `㎏` becomes `kg`, `№` becomes `no`, `℃` becomes `c`).
|
|
219
|
+
* - Converts runs of spaces, tabs, newlines, underscores, and dashes to a single space, then trims and lowercases the result.
|
|
194
220
|
*
|
|
195
221
|
* @param str The string to simplify.
|
|
196
222
|
* @returns The simplified, lowercased string containing only numbers, letters, and single spaces.
|
|
197
223
|
* @see https://shelving.cc/util/string/simplifyString
|
|
198
|
-
*
|
|
199
|
-
* @todo Convert confusables (e.g. `ℵ` alef symbol or `℮` estimate symbol) to their letterlike equivalent (e.g. `N` and `e`).
|
|
200
224
|
*/
|
|
201
225
|
export function simplifyString(str) {
|
|
202
226
|
return str
|
|
227
|
+
.replace(_LETTERLIKE_REGEXP, _replaceLetterlike) // Convert letterlike characters that `NFKD` doesn't (e.g. `ᴄ` small capital, `🅒` negative circled, `℮` estimate symbol), and remove marks (e.g. `™`).
|
|
203
228
|
.normalize("NFKD") // Normalize ligatures (e.g. `ff` to `ff`), combined characters (e.g. `Ⓜ` to `m`), accents (e.g. `å` to `a`).
|
|
204
|
-
.replace(/[^\p{L}\p{N}\p{Z}\p{Pc}\p{Pd}]+/gu, "") // Strip characters that aren't `\p{L}` letters, `\p{N}` numbers, `\p{Z}` separators (e.g. ` ` space), `\p{Pc}` connector punctuation (e.g. `_`
|
|
205
|
-
.replace(/[\p{Z}\p{Pc}\p{Pd}]+/gu, " ") // Normalise runs of
|
|
229
|
+
.replace(/[^\p{L}\p{N}\p{Z}\p{Pc}\p{Pd}\s]+/gu, "") // Strip characters that aren't `\p{L}` letters, `\p{N}` numbers, `\p{Z}` separators (e.g. ` ` space), `\p{Pc}` connector punctuation (e.g. `_` underscore), `\p{Pd}` dash punctuation (e.g. `-` hyphen), or `\s` whitespace (e.g. `\t` tab or `\n` newline).
|
|
230
|
+
.replace(/[\p{Z}\p{Pc}\p{Pd}\s]+/gu, " ") // Normalise runs of separators, connector punctuation, dash punctuation, and whitespace to ` ` single space.
|
|
206
231
|
.trim()
|
|
207
232
|
.toLowerCase();
|
|
208
233
|
}
|
|
@@ -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 and mark the query as loaded. */
|
|
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
|
-
}
|
|
@@ -1,107 +0,0 @@
|
|
|
1
|
-
import { awaitDispose } from "../../util/dispose.js";
|
|
2
|
-
import { MemoryDBProvider } from "./MemoryDBProvider.js";
|
|
3
|
-
import { RecordingDBProvider } from "./RecordingDBProvider.js";
|
|
4
|
-
import { ThroughDBProvider } from "./ThroughDBProvider.js";
|
|
5
|
-
/**
|
|
6
|
-
* Database provider that keeps a copy of asynchronous remote data in a local synchronous cache.
|
|
7
|
-
*
|
|
8
|
-
* - 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.
|
|
9
|
-
* - Reads fetch from `source`, then refresh the cache; writes hit `source`, then mirror the change into the cache.
|
|
10
|
-
* - 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.
|
|
11
|
-
* - Transactions run on `source` via `transact()` with a transaction-scoped mirror — only a committed transaction's writes reach the cache.
|
|
12
|
-
* - Discover the cache from a wrapping layer with `getSource(CacheDBProvider, provider)` to seed stores from `.memory`.
|
|
13
|
-
*
|
|
14
|
-
* @see https://shelving.cc/db/CacheDBProvider
|
|
15
|
-
*/
|
|
16
|
-
export class CacheDBProvider extends ThroughDBProvider {
|
|
17
|
-
/**
|
|
18
|
-
* The in-memory provider holding the local synchronous cache of `source` data.
|
|
19
|
-
*
|
|
20
|
-
* @see https://shelving.cc/db/CacheDBProvider/memory
|
|
21
|
-
*/
|
|
22
|
-
memory;
|
|
23
|
-
/**
|
|
24
|
-
* @param cache In-memory provider to use as the cache (a fresh `MemoryDBProvider` by default).
|
|
25
|
-
*/
|
|
26
|
-
constructor(source, cache = new MemoryDBProvider()) {
|
|
27
|
-
super(source);
|
|
28
|
-
this.memory = cache;
|
|
29
|
-
}
|
|
30
|
-
/** Read from `source`, then refresh the cache. */
|
|
31
|
-
async getItem(collection, id) {
|
|
32
|
-
const item = await super.getItem(collection, id);
|
|
33
|
-
const table = this.memory.getTable(collection);
|
|
34
|
-
item ? table.setItem(id, item) : table.deleteItem(id);
|
|
35
|
-
return item;
|
|
36
|
-
}
|
|
37
|
-
/** Mirror each emission into the cache. */
|
|
38
|
-
getItemSequence(collection, id) {
|
|
39
|
-
return this.memory.getTable(collection).setItemSequence(id, super.getItemSequence(collection, id));
|
|
40
|
-
}
|
|
41
|
-
/** Mirror the added item into the cache. */
|
|
42
|
-
async addItem(collection, data) {
|
|
43
|
-
const id = await super.addItem(collection, data);
|
|
44
|
-
this.memory.getTable(collection).setItem(id, data);
|
|
45
|
-
return id;
|
|
46
|
-
}
|
|
47
|
-
/** Mirror the set item into the cache. */
|
|
48
|
-
async setItem(collection, id, data) {
|
|
49
|
-
await super.setItem(collection, id, data);
|
|
50
|
-
this.memory.getTable(collection).setItem(id, data);
|
|
51
|
-
}
|
|
52
|
-
/** Fetch the item first (caching it), then update it only if it exists. */
|
|
53
|
-
async updateItem(collection, id, updates) {
|
|
54
|
-
const item = await this.getItem(collection, id);
|
|
55
|
-
if (!item)
|
|
56
|
-
return;
|
|
57
|
-
await super.updateItem(collection, id, updates);
|
|
58
|
-
this.memory.getTable(collection).updateItem(id, updates);
|
|
59
|
-
}
|
|
60
|
-
/** Fetch the item first, then delete it only if it exists. */
|
|
61
|
-
async deleteItem(collection, id) {
|
|
62
|
-
const item = await this.getItem(collection, id);
|
|
63
|
-
if (!item)
|
|
64
|
-
return;
|
|
65
|
-
await super.deleteItem(collection, id);
|
|
66
|
-
this.memory.getTable(collection).deleteItem(id);
|
|
67
|
-
}
|
|
68
|
-
/** Read from `source`, then refresh the cache and mark the query as loaded. */
|
|
69
|
-
async getQuery(collection, query) {
|
|
70
|
-
const items = await super.getQuery(collection, query);
|
|
71
|
-
const table = this.memory.getTable(collection);
|
|
72
|
-
table.setItems(items);
|
|
73
|
-
table.setQueryTime(query);
|
|
74
|
-
return items;
|
|
75
|
-
}
|
|
76
|
-
/** Mirror each emission into the cache. */
|
|
77
|
-
getQuerySequence(collection, query) {
|
|
78
|
-
return this.memory.getTable(collection).setItemsSequence(super.getQuerySequence(collection, query));
|
|
79
|
-
}
|
|
80
|
-
// Override so transaction copies get their own transaction-scoped mirror — uncommitted writes must never touch the real cache.
|
|
81
|
-
cloneWith(source) {
|
|
82
|
-
const clone = super.cloneWith(source);
|
|
83
|
-
Object.defineProperty(clone, "memory", { value: new MemoryDBProvider(), enumerable: true });
|
|
84
|
-
return clone;
|
|
85
|
-
}
|
|
86
|
-
/**
|
|
87
|
-
* Runs the transaction on `source`, recording the callback's operations, then commits the recorded writes into the cache once the source commits.
|
|
88
|
-
* - 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.
|
|
89
|
-
* - 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.
|
|
90
|
-
* - 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.
|
|
91
|
-
*/
|
|
92
|
-
async transact(callback) {
|
|
93
|
-
let transaction;
|
|
94
|
-
const result = await this.source.transact(provider => {
|
|
95
|
-
transaction = new RecordingDBProvider(this.cloneWith(provider));
|
|
96
|
-
return callback(transaction);
|
|
97
|
-
});
|
|
98
|
-
if (transaction)
|
|
99
|
-
await transaction.replayWrites(this.memory); // Commit the recorded writes into the cache.
|
|
100
|
-
return result;
|
|
101
|
-
}
|
|
102
|
-
// Implement `AsyncDisposable`
|
|
103
|
-
async [Symbol.asyncDispose]() {
|
|
104
|
-
await awaitDispose(this.memory, // Dispose the cache memory provider.
|
|
105
|
-
super[Symbol.asyncDispose]());
|
|
106
|
-
}
|
|
107
|
-
}
|