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/api/APIProvider.md
CHANGED
|
@@ -17,10 +17,10 @@ You never instantiate `APIProvider` directly — use the concrete `ClientAPIProv
|
|
|
17
17
|
Code that accepts "any provider" should type against `APIProvider` so a bare client, a validated chain, or a mock are all interchangeable:
|
|
18
18
|
|
|
19
19
|
```ts
|
|
20
|
-
import type { APIProvider } from "shelving/api"
|
|
20
|
+
import type { APIProvider } from "shelving/api";
|
|
21
21
|
|
|
22
22
|
async function loadUser(provider: APIProvider, id: string) {
|
|
23
|
-
|
|
23
|
+
return provider.call(getUser, { id }); // works with any provider in the chain
|
|
24
24
|
}
|
|
25
25
|
```
|
|
26
26
|
|
|
@@ -16,17 +16,15 @@ The constructor takes the `source` provider and an optional default `maxAge` (de
|
|
|
16
16
|
## Usage
|
|
17
17
|
|
|
18
18
|
```ts
|
|
19
|
-
import { CachedAPIProvider, ValidationAPIProvider, ClientAPIProvider } from "shelving/api"
|
|
19
|
+
import { CachedAPIProvider, ValidationAPIProvider, ClientAPIProvider } from "shelving/api";
|
|
20
20
|
|
|
21
|
-
const provider = new CachedAPIProvider(
|
|
22
|
-
new ValidationAPIProvider(new ClientAPIProvider({ url: "https://api.example.com" }))
|
|
23
|
-
)
|
|
21
|
+
const provider = new CachedAPIProvider(new ValidationAPIProvider(new ClientAPIProvider({ url: "https://api.example.com" })));
|
|
24
22
|
|
|
25
|
-
await provider.call(getUser, { id: "u_1" }) // fetches
|
|
26
|
-
await provider.call(getUser, { id: "u_1" }) // returns cached
|
|
23
|
+
await provider.call(getUser, { id: "u_1" }); // fetches
|
|
24
|
+
await provider.call(getUser, { id: "u_1" }); // returns cached
|
|
27
25
|
|
|
28
|
-
provider.invalidate(getUser, { id: "u_1" }) // mark stale
|
|
29
|
-
provider.refresh(getUser, { id: "u_1" })
|
|
26
|
+
provider.invalidate(getUser, { id: "u_1" }); // mark stale
|
|
27
|
+
provider.refresh(getUser, { id: "u_1" }); // re-fetch eagerly
|
|
30
28
|
```
|
|
31
29
|
|
|
32
30
|
`invalidateAll(endpoint)` and `refreshAll(endpoint)` act on every cached payload for an endpoint at once.
|
|
@@ -18,14 +18,14 @@ The constructor takes `{ url, options?, timeout? }` — a base URL that endpoint
|
|
|
18
18
|
## Usage
|
|
19
19
|
|
|
20
20
|
```ts
|
|
21
|
-
import { ClientAPIProvider } from "shelving/api"
|
|
21
|
+
import { ClientAPIProvider } from "shelving/api";
|
|
22
22
|
|
|
23
23
|
const provider = new ClientAPIProvider({
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
})
|
|
24
|
+
url: "https://api.example.com",
|
|
25
|
+
timeout: 10_000,
|
|
26
|
+
});
|
|
27
27
|
|
|
28
|
-
const user = await provider.call(getUser, { id: "u_123" })
|
|
28
|
+
const user = await provider.call(getUser, { id: "u_123" });
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
In practice you wrap it — e.g. `new ValidationAPIProvider(new ClientAPIProvider({ url }))` — so payloads and results are validated. See `shelving/api` for building a provider chain.
|
|
@@ -13,13 +13,11 @@ It is the noisy counterpart to `LoggingAPIProvider`: use `DebugAPIProvider` whil
|
|
|
13
13
|
## Usage
|
|
14
14
|
|
|
15
15
|
```ts
|
|
16
|
-
import { ClientAPIProvider, DebugAPIProvider } from "shelving/api"
|
|
16
|
+
import { ClientAPIProvider, DebugAPIProvider } from "shelving/api";
|
|
17
17
|
|
|
18
|
-
const provider = new DebugAPIProvider(
|
|
19
|
-
new ClientAPIProvider({ url: "https://api.example.com" })
|
|
20
|
-
)
|
|
18
|
+
const provider = new DebugAPIProvider(new ClientAPIProvider({ url: "https://api.example.com" }));
|
|
21
19
|
|
|
22
|
-
await provider.call(getUser, { id: "u_123" })
|
|
20
|
+
await provider.call(getUser, { id: "u_123" });
|
|
23
21
|
// Console shows the full request and response, including bodies.
|
|
24
22
|
```
|
|
25
23
|
|
|
@@ -55,8 +55,8 @@ export const getMyMembersQuery = (user: string): Query<MemberItem> => ({ user, $
|
|
|
55
55
|
|
|
56
56
|
// Server handler.
|
|
57
57
|
MY_SQUADS.handler(async (_payload, _request, { user }) => ({
|
|
58
|
-
|
|
59
|
-
|
|
58
|
+
squads: await getMySquads(user),
|
|
59
|
+
members: { query: getMyMembersQuery(user), items: await getMyMembers(user) },
|
|
60
60
|
}));
|
|
61
61
|
```
|
|
62
62
|
|
|
@@ -14,13 +14,11 @@ Because it extends `ClientAPIProvider`, it is a concrete network provider: const
|
|
|
14
14
|
## Usage
|
|
15
15
|
|
|
16
16
|
```ts
|
|
17
|
-
import { JSONAPIProvider, ValidationAPIProvider } from "shelving/api"
|
|
17
|
+
import { JSONAPIProvider, ValidationAPIProvider } from "shelving/api";
|
|
18
18
|
|
|
19
|
-
const provider = new ValidationAPIProvider(
|
|
20
|
-
new JSONAPIProvider({ url: "https://api.example.com" })
|
|
21
|
-
)
|
|
19
|
+
const provider = new ValidationAPIProvider(new JSONAPIProvider({ url: "https://api.example.com" }));
|
|
22
20
|
|
|
23
|
-
const user = await provider.call(getUser, { id: "u_123" })
|
|
21
|
+
const user = await provider.call(getUser, { id: "u_123" });
|
|
24
22
|
```
|
|
25
23
|
|
|
26
24
|
|
|
@@ -14,20 +14,18 @@ The constructor takes the `source` provider plus three optional callbacks — `o
|
|
|
14
14
|
## Usage
|
|
15
15
|
|
|
16
16
|
```ts
|
|
17
|
-
import { ClientAPIProvider, LoggingAPIProvider } from "shelving/api"
|
|
17
|
+
import { ClientAPIProvider, LoggingAPIProvider } from "shelving/api";
|
|
18
18
|
|
|
19
19
|
// Default console logging.
|
|
20
|
-
const provider = new LoggingAPIProvider(
|
|
21
|
-
new ClientAPIProvider({ url: "https://api.example.com" })
|
|
22
|
-
)
|
|
20
|
+
const provider = new LoggingAPIProvider(new ClientAPIProvider({ url: "https://api.example.com" }));
|
|
23
21
|
|
|
24
22
|
// Or route logs into your own logger.
|
|
25
23
|
const custom = new LoggingAPIProvider(
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
)
|
|
24
|
+
new ClientAPIProvider({ url: "https://api.example.com" }),
|
|
25
|
+
request => logger.info("api request", request.url),
|
|
26
|
+
(response, request) => logger.info("api response", request.url, response.status),
|
|
27
|
+
(reason, request) => logger.error("api error", request.url, reason),
|
|
28
|
+
);
|
|
31
29
|
```
|
|
32
30
|
|
|
33
31
|
|
|
@@ -16,13 +16,13 @@ The constructor takes an optional `RequestHandler` and an optional `source` prov
|
|
|
16
16
|
## Usage
|
|
17
17
|
|
|
18
18
|
```ts
|
|
19
|
-
import { MockAPIProvider } from "shelving/api"
|
|
19
|
+
import { MockAPIProvider } from "shelving/api";
|
|
20
20
|
|
|
21
|
-
const api = new MockAPIProvider(
|
|
21
|
+
const api = new MockAPIProvider(request => new Response(JSON.stringify({ id: "u_1", name: "Alice" })));
|
|
22
22
|
|
|
23
|
-
const user = await api.call(getUser, { id: "u_1" })
|
|
23
|
+
const user = await api.call(getUser, { id: "u_1" });
|
|
24
24
|
|
|
25
|
-
console.log(api.requestCalls) // inspect every recorded request
|
|
25
|
+
console.log(api.requestCalls); // inspect every recorded request
|
|
26
26
|
```
|
|
27
27
|
|
|
28
28
|
For tests that exercise client and server logic together, use `MockEndpointAPIProvider`, which routes the mock transport through a real handler array.
|
|
@@ -14,18 +14,16 @@ The constructor takes the `handlers` array, a `context` value passed to every ha
|
|
|
14
14
|
## Usage
|
|
15
15
|
|
|
16
16
|
```ts
|
|
17
|
-
import { MockEndpointAPIProvider } from "shelving/api"
|
|
17
|
+
import { MockEndpointAPIProvider } from "shelving/api";
|
|
18
18
|
|
|
19
|
-
const handlers = [
|
|
20
|
-
getUser.handler(async ({ id }) => ({ id, name: "Alice", email: "alice@example.com" })),
|
|
21
|
-
]
|
|
19
|
+
const handlers = [getUser.handler(async ({ id }) => ({ id, name: "Alice", email: "alice@example.com" }))];
|
|
22
20
|
|
|
23
|
-
const api = new MockEndpointAPIProvider(handlers, undefined)
|
|
21
|
+
const api = new MockEndpointAPIProvider(handlers, undefined);
|
|
24
22
|
|
|
25
|
-
const user = await api.call(getUser, { id: "u_1" })
|
|
23
|
+
const user = await api.call(getUser, { id: "u_1" });
|
|
26
24
|
// user == { id: "u_1", name: "Alice", email: "alice@example.com" }
|
|
27
25
|
|
|
28
|
-
console.log(api.requestCalls) // inspect recorded calls
|
|
26
|
+
console.log(api.requestCalls); // inspect recorded calls
|
|
29
27
|
```
|
|
30
28
|
|
|
31
29
|
|
|
@@ -18,18 +18,23 @@ The pass-through base class for wrapping providers. `ThroughAPIProvider` takes a
|
|
|
18
18
|
Override `fetch()` (or `call()`) and call `super` to delegate the rest. For example, a provider that injects an `Authorization` header:
|
|
19
19
|
|
|
20
20
|
```ts
|
|
21
|
-
import { ThroughAPIProvider } from "shelving/api"
|
|
22
|
-
import type { APIProvider } from "shelving/api"
|
|
21
|
+
import { ThroughAPIProvider } from "shelving/api";
|
|
22
|
+
import type { APIProvider } from "shelving/api";
|
|
23
23
|
|
|
24
24
|
class AuthAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
25
|
+
constructor(
|
|
26
|
+
source: APIProvider<P, R>,
|
|
27
|
+
readonly token: string,
|
|
28
|
+
) {
|
|
29
|
+
super(source);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
override fetch(request: Request): Promise<Response> {
|
|
33
|
+
const authed = new Request(request, {
|
|
34
|
+
headers: { ...Object.fromEntries(request.headers), Authorization: `Bearer ${this.token}` },
|
|
35
|
+
});
|
|
36
|
+
return super.fetch(authed);
|
|
37
|
+
}
|
|
33
38
|
}
|
|
34
39
|
```
|
|
35
40
|
|
|
@@ -14,15 +14,13 @@ Place it just inside the network provider so everything above it works with vali
|
|
|
14
14
|
## Usage
|
|
15
15
|
|
|
16
16
|
```ts
|
|
17
|
-
import { ClientAPIProvider, ValidationAPIProvider } from "shelving/api"
|
|
17
|
+
import { ClientAPIProvider, ValidationAPIProvider } from "shelving/api";
|
|
18
18
|
|
|
19
|
-
const provider = new ValidationAPIProvider(
|
|
20
|
-
new ClientAPIProvider({ url: "https://api.example.com" })
|
|
21
|
-
)
|
|
19
|
+
const provider = new ValidationAPIProvider(new ClientAPIProvider({ url: "https://api.example.com" }));
|
|
22
20
|
|
|
23
21
|
// Payload validated against the endpoint's payload schema before sending;
|
|
24
22
|
// result validated against its result schema before returning.
|
|
25
|
-
const user = await provider.call(getUser, { id: "u_123" })
|
|
23
|
+
const user = await provider.call(getUser, { id: "u_123" });
|
|
26
24
|
```
|
|
27
25
|
|
|
28
26
|
|
|
@@ -14,12 +14,12 @@ Because it extends `ClientAPIProvider`, it is a concrete network provider: const
|
|
|
14
14
|
## Usage
|
|
15
15
|
|
|
16
16
|
```ts
|
|
17
|
-
import { XMLAPIProvider } from "shelving/api"
|
|
17
|
+
import { XMLAPIProvider } from "shelving/api";
|
|
18
18
|
|
|
19
|
-
const provider = new XMLAPIProvider({ url: "https://legacy.example.com" })
|
|
19
|
+
const provider = new XMLAPIProvider({ url: "https://legacy.example.com" });
|
|
20
20
|
|
|
21
21
|
// The result is the raw response text.
|
|
22
|
-
const xml = await provider.call(getFeed, { channel: "news" })
|
|
22
|
+
const xml = await provider.call(getFeed, { channel: "news" });
|
|
23
23
|
```
|
|
24
24
|
|
|
25
25
|
|
package/docs/api.md
CHANGED
|
@@ -14,11 +14,11 @@ An `Endpoint` is a declarative, typed description of a single API route. It capt
|
|
|
14
14
|
Factory functions (`GET()`, `POST()`, `PUT()`, `PATCH()`, `DELETE()`, `HEAD()`) create endpoints concisely:
|
|
15
15
|
|
|
16
16
|
```ts
|
|
17
|
-
import { GET, POST } from "shelving/api"
|
|
18
|
-
import { STRING, NUMBER } from "shelving/schema"
|
|
17
|
+
import { GET, POST } from "shelving/api";
|
|
18
|
+
import { STRING, NUMBER } from "shelving/schema";
|
|
19
19
|
|
|
20
|
-
const getUser = GET("/users/{id}", { id: STRING }, { name: STRING, age: NUMBER })
|
|
21
|
-
const createPost = POST("/posts", { title: STRING, body: STRING }, { id: STRING })
|
|
20
|
+
const getUser = GET("/users/{id}", { id: STRING }, { name: STRING, age: NUMBER });
|
|
21
|
+
const createPost = POST("/posts", { title: STRING, body: STRING }, { id: STRING });
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
For `GET` and `HEAD` requests, payload fields that don't fill a `{placeholder}` are appended as `?query` params. All other methods send a JSON body.
|
|
@@ -27,29 +27,36 @@ For `GET` and `HEAD` requests, payload fields that don't fill a `{placeholder}`
|
|
|
27
27
|
|
|
28
28
|
An `APIProvider` is the abstract interface for executing calls against endpoints. `ClientAPIProvider` is the concrete implementation that uses the global `fetch` API. Wrap it with `ThroughAPIProvider` subclasses to layer in behaviour without rewriting transport logic:
|
|
29
29
|
|
|
30
|
-
| Provider
|
|
31
|
-
|
|
32
|
-
| `ClientAPIProvider`
|
|
33
|
-
| `ThroughAPIProvider`
|
|
34
|
-
| `ValidationAPIProvider`
|
|
35
|
-
| `DebugAPIProvider`
|
|
36
|
-
| `JSONAPIProvider`
|
|
37
|
-
| `MockAPIProvider`
|
|
30
|
+
| Provider | Purpose |
|
|
31
|
+
| ------------------------- | ---------------------------------------------------------------- |
|
|
32
|
+
| `ClientAPIProvider` | Concrete base — sends requests over the network with `fetch()` |
|
|
33
|
+
| `ThroughAPIProvider` | Pass-through base for wrapping another provider |
|
|
34
|
+
| `ValidationAPIProvider` | Validates payload and result against endpoint schemas |
|
|
35
|
+
| `DebugAPIProvider` | Logs fetch attempts, results, and errors to the console |
|
|
36
|
+
| `JSONAPIProvider` | Forces JSON request bodies and JSON response parsing |
|
|
37
|
+
| `MockAPIProvider` | Records calls without sending network requests |
|
|
38
38
|
| `MockEndpointAPIProvider` | Dispatches calls through handler objects (useful for unit tests) |
|
|
39
|
-
| `XMLAPIProvider`
|
|
39
|
+
| `XMLAPIProvider` | Forces XML request bodies and returns raw text responses |
|
|
40
40
|
|
|
41
41
|
Extend `ThroughAPIProvider` to add custom behaviour such as auth headers:
|
|
42
42
|
|
|
43
43
|
```ts
|
|
44
|
-
import { ThroughAPIProvider } from "shelving/api"
|
|
44
|
+
import { ThroughAPIProvider } from "shelving/api";
|
|
45
45
|
|
|
46
46
|
class AuthAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
47
|
+
constructor(
|
|
48
|
+
source: APIProvider<P, R>,
|
|
49
|
+
readonly token: string,
|
|
50
|
+
) {
|
|
51
|
+
super(source);
|
|
52
|
+
}
|
|
53
|
+
override fetch(request: Request): Promise<Response> {
|
|
54
|
+
return super.fetch(
|
|
55
|
+
new Request(request, {
|
|
56
|
+
headers: { ...Object.fromEntries(request.headers), Authorization: `Bearer ${this.token}` },
|
|
57
|
+
}),
|
|
58
|
+
);
|
|
59
|
+
}
|
|
53
60
|
}
|
|
54
61
|
```
|
|
55
62
|
|
|
@@ -64,35 +71,32 @@ The cache is primarily useful as the backbone of the [React integration](#react-
|
|
|
64
71
|
### Define endpoints and fetch directly
|
|
65
72
|
|
|
66
73
|
```ts
|
|
67
|
-
import { GET, POST, ClientAPIProvider, ValidationAPIProvider } from "shelving/api"
|
|
68
|
-
import { DATA, STRING } from "shelving/schema"
|
|
74
|
+
import { GET, POST, ClientAPIProvider, ValidationAPIProvider } from "shelving/api";
|
|
75
|
+
import { DATA, STRING } from "shelving/schema";
|
|
69
76
|
|
|
70
|
-
const UserSchema = DATA({ id: STRING, name: STRING, email: STRING })
|
|
71
|
-
const getUser
|
|
72
|
-
const createUser = POST("/users", DATA({ name: STRING, email: STRING }), UserSchema)
|
|
77
|
+
const UserSchema = DATA({ id: STRING, name: STRING, email: STRING });
|
|
78
|
+
const getUser = GET("/users/{id}", DATA({ id: STRING }), UserSchema);
|
|
79
|
+
const createUser = POST("/users", DATA({ name: STRING, email: STRING }), UserSchema);
|
|
73
80
|
|
|
74
|
-
const provider = new ValidationAPIProvider(new ClientAPIProvider({ url: "https://api.example.com" }))
|
|
81
|
+
const provider = new ValidationAPIProvider(new ClientAPIProvider({ url: "https://api.example.com" }));
|
|
75
82
|
|
|
76
|
-
const user
|
|
77
|
-
const created = await provider.call(createUser, { name: "Alice", email: "alice@example.com" })
|
|
83
|
+
const user = await provider.call(getUser, { id: "u_123" });
|
|
84
|
+
const created = await provider.call(createUser, { name: "Alice", email: "alice@example.com" });
|
|
78
85
|
```
|
|
79
86
|
|
|
80
87
|
### Server-side routing
|
|
81
88
|
|
|
82
89
|
```ts
|
|
83
|
-
import { handleEndpoints } from "shelving/api"
|
|
90
|
+
import { handleEndpoints } from "shelving/api";
|
|
84
91
|
|
|
85
|
-
const handlers = [
|
|
86
|
-
getUser.handler(({ id }) => db.users.get(id)),
|
|
87
|
-
createUser.handler(({ name, email }) => db.users.create({ name, email })),
|
|
88
|
-
]
|
|
92
|
+
const handlers = [getUser.handler(({ id }) => db.users.get(id)), createUser.handler(({ name, email }) => db.users.create({ name, email }))];
|
|
89
93
|
|
|
90
94
|
// In a Cloudflare Worker or similar:
|
|
91
95
|
export default {
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
}
|
|
96
|
+
fetch(request: Request) {
|
|
97
|
+
return handleEndpoints("https://api.example.com", handlers, request);
|
|
98
|
+
},
|
|
99
|
+
};
|
|
96
100
|
```
|
|
97
101
|
|
|
98
102
|
### Testing with `MockEndpointAPIProvider`
|
|
@@ -100,10 +104,10 @@ export default {
|
|
|
100
104
|
Wires your handler array directly into a mock transport so you can test client and server code together without a real network:
|
|
101
105
|
|
|
102
106
|
```ts
|
|
103
|
-
import { MockEndpointAPIProvider } from "shelving/api"
|
|
107
|
+
import { MockEndpointAPIProvider } from "shelving/api";
|
|
104
108
|
|
|
105
|
-
const api = new MockEndpointAPIProvider(handlers, undefined)
|
|
106
|
-
const user = await api.call(getUser, { id: "u_123" })
|
|
109
|
+
const api = new MockEndpointAPIProvider(handlers, undefined);
|
|
110
|
+
const user = await api.call(getUser, { id: "u_123" });
|
|
107
111
|
```
|
|
108
112
|
|
|
109
113
|
## React integration
|
|
@@ -111,11 +115,11 @@ const user = await api.call(getUser, { id: "u_123" })
|
|
|
111
115
|
The `shelving/react` module's `createAPIContext()` is the primary way to use a provider in a React app. It creates a context backed by an `APICache` and exposes a typed `APIContext.useAPI()` hook that returns reactive `EndpointStore` instances and suspends automatically while loading.
|
|
112
116
|
|
|
113
117
|
```ts
|
|
114
|
-
import { createAPIContext } from "shelving/react"
|
|
115
|
-
import { ClientAPIProvider, ValidationAPIProvider } from "shelving/api"
|
|
118
|
+
import { createAPIContext } from "shelving/react";
|
|
119
|
+
import { ClientAPIProvider, ValidationAPIProvider } from "shelving/api";
|
|
116
120
|
|
|
117
|
-
const provider = new ValidationAPIProvider(new ClientAPIProvider({ url: "https://api.example.com" }))
|
|
118
|
-
export const { APIContext, useAPI } = createAPIContext(provider)
|
|
121
|
+
const provider = new ValidationAPIProvider(new ClientAPIProvider({ url: "https://api.example.com" }));
|
|
122
|
+
export const { APIContext, useAPI } = createAPIContext(provider);
|
|
119
123
|
```
|
|
120
124
|
|
|
121
125
|
See the `shelving/react` module for full usage.
|
package/docs/bun.md
CHANGED
|
@@ -26,11 +26,11 @@ import { PostgresMigrator } from "shelving/db";
|
|
|
26
26
|
import { USERS } from "./collections.js";
|
|
27
27
|
|
|
28
28
|
const sql = new SQL({
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
29
|
+
hostname: "localhost",
|
|
30
|
+
port: 5432,
|
|
31
|
+
database: "mydb",
|
|
32
|
+
username: "postgres",
|
|
33
|
+
password: "secret",
|
|
34
34
|
});
|
|
35
35
|
|
|
36
36
|
const provider = new BunPostgresProvider(sql);
|
|
@@ -48,10 +48,10 @@ await migrator.migrate(USERS);
|
|
|
48
48
|
|
|
49
49
|
```ts
|
|
50
50
|
await provider.transact(async tx => {
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
51
|
+
const from = await tx.requireItem(ACCOUNTS, "alice");
|
|
52
|
+
const to = await tx.requireItem(ACCOUNTS, "bob");
|
|
53
|
+
await tx.updateItem(ACCOUNTS, "alice", { balance: from.balance - 100 });
|
|
54
|
+
await tx.updateItem(ACCOUNTS, "bob", { balance: to.balance + 100 });
|
|
55
55
|
});
|
|
56
56
|
```
|
|
57
57
|
|
package/docs/db/DBProvider.md
CHANGED
|
@@ -19,10 +19,10 @@ Concrete backends implement the abstract methods; the base class derives `requir
|
|
|
19
19
|
Type code that accepts "any database" against `DBProvider` so an in-memory store, a validated chain, or a SQL backend are all interchangeable:
|
|
20
20
|
|
|
21
21
|
```ts
|
|
22
|
-
import type { DBProvider } from "shelving/db"
|
|
22
|
+
import type { DBProvider } from "shelving/db";
|
|
23
23
|
|
|
24
24
|
async function publishPost(provider: DBProvider, id: string) {
|
|
25
|
-
|
|
25
|
+
await provider.updateItem(POSTS, id, { published: true });
|
|
26
26
|
}
|
|
27
27
|
```
|
|
28
28
|
|
|
@@ -38,10 +38,10 @@ The derived reads (`requireItem`, `getFirst`, `requireFirst`) and the default `c
|
|
|
38
38
|
|
|
39
39
|
```ts
|
|
40
40
|
await provider.transact(async db => {
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
41
|
+
const from = await db.requireItem(ACCOUNTS, "alice");
|
|
42
|
+
const to = await db.requireItem(ACCOUNTS, "bob");
|
|
43
|
+
await db.updateItem(ACCOUNTS, "alice", { balance: from.balance - 100 });
|
|
44
|
+
await db.updateItem(ACCOUNTS, "bob", { balance: to.balance + 100 });
|
|
45
45
|
});
|
|
46
46
|
```
|
|
47
47
|
|
|
@@ -27,7 +27,7 @@ const post = await provider.getItem(POSTS, id);
|
|
|
27
27
|
|
|
28
28
|
// Realtime — emits whenever the item changes.
|
|
29
29
|
for await (const next of provider.getItemSequence(POSTS, id)) {
|
|
30
|
-
|
|
30
|
+
console.log(next);
|
|
31
31
|
}
|
|
32
32
|
```
|
|
33
33
|
|
|
@@ -50,8 +50,8 @@ table.setQueryTime({ user: "dave" }); // `items` is the complete answer to this
|
|
|
50
50
|
|
|
51
51
|
```ts
|
|
52
52
|
await provider.transact(async db => {
|
|
53
|
-
|
|
54
|
-
|
|
53
|
+
const post = await db.requireItem(POSTS, id);
|
|
54
|
+
await db.updateItem(POSTS, id, { title: `${post.title}!` });
|
|
55
55
|
});
|
|
56
56
|
```
|
|
57
57
|
|
|
@@ -16,10 +16,12 @@ It is abstract — a concrete subclass implements `exec()` against a specific Po
|
|
|
16
16
|
import { PostgresProvider } from "shelving/db";
|
|
17
17
|
|
|
18
18
|
class BunPostgresProvider extends PostgresProvider {
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
19
|
+
constructor(private sql: Bun.SQL) {
|
|
20
|
+
super();
|
|
21
|
+
}
|
|
22
|
+
async exec(strings, ...values) {
|
|
23
|
+
return this.sql(strings, ...values);
|
|
24
|
+
}
|
|
23
25
|
}
|
|
24
26
|
```
|
|
25
27
|
|
package/docs/db/SQLProvider.md
CHANGED
|
@@ -23,9 +23,12 @@ import { SQLiteProvider } from "shelving/db";
|
|
|
23
23
|
|
|
24
24
|
// A concrete subclass implements exec() against a specific driver.
|
|
25
25
|
class D1Provider extends SQLiteProvider {
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
26
|
+
async exec(strings, ...values) {
|
|
27
|
+
return this.db
|
|
28
|
+
.prepare(strings.join("?"))
|
|
29
|
+
.bind(...values)
|
|
30
|
+
.all();
|
|
31
|
+
}
|
|
29
32
|
}
|
|
30
33
|
```
|
|
31
34
|
|
|
@@ -20,10 +20,15 @@ It is abstract — a concrete subclass implements `exec()` against a specific SQ
|
|
|
20
20
|
import { SQLiteProvider } from "shelving/db";
|
|
21
21
|
|
|
22
22
|
class D1Provider extends SQLiteProvider {
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
23
|
+
constructor(private d1: D1Database) {
|
|
24
|
+
super();
|
|
25
|
+
}
|
|
26
|
+
async exec(strings, ...values) {
|
|
27
|
+
return this.d1
|
|
28
|
+
.prepare(strings.join("?"))
|
|
29
|
+
.bind(...values)
|
|
30
|
+
.all();
|
|
31
|
+
}
|
|
27
32
|
}
|
|
28
33
|
```
|
|
29
34
|
|
|
@@ -13,7 +13,7 @@ In-memory database provider that persists every collection to a `Storage` — `l
|
|
|
13
13
|
|
|
14
14
|
A `MemoryDBProvider` that persists every collection to a `Storage` — `localStorage`, `sessionStorage`, or anything else with the same interface. Each collection is hydrated from storage once, lazily, on first access — after that all reads, queries, and realtime sequences are served synchronously from memory, and every write persists to storage before it touches memory.
|
|
15
15
|
|
|
16
|
-
Because it
|
|
16
|
+
Because it _is_ a `MemoryDBProvider`, it plugs into everything that expects one: it seeds `ItemStore` / `QueryStore` synchronously (including via `DBCache` and the React hooks from `createDBContext()`), and `HydratingAPIProvider` can fill it, to give API results a persistent local copy.
|
|
17
17
|
|
|
18
18
|
`storage` events from other tabs/windows are applied to memory and notify realtime sequences, so `getItemSequence()` / `getQuerySequence()` update live across tabs.
|
|
19
19
|
|
|
@@ -55,7 +55,7 @@ Items persisted from an earlier visit show at once, but times are not persisted.
|
|
|
55
55
|
|
|
56
56
|
Treat the persisted data as best-effort, not guaranteed:
|
|
57
57
|
|
|
58
|
-
- **Quota** is shared across the whole origin (typically ~5MB) and a write can fail at any time with `QuotaExceededError`. The provider persists
|
|
58
|
+
- **Quota** is shared across the whole origin (typically ~5MB) and a write can fail at any time with `QuotaExceededError`. The provider persists _before_ updating memory, so a failed write throws and changes nothing — catch it at the app level to warn the user (e.g. "we can't save data locally right now").
|
|
59
59
|
- **Users can clear storage** at any time, and browsers may partition or restrict it.
|
|
60
60
|
- **Unusable storage** (writes blocked by browser settings, or private browsing with zero quota) makes the provider degrade to memory-only operation without throwing. Check `StorageDBProvider.persistent` to detect this and warn users their changes won't be saved.
|
|
61
61
|
- **Stored data is unvalidated** — it may have been written by an older version of your app. Wrap the provider in `ValidationDBProvider`, and use `shelving/db` migrations for upgrading old shapes.
|
|
@@ -23,12 +23,12 @@ Override only the methods you need and call `super` to delegate the rest:
|
|
|
23
23
|
import { ThroughDBProvider } from "shelving/db";
|
|
24
24
|
|
|
25
25
|
class TimingDBProvider extends ThroughDBProvider {
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
26
|
+
override async getItem(collection, id) {
|
|
27
|
+
const t = performance.now();
|
|
28
|
+
const result = await super.getItem(collection, id);
|
|
29
|
+
console.log(`getItem took ${performance.now() - t}ms`);
|
|
30
|
+
return result;
|
|
31
|
+
}
|
|
32
32
|
}
|
|
33
33
|
```
|
|
34
34
|
|
|
@@ -22,9 +22,9 @@ import { UndoDBProvider } from "shelving/db";
|
|
|
22
22
|
const local = new UndoDBProvider(memory);
|
|
23
23
|
await runServiceLogic(local); // Applies locally right away.
|
|
24
24
|
try {
|
|
25
|
-
|
|
25
|
+
await api.push(local.writes); // Send the writes to the server.
|
|
26
26
|
} catch {
|
|
27
|
-
|
|
27
|
+
await local.undo(); // Server failed — restore the local copy.
|
|
28
28
|
}
|
|
29
29
|
```
|
|
30
30
|
|