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.
@@ -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, this.memory));
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, this.memory));
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.
@@ -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 chain contains a `CacheDBProvider`, its memory is reused so stores can seed synchronously.
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
  /**
@@ -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 chain contains a `CacheDBProvider`, its memory is reused so stores can seed synchronously.
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, this.memory));
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 cache behind `CacheDBProvider`!), but does not persist data after the process or browser window closes.
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 cache behind `CacheDBProvider`!), but does not persist data after the process or browser window closes.
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(cache.memory);
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(cache.memory);
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 act as the cache inside `CacheDBProvider`. The only difference is that collections are backed by `StorageTable` instead of `MemoryTable`.
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 act as the cache inside `CacheDBProvider`. The only difference is that collections are backed by `StorageTable` instead of `MemoryTable`.
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.
@@ -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
- * - Seeds from a `MemoryDBProvider` snapshot when available, and subscribes to realtime updates.
12
- * - A missing item in the memory only counts as loaded when the memory has a time for it (see `MemoryTable.getItemTime()`). Until then the store is loading.
13
- * - When the provider is a `MemoryDBProvider`, a fetch waits until the memory has loaded the item (e.g. from `HydratingAPIProvider`).
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
- constructor(collection: Collection<string, I, T>, id: I, provider: DBProvider<I>, memory?: MemoryDBProvider<I>);
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
  }
@@ -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
- * - Seeds from a `MemoryDBProvider` snapshot when available, and subscribes to realtime updates.
15
- * - A missing item in the memory only counts as loaded when the memory has a time for it (see `MemoryTable.getItemTime()`). Until then the store is loading.
16
- * - When the provider is a `MemoryDBProvider`, a fetch waits until the memory has loaded the item (e.g. from `HydratingAPIProvider`).
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
- constructor(collection, id, provider, memory) {
64
- const table = memory?.getTable(collection);
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 `MemoryDBProvider` waits until it has loaded the item.
78
+ // - A memory waits until it has loaded the item.
74
79
  async _fetch(signal) {
75
- const { provider, collection, id } = this;
76
- if (provider instanceof MemoryDBProvider) {
77
- const table = provider.getTable(collection);
78
- if (!_isLoaded(table, id))
79
- await _awaitFirst(_getLoadedSequence(table, id), signal);
80
- }
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]();
@@ -1,20 +1,16 @@
1
1
  import { FetchStore } from "../../store/FetchStore.js";
2
- import { type Data } from "../../util/data.js";
2
+ import type { Data } from "../../util/data.js";
3
3
  import type { Identifier, Item, Items } from "../../util/item.js";
4
- import { type Query } from "../../util/query.js";
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
- * - Seeds from a `MemoryDBProvider` snapshot when available, and follows changes in the memory.
13
- * - An empty result in the memory only counts as loaded when the memory has a time for the query (see `MemoryTable.getQueryTime()`). Until then the store is loading.
14
- * - When the provider is a `MemoryDBProvider`, a fetch waits until the memory has loaded the query (e.g. from `HydratingAPIProvider`).
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
- private readonly _orders;
98
- private readonly _filters;
99
- private _ids;
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
  }
@@ -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, requireFirst } from "../../util/array.js";
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 { isDefined } from "../../util/undefined.js";
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
- * - Seeds from a `MemoryDBProvider` snapshot when available, and follows changes in the memory.
19
- * - An empty result in the memory only counts as loaded when the memory has a time for the query (see `MemoryTable.getQueryTime()`). Until then the store is loading.
20
- * - When the provider is a `MemoryDBProvider`, a fetch waits until the memory has loaded the query (e.g. from `HydratingAPIProvider`).
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
- // Paging state (only used when the query has an `$order`).
138
- _orders;
139
- _filters;
140
- _ids = []; // Pinned IDs in display order.
141
- _rows = new Map(); // Pinned items as they were fetched (their sort values are the cursors).
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.memory = memory;
152
- this._orders = getQueryOrders(query);
153
- this._filters = getQueryFilters(query);
154
- if (this._orders.length) {
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 paged query loads the first page again, and drops any other loaded pages.
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, limit } = this;
173
- if (provider instanceof MemoryDBProvider) {
174
- const table = provider.getTable(collection);
175
- if (!_isLoaded(table, query))
176
- await _awaitFirst(_getLoadedSequence(table, query), signal);
177
- }
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shelving",
3
- "version": "1.308.0",
3
+ "version": "1.310.0",
4
4
  "author": "Dave Houlbrooke <dave@shax.com>",
5
5
  "repository": {
6
6
  "type": "git",
@@ -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 has a `CacheDBProvider` in its chain then in-memory data will be used in the returned stores.
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
  *
@@ -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 has a `CacheDBProvider` in its chain then in-memory data will be used in the returned stores.
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
- * - Normalizes the string by
161
- * - Useful when you're running a query against a string entered by a user.
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
- * - Normalizes the string by
193
- * - Useful when you're running a query against a string entered by a user.
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. `_` underscore_, `\p{Pd}` dash punctuation (e.g. `-` hyphen)
205
- .replace(/[\p{Z}\p{Pc}\p{Pd}]+/gu, " ") // Normalise runs of `\p{Z}` separators (e.g. ` ` space), `\p{Pc}` connector punctuation (e.g. `_` underscore_, `\p{Pd}` dash punctuation (e.g. `-` hyphen), to ` ` single space.
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
- }