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.
Files changed (37) hide show
  1. package/api/index.d.ts +1 -0
  2. package/api/index.js +1 -0
  3. package/api/provider/HydratingAPIProvider.d.ts +28 -0
  4. package/api/provider/HydratingAPIProvider.js +82 -0
  5. package/db/cache/CollectionCache.d.ts +1 -7
  6. package/db/cache/CollectionCache.js +3 -9
  7. package/db/cache/DBCache.d.ts +1 -7
  8. package/db/cache/DBCache.js +2 -12
  9. package/db/collection/Collection.d.ts +24 -1
  10. package/db/collection/Collection.js +28 -2
  11. package/db/collection/CollectionItemSchema.d.ts +24 -0
  12. package/db/collection/CollectionItemSchema.js +23 -0
  13. package/db/collection/CollectionItemsSchema.d.ts +25 -0
  14. package/db/collection/CollectionItemsSchema.js +24 -0
  15. package/db/collection/CollectionQueryItemsSchema.d.ts +27 -0
  16. package/db/collection/CollectionQueryItemsSchema.js +25 -0
  17. package/db/collection/CollectionQuerySchema.d.ts +25 -0
  18. package/db/collection/CollectionQuerySchema.js +28 -0
  19. package/db/index.d.ts +4 -1
  20. package/db/index.js +4 -1
  21. package/db/provider/MemoryDBProvider.d.ts +42 -4
  22. package/db/provider/MemoryDBProvider.js +73 -6
  23. package/db/provider/RecordingDBProvider.d.ts +1 -1
  24. package/db/provider/RecordingDBProvider.js +1 -1
  25. package/db/provider/StorageDBProvider.d.ts +1 -1
  26. package/db/provider/StorageDBProvider.js +1 -1
  27. package/db/store/ItemStore.d.ts +6 -4
  28. package/db/store/ItemStore.js +55 -8
  29. package/db/store/QueryStore.d.ts +9 -99
  30. package/db/store/QueryStore.js +55 -260
  31. package/package.json +1 -1
  32. package/react/createDBContext.d.ts +1 -1
  33. package/react/createDBContext.js +1 -1
  34. package/util/query.d.ts +29 -6
  35. package/util/query.js +33 -6
  36. package/db/provider/CacheDBProvider.d.ts +0 -56
  37. 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, 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.
@@ -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: DataSchema<Item<I, T>>;
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, ITEM } from "../../schema/DataSchema.js";
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 = ITEM(id, dataSchema);
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";