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.
Files changed (313) hide show
  1. package/docs/api/APIProvider.md +2 -2
  2. package/docs/api/CachedAPIProvider.md +6 -8
  3. package/docs/api/ClientAPIProvider.md +5 -5
  4. package/docs/api/DebugAPIProvider.md +3 -5
  5. package/docs/api/HydratingAPIProvider.md +2 -2
  6. package/docs/api/JSONAPIProvider.md +3 -5
  7. package/docs/api/LoggingAPIProvider.md +7 -9
  8. package/docs/api/MockAPIProvider.md +4 -4
  9. package/docs/api/MockEndpointAPIProvider.md +5 -7
  10. package/docs/api/ThroughAPIProvider.md +15 -10
  11. package/docs/api/ValidationAPIProvider.md +3 -5
  12. package/docs/api/XMLAPIProvider.md +3 -3
  13. package/docs/api.md +48 -44
  14. package/docs/bun.md +9 -9
  15. package/docs/db/DBProvider.md +6 -6
  16. package/docs/db/MemoryDBProvider.md +3 -3
  17. package/docs/db/PostgresProvider.md +6 -4
  18. package/docs/db/SQLProvider.md +6 -3
  19. package/docs/db/SQLiteProvider.md +9 -4
  20. package/docs/db/StorageDBProvider.md +2 -2
  21. package/docs/db/ThroughDBProvider.md +6 -6
  22. package/docs/db/UndoDBProvider.md +2 -2
  23. package/docs/db.md +32 -32
  24. package/docs/error/NetworkError.md +5 -5
  25. package/docs/error/RequestError.md +4 -4
  26. package/docs/error/RequiredError.md +2 -2
  27. package/docs/error/ResponseError.md +1 -1
  28. package/docs/error/UnexpectedError.md +1 -1
  29. package/docs/error/UnsupportedError.md +3 -3
  30. package/docs/error/ValueError.md +2 -2
  31. package/docs/error.md +20 -19
  32. package/docs/extract.md +14 -14
  33. package/docs/firebase.md +6 -6
  34. package/docs/guides/building-with-shelving.md +112 -84
  35. package/docs/guides/styleguide.md +29 -29
  36. package/docs/index.md +3 -2
  37. package/docs/llms-full.txt +2531 -2291
  38. package/docs/markup.md +15 -17
  39. package/docs/react/createAPIContext.md +12 -12
  40. package/docs/react/createDBContext.md +21 -15
  41. package/docs/react/useInstance.md +2 -2
  42. package/docs/react/useLazy.md +1 -1
  43. package/docs/react/useMap.md +10 -6
  44. package/docs/react/useReduce.md +2 -2
  45. package/docs/react/useSequence.md +2 -2
  46. package/docs/react/useStore.md +10 -10
  47. package/docs/react.md +22 -16
  48. package/docs/schema/ArraySchema.md +6 -6
  49. package/docs/schema/BooleanSchema.md +5 -5
  50. package/docs/schema/ChoiceSchema.md +1 -1
  51. package/docs/schema/CurrencyAmountSchema.md +2 -2
  52. package/docs/schema/DataSchema.md +5 -5
  53. package/docs/schema/NullableSchema.md +4 -4
  54. package/docs/schema/NumberSchema.md +4 -4
  55. package/docs/schema/OptionalSchema.md +1 -1
  56. package/docs/schema/StringSchema.md +7 -7
  57. package/docs/schema.md +21 -21
  58. package/docs/sequence/DeferredSequence.md +1 -1
  59. package/docs/sequence/InspectSequence.md +8 -6
  60. package/docs/sequence/LazySequence.md +3 -3
  61. package/docs/sequence/Sequence.md +6 -6
  62. package/docs/sequence/ThroughSequence.md +4 -2
  63. package/docs/sequence.md +3 -3
  64. package/docs/store/ArrayStore.md +6 -6
  65. package/docs/store/BooleanStore.md +2 -2
  66. package/docs/store/BusyStore.md +1 -1
  67. package/docs/store/DataStore.md +5 -5
  68. package/docs/store/DictionaryStore.md +4 -4
  69. package/docs/store/FetchStore.md +6 -6
  70. package/docs/store/PathStore.md +4 -4
  71. package/docs/store/PayloadFetchStore.md +1 -5
  72. package/docs/store/Store.md +8 -6
  73. package/docs/store/URLStore.md +5 -5
  74. package/docs/store.md +15 -15
  75. package/docs/test.md +6 -6
  76. package/docs/ui/App.md +99 -69
  77. package/docs/ui/AppLayout.md +33 -24
  78. package/docs/ui/BackButton.md +13 -11
  79. package/docs/ui/Button.md +73 -64
  80. package/docs/ui/Card.md +23 -22
  81. package/docs/ui/Catcher.md +3 -3
  82. package/docs/ui/ClassProps.md +1 -1
  83. package/docs/ui/Code.md +11 -11
  84. package/docs/ui/CollapseTransition.md +5 -5
  85. package/docs/ui/Deleted.md +6 -6
  86. package/docs/ui/Details.md +13 -13
  87. package/docs/ui/Dialog.md +39 -27
  88. package/docs/ui/DocumentationButtons.md +2 -2
  89. package/docs/ui/DocumentationCard.md +2 -2
  90. package/docs/ui/DocumentationFrame.md +4 -4
  91. package/docs/ui/DocumentationLive.md +11 -11
  92. package/docs/ui/DocumentationPage.md +3 -3
  93. package/docs/ui/Emphasis.md +4 -4
  94. package/docs/ui/Empty.md +2 -2
  95. package/docs/ui/FadeTransition.md +9 -9
  96. package/docs/ui/Field.md +14 -14
  97. package/docs/ui/FixedLayout.md +27 -25
  98. package/docs/ui/Form.md +41 -39
  99. package/docs/ui/FormStore.md +6 -2
  100. package/docs/ui/Grid.md +21 -9
  101. package/docs/ui/HTML.md +10 -8
  102. package/docs/ui/Head.md +2 -3
  103. package/docs/ui/Heading.md +12 -12
  104. package/docs/ui/HorizontalTransition.md +10 -10
  105. package/docs/ui/Icon.md +4 -4
  106. package/docs/ui/ImageInput.md +12 -12
  107. package/docs/ui/Inserted.md +6 -6
  108. package/docs/ui/Link.md +11 -11
  109. package/docs/ui/List.md +7 -7
  110. package/docs/ui/Loading.md +6 -6
  111. package/docs/ui/Mark.md +11 -9
  112. package/docs/ui/Markup.md +4 -4
  113. package/docs/ui/Menu.md +24 -24
  114. package/docs/ui/MenuItem.md +29 -29
  115. package/docs/ui/Modal.md +57 -45
  116. package/docs/ui/Navigation.md +28 -26
  117. package/docs/ui/NavigationStore.md +18 -18
  118. package/docs/ui/Notice.md +15 -15
  119. package/docs/ui/Notices.md +17 -17
  120. package/docs/ui/Page.md +13 -13
  121. package/docs/ui/Panel.md +8 -8
  122. package/docs/ui/Paragraph.md +5 -5
  123. package/docs/ui/Progress.md +11 -11
  124. package/docs/ui/Prose.md +6 -6
  125. package/docs/ui/QueryRadiosInput.md +2 -2
  126. package/docs/ui/RouteCache.md +27 -27
  127. package/docs/ui/Router.md +70 -61
  128. package/docs/ui/SchemaInput.md +20 -20
  129. package/docs/ui/Scroll.md +16 -16
  130. package/docs/ui/Section.md +13 -10
  131. package/docs/ui/SidebarLayout.md +27 -27
  132. package/docs/ui/Small.md +4 -4
  133. package/docs/ui/Span.md +3 -1
  134. package/docs/ui/StackButton.md +13 -7
  135. package/docs/ui/Strong.md +4 -4
  136. package/docs/ui/Subheading.md +12 -12
  137. package/docs/ui/TINT_CLASS.md +11 -11
  138. package/docs/ui/Table.md +40 -29
  139. package/docs/ui/Tag.md +15 -15
  140. package/docs/ui/Title.md +13 -13
  141. package/docs/ui/Transition.md +22 -22
  142. package/docs/ui/TreeApp.md +8 -8
  143. package/docs/ui/TreeMarkup.md +2 -2
  144. package/docs/ui/TreeMenu.md +3 -3
  145. package/docs/ui/TreeSidebar.md +1 -1
  146. package/docs/ui/VerticalTransition.md +8 -8
  147. package/docs/ui/getClass.md +10 -10
  148. package/docs/ui/getColorClass.md +23 -23
  149. package/docs/ui/getDurationClass.md +5 -5
  150. package/docs/ui/getGridClass.md +2 -2
  151. package/docs/ui/getHeightClass.md +4 -4
  152. package/docs/ui/getRadiusClass.md +9 -9
  153. package/docs/ui/getShadowClass.md +6 -6
  154. package/docs/ui/getSpaceClass.md +13 -13
  155. package/docs/ui/getStrokeClass.md +6 -6
  156. package/docs/ui/getTypographyClass.md +38 -38
  157. package/docs/ui/getWidthClass.md +4 -4
  158. package/docs/ui/notify.md +11 -11
  159. package/docs/ui/requireContext.md +1 -1
  160. package/docs/ui.md +4 -4
  161. package/docs/util/array.md +35 -29
  162. package/docs/util/async.md +2 -2
  163. package/docs/util/base64.md +7 -7
  164. package/docs/util/boolean.md +10 -10
  165. package/docs/util/buffer.md +5 -5
  166. package/docs/util/bytes.md +9 -9
  167. package/docs/util/class.md +10 -6
  168. package/docs/util/color.md +13 -13
  169. package/docs/util/constants.md +2 -2
  170. package/docs/util/crypto.md +1 -1
  171. package/docs/util/currency.md +2 -2
  172. package/docs/util/data.md +18 -18
  173. package/docs/util/date.md +22 -22
  174. package/docs/util/debug/debug.md +12 -12
  175. package/docs/util/dictionary.md +21 -18
  176. package/docs/util/diff.md +6 -6
  177. package/docs/util/dispose/dispose.md +5 -5
  178. package/docs/util/duration.md +9 -9
  179. package/docs/util/element.md +1 -1
  180. package/docs/util/entity.md +6 -6
  181. package/docs/util/entry.md +21 -8
  182. package/docs/util/env.md +2 -2
  183. package/docs/util/equal.md +16 -16
  184. package/docs/util/error.md +4 -4
  185. package/docs/util/file.md +8 -8
  186. package/docs/util/filter.md +9 -5
  187. package/docs/util/format.md +18 -18
  188. package/docs/util/function.md +4 -4
  189. package/docs/util/geo.md +13 -13
  190. package/docs/util/hash.md +3 -3
  191. package/docs/util/http.md +1 -1
  192. package/docs/util/hydrate/hydrate.md +7 -4
  193. package/docs/util/item.md +4 -4
  194. package/docs/util/iterate.md +11 -11
  195. package/docs/util/jwt.md +1 -6
  196. package/docs/util/link.md +5 -5
  197. package/docs/util/map.md +17 -11
  198. package/docs/util/merge.md +2 -5
  199. package/docs/util/null.md +20 -10
  200. package/docs/util/number.md +16 -16
  201. package/docs/util/object.md +25 -22
  202. package/docs/util/path.md +17 -17
  203. package/docs/util/query.md +23 -25
  204. package/docs/util/random.md +7 -7
  205. package/docs/util/regexp.md +16 -16
  206. package/docs/util/sequence.md +16 -10
  207. package/docs/util/serialise/serialise.md +6 -6
  208. package/docs/util/set.md +10 -10
  209. package/docs/util/sort.md +10 -11
  210. package/docs/util/source.md +11 -7
  211. package/docs/util/start.md +8 -8
  212. package/docs/util/string.md +14 -14
  213. package/docs/util/template.md +3 -3
  214. package/docs/util/timeout.md +5 -5
  215. package/docs/util/transform.md +6 -6
  216. package/docs/util/tree.md +13 -13
  217. package/docs/util/undefined.md +3 -3
  218. package/docs/util/units.md +15 -15
  219. package/docs/util/update.md +16 -16
  220. package/docs/util/uri.md +12 -12
  221. package/docs/util/url.md +11 -11
  222. package/docs/util/uuid.md +3 -3
  223. package/docs/util/validate.md +14 -9
  224. package/package.json +3 -3
  225. package/skills/shelving/SKILL.md +1 -0
  226. package/ui/README.md +4 -4
  227. package/ui/app/App.md +99 -69
  228. package/ui/block/Card.md +23 -22
  229. package/ui/block/Card.module.css +10 -5
  230. package/ui/block/Details.md +13 -13
  231. package/ui/block/Grid.md +21 -9
  232. package/ui/block/Heading.md +12 -12
  233. package/ui/block/List.md +7 -7
  234. package/ui/block/Panel.md +8 -8
  235. package/ui/block/Paragraph.md +5 -5
  236. package/ui/block/Prose.md +6 -6
  237. package/ui/block/Section.md +13 -10
  238. package/ui/block/Subheading.md +12 -12
  239. package/ui/block/Title.md +13 -13
  240. package/ui/button/Button.md +73 -64
  241. package/ui/dialog/Dialog.md +39 -27
  242. package/ui/dialog/Modal.md +57 -45
  243. package/ui/docs/DocumentationButtons.md +2 -2
  244. package/ui/docs/DocumentationCard.md +2 -2
  245. package/ui/docs/DocumentationFrame.md +4 -4
  246. package/ui/docs/DocumentationLive.md +11 -11
  247. package/ui/docs/DocumentationPage.md +3 -3
  248. package/ui/form/Field.md +14 -14
  249. package/ui/form/Form.md +41 -39
  250. package/ui/form/FormStore.md +6 -2
  251. package/ui/form/Progress.md +11 -11
  252. package/ui/inline/Code.md +11 -11
  253. package/ui/inline/Deleted.md +6 -6
  254. package/ui/inline/Emphasis.md +4 -4
  255. package/ui/inline/Inserted.md +6 -6
  256. package/ui/inline/Link.md +11 -11
  257. package/ui/inline/Mark.md +11 -9
  258. package/ui/inline/Small.md +4 -4
  259. package/ui/inline/Span.md +3 -1
  260. package/ui/inline/Strong.md +4 -4
  261. package/ui/input/ImageInput.md +12 -12
  262. package/ui/input/QueryRadiosInput.md +2 -2
  263. package/ui/input/SchemaInput.md +20 -20
  264. package/ui/layout/AppLayout.md +33 -24
  265. package/ui/layout/AppLayout.module.css +1 -0
  266. package/ui/layout/FixedLayout.md +27 -25
  267. package/ui/layout/SidebarLayout.md +27 -27
  268. package/ui/layout/SidebarLayout.module.css +1 -0
  269. package/ui/menu/Menu.md +24 -24
  270. package/ui/menu/MenuItem.md +29 -29
  271. package/ui/misc/Catcher.md +3 -3
  272. package/ui/misc/Icon.md +4 -4
  273. package/ui/misc/Loading.md +6 -6
  274. package/ui/misc/Markup.md +4 -4
  275. package/ui/misc/Tag.md +15 -15
  276. package/ui/notice/Empty.md +2 -2
  277. package/ui/notice/Notice.md +15 -15
  278. package/ui/notice/Notices.md +17 -17
  279. package/ui/page/HTML.md +10 -8
  280. package/ui/page/Head.md +2 -3
  281. package/ui/page/Page.md +13 -13
  282. package/ui/router/BackButton.md +13 -11
  283. package/ui/router/Navigation.md +28 -26
  284. package/ui/router/NavigationStore.md +18 -18
  285. package/ui/router/RouteCache.md +27 -27
  286. package/ui/router/Router.md +70 -61
  287. package/ui/router/StackButton.md +13 -7
  288. package/ui/style/Scroll.md +16 -16
  289. package/ui/style/TINT_CLASS.md +11 -11
  290. package/ui/style/getColorClass.md +23 -23
  291. package/ui/style/getDurationClass.md +5 -5
  292. package/ui/style/getGridClass.md +2 -2
  293. package/ui/style/getHeightClass.md +4 -4
  294. package/ui/style/getRadiusClass.md +9 -9
  295. package/ui/style/getShadowClass.md +6 -6
  296. package/ui/style/getSpaceClass.md +13 -13
  297. package/ui/style/getStrokeClass.md +6 -6
  298. package/ui/style/getTypographyClass.md +38 -38
  299. package/ui/style/getWidthClass.md +4 -4
  300. package/ui/table/Table.md +40 -30
  301. package/ui/transition/CollapseTransition.md +5 -5
  302. package/ui/transition/FadeTransition.md +9 -9
  303. package/ui/transition/HorizontalTransition.md +10 -10
  304. package/ui/transition/Transition.md +22 -22
  305. package/ui/transition/VerticalTransition.md +8 -8
  306. package/ui/tree/TreeApp.md +8 -8
  307. package/ui/tree/TreeMarkup.md +2 -2
  308. package/ui/tree/TreeMenu.md +3 -3
  309. package/ui/tree/TreeSidebar.md +1 -1
  310. package/ui/util/ClassProps.md +1 -1
  311. package/ui/util/getClass.md +10 -10
  312. package/ui/util/notify.md +11 -11
  313. package/ui/util/requireContext.md +1 -1
@@ -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
- return provider.call(getUser, { id }); // works with any provider in the chain
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" }) // re-fetch eagerly
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
- url: "https://api.example.com",
25
- timeout: 10_000,
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
- squads: await getMySquads(user),
59
- members: { query: getMyMembersQuery(user), items: await getMyMembers(user) },
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
- new ClientAPIProvider({ url: "https://api.example.com" }),
27
- (request) => logger.info("api request", request.url),
28
- (response, request) => logger.info("api response", request.url, response.status),
29
- (reason, request) => logger.error("api error", request.url, reason),
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((request) => new Response(JSON.stringify({ id: "u_1", name: "Alice" })))
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
- constructor(source: APIProvider<P, R>, readonly token: string) { super(source) }
26
-
27
- override fetch(request: Request): Promise<Response> {
28
- const authed = new Request(request, {
29
- headers: { ...Object.fromEntries(request.headers), Authorization: `Bearer ${this.token}` },
30
- })
31
- return super.fetch(authed)
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 | 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 |
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` | Forces XML request bodies and returns raw text responses |
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
- constructor(source: APIProvider<P, R>, readonly token: string) { super(source) }
48
- override fetch(request: Request): Promise<Response> {
49
- return super.fetch(new Request(request, {
50
- headers: { ...Object.fromEntries(request.headers), Authorization: `Bearer ${this.token}` },
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 = GET("/users/{id}", DATA({ id: STRING }), UserSchema)
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 = await provider.call(getUser, { id: "u_123" })
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
- fetch(request: Request) {
93
- return handleEndpoints("https://api.example.com", handlers, request)
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
- hostname: "localhost",
30
- port: 5432,
31
- database: "mydb",
32
- username: "postgres",
33
- password: "secret",
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
- 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 });
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
 
@@ -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
- await provider.updateItem(POSTS, id, { published: true });
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
- 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 });
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
- console.log(next);
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
- const post = await db.requireItem(POSTS, id);
54
- await db.updateItem(POSTS, id, { title: `${post.title}!` });
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
- constructor(private sql: Bun.SQL) { super(); }
20
- async exec(strings, ...values) {
21
- return this.sql(strings, ...values);
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
 
@@ -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
- async exec(strings, ...values) {
27
- return this.db.prepare(strings.join("?")).bind(...values).all();
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
- constructor(private d1: D1Database) { super(); }
24
- async exec(strings, ...values) {
25
- return this.d1.prepare(strings.join("?")).bind(...values).all();
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 *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.
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 *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").
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
- 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
- }
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
- await api.push(local.writes); // Send the writes to the server.
25
+ await api.push(local.writes); // Send the writes to the server.
26
26
  } catch {
27
- await local.undo(); // Server failed — restore the local copy.
27
+ await local.undo(); // Server failed — restore the local copy.
28
28
  }
29
29
  ```
30
30