shelving 1.307.4 → 1.309.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/api/index.d.ts +1 -0
- package/api/index.js +1 -0
- package/api/provider/HydratingAPIProvider.d.ts +28 -0
- package/api/provider/HydratingAPIProvider.js +82 -0
- package/db/cache/CollectionCache.d.ts +1 -7
- package/db/cache/CollectionCache.js +3 -9
- package/db/cache/DBCache.d.ts +1 -7
- package/db/cache/DBCache.js +2 -12
- package/db/collection/Collection.d.ts +24 -1
- package/db/collection/Collection.js +28 -2
- package/db/collection/CollectionItemSchema.d.ts +24 -0
- package/db/collection/CollectionItemSchema.js +23 -0
- package/db/collection/CollectionItemsSchema.d.ts +25 -0
- package/db/collection/CollectionItemsSchema.js +24 -0
- package/db/collection/CollectionQueryItemsSchema.d.ts +27 -0
- package/db/collection/CollectionQueryItemsSchema.js +25 -0
- package/db/collection/CollectionQuerySchema.d.ts +25 -0
- package/db/collection/CollectionQuerySchema.js +28 -0
- package/db/index.d.ts +4 -1
- package/db/index.js +4 -1
- package/db/provider/MemoryDBProvider.d.ts +42 -4
- package/db/provider/MemoryDBProvider.js +73 -6
- package/db/provider/RecordingDBProvider.d.ts +1 -1
- package/db/provider/RecordingDBProvider.js +1 -1
- package/db/provider/StorageDBProvider.d.ts +1 -1
- package/db/provider/StorageDBProvider.js +1 -1
- package/db/store/ItemStore.d.ts +6 -4
- package/db/store/ItemStore.js +55 -8
- package/db/store/QueryStore.d.ts +9 -99
- package/db/store/QueryStore.js +55 -260
- package/package.json +1 -1
- package/react/createDBContext.d.ts +1 -1
- package/react/createDBContext.js +1 -1
- package/util/query.d.ts +29 -6
- package/util/query.js +33 -6
- package/db/provider/CacheDBProvider.d.ts +0 -56
- package/db/provider/CacheDBProvider.js +0 -105
package/api/index.d.ts
CHANGED
|
@@ -6,6 +6,7 @@ export * from "./provider/APIProvider.js";
|
|
|
6
6
|
export * from "./provider/CachedAPIProvider.js";
|
|
7
7
|
export * from "./provider/ClientAPIProvider.js";
|
|
8
8
|
export * from "./provider/DebugAPIProvider.js";
|
|
9
|
+
export * from "./provider/HydratingAPIProvider.js";
|
|
9
10
|
export * from "./provider/JSONAPIProvider.js";
|
|
10
11
|
export * from "./provider/LoggingAPIProvider.js";
|
|
11
12
|
export * from "./provider/MockAPIProvider.js";
|
package/api/index.js
CHANGED
|
@@ -6,6 +6,7 @@ export * from "./provider/APIProvider.js";
|
|
|
6
6
|
export * from "./provider/CachedAPIProvider.js";
|
|
7
7
|
export * from "./provider/ClientAPIProvider.js";
|
|
8
8
|
export * from "./provider/DebugAPIProvider.js";
|
|
9
|
+
export * from "./provider/HydratingAPIProvider.js";
|
|
9
10
|
export * from "./provider/JSONAPIProvider.js";
|
|
10
11
|
export * from "./provider/LoggingAPIProvider.js";
|
|
11
12
|
export * from "./provider/MockAPIProvider.js";
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import type { MemoryDBProvider } from "../../db/provider/MemoryDBProvider.js";
|
|
2
|
+
import type { AnyCaller } from "../../util/function.js";
|
|
3
|
+
import type { RequestOptions } from "../../util/http.js";
|
|
4
|
+
import type { Endpoint } from "../endpoint/Endpoint.js";
|
|
5
|
+
import type { APIProvider } from "./APIProvider.js";
|
|
6
|
+
import { ValidationAPIProvider } from "./ValidationAPIProvider.js";
|
|
7
|
+
/**
|
|
8
|
+
* API provider that validates every result, then writes the collection items in it into a local database.
|
|
9
|
+
*
|
|
10
|
+
* - Only results that use a collection's own schemas hydrate: `Collection.item`, `Collection.items` and `Collection.queryItems`, or a `DataSchema` whose props use them (one level deep). Every other result passes through with no change.
|
|
11
|
+
* - `Collection.item` sets the item. A `null` or `undefined` result (e.g. `NULLABLE(USERS.item)`) deletes the item with the `id` from the payload (the payload itself, or its `id` prop).
|
|
12
|
+
* - `Collection.items` sets each item. It never deletes items.
|
|
13
|
+
* - `Collection.queryItems` sets each item, then marks the query as loaded (see `MemoryTable.setQueryTime()`).
|
|
14
|
+
* - Writes happen synchronously before `call()` resolves, so no store sees half of a result.
|
|
15
|
+
* - Extends `ValidationAPIProvider`, so it only ever writes validated items.
|
|
16
|
+
*
|
|
17
|
+
* @see https://shelving.cc/api/HydratingAPIProvider
|
|
18
|
+
*/
|
|
19
|
+
export declare class HydratingAPIProvider<P, R> extends ValidationAPIProvider<P, R> {
|
|
20
|
+
/**
|
|
21
|
+
* The local database the items are written into.
|
|
22
|
+
* @see https://shelving.cc/api/HydratingAPIProvider/db
|
|
23
|
+
*/
|
|
24
|
+
readonly db: MemoryDBProvider;
|
|
25
|
+
constructor(source: APIProvider<P, R>, db: MemoryDBProvider);
|
|
26
|
+
/** Calls the endpoint, then writes the collection items in the result into `db`. */
|
|
27
|
+
call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
|
|
28
|
+
}
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import { CollectionItemSchema } from "../../db/collection/CollectionItemSchema.js";
|
|
2
|
+
import { CollectionItemsSchema } from "../../db/collection/CollectionItemsSchema.js";
|
|
3
|
+
import { CollectionQueryItemsSchema } from "../../db/collection/CollectionQueryItemsSchema.js";
|
|
4
|
+
import { DataSchema } from "../../schema/DataSchema.js";
|
|
5
|
+
import { isArray } from "../../util/array.js";
|
|
6
|
+
import { isData } from "../../util/data.js";
|
|
7
|
+
import { getSource } from "../../util/source.js";
|
|
8
|
+
import { ValidationAPIProvider } from "./ValidationAPIProvider.js";
|
|
9
|
+
/**
|
|
10
|
+
* API provider that validates every result, then writes the collection items in it into a local database.
|
|
11
|
+
*
|
|
12
|
+
* - Only results that use a collection's own schemas hydrate: `Collection.item`, `Collection.items` and `Collection.queryItems`, or a `DataSchema` whose props use them (one level deep). Every other result passes through with no change.
|
|
13
|
+
* - `Collection.item` sets the item. A `null` or `undefined` result (e.g. `NULLABLE(USERS.item)`) deletes the item with the `id` from the payload (the payload itself, or its `id` prop).
|
|
14
|
+
* - `Collection.items` sets each item. It never deletes items.
|
|
15
|
+
* - `Collection.queryItems` sets each item, then marks the query as loaded (see `MemoryTable.setQueryTime()`).
|
|
16
|
+
* - Writes happen synchronously before `call()` resolves, so no store sees half of a result.
|
|
17
|
+
* - Extends `ValidationAPIProvider`, so it only ever writes validated items.
|
|
18
|
+
*
|
|
19
|
+
* @see https://shelving.cc/api/HydratingAPIProvider
|
|
20
|
+
*/
|
|
21
|
+
export class HydratingAPIProvider extends ValidationAPIProvider {
|
|
22
|
+
/**
|
|
23
|
+
* The local database the items are written into.
|
|
24
|
+
* @see https://shelving.cc/api/HydratingAPIProvider/db
|
|
25
|
+
*/
|
|
26
|
+
db;
|
|
27
|
+
constructor(source, db) {
|
|
28
|
+
super(source);
|
|
29
|
+
this.db = db;
|
|
30
|
+
}
|
|
31
|
+
/** Calls the endpoint, then writes the collection items in the result into `db`. */
|
|
32
|
+
async call(endpoint, payload, options, caller = this.call) {
|
|
33
|
+
const result = await super.call(endpoint, payload, options, caller);
|
|
34
|
+
const { db } = this;
|
|
35
|
+
if (!_hydrate(db, endpoint.result, result, payload) && isData(result)) {
|
|
36
|
+
// Go one level deep into a data result, so one endpoint can return several collections.
|
|
37
|
+
const data = getSource(DataSchema, endpoint.result);
|
|
38
|
+
if (data)
|
|
39
|
+
for (const [k, schema] of Object.entries(data.props))
|
|
40
|
+
_hydrate(db, schema, result[k]);
|
|
41
|
+
}
|
|
42
|
+
return result;
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
/** Write a value into the database if its schema is a collection schema, and return whether it was. */
|
|
46
|
+
function _hydrate(db, schema, value, payload) {
|
|
47
|
+
const queryItems = getSource(CollectionQueryItemsSchema, schema);
|
|
48
|
+
if (queryItems) {
|
|
49
|
+
if (isData(value)) {
|
|
50
|
+
const { query, items } = value;
|
|
51
|
+
const table = db.getTable(queryItems.source);
|
|
52
|
+
table.setItems(items);
|
|
53
|
+
table.setQueryTime(query);
|
|
54
|
+
}
|
|
55
|
+
return true;
|
|
56
|
+
}
|
|
57
|
+
const items = getSource(CollectionItemsSchema, schema);
|
|
58
|
+
if (items) {
|
|
59
|
+
if (isArray(value))
|
|
60
|
+
db.getTable(items.source).setItems(value);
|
|
61
|
+
return true;
|
|
62
|
+
}
|
|
63
|
+
const item = getSource(CollectionItemSchema, schema);
|
|
64
|
+
if (item) {
|
|
65
|
+
const table = db.getTable(item.source);
|
|
66
|
+
if (isData(value))
|
|
67
|
+
table.setItem(value.id, value);
|
|
68
|
+
else if (value === null || value === undefined) {
|
|
69
|
+
const id = _getPayloadID(payload);
|
|
70
|
+
if (id !== undefined)
|
|
71
|
+
table.deleteItem(id);
|
|
72
|
+
}
|
|
73
|
+
return true;
|
|
74
|
+
}
|
|
75
|
+
return false;
|
|
76
|
+
}
|
|
77
|
+
/** Get the item `id` from a payload: the payload itself, or its `id` prop. */
|
|
78
|
+
function _getPayloadID(payload) {
|
|
79
|
+
const id = isData(payload) ? payload.id : payload;
|
|
80
|
+
if (typeof id === "string" || typeof id === "number")
|
|
81
|
+
return id;
|
|
82
|
+
}
|
|
@@ -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.
|
|
@@ -4,6 +4,10 @@ import type { Schema, Schemas } from "../../schema/Schema.js";
|
|
|
4
4
|
import type { ImmutableArray } from "../../util/array.js";
|
|
5
5
|
import type { Data } from "../../util/data.js";
|
|
6
6
|
import type { Identifier, Item, Items, OptionalItem } from "../../util/item.js";
|
|
7
|
+
import { CollectionItemSchema } from "./CollectionItemSchema.js";
|
|
8
|
+
import { CollectionItemsSchema } from "./CollectionItemsSchema.js";
|
|
9
|
+
import { CollectionQueryItemsSchema } from "./CollectionQueryItemsSchema.js";
|
|
10
|
+
import { CollectionQuerySchema } from "./CollectionQuerySchema.js";
|
|
7
11
|
/**
|
|
8
12
|
* Default identifier schema (integer) used when a collection doesn't supply its own.
|
|
9
13
|
*
|
|
@@ -15,6 +19,7 @@ export declare const ID: NumberSchema;
|
|
|
15
19
|
*
|
|
16
20
|
* - Pairs a collection name with an identifier schema and a data schema, so providers can validate and address items.
|
|
17
21
|
* - Extends `DataSchema<T>`, so the collection itself validates an item's data, while `.item` validates the complete `id + data` item.
|
|
22
|
+
* - `.item`, `.items`, `.query` and `.queryItems` point back at the collection with `source`, so an endpoint result that uses them can hydrate a database (see `HydratingAPIProvider`).
|
|
18
23
|
*
|
|
19
24
|
* @example
|
|
20
25
|
* const users = new Collection("users", ID, { name: STRING, age: NUMBER });
|
|
@@ -40,7 +45,25 @@ export declare class Collection<N extends string = string, I extends Identifier
|
|
|
40
45
|
*
|
|
41
46
|
* @see https://shelving.cc/db/Collection/item
|
|
42
47
|
*/
|
|
43
|
-
readonly item:
|
|
48
|
+
readonly item: CollectionItemSchema<I, T>;
|
|
49
|
+
/**
|
|
50
|
+
* Schema for a list of complete items (id + data).
|
|
51
|
+
*
|
|
52
|
+
* @see https://shelving.cc/db/Collection/items
|
|
53
|
+
*/
|
|
54
|
+
readonly items: CollectionItemsSchema<I, T>;
|
|
55
|
+
/**
|
|
56
|
+
* Schema for a query on the items. It only checks that the query is an object, so do not trust the query it validates.
|
|
57
|
+
*
|
|
58
|
+
* @see https://shelving.cc/db/Collection/query
|
|
59
|
+
*/
|
|
60
|
+
readonly query: CollectionQuerySchema<I, T>;
|
|
61
|
+
/**
|
|
62
|
+
* Schema for a query and the complete list of items that answer it.
|
|
63
|
+
*
|
|
64
|
+
* @see https://shelving.cc/db/Collection/queryItems
|
|
65
|
+
*/
|
|
66
|
+
readonly queryItems: CollectionQueryItemsSchema<I, T>;
|
|
44
67
|
constructor(name: N, id: Schema<I>, data: Schemas<T> | DataSchema<T>);
|
|
45
68
|
/** Returns the collection name. */
|
|
46
69
|
toString(): string;
|
|
@@ -1,5 +1,9 @@
|
|
|
1
|
-
import { DataSchema
|
|
1
|
+
import { DataSchema } from "../../schema/DataSchema.js";
|
|
2
2
|
import { NumberSchema } from "../../schema/NumberSchema.js";
|
|
3
|
+
import { CollectionItemSchema } from "./CollectionItemSchema.js";
|
|
4
|
+
import { CollectionItemsSchema } from "./CollectionItemsSchema.js";
|
|
5
|
+
import { CollectionQueryItemsSchema } from "./CollectionQueryItemsSchema.js";
|
|
6
|
+
import { CollectionQuerySchema } from "./CollectionQuerySchema.js";
|
|
3
7
|
/**
|
|
4
8
|
* Default identifier schema (integer) used when a collection doesn't supply its own.
|
|
5
9
|
*
|
|
@@ -18,6 +22,7 @@ export const ID = new NumberSchema({
|
|
|
18
22
|
*
|
|
19
23
|
* - Pairs a collection name with an identifier schema and a data schema, so providers can validate and address items.
|
|
20
24
|
* - Extends `DataSchema<T>`, so the collection itself validates an item's data, while `.item` validates the complete `id + data` item.
|
|
25
|
+
* - `.item`, `.items`, `.query` and `.queryItems` point back at the collection with `source`, so an endpoint result that uses them can hydrate a database (see `HydratingAPIProvider`).
|
|
21
26
|
*
|
|
22
27
|
* @example
|
|
23
28
|
* const users = new Collection("users", ID, { name: STRING, age: NUMBER });
|
|
@@ -44,12 +49,33 @@ export class Collection extends DataSchema {
|
|
|
44
49
|
* @see https://shelving.cc/db/Collection/item
|
|
45
50
|
*/
|
|
46
51
|
item;
|
|
52
|
+
/**
|
|
53
|
+
* Schema for a list of complete items (id + data).
|
|
54
|
+
*
|
|
55
|
+
* @see https://shelving.cc/db/Collection/items
|
|
56
|
+
*/
|
|
57
|
+
items;
|
|
58
|
+
/**
|
|
59
|
+
* Schema for a query on the items. It only checks that the query is an object, so do not trust the query it validates.
|
|
60
|
+
*
|
|
61
|
+
* @see https://shelving.cc/db/Collection/query
|
|
62
|
+
*/
|
|
63
|
+
query;
|
|
64
|
+
/**
|
|
65
|
+
* Schema for a query and the complete list of items that answer it.
|
|
66
|
+
*
|
|
67
|
+
* @see https://shelving.cc/db/Collection/queryItems
|
|
68
|
+
*/
|
|
69
|
+
queryItems;
|
|
47
70
|
constructor(name, id, data) {
|
|
48
71
|
const dataSchema = data instanceof DataSchema ? data : new DataSchema({ props: data });
|
|
49
72
|
super({ ...dataSchema, props: dataSchema.props });
|
|
50
73
|
this.name = name;
|
|
51
74
|
this.id = id;
|
|
52
|
-
this.item =
|
|
75
|
+
this.item = new CollectionItemSchema(this);
|
|
76
|
+
this.items = new CollectionItemsSchema(this);
|
|
77
|
+
this.query = new CollectionQuerySchema(this);
|
|
78
|
+
this.queryItems = new CollectionQueryItemsSchema(this);
|
|
53
79
|
}
|
|
54
80
|
/** Returns the collection name. */
|
|
55
81
|
toString() {
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { DataSchema } from "../../schema/DataSchema.js";
|
|
2
|
+
import type { Data } from "../../util/data.js";
|
|
3
|
+
import type { Identifier, Item } from "../../util/item.js";
|
|
4
|
+
import type { Sourceable } from "../../util/source.js";
|
|
5
|
+
import type { Collection } from "./Collection.js";
|
|
6
|
+
/**
|
|
7
|
+
* Schema for one complete item (`id` + data) of a `Collection`.
|
|
8
|
+
*
|
|
9
|
+
* - Built by `Collection` as `Collection.item`. Use that instance, and do not make your own.
|
|
10
|
+
* - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema (e.g. through `NULLABLE(USERS.item)`).
|
|
11
|
+
* - `HydratingAPIProvider` writes an endpoint result that uses this schema into its database. A `null` or `undefined` result deletes the item with the `id` from the payload.
|
|
12
|
+
*
|
|
13
|
+
* @example
|
|
14
|
+
* const GET_USER = GET("/user/{id}", DATA({ id: USERS.id }), NULLABLE(USERS.item));
|
|
15
|
+
* @see https://shelving.cc/db/CollectionItemSchema
|
|
16
|
+
*/
|
|
17
|
+
export declare class CollectionItemSchema<I extends Identifier = Identifier, T extends Data = Data> extends DataSchema<Item<I, T>> implements Sourceable<Collection<string, I, T>> {
|
|
18
|
+
/**
|
|
19
|
+
* The collection this schema validates items of.
|
|
20
|
+
* @see https://shelving.cc/db/CollectionItemSchema/source
|
|
21
|
+
*/
|
|
22
|
+
readonly source: Collection<string, I, T>;
|
|
23
|
+
constructor(collection: Collection<string, I, T>);
|
|
24
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { DataSchema } from "../../schema/DataSchema.js";
|
|
2
|
+
/**
|
|
3
|
+
* Schema for one complete item (`id` + data) of a `Collection`.
|
|
4
|
+
*
|
|
5
|
+
* - Built by `Collection` as `Collection.item`. Use that instance, and do not make your own.
|
|
6
|
+
* - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema (e.g. through `NULLABLE(USERS.item)`).
|
|
7
|
+
* - `HydratingAPIProvider` writes an endpoint result that uses this schema into its database. A `null` or `undefined` result deletes the item with the `id` from the payload.
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* const GET_USER = GET("/user/{id}", DATA({ id: USERS.id }), NULLABLE(USERS.item));
|
|
11
|
+
* @see https://shelving.cc/db/CollectionItemSchema
|
|
12
|
+
*/
|
|
13
|
+
export class CollectionItemSchema extends DataSchema {
|
|
14
|
+
/**
|
|
15
|
+
* The collection this schema validates items of.
|
|
16
|
+
* @see https://shelving.cc/db/CollectionItemSchema/source
|
|
17
|
+
*/
|
|
18
|
+
source;
|
|
19
|
+
constructor(collection) {
|
|
20
|
+
super({ props: { id: collection.id, ...collection.props } });
|
|
21
|
+
this.source = collection;
|
|
22
|
+
}
|
|
23
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { ArraySchema } from "../../schema/ArraySchema.js";
|
|
2
|
+
import type { Data } from "../../util/data.js";
|
|
3
|
+
import type { Identifier, Item } from "../../util/item.js";
|
|
4
|
+
import type { Sourceable } from "../../util/source.js";
|
|
5
|
+
import type { Collection } from "./Collection.js";
|
|
6
|
+
/**
|
|
7
|
+
* Schema for a list of complete items (`id` + data) of a `Collection`.
|
|
8
|
+
*
|
|
9
|
+
* - Built by `Collection` as `Collection.items`. Use that instance, and do not make your own.
|
|
10
|
+
* - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
|
|
11
|
+
* - `HydratingAPIProvider` writes an endpoint result that uses this schema into its database. It only adds and replaces items, and never deletes them.
|
|
12
|
+
* - `ARRAY(USERS.item)` validates the same value, but it does not point at the collection, so it does not hydrate. Use `USERS.items`.
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* const LIST_USERS = GET("/user", undefined, USERS.items);
|
|
16
|
+
* @see https://shelving.cc/db/CollectionItemsSchema
|
|
17
|
+
*/
|
|
18
|
+
export declare class CollectionItemsSchema<I extends Identifier = Identifier, T extends Data = Data> extends ArraySchema<Item<I, T>> implements Sourceable<Collection<string, I, T>> {
|
|
19
|
+
/**
|
|
20
|
+
* The collection this schema validates items of.
|
|
21
|
+
* @see https://shelving.cc/db/CollectionItemsSchema/source
|
|
22
|
+
*/
|
|
23
|
+
readonly source: Collection<string, I, T>;
|
|
24
|
+
constructor(collection: Collection<string, I, T>);
|
|
25
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { ArraySchema } from "../../schema/ArraySchema.js";
|
|
2
|
+
/**
|
|
3
|
+
* Schema for a list of complete items (`id` + data) of a `Collection`.
|
|
4
|
+
*
|
|
5
|
+
* - Built by `Collection` as `Collection.items`. Use that instance, and do not make your own.
|
|
6
|
+
* - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
|
|
7
|
+
* - `HydratingAPIProvider` writes an endpoint result that uses this schema into its database. It only adds and replaces items, and never deletes them.
|
|
8
|
+
* - `ARRAY(USERS.item)` validates the same value, but it does not point at the collection, so it does not hydrate. Use `USERS.items`.
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* const LIST_USERS = GET("/user", undefined, USERS.items);
|
|
12
|
+
* @see https://shelving.cc/db/CollectionItemsSchema
|
|
13
|
+
*/
|
|
14
|
+
export class CollectionItemsSchema extends ArraySchema {
|
|
15
|
+
/**
|
|
16
|
+
* The collection this schema validates items of.
|
|
17
|
+
* @see https://shelving.cc/db/CollectionItemsSchema/source
|
|
18
|
+
*/
|
|
19
|
+
source;
|
|
20
|
+
constructor(collection) {
|
|
21
|
+
super({ items: collection.item });
|
|
22
|
+
this.source = collection;
|
|
23
|
+
}
|
|
24
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { DataSchema } from "../../schema/DataSchema.js";
|
|
2
|
+
import type { Data } from "../../util/data.js";
|
|
3
|
+
import type { Identifier } from "../../util/item.js";
|
|
4
|
+
import type { QueryItems } from "../../util/query.js";
|
|
5
|
+
import type { Sourceable } from "../../util/source.js";
|
|
6
|
+
import type { Collection } from "./Collection.js";
|
|
7
|
+
/**
|
|
8
|
+
* Schema for `QueryItems` of a `Collection`, i.e. a query and the complete list of items that answer it.
|
|
9
|
+
*
|
|
10
|
+
* - Built by `Collection` as `Collection.queryItems`, from `Collection.query` and `Collection.items`. Use that instance, and do not make your own.
|
|
11
|
+
* - **Do not trust the `query` in a value that this schema validates.** `Collection.query` only checks that it is an object. The `items` are validated in full.
|
|
12
|
+
* - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
|
|
13
|
+
* - `HydratingAPIProvider` writes an endpoint result that uses this schema into its database, and marks the query as loaded (see `MemoryTable.getQueryTime()`), so a store for the same query shows the items without loading.
|
|
14
|
+
* - Only use it when `items` is the complete answer to `query` (with its `$limit`).
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* const MY_CHALLENGES = GET("/challenge/me", undefined, DATA({ challenges: CHALLENGES.queryItems }));
|
|
18
|
+
* @see https://shelving.cc/db/CollectionQueryItemsSchema
|
|
19
|
+
*/
|
|
20
|
+
export declare class CollectionQueryItemsSchema<I extends Identifier = Identifier, T extends Data = Data> extends DataSchema<QueryItems<I, T>> implements Sourceable<Collection<string, I, T>> {
|
|
21
|
+
/**
|
|
22
|
+
* The collection this schema validates items of.
|
|
23
|
+
* @see https://shelving.cc/db/CollectionQueryItemsSchema/source
|
|
24
|
+
*/
|
|
25
|
+
readonly source: Collection<string, I, T>;
|
|
26
|
+
constructor(collection: Collection<string, I, T>);
|
|
27
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { DataSchema } from "../../schema/DataSchema.js";
|
|
2
|
+
/**
|
|
3
|
+
* Schema for `QueryItems` of a `Collection`, i.e. a query and the complete list of items that answer it.
|
|
4
|
+
*
|
|
5
|
+
* - Built by `Collection` as `Collection.queryItems`, from `Collection.query` and `Collection.items`. Use that instance, and do not make your own.
|
|
6
|
+
* - **Do not trust the `query` in a value that this schema validates.** `Collection.query` only checks that it is an object. The `items` are validated in full.
|
|
7
|
+
* - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
|
|
8
|
+
* - `HydratingAPIProvider` writes an endpoint result that uses this schema into its database, and marks the query as loaded (see `MemoryTable.getQueryTime()`), so a store for the same query shows the items without loading.
|
|
9
|
+
* - Only use it when `items` is the complete answer to `query` (with its `$limit`).
|
|
10
|
+
*
|
|
11
|
+
* @example
|
|
12
|
+
* const MY_CHALLENGES = GET("/challenge/me", undefined, DATA({ challenges: CHALLENGES.queryItems }));
|
|
13
|
+
* @see https://shelving.cc/db/CollectionQueryItemsSchema
|
|
14
|
+
*/
|
|
15
|
+
export class CollectionQueryItemsSchema extends DataSchema {
|
|
16
|
+
/**
|
|
17
|
+
* The collection this schema validates items of.
|
|
18
|
+
* @see https://shelving.cc/db/CollectionQueryItemsSchema/source
|
|
19
|
+
*/
|
|
20
|
+
source;
|
|
21
|
+
constructor(collection) {
|
|
22
|
+
super({ one: "result", title: "Result", props: { query: collection.query, items: collection.items } });
|
|
23
|
+
this.source = collection;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { Schema } from "../../schema/Schema.js";
|
|
2
|
+
import type { Data } from "../../util/data.js";
|
|
3
|
+
import type { Identifier, Item } from "../../util/item.js";
|
|
4
|
+
import type { Query } from "../../util/query.js";
|
|
5
|
+
import type { Sourceable } from "../../util/source.js";
|
|
6
|
+
import type { Collection } from "./Collection.js";
|
|
7
|
+
/**
|
|
8
|
+
* Schema for a `Query` on the items of a `Collection`.
|
|
9
|
+
*
|
|
10
|
+
* - Built by `Collection` as `Collection.query`. Use that instance, and do not make your own.
|
|
11
|
+
* - **Do not trust a query that this schema validates.** It only checks that the value is an object. It does not check the keys or the values against the collection, so a query from outside (e.g. an API response) can have any keys and values.
|
|
12
|
+
* - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
|
|
13
|
+
*
|
|
14
|
+
* @see https://shelving.cc/db/CollectionQuerySchema
|
|
15
|
+
*/
|
|
16
|
+
export declare class CollectionQuerySchema<I extends Identifier = Identifier, T extends Data = Data> extends Schema<Query<Item<I, T>>> implements Sourceable<Collection<string, I, T>> {
|
|
17
|
+
/**
|
|
18
|
+
* The collection this schema validates queries for.
|
|
19
|
+
* @see https://shelving.cc/db/CollectionQuerySchema/source
|
|
20
|
+
*/
|
|
21
|
+
readonly source: Collection<string, I, T>;
|
|
22
|
+
constructor(collection: Collection<string, I, T>);
|
|
23
|
+
/** Checks that the value is an object, and does nothing more. Do not trust the result. */
|
|
24
|
+
validate(unsafeValue?: unknown): Query<Item<I, T>>;
|
|
25
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { Schema } from "../../schema/Schema.js";
|
|
2
|
+
import { isData } from "../../util/data.js";
|
|
3
|
+
/**
|
|
4
|
+
* Schema for a `Query` on the items of a `Collection`.
|
|
5
|
+
*
|
|
6
|
+
* - Built by `Collection` as `Collection.query`. Use that instance, and do not make your own.
|
|
7
|
+
* - **Do not trust a query that this schema validates.** It only checks that the value is an object. It does not check the keys or the values against the collection, so a query from outside (e.g. an API response) can have any keys and values.
|
|
8
|
+
* - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
|
|
9
|
+
*
|
|
10
|
+
* @see https://shelving.cc/db/CollectionQuerySchema
|
|
11
|
+
*/
|
|
12
|
+
export class CollectionQuerySchema extends Schema {
|
|
13
|
+
/**
|
|
14
|
+
* The collection this schema validates queries for.
|
|
15
|
+
* @see https://shelving.cc/db/CollectionQuerySchema/source
|
|
16
|
+
*/
|
|
17
|
+
source;
|
|
18
|
+
constructor(collection) {
|
|
19
|
+
super({ one: "query", title: "Query", value: {} });
|
|
20
|
+
this.source = collection;
|
|
21
|
+
}
|
|
22
|
+
/** Checks that the value is an object, and does nothing more. Do not trust the result. */
|
|
23
|
+
validate(unsafeValue = this.value) {
|
|
24
|
+
if (!isData(unsafeValue))
|
|
25
|
+
throw "Must be object";
|
|
26
|
+
return unsafeValue;
|
|
27
|
+
}
|
|
28
|
+
}
|
package/db/index.d.ts
CHANGED
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
export * from "./cache/CollectionCache.js";
|
|
2
2
|
export * from "./cache/DBCache.js";
|
|
3
3
|
export * from "./collection/Collection.js";
|
|
4
|
+
export * from "./collection/CollectionItemSchema.js";
|
|
5
|
+
export * from "./collection/CollectionItemsSchema.js";
|
|
6
|
+
export * from "./collection/CollectionQueryItemsSchema.js";
|
|
7
|
+
export * from "./collection/CollectionQuerySchema.js";
|
|
4
8
|
export * from "./migrate/DBMigrator.js";
|
|
5
9
|
export * from "./migrate/PostgresMigrator.js";
|
|
6
10
|
export * from "./migrate/SQLiteMigrator.js";
|
|
7
11
|
export * from "./migrate/SQLMigrator.js";
|
|
8
|
-
export * from "./provider/CacheDBProvider.js";
|
|
9
12
|
export * from "./provider/DBProvider.js";
|
|
10
13
|
export * from "./provider/DebugDBProvider.js";
|
|
11
14
|
export * from "./provider/MemoryDBProvider.js";
|
package/db/index.js
CHANGED
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
export * from "./cache/CollectionCache.js";
|
|
2
2
|
export * from "./cache/DBCache.js";
|
|
3
3
|
export * from "./collection/Collection.js";
|
|
4
|
+
export * from "./collection/CollectionItemSchema.js";
|
|
5
|
+
export * from "./collection/CollectionItemsSchema.js";
|
|
6
|
+
export * from "./collection/CollectionQueryItemsSchema.js";
|
|
7
|
+
export * from "./collection/CollectionQuerySchema.js";
|
|
4
8
|
export * from "./migrate/DBMigrator.js";
|
|
5
9
|
export * from "./migrate/PostgresMigrator.js";
|
|
6
10
|
export * from "./migrate/SQLiteMigrator.js";
|
|
7
11
|
export * from "./migrate/SQLMigrator.js";
|
|
8
|
-
export * from "./provider/CacheDBProvider.js";
|
|
9
12
|
export * from "./provider/DBProvider.js";
|
|
10
13
|
export * from "./provider/DebugDBProvider.js";
|
|
11
14
|
export * from "./provider/MemoryDBProvider.js";
|