shelving 1.322.0 → 1.322.2

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 (316) 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 +113 -85
  35. package/docs/guides/styleguide.md +29 -29
  36. package/docs/index.md +3 -2
  37. package/docs/llms-full.txt +2541 -2295
  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 +35 -26
  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 +42 -28
  88. package/docs/ui/Dialogs.md +4 -0
  89. package/docs/ui/DocumentationButtons.md +2 -2
  90. package/docs/ui/DocumentationCard.md +2 -2
  91. package/docs/ui/DocumentationFrame.md +4 -4
  92. package/docs/ui/DocumentationLive.md +11 -11
  93. package/docs/ui/DocumentationPage.md +3 -3
  94. package/docs/ui/Emphasis.md +4 -4
  95. package/docs/ui/Empty.md +2 -2
  96. package/docs/ui/FadeTransition.md +9 -9
  97. package/docs/ui/Field.md +14 -14
  98. package/docs/ui/FixedLayout.md +27 -25
  99. package/docs/ui/Form.md +41 -39
  100. package/docs/ui/FormStore.md +6 -2
  101. package/docs/ui/Grid.md +21 -9
  102. package/docs/ui/HTML.md +10 -8
  103. package/docs/ui/Head.md +2 -3
  104. package/docs/ui/Heading.md +12 -12
  105. package/docs/ui/HorizontalTransition.md +10 -10
  106. package/docs/ui/Icon.md +4 -4
  107. package/docs/ui/ImageInput.md +12 -12
  108. package/docs/ui/Inserted.md +6 -6
  109. package/docs/ui/Link.md +11 -11
  110. package/docs/ui/List.md +7 -7
  111. package/docs/ui/Loading.md +6 -6
  112. package/docs/ui/Mark.md +11 -9
  113. package/docs/ui/Markup.md +4 -4
  114. package/docs/ui/Menu.md +24 -24
  115. package/docs/ui/MenuItem.md +29 -29
  116. package/docs/ui/Modal.md +57 -45
  117. package/docs/ui/Navigation.md +28 -26
  118. package/docs/ui/NavigationStore.md +18 -18
  119. package/docs/ui/Notice.md +15 -15
  120. package/docs/ui/Notices.md +17 -17
  121. package/docs/ui/Page.md +13 -13
  122. package/docs/ui/Panel.md +8 -8
  123. package/docs/ui/Paragraph.md +5 -5
  124. package/docs/ui/Progress.md +11 -11
  125. package/docs/ui/Prose.md +6 -6
  126. package/docs/ui/QueryRadiosInput.md +2 -2
  127. package/docs/ui/RouteCache.md +27 -27
  128. package/docs/ui/Router.md +70 -61
  129. package/docs/ui/SchemaInput.md +20 -20
  130. package/docs/ui/Scroll.md +16 -16
  131. package/docs/ui/Section.md +13 -10
  132. package/docs/ui/SidebarLayout.md +27 -27
  133. package/docs/ui/Small.md +4 -4
  134. package/docs/ui/Span.md +3 -1
  135. package/docs/ui/StackButton.md +13 -7
  136. package/docs/ui/Strong.md +4 -4
  137. package/docs/ui/Subheading.md +12 -12
  138. package/docs/ui/TINT_CLASS.md +11 -11
  139. package/docs/ui/Table.md +40 -29
  140. package/docs/ui/Tag.md +15 -15
  141. package/docs/ui/Title.md +13 -13
  142. package/docs/ui/Transition.md +22 -22
  143. package/docs/ui/TreeApp.md +8 -8
  144. package/docs/ui/TreeMarkup.md +2 -2
  145. package/docs/ui/TreeMenu.md +3 -3
  146. package/docs/ui/TreeSidebar.md +1 -1
  147. package/docs/ui/VerticalTransition.md +8 -8
  148. package/docs/ui/getClass.md +10 -10
  149. package/docs/ui/getColorClass.md +23 -23
  150. package/docs/ui/getDurationClass.md +5 -5
  151. package/docs/ui/getGridClass.md +2 -2
  152. package/docs/ui/getHeightClass.md +4 -4
  153. package/docs/ui/getRadiusClass.md +9 -9
  154. package/docs/ui/getShadowClass.md +6 -6
  155. package/docs/ui/getSpaceClass.md +13 -13
  156. package/docs/ui/getStrokeClass.md +6 -6
  157. package/docs/ui/getTypographyClass.md +38 -38
  158. package/docs/ui/getWidthClass.md +4 -4
  159. package/docs/ui/notify.md +11 -11
  160. package/docs/ui/requireContext.md +1 -1
  161. package/docs/ui.md +4 -4
  162. package/docs/util/array.md +35 -29
  163. package/docs/util/async.md +2 -2
  164. package/docs/util/base64.md +7 -7
  165. package/docs/util/boolean.md +10 -10
  166. package/docs/util/buffer.md +5 -5
  167. package/docs/util/bytes.md +9 -9
  168. package/docs/util/class.md +10 -6
  169. package/docs/util/color.md +13 -13
  170. package/docs/util/constants.md +2 -2
  171. package/docs/util/crypto.md +1 -1
  172. package/docs/util/currency.md +2 -2
  173. package/docs/util/data.md +18 -18
  174. package/docs/util/date.md +22 -22
  175. package/docs/util/debug/debug.md +12 -12
  176. package/docs/util/dictionary.md +21 -18
  177. package/docs/util/diff.md +6 -6
  178. package/docs/util/dispose/dispose.md +5 -5
  179. package/docs/util/duration.md +9 -9
  180. package/docs/util/element.md +1 -1
  181. package/docs/util/entity.md +6 -6
  182. package/docs/util/entry.md +21 -8
  183. package/docs/util/env.md +2 -2
  184. package/docs/util/equal.md +16 -16
  185. package/docs/util/error.md +4 -4
  186. package/docs/util/file.md +8 -8
  187. package/docs/util/filter.md +9 -5
  188. package/docs/util/format.md +18 -18
  189. package/docs/util/function.md +4 -4
  190. package/docs/util/geo.md +13 -13
  191. package/docs/util/hash.md +3 -3
  192. package/docs/util/http.md +1 -1
  193. package/docs/util/hydrate/hydrate.md +7 -4
  194. package/docs/util/item.md +4 -4
  195. package/docs/util/iterate.md +11 -11
  196. package/docs/util/jwt.md +1 -6
  197. package/docs/util/link.md +5 -5
  198. package/docs/util/map.md +17 -11
  199. package/docs/util/merge.md +2 -5
  200. package/docs/util/null.md +20 -10
  201. package/docs/util/number.md +16 -16
  202. package/docs/util/object.md +25 -22
  203. package/docs/util/path.md +17 -17
  204. package/docs/util/query.md +23 -25
  205. package/docs/util/random.md +7 -7
  206. package/docs/util/regexp.md +16 -16
  207. package/docs/util/sequence.md +16 -10
  208. package/docs/util/serialise/serialise.md +6 -6
  209. package/docs/util/set.md +10 -10
  210. package/docs/util/sort.md +10 -11
  211. package/docs/util/source.md +11 -7
  212. package/docs/util/start.md +8 -8
  213. package/docs/util/string.md +14 -14
  214. package/docs/util/template.md +3 -3
  215. package/docs/util/timeout.md +5 -5
  216. package/docs/util/transform.md +6 -6
  217. package/docs/util/tree.md +13 -13
  218. package/docs/util/undefined.md +3 -3
  219. package/docs/util/units.md +15 -15
  220. package/docs/util/update.md +16 -16
  221. package/docs/util/uri.md +12 -12
  222. package/docs/util/url.md +11 -11
  223. package/docs/util/uuid.md +3 -3
  224. package/docs/util/validate.md +14 -9
  225. package/package.json +3 -3
  226. package/skills/shelving/SKILL.md +1 -0
  227. package/ui/README.md +4 -4
  228. package/ui/app/App.md +99 -69
  229. package/ui/block/Card.md +23 -22
  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 +42 -28
  242. package/ui/dialog/Dialogs.d.ts +4 -0
  243. package/ui/dialog/Dialogs.js +4 -0
  244. package/ui/dialog/Dialogs.tsx +4 -0
  245. package/ui/dialog/Modal.md +57 -45
  246. package/ui/docs/DocumentationButtons.md +2 -2
  247. package/ui/docs/DocumentationCard.md +2 -2
  248. package/ui/docs/DocumentationFrame.md +4 -4
  249. package/ui/docs/DocumentationLive.md +11 -11
  250. package/ui/docs/DocumentationPage.md +3 -3
  251. package/ui/form/Field.md +14 -14
  252. package/ui/form/Form.md +41 -39
  253. package/ui/form/FormStore.md +6 -2
  254. package/ui/form/Progress.md +11 -11
  255. package/ui/inline/Code.md +11 -11
  256. package/ui/inline/Deleted.md +6 -6
  257. package/ui/inline/Emphasis.md +4 -4
  258. package/ui/inline/Inserted.md +6 -6
  259. package/ui/inline/Link.md +11 -11
  260. package/ui/inline/Mark.md +11 -9
  261. package/ui/inline/Small.md +4 -4
  262. package/ui/inline/Span.md +3 -1
  263. package/ui/inline/Strong.md +4 -4
  264. package/ui/input/ImageInput.md +12 -12
  265. package/ui/input/QueryRadiosInput.md +2 -2
  266. package/ui/input/SchemaInput.md +20 -20
  267. package/ui/layout/AppLayout.md +35 -26
  268. package/ui/layout/AppLayout.module.css +3 -16
  269. package/ui/layout/FixedLayout.md +27 -25
  270. package/ui/layout/SidebarLayout.md +27 -27
  271. package/ui/layout/SidebarLayout.module.css +1 -0
  272. package/ui/menu/Menu.md +24 -24
  273. package/ui/menu/MenuItem.md +29 -29
  274. package/ui/misc/Catcher.md +3 -3
  275. package/ui/misc/Icon.md +4 -4
  276. package/ui/misc/Loading.md +6 -6
  277. package/ui/misc/Markup.md +4 -4
  278. package/ui/misc/Tag.md +15 -15
  279. package/ui/notice/Empty.md +2 -2
  280. package/ui/notice/Notice.md +15 -15
  281. package/ui/notice/Notices.md +17 -17
  282. package/ui/page/HTML.md +10 -8
  283. package/ui/page/Head.md +2 -3
  284. package/ui/page/Page.md +13 -13
  285. package/ui/router/BackButton.md +13 -11
  286. package/ui/router/Navigation.md +28 -26
  287. package/ui/router/NavigationStore.md +18 -18
  288. package/ui/router/RouteCache.md +27 -27
  289. package/ui/router/Router.md +70 -61
  290. package/ui/router/StackButton.md +13 -7
  291. package/ui/style/Scroll.md +16 -16
  292. package/ui/style/TINT_CLASS.md +11 -11
  293. package/ui/style/getColorClass.md +23 -23
  294. package/ui/style/getDurationClass.md +5 -5
  295. package/ui/style/getGridClass.md +2 -2
  296. package/ui/style/getHeightClass.md +4 -4
  297. package/ui/style/getRadiusClass.md +9 -9
  298. package/ui/style/getShadowClass.md +6 -6
  299. package/ui/style/getSpaceClass.md +13 -13
  300. package/ui/style/getStrokeClass.md +6 -6
  301. package/ui/style/getTypographyClass.md +38 -38
  302. package/ui/style/getWidthClass.md +4 -4
  303. package/ui/table/Table.md +40 -30
  304. package/ui/transition/CollapseTransition.md +5 -5
  305. package/ui/transition/FadeTransition.md +9 -9
  306. package/ui/transition/HorizontalTransition.md +10 -10
  307. package/ui/transition/Transition.md +22 -22
  308. package/ui/transition/VerticalTransition.md +8 -8
  309. package/ui/tree/TreeApp.md +8 -8
  310. package/ui/tree/TreeMarkup.md +2 -2
  311. package/ui/tree/TreeMenu.md +3 -3
  312. package/ui/tree/TreeSidebar.md +1 -1
  313. package/ui/util/ClassProps.md +1 -1
  314. package/ui/util/getClass.md +10 -10
  315. package/ui/util/notify.md +11 -11
  316. 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
- title: STRING,
20
- body: STRING,
21
- published: BOOLEAN,
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 | 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()` |
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
- title: STRING,
78
- body: STRING,
79
- published: BOOLEAN,
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
- published: true,
107
- $order: "title",
108
- $limit: 10,
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
- console.log(post) // emits whenever this item changes
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
- try {
19
- return await fetch(url);
20
- } catch {
21
- throw new NetworkError("Could not reach server");
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
- 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;
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
- if (!id) throw new RequiredError("User ID is required");
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
- if (!res.ok) throw new ResponseError(res.statusText, { code: res.status });
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
- throw new UnexpectedError("Unhandled case", { received: x });
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
- getQuery(): Promise<Items> {
19
- throw new UnsupportedError("KVProvider does not support querying items");
20
- }
18
+ getQuery(): Promise<Items> {
19
+ throw new UnsupportedError("KVProvider does not support querying items");
20
+ }
21
21
  }
22
22
  ```
23
23
 
@@ -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
- if (!isConfig(raw)) throw new ValueError("Invalid config from server", { received: raw });
20
- return raw;
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
- if (n <= 0) throw new ValueError("Value must be positive", {
22
- caller: requirePositive, // stack starts here, not inside ValueError
23
- received: n,
24
- expected: "> 0",
25
- });
26
- return n;
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 | When to throw |
33
- |---|---|
34
- | `RequiredError` | Something required was absent (also thrown by `require*()` helpers) |
35
- | `ValueError` | A value was present but invalid in context (e.g. data from a database failed validation) |
36
- | `NetworkError` | Network-level failure — connection refused, server unreachable |
37
- | `RequestError` | The request was malformed or unacceptable (HTTP 4xx range; `RequestError.code` defaults to `400`) |
38
- | `ResponseError` | The received response indicated an error (HTTP 4xx/5xx; `ResponseError.code` defaults to `400`) |
39
- | `UnexpectedError` | Something that should never happen did — an invariant was violated |
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
- received: status,
55
- expected: ["active", "inactive"],
56
- entity: "subscription",
57
- cause: originalError,
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 | 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 |
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 *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.
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
- extractors: { md: new MarkupExtractor() }, // file extension → extractor
91
- ignore: [/\.test\.tsx?$/i], // entries to skip
92
- base: "/abs/path", // base for resolving relative paths
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 *mappings* — wrap a subtree to swap a renderer for one element type:
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
- <TreeApp tree={root} />
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
- project: "my-project",
19
- token: () => auth.getAccessToken(), // e.g. from `google-auth-library`
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
- const post = await db.requireItem(POSTS, id);
26
- await db.updateItem(POSTS, id, { published: true, "+=views": 1 });
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
- project: "demo-project",
43
- host: `http://${process.env.FIRESTORE_EMULATOR_HOST}`,
42
+ project: "demo-project",
43
+ host: `http://${process.env.FIRESTORE_EMULATOR_HOST}`,
44
44
  });
45
45
  ```
46
46