shelving 1.311.0 → 1.312.1
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/README.md +7 -0
- package/db/collection/Collection.d.ts +9 -1
- package/db/collection/Collection.js +10 -1
- package/db/collection/CollectionQueryItemsSchema.d.ts +1 -1
- package/db/collection/CollectionQueryItemsSchema.js +1 -1
- package/db/collection/CollectionQuerySchema.d.ts +3 -6
- package/db/collection/CollectionQuerySchema.js +4 -11
- package/db/provider/ValidationDBProvider.d.ts +11 -6
- package/db/provider/ValidationDBProvider.js +33 -28
- package/docs/api/APICache.md +6 -6
- package/docs/api/APIProvider.md +5 -5
- package/docs/api/CachedAPIProvider.md +4 -4
- package/docs/api/Endpoint.md +4 -4
- package/docs/api/EndpointCache.md +6 -6
- package/docs/api.md +26 -26
- package/docs/cloudflare/D1Database.md +3 -3
- package/docs/cloudflare/D1PreparedStatement.md +4 -4
- package/docs/cloudflare/KVNamespace.md +3 -3
- package/docs/cloudflare.md +1 -1
- package/docs/db/Collection.md +3 -1
- package/docs/db/CollectionCache.md +7 -7
- package/docs/db/CollectionQueryItemsSchema.md +1 -1
- package/docs/db/CollectionQuerySchema.md +2 -2
- package/docs/db/DBCache.md +8 -8
- package/docs/db/DBMigrator.md +1 -1
- package/docs/db/DBProvider.md +16 -16
- package/docs/db/MemoryDBProvider.md +4 -4
- package/docs/db/MemoryTable.md +20 -20
- package/docs/db/RecordingDBProvider.md +3 -3
- package/docs/db/SQLMigrator.md +5 -5
- package/docs/db/SQLProvider.md +15 -15
- package/docs/db/ThroughDBProvider.md +1 -1
- package/docs/db/UndoDBProvider.md +1 -1
- package/docs/db/ValidationDBProvider.md +1 -0
- package/docs/db.md +18 -18
- package/docs/error.md +6 -6
- package/docs/extract/DirectoryExtractor.md +1 -0
- package/docs/extract/Extractor.md +1 -1
- package/docs/extract/FileExtractor.md +2 -2
- package/docs/extract/ThroughExtractor.md +1 -1
- package/docs/extract.md +10 -10
- package/docs/firebase.md +4 -4
- package/docs/guides/building-with-shelving.md +707 -0
- package/docs/guides/styleguide.md +287 -0
- package/docs/guides.md +9 -0
- package/docs/index.md +88 -84
- package/docs/llms-full.txt +29196 -27845
- package/docs/llms.txt +61 -56
- package/docs/markup/MarkupParser.md +4 -4
- package/docs/markup/MarkupRule.md +1 -1
- package/docs/markup/Parser.md +1 -1
- package/docs/markup.md +15 -15
- package/docs/react/APIContext.md +2 -2
- package/docs/react/DBContext.md +3 -3
- package/docs/react.md +9 -9
- package/docs/schema/BooleanSchema.md +1 -1
- package/docs/schema/ChoiceSchema.md +2 -2
- package/docs/schema/DataSchema.md +2 -2
- package/docs/schema/DateSchema.md +1 -1
- package/docs/schema/QUERY.md +32 -0
- package/docs/schema/QuerySchema.md +46 -0
- package/docs/schema/QuerySchemaOptions.md +21 -0
- package/docs/schema/Schema.md +2 -2
- package/docs/schema/StringSchema.md +1 -1
- package/docs/schema/ThroughSchema.md +1 -1
- package/docs/schema/UPDATES.md +32 -0
- package/docs/schema/UpdatesSchema.md +45 -0
- package/docs/schema/UpdatesSchemaOptions.md +21 -0
- package/docs/schema/getDataSchemaProp.md +39 -0
- package/docs/schema/getSourceSchema.md +32 -0
- package/docs/schema.md +116 -88
- package/docs/sequence/DeferredSequence.md +9 -9
- package/docs/sequence/LazySequence.md +2 -2
- package/docs/sequence/Sequence.md +3 -3
- package/docs/sequence/ThroughSequence.md +1 -1
- package/docs/sequence.md +2 -2
- package/docs/store/ArrayStore.md +3 -3
- package/docs/store/BooleanStore.md +1 -1
- package/docs/store/DataStore.md +3 -3
- package/docs/store/DictionaryStore.md +5 -5
- package/docs/store/FetchStore.md +2 -2
- package/docs/store/OptionalDataStore.md +5 -5
- package/docs/store/PathStore.md +3 -3
- package/docs/store/Store.md +11 -11
- package/docs/store/URLStore.md +14 -14
- package/docs/store.md +8 -8
- package/docs/test.md +4 -4
- package/docs/ui/Catcher.md +1 -1
- package/docs/ui/DialogsStore.md +1 -1
- package/docs/ui/FormStore.md +3 -3
- package/docs/ui/NavigationStore.md +3 -3
- package/docs/ui/NoticeStore.md +2 -2
- package/docs/ui/NoticesStore.md +1 -1
- package/docs/ui/ValueInputProps.md +1 -1
- package/docs/ui.md +358 -358
- package/docs/util/ansi.md +1 -1
- package/docs/util/array.md +28 -28
- package/docs/util/async.md +13 -13
- package/docs/util/base64.md +6 -6
- package/docs/util/boolean.md +10 -10
- package/docs/util/buffer.md +3 -3
- package/docs/util/bytes.md +4 -4
- package/docs/util/class.md +5 -5
- package/docs/util/color/Color.md +2 -2
- package/docs/util/color.md +4 -4
- package/docs/util/crypto.md +3 -3
- package/docs/util/currency.md +4 -4
- package/docs/util/data.md +9 -9
- package/docs/util/date.md +28 -28
- package/docs/util/debug.md +12 -12
- package/docs/util/dictionary.md +8 -8
- package/docs/util/diff.md +3 -3
- package/docs/util/dispose.md +4 -4
- package/docs/util/duration.md +28 -28
- package/docs/util/element.md +7 -7
- package/docs/util/entity.md +2 -2
- package/docs/util/entry.md +5 -5
- package/docs/util/env.md +4 -4
- package/docs/util/equal.md +22 -22
- package/docs/util/error.md +7 -7
- package/docs/util/file.md +4 -4
- package/docs/util/filter.md +3 -3
- package/docs/util/focus.md +1 -1
- package/docs/util/format.md +16 -16
- package/docs/util/function.md +4 -4
- package/docs/util/geo.md +4 -4
- package/docs/util/hash.md +2 -2
- package/docs/util/http.md +18 -18
- package/docs/util/hydrate.md +2 -2
- package/docs/util/item.md +4 -4
- package/docs/util/iterate.md +12 -12
- package/docs/util/jwt.md +7 -7
- package/docs/util/lazy.md +1 -1
- package/docs/util/link.md +2 -2
- package/docs/util/log.md +3 -3
- package/docs/util/map.md +11 -11
- package/docs/util/merge.md +5 -5
- package/docs/util/null.md +11 -11
- package/docs/util/number.md +17 -17
- package/docs/util/object.md +21 -21
- package/docs/util/path.md +10 -10
- package/docs/util/query.md +13 -13
- package/docs/util/random.md +5 -5
- package/docs/util/regexp/NamedRegExp.md +1 -1
- package/docs/util/regexp/TypedRegExp.md +1 -1
- package/docs/util/regexp.md +16 -16
- package/docs/util/sequence.md +6 -6
- package/docs/util/serialise.md +1 -1
- package/docs/util/set.md +9 -9
- package/docs/util/sort.md +3 -3
- package/docs/util/source.md +2 -2
- package/docs/util/start/Starter.md +2 -2
- package/docs/util/start.md +1 -1
- package/docs/util/string.md +25 -25
- package/docs/util/template.md +7 -7
- package/docs/util/timeout/Timeout.md +2 -2
- package/docs/util/transform.md +8 -8
- package/docs/util/tree.md +2 -2
- package/docs/util/undefined.md +5 -5
- package/docs/util/units/Unit.md +4 -4
- package/docs/util/units/UnitList.md +2 -2
- package/docs/util/update.md +2 -2
- package/docs/util/uri.md +11 -11
- package/docs/util/url.md +11 -11
- package/docs/util/uuid.md +3 -3
- package/docs/util/validate/Validator.md +1 -1
- package/docs/util/validate.md +6 -6
- package/docs/util/xml.md +2 -2
- package/extract/DirectoryExtractor.d.ts +1 -0
- package/extract/DirectoryExtractor.js +3 -0
- package/firebase/FirestoreProvider.d.ts +1 -1
- package/firebase/FirestoreProvider.js +43 -1
- package/package.json +1 -1
- package/schema/DataSchema.d.ts +17 -1
- package/schema/DataSchema.js +18 -1
- package/schema/QuerySchema.d.ts +46 -0
- package/schema/QuerySchema.js +110 -0
- package/schema/ThroughSchema.d.ts +11 -0
- package/schema/ThroughSchema.js +16 -0
- package/schema/UpdatesSchema.d.ts +45 -0
- package/schema/UpdatesSchema.js +88 -0
- package/schema/index.d.ts +2 -0
- package/schema/index.js +2 -0
- package/skills/shelving/SKILL.md +3 -1
- package/util/start.js +1 -1
package/README.md
CHANGED
|
@@ -12,6 +12,13 @@ Full documentation is published at **<https://shelving.cc/>**.
|
|
|
12
12
|
npm install shelving
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
+
## Guides
|
|
16
|
+
|
|
17
|
+
- [Building with Shelving](https://shelving.cc/guides/building-with-shelving): how to lay out a full-stack TypeScript project with Shelving.
|
|
18
|
+
- [Code styleguide](https://shelving.cc/guides/styleguide): how to write code in the Shelving style.
|
|
19
|
+
|
|
20
|
+
The guides are in the [`guides/`](./guides/) folder of this repository. Add a `.md` file there to add a guide to the docs site, `llms.txt`, and the npm package.
|
|
21
|
+
|
|
15
22
|
## For AI agents
|
|
16
23
|
|
|
17
24
|
The docs are also published as Markdown for LLMs and coding agents:
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { DataSchema } from "../../schema/DataSchema.js";
|
|
2
2
|
import { NumberSchema } from "../../schema/NumberSchema.js";
|
|
3
3
|
import type { Schema, Schemas } from "../../schema/Schema.js";
|
|
4
|
+
import { UpdatesSchema } from "../../schema/UpdatesSchema.js";
|
|
4
5
|
import type { ImmutableArray } from "../../util/array.js";
|
|
5
6
|
import type { Data } from "../../util/data.js";
|
|
6
7
|
import type { Identifier, Item, Items, OptionalItem } from "../../util/item.js";
|
|
@@ -19,6 +20,7 @@ export declare const ID: NumberSchema;
|
|
|
19
20
|
*
|
|
20
21
|
* - Pairs a collection name with an identifier schema and a data schema, so providers can validate and address items.
|
|
21
22
|
* - Extends `DataSchema<T>`, so the collection itself validates an item's data, while `.item` validates the complete `id + data` item.
|
|
23
|
+
* - `.updates` validates an `Updates` object for the item data, and `.query` validates a `Query` on the items.
|
|
22
24
|
* - `.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`).
|
|
23
25
|
*
|
|
24
26
|
* @example
|
|
@@ -53,7 +55,13 @@ export declare class Collection<N extends string = string, I extends Identifier
|
|
|
53
55
|
*/
|
|
54
56
|
readonly items: CollectionItemsSchema<I, T>;
|
|
55
57
|
/**
|
|
56
|
-
* Schema for a
|
|
58
|
+
* Schema for a set of updates to the data of an item.
|
|
59
|
+
*
|
|
60
|
+
* @see https://shelving.cc/db/Collection/updates
|
|
61
|
+
*/
|
|
62
|
+
readonly updates: UpdatesSchema<T>;
|
|
63
|
+
/**
|
|
64
|
+
* Schema for a query on the items.
|
|
57
65
|
*
|
|
58
66
|
* @see https://shelving.cc/db/Collection/query
|
|
59
67
|
*/
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { DataSchema } from "../../schema/DataSchema.js";
|
|
2
2
|
import { NumberSchema } from "../../schema/NumberSchema.js";
|
|
3
|
+
import { UpdatesSchema } from "../../schema/UpdatesSchema.js";
|
|
3
4
|
import { CollectionItemSchema } from "./CollectionItemSchema.js";
|
|
4
5
|
import { CollectionItemsSchema } from "./CollectionItemsSchema.js";
|
|
5
6
|
import { CollectionQueryItemsSchema } from "./CollectionQueryItemsSchema.js";
|
|
@@ -22,6 +23,7 @@ export const ID = new NumberSchema({
|
|
|
22
23
|
*
|
|
23
24
|
* - Pairs a collection name with an identifier schema and a data schema, so providers can validate and address items.
|
|
24
25
|
* - Extends `DataSchema<T>`, so the collection itself validates an item's data, while `.item` validates the complete `id + data` item.
|
|
26
|
+
* - `.updates` validates an `Updates` object for the item data, and `.query` validates a `Query` on the items.
|
|
25
27
|
* - `.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`).
|
|
26
28
|
*
|
|
27
29
|
* @example
|
|
@@ -56,7 +58,13 @@ export class Collection extends DataSchema {
|
|
|
56
58
|
*/
|
|
57
59
|
items;
|
|
58
60
|
/**
|
|
59
|
-
* Schema for a
|
|
61
|
+
* Schema for a set of updates to the data of an item.
|
|
62
|
+
*
|
|
63
|
+
* @see https://shelving.cc/db/Collection/updates
|
|
64
|
+
*/
|
|
65
|
+
updates;
|
|
66
|
+
/**
|
|
67
|
+
* Schema for a query on the items.
|
|
60
68
|
*
|
|
61
69
|
* @see https://shelving.cc/db/Collection/query
|
|
62
70
|
*/
|
|
@@ -74,6 +82,7 @@ export class Collection extends DataSchema {
|
|
|
74
82
|
this.id = id;
|
|
75
83
|
this.item = new CollectionItemSchema(this);
|
|
76
84
|
this.items = new CollectionItemsSchema(this);
|
|
85
|
+
this.updates = new UpdatesSchema({ data: this });
|
|
77
86
|
this.query = new CollectionQuerySchema(this);
|
|
78
87
|
this.queryItems = new CollectionQueryItemsSchema(this);
|
|
79
88
|
}
|
|
@@ -8,7 +8,7 @@ import type { Collection } from "./Collection.js";
|
|
|
8
8
|
* Schema for `QueryItems` of a `Collection`, i.e. a query and the complete list of items that answer it.
|
|
9
9
|
*
|
|
10
10
|
* - Built by `Collection` as `Collection.queryItems`, from `Collection.query` and `Collection.items`. Use that instance, and do not make your own.
|
|
11
|
-
* -
|
|
11
|
+
* - The `query` is validated in full by `Collection.query`, and the `items` by `Collection.items`.
|
|
12
12
|
* - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
|
|
13
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
14
|
* - Only use it when `items` is the complete answer to `query` (with its `$limit`).
|
|
@@ -3,7 +3,7 @@ import { DataSchema } from "../../schema/DataSchema.js";
|
|
|
3
3
|
* Schema for `QueryItems` of a `Collection`, i.e. a query and the complete list of items that answer it.
|
|
4
4
|
*
|
|
5
5
|
* - Built by `Collection` as `Collection.queryItems`, from `Collection.query` and `Collection.items`. Use that instance, and do not make your own.
|
|
6
|
-
* -
|
|
6
|
+
* - The `query` is validated in full by `Collection.query`, and the `items` by `Collection.items`.
|
|
7
7
|
* - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
|
|
8
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
9
|
* - Only use it when `items` is the complete answer to `query` (with its `$limit`).
|
|
@@ -1,25 +1,22 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { QuerySchema } from "../../schema/QuerySchema.js";
|
|
2
2
|
import type { Data } from "../../util/data.js";
|
|
3
3
|
import type { Identifier, Item } from "../../util/item.js";
|
|
4
|
-
import type { Query } from "../../util/query.js";
|
|
5
4
|
import type { Sourceable } from "../../util/source.js";
|
|
6
5
|
import type { Collection } from "./Collection.js";
|
|
7
6
|
/**
|
|
8
7
|
* Schema for a `Query` on the items of a `Collection`.
|
|
9
8
|
*
|
|
10
9
|
* - Built by `Collection` as `Collection.query`. Use that instance, and do not make your own.
|
|
11
|
-
* -
|
|
10
|
+
* - Validates the query in full against `Collection.item` (see `QuerySchema`), so a query from outside (e.g. an API request or response) can be trusted. Filter and `$order` keys can use `id` and any prop path of the collection.
|
|
12
11
|
* - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
|
|
13
12
|
*
|
|
14
13
|
* @see https://shelving.cc/db/CollectionQuerySchema
|
|
15
14
|
*/
|
|
16
|
-
export declare class CollectionQuerySchema<I extends Identifier = Identifier, T extends Data = Data> extends
|
|
15
|
+
export declare class CollectionQuerySchema<I extends Identifier = Identifier, T extends Data = Data> extends QuerySchema<Item<I, T>> implements Sourceable<Collection<string, I, T>> {
|
|
17
16
|
/**
|
|
18
17
|
* The collection this schema validates queries for.
|
|
19
18
|
* @see https://shelving.cc/db/CollectionQuerySchema/source
|
|
20
19
|
*/
|
|
21
20
|
readonly source: Collection<string, I, T>;
|
|
22
21
|
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
22
|
}
|
|
@@ -1,28 +1,21 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { isData } from "../../util/data.js";
|
|
1
|
+
import { QuerySchema } from "../../schema/QuerySchema.js";
|
|
3
2
|
/**
|
|
4
3
|
* Schema for a `Query` on the items of a `Collection`.
|
|
5
4
|
*
|
|
6
5
|
* - Built by `Collection` as `Collection.query`. Use that instance, and do not make your own.
|
|
7
|
-
* -
|
|
6
|
+
* - Validates the query in full against `Collection.item` (see `QuerySchema`), so a query from outside (e.g. an API request or response) can be trusted. Filter and `$order` keys can use `id` and any prop path of the collection.
|
|
8
7
|
* - Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
|
|
9
8
|
*
|
|
10
9
|
* @see https://shelving.cc/db/CollectionQuerySchema
|
|
11
10
|
*/
|
|
12
|
-
export class CollectionQuerySchema extends
|
|
11
|
+
export class CollectionQuerySchema extends QuerySchema {
|
|
13
12
|
/**
|
|
14
13
|
* The collection this schema validates queries for.
|
|
15
14
|
* @see https://shelving.cc/db/CollectionQuerySchema/source
|
|
16
15
|
*/
|
|
17
16
|
source;
|
|
18
17
|
constructor(collection) {
|
|
19
|
-
super({
|
|
18
|
+
super({ data: collection.item });
|
|
20
19
|
this.source = collection;
|
|
21
20
|
}
|
|
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
21
|
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { Data } from "../../util/data.js";
|
|
2
2
|
import type { Identifier, Item, Items, ItemsSequence, OptionalItem, OptionalItemSequence } from "../../util/item.js";
|
|
3
3
|
import type { Query } from "../../util/query.js";
|
|
4
|
-
import {
|
|
4
|
+
import type { Updates } from "../../util/update.js";
|
|
5
5
|
import type { Collection } from "../collection/Collection.js";
|
|
6
6
|
import { ThroughDBProvider } from "./ThroughDBProvider.js";
|
|
7
7
|
/**
|
|
@@ -9,6 +9,7 @@ import { ThroughDBProvider } from "./ThroughDBProvider.js";
|
|
|
9
9
|
*
|
|
10
10
|
* - Wraps a `source` provider (which may have any type, because validation guarantees the type) and runs every value through the relevant `Collection` schema before writing and after reading.
|
|
11
11
|
* - Written data is validated against the collection's data schema; read data is validated against the item schema, so trusted, correctly-typed values reach the rest of the app.
|
|
12
|
+
* - Updates are validated with `Collection.updates`, and every query with `Collection.query`, so an unknown key or a bad value never reaches the source.
|
|
12
13
|
* - Validation failures here are program-state errors, so they throw a typed `ValueError` rather than a raw validation `string`.
|
|
13
14
|
* - Applies inside `transact()` too — the transaction provider the callback receives validates its reads and writes the same way.
|
|
14
15
|
*
|
|
@@ -25,21 +26,25 @@ export declare class ValidationDBProvider<I extends Identifier, T extends Data>
|
|
|
25
26
|
setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
|
|
26
27
|
/** Validate the updates before writing; throws `ValueError` if they fail the collection schema. */
|
|
27
28
|
updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
|
|
29
|
+
/** Validate the query before reading; throws `ValueError` if it fails the collection schema. */
|
|
28
30
|
countQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<number>;
|
|
29
|
-
/** Validate the items after
|
|
31
|
+
/** Validate the query before reading and the items after; throws `ValueError` if either fails the collection schema. */
|
|
30
32
|
getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
|
|
31
|
-
/** Validate each emitted result; throws `ValueError` if
|
|
33
|
+
/** Validate the query before reading and each emitted result; throws `ValueError` if either fails the collection schema. */
|
|
32
34
|
getQuerySequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
|
|
33
35
|
/**
|
|
34
|
-
* Validate the data before writing; throws `ValueError` if
|
|
36
|
+
* Validate the query and data before writing; throws `ValueError` if they fail the collection schema.
|
|
35
37
|
* - Passthrough, not two-step: validation applies to the query write's own inputs up front, so per-item routing adds nothing — pass through to keep the source's native query write.
|
|
36
38
|
*/
|
|
37
39
|
setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
|
|
38
40
|
/**
|
|
39
|
-
* Validate the updates before writing; throws `ValueError` if they fail the collection schema.
|
|
41
|
+
* Validate the query and updates before writing; throws `ValueError` if they fail the collection schema.
|
|
40
42
|
* - Passthrough, not two-step: validation applies to the query write's own inputs up front, so per-item routing adds nothing — pass through to keep the source's native query write.
|
|
41
43
|
*/
|
|
42
44
|
updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
|
|
43
|
-
/**
|
|
45
|
+
/**
|
|
46
|
+
* Validate the query before writing; throws `ValueError` if it fails the collection schema.
|
|
47
|
+
* - Passthrough, not two-step: there are no inputs to validate per item, so keep the source's native query write.
|
|
48
|
+
*/
|
|
44
49
|
deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
|
|
45
50
|
}
|
|
@@ -1,13 +1,12 @@
|
|
|
1
1
|
import { ValueError } from "../../error/ValueError.js";
|
|
2
|
-
import { PARTIAL } from "../../schema/DataSchema.js";
|
|
3
2
|
import { getNamedMessage } from "../../util/error.js";
|
|
4
|
-
import { getUpdates } from "../../util/update.js";
|
|
5
3
|
import { ThroughDBProvider } from "./ThroughDBProvider.js";
|
|
6
4
|
/**
|
|
7
5
|
* Database provider that validates data flowing to and from an asynchronous source provider.
|
|
8
6
|
*
|
|
9
7
|
* - Wraps a `source` provider (which may have any type, because validation guarantees the type) and runs every value through the relevant `Collection` schema before writing and after reading.
|
|
10
8
|
* - Written data is validated against the collection's data schema; read data is validated against the item schema, so trusted, correctly-typed values reach the rest of the app.
|
|
9
|
+
* - Updates are validated with `Collection.updates`, and every query with `Collection.query`, so an unknown key or a bad value never reaches the source.
|
|
11
10
|
* - Validation failures here are program-state errors, so they throw a typed `ValueError` rather than a raw validation `string`.
|
|
12
11
|
* - Applies inside `transact()` too — the transaction provider the callback receives validates its reads and writes the same way.
|
|
13
12
|
*
|
|
@@ -35,35 +34,40 @@ export class ValidationDBProvider extends ThroughDBProvider {
|
|
|
35
34
|
updateItem(collection, id, updates) {
|
|
36
35
|
return super.updateItem(collection, id, _validateUpdates(collection, updates, this.updateItem));
|
|
37
36
|
}
|
|
37
|
+
/** Validate the query before reading; throws `ValueError` if it fails the collection schema. */
|
|
38
38
|
countQuery(collection, query) {
|
|
39
|
-
return super.countQuery(collection, query);
|
|
39
|
+
return super.countQuery(collection, _validateQuery(collection, query, this.countQuery));
|
|
40
40
|
}
|
|
41
|
-
/** Validate the items after
|
|
41
|
+
/** Validate the query before reading and the items after; throws `ValueError` if either fails the collection schema. */
|
|
42
42
|
async getQuery(collection, query) {
|
|
43
|
-
return _validateItems(collection, await super.getQuery(collection, query), this.getQuery);
|
|
43
|
+
return _validateItems(collection, await super.getQuery(collection, _validateQuery(collection, query, this.getQuery)), this.getQuery);
|
|
44
44
|
}
|
|
45
|
-
/** Validate each emitted result; throws `ValueError` if
|
|
45
|
+
/** Validate the query before reading and each emitted result; throws `ValueError` if either fails the collection schema. */
|
|
46
46
|
async *getQuerySequence(collection, query) {
|
|
47
|
-
|
|
47
|
+
const valid = _validateQuery(collection, query, this.getQuerySequence);
|
|
48
|
+
for await (const items of super.getQuerySequence(collection, valid))
|
|
48
49
|
yield _validateItems(collection, items, this.getQuerySequence);
|
|
49
50
|
}
|
|
50
51
|
/**
|
|
51
|
-
* Validate the data before writing; throws `ValueError` if
|
|
52
|
+
* Validate the query and data before writing; throws `ValueError` if they fail the collection schema.
|
|
52
53
|
* - Passthrough, not two-step: validation applies to the query write's own inputs up front, so per-item routing adds nothing — pass through to keep the source's native query write.
|
|
53
54
|
*/
|
|
54
55
|
setQuery(collection, query, data) {
|
|
55
|
-
return this.source.setQuery(collection, query, collection.validate(data));
|
|
56
|
+
return this.source.setQuery(collection, _validateQuery(collection, query, this.setQuery), collection.validate(data));
|
|
56
57
|
}
|
|
57
58
|
/**
|
|
58
|
-
* Validate the updates before writing; throws `ValueError` if they fail the collection schema.
|
|
59
|
+
* Validate the query and updates before writing; throws `ValueError` if they fail the collection schema.
|
|
59
60
|
* - Passthrough, not two-step: validation applies to the query write's own inputs up front, so per-item routing adds nothing — pass through to keep the source's native query write.
|
|
60
61
|
*/
|
|
61
62
|
updateQuery(collection, query, updates) {
|
|
62
|
-
return this.source.updateQuery(collection, query, _validateUpdates(collection, updates, this.updateQuery));
|
|
63
|
+
return this.source.updateQuery(collection, _validateQuery(collection, query, this.updateQuery), _validateUpdates(collection, updates, this.updateQuery));
|
|
63
64
|
}
|
|
64
|
-
/**
|
|
65
|
+
/**
|
|
66
|
+
* Validate the query before writing; throws `ValueError` if it fails the collection schema.
|
|
67
|
+
* - Passthrough, not two-step: there are no inputs to validate per item, so keep the source's native query write.
|
|
68
|
+
*/
|
|
65
69
|
deleteQuery(collection, query) {
|
|
66
|
-
return this.source.deleteQuery(collection, query);
|
|
70
|
+
return this.source.deleteQuery(collection, _validateQuery(collection, query, this.deleteQuery));
|
|
67
71
|
}
|
|
68
72
|
}
|
|
69
73
|
/**
|
|
@@ -113,20 +117,13 @@ function* _yieldValidItems(collection, items, caller) {
|
|
|
113
117
|
if (messages.length)
|
|
114
118
|
throw new ValueError(`Invalid data for "${collection}"\n${messages.join("\n")}`, { received: items, caller });
|
|
115
119
|
}
|
|
120
|
+
/**
|
|
121
|
+
* Validate a set of updates for a collection.
|
|
122
|
+
* @throws `ValueError` if the updates do not validate (conflict because the program is not in an expected state).
|
|
123
|
+
*/
|
|
116
124
|
function _validateUpdates(collection, updates, caller) {
|
|
117
|
-
// Only a plain top-level key is a prop of the data schema. An encoded key (`+=num`, `+[]tags`, `=a.b`) or a path (`a.b`)
|
|
118
|
-
// is not, so the schema would strip it: keep it as it is. `getUpdates()` throws if a sum is not a number.
|
|
119
|
-
const plain = {};
|
|
120
|
-
const encoded = {};
|
|
121
|
-
for (const [key, value] of Object.entries(updates)) {
|
|
122
|
-
if (_isPlainKey(key))
|
|
123
|
-
plain[key] = value;
|
|
124
|
-
else
|
|
125
|
-
encoded[key] = value;
|
|
126
|
-
}
|
|
127
|
-
getUpdates(encoded);
|
|
128
125
|
try {
|
|
129
|
-
return
|
|
126
|
+
return collection.updates.validate(updates);
|
|
130
127
|
}
|
|
131
128
|
catch (thrown) {
|
|
132
129
|
if (typeof thrown !== "string")
|
|
@@ -134,7 +131,15 @@ function _validateUpdates(collection, updates, caller) {
|
|
|
134
131
|
throw new ValueError(`Invalid updates for "${collection}"\n${thrown}`, { received: updates, caller });
|
|
135
132
|
}
|
|
136
133
|
}
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
134
|
+
function _validateQuery(collection, query, caller) {
|
|
135
|
+
if (!query)
|
|
136
|
+
return undefined;
|
|
137
|
+
try {
|
|
138
|
+
return collection.query.validate(query);
|
|
139
|
+
}
|
|
140
|
+
catch (thrown) {
|
|
141
|
+
if (typeof thrown !== "string")
|
|
142
|
+
throw thrown;
|
|
143
|
+
throw new ValueError(`Invalid query for "${collection}"\n${thrown}`, { received: query, caller });
|
|
144
|
+
}
|
|
140
145
|
}
|
package/docs/api/APICache.md
CHANGED
|
@@ -41,9 +41,9 @@ const user = await cache.call(getUser, { id: "abc" });
|
|
|
41
41
|
|
|
42
42
|
## Methods
|
|
43
43
|
|
|
44
|
-
- [get](APICache/get.md): Get (or create) the EndpointCache for the given endpoint.
|
|
45
|
-
- [call](APICache/call.md): Fetch (or return a cached result) for the given endpoint and payload.
|
|
46
|
-
- [invalidate](APICache/invalidate.md): Invalidate a specific store for an endpoint so the next read refetches.
|
|
47
|
-
- [invalidateAll](APICache/invalidateAll.md): Invalidate all stores for an endpoint so the next read of any payload refetches.
|
|
48
|
-
- [refresh](APICache/refresh.md): Trigger a refetch on a specific store for an endpoint.
|
|
49
|
-
- [refreshAll](APICache/refreshAll.md): Trigger a refetch on all stores for an endpoint.
|
|
44
|
+
- [APICache.get()](APICache/get.md): Get (or create) the EndpointCache for the given endpoint.
|
|
45
|
+
- [APICache.call()](APICache/call.md): Fetch (or return a cached result) for the given endpoint and payload.
|
|
46
|
+
- [APICache.invalidate()](APICache/invalidate.md): Invalidate a specific store for an endpoint so the next read refetches.
|
|
47
|
+
- [APICache.invalidateAll()](APICache/invalidateAll.md): Invalidate all stores for an endpoint so the next read of any payload refetches.
|
|
48
|
+
- [APICache.refresh()](APICache/refresh.md): Trigger a refetch on a specific store for an endpoint.
|
|
49
|
+
- [APICache.refreshAll()](APICache/refreshAll.md): Trigger a refetch on all stores for an endpoint.
|
package/docs/api/APIProvider.md
CHANGED
|
@@ -45,8 +45,8 @@ new APIProvider<P, R>()
|
|
|
45
45
|
|
|
46
46
|
## Methods
|
|
47
47
|
|
|
48
|
-
- [renderURL](APIProvider/renderURL.md): Render the full final URL for an API request to a given endpoint with a given payload.
|
|
49
|
-
- [createRequest](APIProvider/createRequest.md): Create a Request that targets this endpoint with a given base URL.
|
|
50
|
-
- [fetch](APIProvider/fetch.md): Send a Request and return its Response (defaults to the JavaScript fetch() API).
|
|
51
|
-
- [parseResponse](APIProvider/parseResponse.md): Parse an HTTP Response for this endpoint into a result value.
|
|
52
|
-
- [call](APIProvider/call.md): Send a payload to an Endpoint and retrieve the parsed result.
|
|
48
|
+
- [APIProvider.renderURL()](APIProvider/renderURL.md): Render the full final URL for an API request to a given endpoint with a given payload.
|
|
49
|
+
- [APIProvider.createRequest()](APIProvider/createRequest.md): Create a Request that targets this endpoint with a given base URL.
|
|
50
|
+
- [APIProvider.fetch()](APIProvider/fetch.md): Send a Request and return its Response (defaults to the JavaScript fetch() API).
|
|
51
|
+
- [APIProvider.parseResponse()](APIProvider/parseResponse.md): Parse an HTTP Response for this endpoint into a result value.
|
|
52
|
+
- [APIProvider.call()](APIProvider/call.md): Send a payload to an Endpoint and retrieve the parsed result.
|
|
@@ -59,7 +59,7 @@ new CachedAPIProvider<P, R>(source: APIProvider<P, R>, maxAge: number = AVOID_RE
|
|
|
59
59
|
|
|
60
60
|
## Methods
|
|
61
61
|
|
|
62
|
-
- [invalidate](CachedAPIProvider/invalidate.md): Invalidate the cached result for a specific endpoint and payload.
|
|
63
|
-
- [invalidateAll](CachedAPIProvider/invalidateAll.md): Invalidate every cached result for an endpoint, across all payloads.
|
|
64
|
-
- [refresh](CachedAPIProvider/refresh.md): Refresh the cached result for a specific endpoint and payload.
|
|
65
|
-
- [refreshAll](CachedAPIProvider/refreshAll.md): Refresh every cached result for an endpoint, across all payloads.
|
|
62
|
+
- [CachedAPIProvider.invalidate()](CachedAPIProvider/invalidate.md): Invalidate the cached result for a specific endpoint and payload.
|
|
63
|
+
- [CachedAPIProvider.invalidateAll()](CachedAPIProvider/invalidateAll.md): Invalidate every cached result for an endpoint, across all payloads.
|
|
64
|
+
- [CachedAPIProvider.refresh()](CachedAPIProvider/refresh.md): Refresh the cached result for a specific endpoint and payload.
|
|
65
|
+
- [CachedAPIProvider.refreshAll()](CachedAPIProvider/refreshAll.md): Refresh every cached result for an endpoint, across all payloads.
|
package/docs/api/Endpoint.md
CHANGED
|
@@ -46,7 +46,7 @@ const getUser = new Endpoint("GET", "/users/{id}", USER_PAYLOAD, USER_RESULT);
|
|
|
46
46
|
|
|
47
47
|
## Methods
|
|
48
48
|
|
|
49
|
-
- [renderPath](Endpoint/renderPath.md): Render the path for this endpoint with the given payload.
|
|
50
|
-
- [match](Endpoint/match.md): Match a method/path pair against this endpoint and return any matched {placeholder} params.
|
|
51
|
-
- [handler](Endpoint/handler.md): Create an endpoint handler pairing for this endpoint.
|
|
52
|
-
- [toString](Endpoint/toString.md): Convert this endpoint to a string in METHOD /path form, e.g. GET /user/{id}
|
|
49
|
+
- [Endpoint.renderPath()](Endpoint/renderPath.md): Render the path for this endpoint with the given payload.
|
|
50
|
+
- [Endpoint.match()](Endpoint/match.md): Match a method/path pair against this endpoint and return any matched {placeholder} params.
|
|
51
|
+
- [Endpoint.handler()](Endpoint/handler.md): Create an endpoint handler pairing for this endpoint.
|
|
52
|
+
- [Endpoint.toString()](Endpoint/toString.md): Convert this endpoint to a string in METHOD /path form, e.g. GET /user/{id}
|
|
@@ -43,9 +43,9 @@ const user = await cache.call({ id: "abc" });
|
|
|
43
43
|
|
|
44
44
|
## Methods
|
|
45
45
|
|
|
46
|
-
- [get](EndpointCache/get.md): Get (or create) the EndpointStore for the given payload.
|
|
47
|
-
- [call](EndpointCache/call.md): Fetch (or return a cached result) for the given payload.
|
|
48
|
-
- [invalidate](EndpointCache/invalidate.md): Invalidate a specific store so the next read refetches.
|
|
49
|
-
- [invalidateAll](EndpointCache/invalidateAll.md): Invalidate all stores so the next read of any payload refetches.
|
|
50
|
-
- [refresh](EndpointCache/refresh.md): Trigger a refetch on a specific store.
|
|
51
|
-
- [refreshAll](EndpointCache/refreshAll.md): Trigger a refetch on all stores.
|
|
46
|
+
- [EndpointCache.get()](EndpointCache/get.md): Get (or create) the EndpointStore for the given payload.
|
|
47
|
+
- [EndpointCache.call()](EndpointCache/call.md): Fetch (or return a cached result) for the given payload.
|
|
48
|
+
- [EndpointCache.invalidate()](EndpointCache/invalidate.md): Invalidate a specific store so the next read refetches.
|
|
49
|
+
- [EndpointCache.invalidateAll()](EndpointCache/invalidateAll.md): Invalidate all stores so the next read of any payload refetches.
|
|
50
|
+
- [EndpointCache.refresh()](EndpointCache/refresh.md): Trigger a refetch on a specific store.
|
|
51
|
+
- [EndpointCache.refreshAll()](EndpointCache/refreshAll.md): Trigger a refetch on all stores.
|
package/docs/api.md
CHANGED
|
@@ -123,47 +123,47 @@ See the `shelving/react` module for full usage.
|
|
|
123
123
|
|
|
124
124
|
## Functions
|
|
125
125
|
|
|
126
|
-
- [
|
|
127
|
-
- [
|
|
128
|
-
- [
|
|
129
|
-
- [
|
|
130
|
-
- [
|
|
131
|
-
- [
|
|
132
|
-
- [
|
|
126
|
+
- [HEAD()](api/HEAD.md): Define a HEAD endpoint at a path, with validated payload and result types.
|
|
127
|
+
- [GET()](api/GET.md): Define a GET endpoint at a path, with validated payload and result types.
|
|
128
|
+
- [POST()](api/POST.md): Define a POST endpoint at a path, with validated payload and result types.
|
|
129
|
+
- [PUT()](api/PUT.md): Define a PUT endpoint at a path, with validated payload and result types.
|
|
130
|
+
- [PATCH()](api/PATCH.md): Define a PATCH endpoint at a path, with validated payload and result types.
|
|
131
|
+
- [DELETE()](api/DELETE.md): Define a DELETE endpoint at a path, with validated payload and result types.
|
|
132
|
+
- [handleEndpoints()](api/handleEndpoints.md): Handle a Request with the first matching endpoint handler after stripping any base-path prefix from the request pathname.
|
|
133
133
|
|
|
134
134
|
## Classes
|
|
135
135
|
|
|
136
|
-
- [
|
|
137
|
-
- [
|
|
138
|
-
- [
|
|
139
|
-
- [
|
|
140
|
-
- [
|
|
136
|
+
- [APICache](api/APICache.md): Cache of EndpointCache objects keyed by Endpoint, providing memoised API results across many endpoints.
|
|
137
|
+
- [EndpointCache](api/EndpointCache.md): Cache of EndpointStore objects for a single endpoint, keyed by the rendered request URL of each payload.
|
|
138
|
+
- [Endpoint](api/Endpoint.md): A typed API resource definition pairing a method and path with payload and result schemas.
|
|
139
|
+
- [APIProvider](api/APIProvider.md): Abstract base for API providers that send requests to a set of Endpoint definitions rooted at a common base URL.
|
|
140
|
+
- [CachedAPIProvider](api/CachedAPIProvider.md): API provider wrapper that serves requests through an APICache so repeated calls reuse cached results.
|
|
141
|
+
- [ClientAPIProvider](api/ClientAPIProvider.md): A client-side API provider that sends requests over the network using fetch().
|
|
141
142
|
- [DebugAPIProvider](api/DebugAPIProvider.md): Provider that logs every request, response, and error to the console in detail to help diagnose issues in development.
|
|
142
|
-
- [LoggingAPIProvider](api/LoggingAPIProvider.md): Provider that logs fetches to the console to keep useful request/response logs in production.
|
|
143
143
|
- [HydratingAPIProvider](api/HydratingAPIProvider.md): API provider that validates every result, then writes the collection items in it into a local database.
|
|
144
|
+
- [JSONAPIProvider](api/JSONAPIProvider.md): Client API provider that always sends request bodies as JSON and parses responses as JSON.
|
|
145
|
+
- [LoggingAPIProvider](api/LoggingAPIProvider.md): Provider that logs fetches to the console to keep useful request/response logs in production.
|
|
144
146
|
- [MockAPIProvider](api/MockAPIProvider.md): Provider that records API calls and serves them from a handler without sending network requests.
|
|
145
|
-
- [CachedAPIProvider](api/CachedAPIProvider.md): API provider wrapper that serves requests through an APICache so repeated calls reuse cached results.
|
|
146
147
|
- [MockEndpointAPIProvider](api/MockEndpointAPIProvider.md): Provider that mocks an API that calls and matches an array of EndpointHandler objects returned from Endpoint.handler()
|
|
147
|
-
- [
|
|
148
|
-
- [
|
|
149
|
-
- [
|
|
150
|
-
- [
|
|
151
|
-
- [EndpointCache](api/EndpointCache.md): Cache of EndpointStore objects for a single endpoint, keyed by the rendered request URL of each payload.
|
|
148
|
+
- [ThroughAPIProvider](api/ThroughAPIProvider.md): Provider wrapper that delegates every API operation to a wrapped source provider.
|
|
149
|
+
- [ValidationAPIProvider](api/ValidationAPIProvider.md): Provider that validates payloads and results against the endpoint's schemas, so a source of any type is made type-safe.
|
|
150
|
+
- [XMLAPIProvider](api/XMLAPIProvider.md): Client API provider that always sends request bodies as XML and parses responses as plain text.
|
|
151
|
+
- [EndpointStore](api/EndpointStore.md): Store that loads and tracks the result of calling a single API endpoint with a fixed payload, through an APIProvider.
|
|
152
152
|
|
|
153
153
|
## Interfaces
|
|
154
154
|
|
|
155
|
-
- [ClientAPIProviderOptions](api/ClientAPIProviderOptions.md): Options for constructing a ClientAPIProvider.
|
|
156
155
|
- [EndpointHandler](api/EndpointHandler.md): A typed endpoint definition paired with its implementation callback.
|
|
156
|
+
- [ClientAPIProviderOptions](api/ClientAPIProviderOptions.md): Options for constructing a ClientAPIProvider.
|
|
157
157
|
|
|
158
158
|
## Types
|
|
159
159
|
|
|
160
|
-
- [MockAPIFetchCall](api/MockAPIFetchCall.md): Record of a single mocked fetch, pairing the request with the response the handler returned.
|
|
161
|
-
- [MockAPIRequestCall](api/MockAPIRequestCall.md): Record of a single request build, capturing the endpoint, payload, options, and built request.
|
|
162
|
-
- [MockAPIResponseCall](api/MockAPIResponseCall.md): Record of a single response parse, capturing the endpoint, response, and parsed result.
|
|
163
|
-
- [EndpointCallback](api/EndpointCallback.md): A function that handles an endpoint request, receiving a validated payload and returning a result.
|
|
164
|
-
- [AnyEndpointHandler](api/AnyEndpointHandler.md): An EndpointHandler with any payload and result type, for use where the specific types don't matter.
|
|
165
|
-
- [EndpointHandlers](api/EndpointHandlers.md): A collection of endpoint handlers that can be matched and invoked by handleEndpoints().
|
|
166
160
|
- [AnyEndpoint](api/AnyEndpoint.md): An Endpoint with any payload and result type, for use where the specific types don't matter.
|
|
167
161
|
- [Endpoints](api/Endpoints.md): An immutable list of endpoints.
|
|
168
162
|
- [PayloadType](api/PayloadType.md): Extract the payload type from an Endpoint.
|
|
169
163
|
- [EndpointType](api/EndpointType.md): Extract the result type from an Endpoint.
|
|
164
|
+
- [EndpointCallback](api/EndpointCallback.md): A function that handles an endpoint request, receiving a validated payload and returning a result.
|
|
165
|
+
- [AnyEndpointHandler](api/AnyEndpointHandler.md): An EndpointHandler with any payload and result type, for use where the specific types don't matter.
|
|
166
|
+
- [EndpointHandlers](api/EndpointHandlers.md): A collection of endpoint handlers that can be matched and invoked by handleEndpoints().
|
|
167
|
+
- [MockAPIFetchCall](api/MockAPIFetchCall.md): Record of a single mocked fetch, pairing the request with the response the handler returned.
|
|
168
|
+
- [MockAPIRequestCall](api/MockAPIRequestCall.md): Record of a single request build, capturing the endpoint, payload, options, and built request.
|
|
169
|
+
- [MockAPIResponseCall](api/MockAPIResponseCall.md): Record of a single response parse, capturing the endpoint, response, and parsed result.
|
|
@@ -21,6 +21,6 @@ Declares only the subset of the D1 binding API the provider needs, so the `@clou
|
|
|
21
21
|
|
|
22
22
|
## Methods
|
|
23
23
|
|
|
24
|
-
- [batch](D1Database/batch.md)
|
|
25
|
-
- [exec](D1Database/exec.md)
|
|
26
|
-
- [prepare](D1Database/prepare.md)
|
|
24
|
+
- [D1Database.batch()](D1Database/batch.md)
|
|
25
|
+
- [D1Database.exec()](D1Database/exec.md)
|
|
26
|
+
- [D1Database.prepare()](D1Database/prepare.md)
|
|
@@ -20,7 +20,7 @@ Declares only the subset of the D1 prepared-statement API used by `CloudflareD1P
|
|
|
20
20
|
|
|
21
21
|
## Methods
|
|
22
22
|
|
|
23
|
-
- [bind](D1PreparedStatement/bind.md)
|
|
24
|
-
- [first](D1PreparedStatement/first.md)
|
|
25
|
-
- [raw](D1PreparedStatement/raw.md)
|
|
26
|
-
- [run](D1PreparedStatement/run.md)
|
|
23
|
+
- [D1PreparedStatement.bind()](D1PreparedStatement/bind.md)
|
|
24
|
+
- [D1PreparedStatement.first()](D1PreparedStatement/first.md)
|
|
25
|
+
- [D1PreparedStatement.raw()](D1PreparedStatement/raw.md)
|
|
26
|
+
- [D1PreparedStatement.run()](D1PreparedStatement/run.md)
|
|
@@ -19,6 +19,6 @@ Declares only the subset of methods `CloudflareKVProvider` uses, so the `@cloudf
|
|
|
19
19
|
|
|
20
20
|
## Methods
|
|
21
21
|
|
|
22
|
-
- [get](KVNamespace/get.md)
|
|
23
|
-
- [put](KVNamespace/put.md)
|
|
24
|
-
- [delete](KVNamespace/delete.md)
|
|
22
|
+
- [KVNamespace.get()](KVNamespace/get.md)
|
|
23
|
+
- [KVNamespace.put()](KVNamespace/put.md)
|
|
24
|
+
- [KVNamespace.delete()](KVNamespace/delete.md)
|
package/docs/cloudflare.md
CHANGED
|
@@ -79,8 +79,8 @@ export default {
|
|
|
79
79
|
|
|
80
80
|
## Classes
|
|
81
81
|
|
|
82
|
-
- [CloudflareKVProvider](cloudflare/CloudflareKVProvider.md): Cloudflare Workers KV database provider.
|
|
83
82
|
- [CloudflareD1Provider](cloudflare/CloudflareD1Provider.md): SQLite database provider backed by Cloudflare D1.
|
|
83
|
+
- [CloudflareKVProvider](cloudflare/CloudflareKVProvider.md): Cloudflare Workers KV database provider.
|
|
84
84
|
|
|
85
85
|
## Interfaces
|
|
86
86
|
|
package/docs/db/Collection.md
CHANGED
|
@@ -8,6 +8,7 @@ Declarative definition of a database collection/table.
|
|
|
8
8
|
|
|
9
9
|
- Pairs a collection name with an identifier schema and a data schema, so providers can validate and address items.
|
|
10
10
|
- Extends `DataSchema<T>`, so the collection itself validates an item's data, while `.item` validates the complete `id + data` item.
|
|
11
|
+
- `.updates` validates an `Updates` object for the item data, and `.query` validates a `Query` on the items.
|
|
11
12
|
- `.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`).
|
|
12
13
|
|
|
13
14
|
## Signatures
|
|
@@ -38,7 +39,8 @@ new Collection<N, I, T>(name: N, id: Schema<I>, data: Schemas<T> | DataSchema<T>
|
|
|
38
39
|
| `id` | `Schema<I>` | Schema for the identifier type. Read only. |
|
|
39
40
|
| `item` | `CollectionItemSchema<I, T>` | Schema for a complete item (id + data). Read only. |
|
|
40
41
|
| `items` | `CollectionItemsSchema<I, T>` | Schema for a list of complete items (id + data). Read only. |
|
|
41
|
-
| `
|
|
42
|
+
| `updates` | `UpdatesSchema<T>` | Schema for a set of updates to the data of an item. Read only. |
|
|
43
|
+
| `query` | `CollectionQuerySchema<I, T>` | Schema for a query on the items. Read only. |
|
|
42
44
|
| `queryItems` | `CollectionQueryItemsSchema<I, T>` | Schema for a query and the complete list of items that answer it. Read only. |
|
|
43
45
|
|
|
44
46
|
## Examples
|
|
@@ -43,10 +43,10 @@ const cache = new CollectionCache(collection, provider);
|
|
|
43
43
|
|
|
44
44
|
## Methods
|
|
45
45
|
|
|
46
|
-
- [getItem](CollectionCache/getItem.md): Get (or create) the ItemStore for the given id.
|
|
47
|
-
- [getQuery](CollectionCache/getQuery.md): Get (or create) the QueryStore for the given query.
|
|
48
|
-
- [refreshItem](CollectionCache/refreshItem.md): Refresh a specific item store.
|
|
49
|
-
- [refreshItems](CollectionCache/refreshItems.md): Refresh every cached item store.
|
|
50
|
-
- [refreshQuery](CollectionCache/refreshQuery.md): Refresh a specific query store.
|
|
51
|
-
- [refreshQueries](CollectionCache/refreshQueries.md): Refresh every cached query store.
|
|
52
|
-
- [refreshAll](CollectionCache/refreshAll.md): Refresh every cached store (items and queries).
|
|
46
|
+
- [CollectionCache.getItem()](CollectionCache/getItem.md): Get (or create) the ItemStore for the given id.
|
|
47
|
+
- [CollectionCache.getQuery()](CollectionCache/getQuery.md): Get (or create) the QueryStore for the given query.
|
|
48
|
+
- [CollectionCache.refreshItem()](CollectionCache/refreshItem.md): Refresh a specific item store.
|
|
49
|
+
- [CollectionCache.refreshItems()](CollectionCache/refreshItems.md): Refresh every cached item store.
|
|
50
|
+
- [CollectionCache.refreshQuery()](CollectionCache/refreshQuery.md): Refresh a specific query store.
|
|
51
|
+
- [CollectionCache.refreshQueries()](CollectionCache/refreshQueries.md): Refresh every cached query store.
|
|
52
|
+
- [CollectionCache.refreshAll()](CollectionCache/refreshAll.md): Refresh every cached store (items and queries).
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
Schema for `QueryItems` of a `Collection`, i.e. a query and the complete list of items that answer it.
|
|
9
9
|
|
|
10
10
|
- Built by `Collection` as `Collection.queryItems`, from `Collection.query` and `Collection.items`. Use that instance, and do not make your own.
|
|
11
|
-
-
|
|
11
|
+
- The `query` is validated in full by `Collection.query`, and the `items` by `Collection.items`.
|
|
12
12
|
- Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
|
|
13
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
14
|
- Only use it when `items` is the complete answer to `query` (with its `$limit`).
|
|
@@ -2,13 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
- Kind: class
|
|
4
4
|
- Import: `import { CollectionQuerySchema } from "shelving/db";`
|
|
5
|
-
- Extends: `
|
|
5
|
+
- Extends: `QuerySchema<Item<I, T>>`
|
|
6
6
|
- Implements: `Sourceable<Collection<string, I, T>>`
|
|
7
7
|
|
|
8
8
|
Schema for a `Query` on the items of a `Collection`.
|
|
9
9
|
|
|
10
10
|
- Built by `Collection` as `Collection.query`. Use that instance, and do not make your own.
|
|
11
|
-
-
|
|
11
|
+
- Validates the query in full against `Collection.item` (see `QuerySchema`), so a query from outside (e.g. an API request or response) can be trusted. Filter and `$order` keys can use `id` and any prop path of the collection.
|
|
12
12
|
- Its `source` is the `Collection`, so `getSource()` can find the collection from the schema.
|
|
13
13
|
|
|
14
14
|
## Signatures
|