shelving 1.322.1 → 1.322.3
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/docs/api/APIProvider.md +2 -2
- package/docs/api/CachedAPIProvider.md +6 -8
- package/docs/api/ClientAPIProvider.md +5 -5
- package/docs/api/DebugAPIProvider.md +3 -5
- package/docs/api/HydratingAPIProvider.md +2 -2
- package/docs/api/JSONAPIProvider.md +3 -5
- package/docs/api/LoggingAPIProvider.md +7 -9
- package/docs/api/MockAPIProvider.md +4 -4
- package/docs/api/MockEndpointAPIProvider.md +5 -7
- package/docs/api/ThroughAPIProvider.md +15 -10
- package/docs/api/ValidationAPIProvider.md +3 -5
- package/docs/api/XMLAPIProvider.md +3 -3
- package/docs/api.md +48 -44
- package/docs/bun.md +9 -9
- package/docs/db/DBProvider.md +6 -6
- package/docs/db/MemoryDBProvider.md +3 -3
- package/docs/db/PostgresProvider.md +6 -4
- package/docs/db/SQLProvider.md +6 -3
- package/docs/db/SQLiteProvider.md +9 -4
- package/docs/db/StorageDBProvider.md +2 -2
- package/docs/db/ThroughDBProvider.md +6 -6
- package/docs/db/UndoDBProvider.md +2 -2
- package/docs/db.md +32 -32
- package/docs/error/NetworkError.md +5 -5
- package/docs/error/RequestError.md +4 -4
- package/docs/error/RequiredError.md +2 -2
- package/docs/error/ResponseError.md +1 -1
- package/docs/error/UnexpectedError.md +1 -1
- package/docs/error/UnsupportedError.md +3 -3
- package/docs/error/ValueError.md +2 -2
- package/docs/error.md +20 -19
- package/docs/extract.md +14 -14
- package/docs/firebase.md +6 -6
- package/docs/guides/building-with-shelving.md +112 -84
- package/docs/guides/styleguide.md +29 -29
- package/docs/index.md +3 -2
- package/docs/llms-full.txt +2531 -2291
- package/docs/markup.md +15 -17
- package/docs/react/createAPIContext.md +12 -12
- package/docs/react/createDBContext.md +21 -15
- package/docs/react/useInstance.md +2 -2
- package/docs/react/useLazy.md +1 -1
- package/docs/react/useMap.md +10 -6
- package/docs/react/useReduce.md +2 -2
- package/docs/react/useSequence.md +2 -2
- package/docs/react/useStore.md +10 -10
- package/docs/react.md +22 -16
- package/docs/schema/ArraySchema.md +6 -6
- package/docs/schema/BooleanSchema.md +5 -5
- package/docs/schema/ChoiceSchema.md +1 -1
- package/docs/schema/CurrencyAmountSchema.md +2 -2
- package/docs/schema/DataSchema.md +5 -5
- package/docs/schema/NullableSchema.md +4 -4
- package/docs/schema/NumberSchema.md +4 -4
- package/docs/schema/OptionalSchema.md +1 -1
- package/docs/schema/StringSchema.md +7 -7
- package/docs/schema.md +21 -21
- package/docs/sequence/DeferredSequence.md +1 -1
- package/docs/sequence/InspectSequence.md +8 -6
- package/docs/sequence/LazySequence.md +3 -3
- package/docs/sequence/Sequence.md +6 -6
- package/docs/sequence/ThroughSequence.md +4 -2
- package/docs/sequence.md +3 -3
- package/docs/store/ArrayStore.md +6 -6
- package/docs/store/BooleanStore.md +2 -2
- package/docs/store/BusyStore.md +1 -1
- package/docs/store/DataStore.md +5 -5
- package/docs/store/DictionaryStore.md +4 -4
- package/docs/store/FetchStore.md +6 -6
- package/docs/store/PathStore.md +4 -4
- package/docs/store/PayloadFetchStore.md +1 -5
- package/docs/store/Store.md +8 -6
- package/docs/store/URLStore.md +5 -5
- package/docs/store.md +15 -15
- package/docs/test.md +6 -6
- package/docs/ui/App.md +99 -69
- package/docs/ui/AppLayout.md +33 -24
- package/docs/ui/BackButton.md +13 -11
- package/docs/ui/Button.md +73 -64
- package/docs/ui/Card.md +23 -22
- package/docs/ui/Catcher.md +3 -3
- package/docs/ui/ClassProps.md +1 -1
- package/docs/ui/Code.md +11 -11
- package/docs/ui/CollapseTransition.md +5 -5
- package/docs/ui/Deleted.md +6 -6
- package/docs/ui/Details.md +13 -13
- package/docs/ui/Dialog.md +39 -27
- package/docs/ui/DocumentationButtons.md +2 -2
- package/docs/ui/DocumentationCard.md +2 -2
- package/docs/ui/DocumentationFrame.md +4 -4
- package/docs/ui/DocumentationLive.md +11 -11
- package/docs/ui/DocumentationPage.md +3 -3
- package/docs/ui/Emphasis.md +4 -4
- package/docs/ui/Empty.md +2 -2
- package/docs/ui/FadeTransition.md +9 -9
- package/docs/ui/Field.md +14 -14
- package/docs/ui/FixedLayout.md +27 -25
- package/docs/ui/Form.md +41 -39
- package/docs/ui/FormStore.md +6 -2
- package/docs/ui/Grid.md +21 -9
- package/docs/ui/HTML.md +10 -8
- package/docs/ui/Head.md +2 -3
- package/docs/ui/Heading.md +12 -12
- package/docs/ui/HorizontalTransition.md +10 -10
- package/docs/ui/Icon.md +4 -4
- package/docs/ui/ImageInput.md +12 -12
- package/docs/ui/Inserted.md +6 -6
- package/docs/ui/Link.md +11 -11
- package/docs/ui/List.md +7 -7
- package/docs/ui/Loading.md +6 -6
- package/docs/ui/Mark.md +11 -9
- package/docs/ui/Markup.md +4 -4
- package/docs/ui/Menu.md +24 -24
- package/docs/ui/MenuItem.md +29 -29
- package/docs/ui/Modal.md +57 -45
- package/docs/ui/Navigation.md +28 -26
- package/docs/ui/NavigationStore.md +18 -18
- package/docs/ui/Notice.md +15 -15
- package/docs/ui/Notices.md +17 -17
- package/docs/ui/Page.md +13 -13
- package/docs/ui/Panel.md +8 -8
- package/docs/ui/Paragraph.md +5 -5
- package/docs/ui/Progress.md +11 -11
- package/docs/ui/Prose.md +6 -6
- package/docs/ui/QueryRadiosInput.md +2 -2
- package/docs/ui/RouteCache.md +27 -27
- package/docs/ui/Router.md +70 -61
- package/docs/ui/SchemaInput.md +20 -20
- package/docs/ui/Scroll.md +16 -16
- package/docs/ui/Section.md +13 -10
- package/docs/ui/SidebarLayout.md +27 -27
- package/docs/ui/Small.md +4 -4
- package/docs/ui/Span.md +3 -1
- package/docs/ui/StackButton.md +13 -7
- package/docs/ui/Strong.md +4 -4
- package/docs/ui/Subheading.md +12 -12
- package/docs/ui/TINT_CLASS.md +11 -11
- package/docs/ui/Table.md +40 -29
- package/docs/ui/Tag.md +15 -15
- package/docs/ui/Title.md +13 -13
- package/docs/ui/Transition.md +22 -22
- package/docs/ui/TreeApp.md +8 -8
- package/docs/ui/TreeMarkup.md +2 -2
- package/docs/ui/TreeMenu.md +3 -3
- package/docs/ui/TreeSidebar.md +1 -1
- package/docs/ui/VerticalTransition.md +8 -8
- package/docs/ui/getClass.md +10 -10
- package/docs/ui/getColorClass.md +23 -23
- package/docs/ui/getDurationClass.md +5 -5
- package/docs/ui/getGridClass.md +2 -2
- package/docs/ui/getHeightClass.md +4 -4
- package/docs/ui/getRadiusClass.md +9 -9
- package/docs/ui/getShadowClass.md +6 -6
- package/docs/ui/getSpaceClass.md +13 -13
- package/docs/ui/getStrokeClass.md +6 -6
- package/docs/ui/getTypographyClass.md +38 -38
- package/docs/ui/getWidthClass.md +4 -4
- package/docs/ui/notify.md +11 -11
- package/docs/ui/requireContext.md +1 -1
- package/docs/ui.md +4 -4
- package/docs/util/array.md +35 -29
- package/docs/util/async.md +2 -2
- package/docs/util/base64.md +7 -7
- package/docs/util/boolean.md +10 -10
- package/docs/util/buffer.md +5 -5
- package/docs/util/bytes.md +9 -9
- package/docs/util/class.md +10 -6
- package/docs/util/color.md +13 -13
- package/docs/util/constants.md +2 -2
- package/docs/util/crypto.md +1 -1
- package/docs/util/currency.md +2 -2
- package/docs/util/data.md +18 -18
- package/docs/util/date.md +22 -22
- package/docs/util/debug/debug.md +12 -12
- package/docs/util/dictionary.md +21 -18
- package/docs/util/diff.md +6 -6
- package/docs/util/dispose/dispose.md +5 -5
- package/docs/util/duration.md +9 -9
- package/docs/util/element.md +1 -1
- package/docs/util/entity.md +6 -6
- package/docs/util/entry.md +21 -8
- package/docs/util/env.md +2 -2
- package/docs/util/equal.md +16 -16
- package/docs/util/error.md +4 -4
- package/docs/util/file.md +8 -8
- package/docs/util/filter.md +9 -5
- package/docs/util/format.md +18 -18
- package/docs/util/function.md +4 -4
- package/docs/util/geo.md +13 -13
- package/docs/util/hash.md +3 -3
- package/docs/util/http.md +1 -1
- package/docs/util/hydrate/hydrate.md +7 -4
- package/docs/util/item.md +4 -4
- package/docs/util/iterate.md +11 -11
- package/docs/util/jwt.md +1 -6
- package/docs/util/link.md +5 -5
- package/docs/util/map.md +17 -11
- package/docs/util/merge.md +2 -5
- package/docs/util/null.md +20 -10
- package/docs/util/number.md +16 -16
- package/docs/util/object.md +25 -22
- package/docs/util/path.md +17 -17
- package/docs/util/query.md +23 -25
- package/docs/util/random.md +7 -7
- package/docs/util/regexp.md +16 -16
- package/docs/util/sequence.md +16 -10
- package/docs/util/serialise/serialise.md +6 -6
- package/docs/util/set.md +10 -10
- package/docs/util/sort.md +10 -11
- package/docs/util/source.md +11 -7
- package/docs/util/start.md +8 -8
- package/docs/util/string.md +14 -14
- package/docs/util/template.md +3 -3
- package/docs/util/timeout.md +5 -5
- package/docs/util/transform.md +6 -6
- package/docs/util/tree.md +13 -13
- package/docs/util/undefined.md +3 -3
- package/docs/util/units.md +15 -15
- package/docs/util/update.md +16 -16
- package/docs/util/uri.md +12 -12
- package/docs/util/url.md +11 -11
- package/docs/util/uuid.md +3 -3
- package/docs/util/validate.md +14 -9
- package/package.json +3 -3
- package/skills/shelving/SKILL.md +1 -0
- package/ui/README.md +4 -4
- package/ui/app/App.md +99 -69
- package/ui/block/Card.md +23 -22
- package/ui/block/Card.module.css +10 -5
- package/ui/block/Details.md +13 -13
- package/ui/block/Grid.md +21 -9
- package/ui/block/Heading.md +12 -12
- package/ui/block/List.md +7 -7
- package/ui/block/Panel.md +8 -8
- package/ui/block/Paragraph.md +5 -5
- package/ui/block/Prose.md +6 -6
- package/ui/block/Section.md +13 -10
- package/ui/block/Subheading.md +12 -12
- package/ui/block/Title.md +13 -13
- package/ui/button/Button.md +73 -64
- package/ui/dialog/Dialog.md +39 -27
- package/ui/dialog/Modal.md +57 -45
- package/ui/docs/DocumentationButtons.md +2 -2
- package/ui/docs/DocumentationCard.md +2 -2
- package/ui/docs/DocumentationFrame.md +4 -4
- package/ui/docs/DocumentationLive.md +11 -11
- package/ui/docs/DocumentationPage.md +3 -3
- package/ui/form/Field.md +14 -14
- package/ui/form/Form.md +41 -39
- package/ui/form/FormStore.md +6 -2
- package/ui/form/Progress.md +11 -11
- package/ui/inline/Code.md +11 -11
- package/ui/inline/Deleted.md +6 -6
- package/ui/inline/Emphasis.md +4 -4
- package/ui/inline/Inserted.md +6 -6
- package/ui/inline/Link.md +11 -11
- package/ui/inline/Mark.md +11 -9
- package/ui/inline/Small.md +4 -4
- package/ui/inline/Span.md +3 -1
- package/ui/inline/Strong.md +4 -4
- package/ui/input/ImageInput.md +12 -12
- package/ui/input/QueryRadiosInput.md +2 -2
- package/ui/input/SchemaInput.md +20 -20
- package/ui/layout/AppLayout.md +33 -24
- package/ui/layout/AppLayout.module.css +1 -0
- package/ui/layout/FixedLayout.md +27 -25
- package/ui/layout/SidebarLayout.md +27 -27
- package/ui/layout/SidebarLayout.module.css +1 -0
- package/ui/menu/Menu.md +24 -24
- package/ui/menu/MenuItem.md +29 -29
- package/ui/misc/Catcher.md +3 -3
- package/ui/misc/Icon.md +4 -4
- package/ui/misc/Loading.md +6 -6
- package/ui/misc/Markup.md +4 -4
- package/ui/misc/Tag.md +15 -15
- package/ui/notice/Empty.md +2 -2
- package/ui/notice/Notice.md +15 -15
- package/ui/notice/Notices.md +17 -17
- package/ui/page/HTML.md +10 -8
- package/ui/page/Head.md +2 -3
- package/ui/page/Page.md +13 -13
- package/ui/router/BackButton.md +13 -11
- package/ui/router/Navigation.md +28 -26
- package/ui/router/NavigationStore.md +18 -18
- package/ui/router/RouteCache.md +27 -27
- package/ui/router/Router.md +70 -61
- package/ui/router/StackButton.md +13 -7
- package/ui/style/Scroll.md +16 -16
- package/ui/style/TINT_CLASS.md +11 -11
- package/ui/style/getColorClass.md +23 -23
- package/ui/style/getDurationClass.md +5 -5
- package/ui/style/getGridClass.md +2 -2
- package/ui/style/getHeightClass.md +4 -4
- package/ui/style/getRadiusClass.md +9 -9
- package/ui/style/getShadowClass.md +6 -6
- package/ui/style/getSpaceClass.md +13 -13
- package/ui/style/getStrokeClass.md +6 -6
- package/ui/style/getTypographyClass.md +38 -38
- package/ui/style/getWidthClass.md +4 -4
- package/ui/table/Table.md +40 -30
- package/ui/transition/CollapseTransition.md +5 -5
- package/ui/transition/FadeTransition.md +9 -9
- package/ui/transition/HorizontalTransition.md +10 -10
- package/ui/transition/Transition.md +22 -22
- package/ui/transition/VerticalTransition.md +8 -8
- package/ui/tree/TreeApp.md +8 -8
- package/ui/tree/TreeMarkup.md +2 -2
- package/ui/tree/TreeMenu.md +3 -3
- package/ui/tree/TreeSidebar.md +1 -1
- package/ui/util/ClassProps.md +1 -1
- package/ui/util/getClass.md +10 -10
- package/ui/util/notify.md +11 -11
- package/ui/util/requireContext.md +1 -1
package/docs/db.md
CHANGED
|
@@ -12,14 +12,14 @@ Typed database provider abstraction. Define your schema once as a `Collection`,
|
|
|
12
12
|
A `Collection` is a declarative description of a database table or collection. It extends `DataSchema` and carries three things: a string `name`, an `id` schema (the identifier type), and a data schema (the shape of each record).
|
|
13
13
|
|
|
14
14
|
```ts
|
|
15
|
-
import { COLLECTION } from "shelving/db"
|
|
16
|
-
import { STRING, BOOLEAN } from "shelving/schema"
|
|
15
|
+
import { COLLECTION } from "shelving/db";
|
|
16
|
+
import { STRING, BOOLEAN } from "shelving/schema";
|
|
17
17
|
|
|
18
18
|
const POSTS = COLLECTION("posts", STRING, {
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
})
|
|
19
|
+
title: STRING,
|
|
20
|
+
body: STRING,
|
|
21
|
+
published: BOOLEAN,
|
|
22
|
+
});
|
|
23
23
|
```
|
|
24
24
|
|
|
25
25
|
`Collection` is the single source of truth for both runtime validation and TypeScript types. All provider methods are generic over the collection so the compiler tracks `id` and `data` types automatically.
|
|
@@ -28,12 +28,12 @@ const POSTS = COLLECTION("posts", STRING, {
|
|
|
28
28
|
|
|
29
29
|
`DBProvider` is the abstract base class every backend implements. Its surface covers:
|
|
30
30
|
|
|
31
|
-
| Category
|
|
32
|
-
|
|
33
|
-
| Single item
|
|
34
|
-
| Single item (realtime) | `DBProvider.getItemSequence()`
|
|
35
|
-
| Queries
|
|
36
|
-
| Query (realtime)
|
|
31
|
+
| Category | Methods |
|
|
32
|
+
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
33
|
+
| Single item | `DBProvider.getItem()`, `DBProvider.requireItem()`, `DBProvider.addItem()`, `DBProvider.setItem()`, `DBProvider.updateItem()`, `DBProvider.deleteItem()` |
|
|
34
|
+
| Single item (realtime) | `DBProvider.getItemSequence()` |
|
|
35
|
+
| Queries | `DBProvider.getQuery()`, `DBProvider.countQuery()`, `DBProvider.setQuery()`, `DBProvider.updateQuery()`, `DBProvider.deleteQuery()`, `DBProvider.getFirst()`, `DBProvider.requireFirst()` |
|
|
36
|
+
| Query (realtime) | `DBProvider.getQuerySequence()` |
|
|
37
37
|
|
|
38
38
|
`.getItemSequence()` and `.getQuerySequence()` return `AsyncIterable` — iterate them with `for await...of` to receive realtime updates as data changes.
|
|
39
39
|
|
|
@@ -70,50 +70,50 @@ Cloud providers live in the `shelving/cloudflare` and `shelving/firebase` siblin
|
|
|
70
70
|
### Define a collection and build a provider chain
|
|
71
71
|
|
|
72
72
|
```ts
|
|
73
|
-
import { COLLECTION, MemoryDBProvider, ValidationDBProvider } from "shelving/db"
|
|
74
|
-
import { STRING, BOOLEAN } from "shelving/schema"
|
|
73
|
+
import { COLLECTION, MemoryDBProvider, ValidationDBProvider } from "shelving/db";
|
|
74
|
+
import { STRING, BOOLEAN } from "shelving/schema";
|
|
75
75
|
|
|
76
76
|
const POSTS = COLLECTION("posts", STRING, {
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
})
|
|
77
|
+
title: STRING,
|
|
78
|
+
body: STRING,
|
|
79
|
+
published: BOOLEAN,
|
|
80
|
+
});
|
|
81
81
|
|
|
82
82
|
// In production replace MemoryDBProvider with a real backend (Firestore, D1, …).
|
|
83
|
-
const provider = new ValidationDBProvider(new MemoryDBProvider())
|
|
83
|
+
const provider = new ValidationDBProvider(new MemoryDBProvider());
|
|
84
84
|
```
|
|
85
85
|
|
|
86
86
|
### Read and write items
|
|
87
87
|
|
|
88
88
|
```ts
|
|
89
89
|
// Add a new item — returns the generated id.
|
|
90
|
-
const id = await provider.addItem(POSTS, { title: "Hello world", body: "First post.", published: false })
|
|
90
|
+
const id = await provider.addItem(POSTS, { title: "Hello world", body: "First post.", published: false });
|
|
91
91
|
|
|
92
92
|
// Read it back.
|
|
93
|
-
const post = await provider.getItem(POSTS, id)
|
|
93
|
+
const post = await provider.getItem(POSTS, id);
|
|
94
94
|
|
|
95
95
|
// Partial update.
|
|
96
|
-
await provider.updateItem(POSTS, id, { published: true })
|
|
96
|
+
await provider.updateItem(POSTS, id, { published: true });
|
|
97
97
|
|
|
98
98
|
// Delete.
|
|
99
|
-
await provider.deleteItem(POSTS, id)
|
|
99
|
+
await provider.deleteItem(POSTS, id);
|
|
100
100
|
```
|
|
101
101
|
|
|
102
102
|
### Query items
|
|
103
103
|
|
|
104
104
|
```ts
|
|
105
105
|
const posts = await provider.getQuery(POSTS, {
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
})
|
|
106
|
+
published: true,
|
|
107
|
+
$order: "title",
|
|
108
|
+
$limit: 10,
|
|
109
|
+
});
|
|
110
110
|
```
|
|
111
111
|
|
|
112
112
|
### Realtime subscriptions
|
|
113
113
|
|
|
114
114
|
```ts
|
|
115
115
|
for await (const post of provider.getItemSequence(POSTS, id)) {
|
|
116
|
-
|
|
116
|
+
console.log(post); // emits whenever this item changes
|
|
117
117
|
}
|
|
118
118
|
```
|
|
119
119
|
|
|
@@ -122,11 +122,11 @@ for await (const post of provider.getItemSequence(POSTS, id)) {
|
|
|
122
122
|
The `shelving/react` module's `createDBContext()` is the primary way to use a provider in a React app. It creates a context that wraps a provider (in a client app, typically a `MemoryDBProvider` that `HydratingAPIProvider` fills) and exposes typed hooks — `DBContext.useItem()` and `DBContext.useQuery()` — that return reactive `Store` instances and suspend automatically while loading.
|
|
123
123
|
|
|
124
124
|
```ts
|
|
125
|
-
import { createDBContext } from "shelving/react"
|
|
126
|
-
import { MemoryDBProvider } from "shelving/db"
|
|
125
|
+
import { createDBContext } from "shelving/react";
|
|
126
|
+
import { MemoryDBProvider } from "shelving/db";
|
|
127
127
|
|
|
128
|
-
export const DB = new MemoryDBProvider()
|
|
129
|
-
export const { DBContext, useItem, useQuery } = createDBContext(DB)
|
|
128
|
+
export const DB = new MemoryDBProvider();
|
|
129
|
+
export const { DBContext, useItem, useQuery } = createDBContext(DB);
|
|
130
130
|
```
|
|
131
131
|
|
|
132
132
|
See the `shelving/react` module for full usage.
|
|
@@ -15,11 +15,11 @@ Thrown on a network-level failure — a connection refused, a server unreachable
|
|
|
15
15
|
import { NetworkError } from "shelving/error";
|
|
16
16
|
|
|
17
17
|
async function fetchData(url: string): Promise<Response> {
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
18
|
+
try {
|
|
19
|
+
return await fetch(url);
|
|
20
|
+
} catch {
|
|
21
|
+
throw new NetworkError("Could not reach server");
|
|
22
|
+
}
|
|
23
23
|
}
|
|
24
24
|
```
|
|
25
25
|
|
|
@@ -19,10 +19,10 @@ Thrown when an incoming request is malformed or unacceptable — the HTTP 4xx ra
|
|
|
19
19
|
import { RequestError, NotFoundError } from "shelving/error";
|
|
20
20
|
|
|
21
21
|
function loadDocument(id: string): Document {
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
22
|
+
if (!isValidId(id)) throw new RequestError("Malformed document ID", { received: id });
|
|
23
|
+
const doc = documents.get(id);
|
|
24
|
+
if (!doc) throw new NotFoundError("Document not found", { received: id }); // .code === 404
|
|
25
|
+
return doc;
|
|
26
26
|
}
|
|
27
27
|
```
|
|
28
28
|
|
|
@@ -16,8 +16,8 @@ Thrown when something required was absent — a missing argument, an empty looku
|
|
|
16
16
|
import { RequiredError } from "shelving/error";
|
|
17
17
|
|
|
18
18
|
function getUser(id: string | undefined): User {
|
|
19
|
-
|
|
20
|
-
|
|
19
|
+
if (!id) throw new RequiredError("User ID is required");
|
|
20
|
+
// ...
|
|
21
21
|
}
|
|
22
22
|
```
|
|
23
23
|
|
|
@@ -16,7 +16,7 @@ Thrown when a received response indicates an error — the HTTP 4xx/5xx range. I
|
|
|
16
16
|
import { ResponseError } from "shelving/error";
|
|
17
17
|
|
|
18
18
|
function checkResponse(res: Response): void {
|
|
19
|
-
|
|
19
|
+
if (!res.ok) throw new ResponseError(res.statusText, { code: res.status });
|
|
20
20
|
}
|
|
21
21
|
```
|
|
22
22
|
|
|
@@ -16,7 +16,7 @@ Thrown when something that should never happen did — an invariant was violated
|
|
|
16
16
|
import { UnexpectedError } from "shelving/error";
|
|
17
17
|
|
|
18
18
|
function assertNever(x: never): never {
|
|
19
|
-
|
|
19
|
+
throw new UnexpectedError("Unhandled case", { received: x });
|
|
20
20
|
}
|
|
21
21
|
```
|
|
22
22
|
|
|
@@ -15,9 +15,9 @@ Thrown when functionality is called but is not supported — a backend that can'
|
|
|
15
15
|
import { UnsupportedError } from "shelving/error";
|
|
16
16
|
|
|
17
17
|
class KVProvider {
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
18
|
+
getQuery(): Promise<Items> {
|
|
19
|
+
throw new UnsupportedError("KVProvider does not support querying items");
|
|
20
|
+
}
|
|
21
21
|
}
|
|
22
22
|
```
|
|
23
23
|
|
package/docs/error/ValueError.md
CHANGED
|
@@ -16,8 +16,8 @@ Thrown when a value was present but invalid in its context — for example data
|
|
|
16
16
|
import { ValueError } from "shelving/error";
|
|
17
17
|
|
|
18
18
|
function parseConfig(raw: unknown): Config {
|
|
19
|
-
|
|
20
|
-
|
|
19
|
+
if (!isConfig(raw)) throw new ValueError("Invalid config from server", { received: raw });
|
|
20
|
+
return raw;
|
|
21
21
|
}
|
|
22
22
|
```
|
|
23
23
|
|
package/docs/error.md
CHANGED
|
@@ -18,26 +18,27 @@ Each subclass sets its own `caller` default, so you only need to supply `caller`
|
|
|
18
18
|
|
|
19
19
|
```ts
|
|
20
20
|
function requirePositive(n: number): number {
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
21
|
+
if (n <= 0)
|
|
22
|
+
throw new ValueError("Value must be positive", {
|
|
23
|
+
caller: requirePositive, // stack starts here, not inside ValueError
|
|
24
|
+
received: n,
|
|
25
|
+
expected: "> 0",
|
|
26
|
+
});
|
|
27
|
+
return n;
|
|
27
28
|
}
|
|
28
29
|
```
|
|
29
30
|
|
|
30
31
|
## Choosing the right class
|
|
31
32
|
|
|
32
|
-
| Class
|
|
33
|
-
|
|
34
|
-
| `RequiredError`
|
|
35
|
-
| `ValueError`
|
|
36
|
-
| `NetworkError`
|
|
37
|
-
| `RequestError`
|
|
38
|
-
| `ResponseError`
|
|
39
|
-
| `UnexpectedError`
|
|
40
|
-
| `UnsupportedError` | A method or feature is not supported — by a backend, an environment, or an implementation
|
|
33
|
+
| Class | When to throw |
|
|
34
|
+
| ------------------ | ------------------------------------------------------------------------------------------------- |
|
|
35
|
+
| `RequiredError` | Something required was absent (also thrown by `require*()` helpers) |
|
|
36
|
+
| `ValueError` | A value was present but invalid in context (e.g. data from a database failed validation) |
|
|
37
|
+
| `NetworkError` | Network-level failure — connection refused, server unreachable |
|
|
38
|
+
| `RequestError` | The request was malformed or unacceptable (HTTP 4xx range; `RequestError.code` defaults to `400`) |
|
|
39
|
+
| `ResponseError` | The received response indicated an error (HTTP 4xx/5xx; `ResponseError.code` defaults to `400`) |
|
|
40
|
+
| `UnexpectedError` | Something that should never happen did — an invariant was violated |
|
|
41
|
+
| `UnsupportedError` | A method or feature is not supported — by a backend, an environment, or an implementation |
|
|
41
42
|
|
|
42
43
|
`RequestError` has named subclasses for common HTTP status codes: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `MethodNotAllowedError` (405), and `UnprocessableError` (422).
|
|
43
44
|
|
|
@@ -51,10 +52,10 @@ Any extra fields in the options bag land on the error instance and will appear i
|
|
|
51
52
|
|
|
52
53
|
```ts
|
|
53
54
|
throw new ValueError("Unexpected status", {
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
55
|
+
received: status,
|
|
56
|
+
expected: ["active", "inactive"],
|
|
57
|
+
entity: "subscription",
|
|
58
|
+
cause: originalError,
|
|
58
59
|
});
|
|
59
60
|
```
|
|
60
61
|
|
package/docs/extract.md
CHANGED
|
@@ -15,12 +15,12 @@ Pair the tree with the `shelving/ui` and you have a complete static documentatio
|
|
|
15
15
|
|
|
16
16
|
An `Extractor` converts an input into a `TreeElement`. Extractors are composable — an outer extractor delegates to inner ones.
|
|
17
17
|
|
|
18
|
-
| Extractor
|
|
19
|
-
|
|
20
|
-
| `DirectoryExtractor`
|
|
21
|
-
| `FileExtractor`
|
|
22
|
-
| `MarkupExtractor`
|
|
23
|
-
| `TypescriptExtractor` | a `.ts` / `.tsx` file | a `tree-element` node whose children are the exported symbols
|
|
18
|
+
| Extractor | Input | Output |
|
|
19
|
+
| --------------------- | --------------------- | ------------------------------------------------------------------- |
|
|
20
|
+
| `DirectoryExtractor` | a directory path | a `tree-element` node, recursing into subdirectories |
|
|
21
|
+
| `FileExtractor` | a file | a `tree-element` node holding the raw text |
|
|
22
|
+
| `MarkupExtractor` | a `.md` file | a `tree-element` node with `title` taken from the first `# heading` |
|
|
23
|
+
| `TypescriptExtractor` | a `.ts` / `.tsx` file | a `tree-element` node whose children are the exported symbols |
|
|
24
24
|
|
|
25
25
|
`DirectoryExtractor` is the entry point. It walks a directory, dispatches each file to a `FileExtractor` by extension, and recurses into subdirectories.
|
|
26
26
|
|
|
@@ -35,7 +35,7 @@ The tree is plain, JSON-serialisable data. The docs build writes it to `tree.jso
|
|
|
35
35
|
|
|
36
36
|
### Index files
|
|
37
37
|
|
|
38
|
-
A directory's index file — `README.md` by default — is
|
|
38
|
+
A directory's index file — `README.md` by default — is _absorbed_ into the directory element. Its title, description, and content become the directory's own. This is why writing a `README.md` is all it takes to give a directory an intro page.
|
|
39
39
|
|
|
40
40
|
### Same-key merging
|
|
41
41
|
|
|
@@ -64,7 +64,7 @@ const root = await new DirectoryExtractor().extract("/path/to/modules");
|
|
|
64
64
|
```tsx
|
|
65
65
|
import { TreeApp } from "shelving/ui";
|
|
66
66
|
|
|
67
|
-
<TreeApp tree={root}
|
|
67
|
+
<TreeApp tree={root} />;
|
|
68
68
|
```
|
|
69
69
|
|
|
70
70
|
Internally `<TreeApp>` wires together:
|
|
@@ -87,9 +87,9 @@ Internally `<TreeApp>` wires together:
|
|
|
87
87
|
|
|
88
88
|
```ts
|
|
89
89
|
new DirectoryExtractor({
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
90
|
+
extractors: { md: new MarkupExtractor() }, // file extension → extractor
|
|
91
|
+
ignore: [/\.test\.tsx?$/i], // entries to skip
|
|
92
|
+
base: "/abs/path", // base for resolving relative paths
|
|
93
93
|
});
|
|
94
94
|
```
|
|
95
95
|
|
|
@@ -99,7 +99,7 @@ By default, test files, hidden files, underscore-prefixed files, and `node_modul
|
|
|
99
99
|
|
|
100
100
|
### Overriding page renderers
|
|
101
101
|
|
|
102
|
-
The tree components render through
|
|
102
|
+
The tree components render through _mappings_ — wrap a subtree to swap a renderer for one element type:
|
|
103
103
|
|
|
104
104
|
- `<TreePageMapping>` — the full-page component for an element type.
|
|
105
105
|
- `<TreeMenuMapping>` — the sidebar menu renderer.
|
|
@@ -107,8 +107,8 @@ The tree components render through *mappings* — wrap a subtree to swap a rende
|
|
|
107
107
|
|
|
108
108
|
```tsx
|
|
109
109
|
<TreePageMapping mapping={{ "tree-element": MyTreePage }}>
|
|
110
|
-
|
|
111
|
-
</TreePageMapping
|
|
110
|
+
<TreeApp tree={root} />
|
|
111
|
+
</TreePageMapping>;
|
|
112
112
|
```
|
|
113
113
|
|
|
114
114
|
|
package/docs/firebase.md
CHANGED
|
@@ -15,15 +15,15 @@
|
|
|
15
15
|
import { FirestoreProvider } from "shelving/firebase";
|
|
16
16
|
|
|
17
17
|
const provider = new FirestoreProvider({
|
|
18
|
-
|
|
19
|
-
|
|
18
|
+
project: "my-project",
|
|
19
|
+
token: () => auth.getAccessToken(), // e.g. from `google-auth-library`
|
|
20
20
|
});
|
|
21
21
|
|
|
22
22
|
const id = await provider.addItem(POSTS, { title: "Hello", body: "First post.", published: false });
|
|
23
23
|
|
|
24
24
|
await provider.transact(async db => {
|
|
25
|
-
|
|
26
|
-
|
|
25
|
+
const post = await db.requireItem(POSTS, id);
|
|
26
|
+
await db.updateItem(POSTS, id, { published: true, "+=views": 1 });
|
|
27
27
|
});
|
|
28
28
|
```
|
|
29
29
|
|
|
@@ -39,8 +39,8 @@ await provider.transact(async db => {
|
|
|
39
39
|
|
|
40
40
|
```ts
|
|
41
41
|
const provider = new FirestoreProvider({
|
|
42
|
-
|
|
43
|
-
|
|
42
|
+
project: "demo-project",
|
|
43
|
+
host: `http://${process.env.FIRESTORE_EMULATOR_HOST}`,
|
|
44
44
|
});
|
|
45
45
|
```
|
|
46
46
|
|