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
@@ -16,11 +16,11 @@ Typed helpers for reading, validating, and immutably transforming arrays. All im
16
16
  ```ts
17
17
  import { isArray, assertArray, requireArray } from "shelving/util";
18
18
 
19
- isArray(value); // true if Array
20
- isArray(value, 1); // true if Array with at least 1 item
21
- isArray(value, 2, 5); // true if Array with 2–5 items
19
+ isArray(value); // true if Array
20
+ isArray(value, 1); // true if Array with at least 1 item
21
+ isArray(value, 2, 5); // true if Array with 2–5 items
22
22
 
23
- assertArray(value, 1); // throws RequiredError if empty or not an array
23
+ assertArray(value, 1); // throws RequiredError if empty or not an array
24
24
  requireArray(iterable, 1); // converts iterable then asserts, returns ImmutableArray
25
25
  ```
26
26
 
@@ -29,26 +29,33 @@ requireArray(iterable, 1); // converts iterable then asserts, returns ImmutableA
29
29
  ```ts
30
30
  import { getFirst, requireFirst, getLast, requireLast, getNext, getPrev } from "shelving/util";
31
31
 
32
- getFirst([10, 20, 30]); // 10
33
- requireFirst([]); // throws RequiredError
34
- getLast([10, 20, 30]); // 30
35
- getNext([1, 2, 3], 2); // 3
36
- getPrev([1, 2, 3], 2); // 1
32
+ getFirst([10, 20, 30]); // 10
33
+ requireFirst([]); // throws RequiredError
34
+ getLast([10, 20, 30]); // 30
35
+ getNext([1, 2, 3], 2); // 3
36
+ getPrev([1, 2, 3], 2); // 1
37
37
  ```
38
38
 
39
39
  ### Immutable updates
40
40
 
41
41
  ```ts
42
- import { withArrayItem, withArrayItems, omitArrayItem, omitArrayItems,
43
- toggleArrayItem, withArrayIndex, omitArrayIndex } from "shelving/util";
44
-
45
- withArrayItem(["a", "b"], "c"); // ["a", "b", "c"]
46
- withArrayItem(["a", "b"], "b"); // same ref — already present
47
- omitArrayItem(["a", "b", "c"], "b"); // ["a", "c"]
48
- toggleArrayItem(["a", "b"], "b"); // ["a"]
49
- toggleArrayItem(["a", "b"], "c"); // ["a", "b", "c"]
50
- withArrayIndex([10, 20, 30], 1, 99); // [10, 99, 30]
51
- omitArrayIndex([10, 20, 30], 1); // [10, 30]
42
+ import {
43
+ withArrayItem,
44
+ withArrayItems,
45
+ omitArrayItem,
46
+ omitArrayItems,
47
+ toggleArrayItem,
48
+ withArrayIndex,
49
+ omitArrayIndex,
50
+ } from "shelving/util";
51
+
52
+ withArrayItem(["a", "b"], "c"); // ["a", "b", "c"]
53
+ withArrayItem(["a", "b"], "b"); // same ref — already present
54
+ omitArrayItem(["a", "b", "c"], "b"); // ["a", "c"]
55
+ toggleArrayItem(["a", "b"], "b"); // ["a"]
56
+ toggleArrayItem(["a", "b"], "c"); // ["a", "b", "c"]
57
+ withArrayIndex([10, 20, 30], 1, 99); // [10, 99, 30]
58
+ omitArrayIndex([10, 20, 30], 1); // [10, 30]
52
59
  ```
53
60
 
54
61
  ### Mutable updates (by reference)
@@ -57,22 +64,21 @@ omitArrayIndex([10, 20, 30], 1); // [10, 30]
57
64
  import { addArrayItem, addArrayItems, deleteArrayItem, deleteArrayItems } from "shelving/util";
58
65
 
59
66
  const arr = ["a", "b"];
60
- addArrayItem(arr, "c"); // arr is now ["a", "b", "c"]; returns "c"
61
- addArrayItem(arr, "b"); // no-op — already present
62
- deleteArrayItem(arr, "a"); // arr is now ["b", "c"]
67
+ addArrayItem(arr, "c"); // arr is now ["a", "b", "c"]; returns "c"
68
+ addArrayItem(arr, "b"); // no-op — already present
69
+ deleteArrayItem(arr, "a"); // arr is now ["b", "c"]
63
70
  ```
64
71
 
65
72
  ### Filtering and shaping
66
73
 
67
74
  ```ts
68
- import { getUniqueArray, limitArray, interleaveArray,
69
- pickArrayItems, shuffleArray } from "shelving/util";
75
+ import { getUniqueArray, limitArray, interleaveArray, pickArrayItems, shuffleArray } from "shelving/util";
70
76
 
71
- getUniqueArray([1, 2, 2, 3]); // [1, 2, 3]
72
- limitArray([1, 2, 3, 4, 5], 3); // [1, 2, 3]
77
+ getUniqueArray([1, 2, 2, 3]); // [1, 2, 3]
78
+ limitArray([1, 2, 3, 4, 5], 3); // [1, 2, 3]
73
79
  interleaveArray(["a", "b", "c"], ", "); // ["a", ", ", "b", ", ", "c"]
74
- pickArrayItems([1, 2, 3, 4], 2, 4); // [2, 4]
75
- shuffleArray([1, 2, 3]); // randomised copy
80
+ pickArrayItems([1, 2, 3, 4], 2, 4); // [2, 4]
81
+ shuffleArray([1, 2, 3]); // randomised copy
76
82
  ```
77
83
 
78
84
  ### Membership checks
@@ -80,7 +86,7 @@ shuffleArray([1, 2, 3]); // randomised copy
80
86
  ```ts
81
87
  import { isArrayItem, assertArrayItem } from "shelving/util";
82
88
 
83
- isArrayItem(["x", "y"], "x"); // true
89
+ isArrayItem(["x", "y"], "x"); // true
84
90
  assertArrayItem(["x", "y"], "z"); // throws RequiredError
85
91
  ```
86
92
 
@@ -15,8 +15,8 @@ Helpers for working with promises and async values: detecting sync/async values,
15
15
  ```ts
16
16
  import { isAsync, notAsync, throwAsync, assertAsync, assertNotAsync } from "shelving/util";
17
17
 
18
- isAsync(promise); // true
19
- notAsync("hello"); // true
18
+ isAsync(promise); // true
19
+ notAsync("hello"); // true
20
20
 
21
21
  // Suspense-style: throw the promise if async, return value if sync
22
22
  const value = throwAsync(maybePromise);
@@ -16,11 +16,11 @@ Encode and decode data to and from standard Base64 and URL-safe Base64 (Base64UR
16
16
  ```ts
17
17
  import { encodeBase64, decodeBase64String, decodeBase64Bytes } from "shelving/util";
18
18
 
19
- encodeBase64("hello"); // "aGVsbG8="
20
- encodeBase64("hello", false); // "aGVsbG8" (no padding)
19
+ encodeBase64("hello"); // "aGVsbG8="
20
+ encodeBase64("hello", false); // "aGVsbG8" (no padding)
21
21
 
22
22
  decodeBase64String("aGVsbG8="); // "hello"
23
- decodeBase64Bytes("aGVsbG8="); // Uint8Array
23
+ decodeBase64Bytes("aGVsbG8="); // Uint8Array
24
24
  ```
25
25
 
26
26
  ### URL-safe Base64 (Base64URL)
@@ -28,11 +28,11 @@ decodeBase64Bytes("aGVsbG8="); // Uint8Array
28
28
  ```ts
29
29
  import { encodeBase64URL, decodeBase64URLString, decodeBase64URLBytes } from "shelving/util";
30
30
 
31
- encodeBase64URL("hello"); // "aGVsbG8" (no padding by default)
32
- encodeBase64URL("hello", true); // "aGVsbG8="
31
+ encodeBase64URL("hello"); // "aGVsbG8" (no padding by default)
32
+ encodeBase64URL("hello", true); // "aGVsbG8="
33
33
 
34
- decodeBase64URLString("aGVsbG8"); // "hello"
35
- decodeBase64URLBytes("aGVsbG8"); // Uint8Array
34
+ decodeBase64URLString("aGVsbG8"); // "hello"
35
+ decodeBase64URLBytes("aGVsbG8"); // Uint8Array
36
36
  ```
37
37
 
38
38
  ### Encoding binary data
@@ -12,12 +12,12 @@ Type guards and assertion functions for boolean values. These follow the standar
12
12
  ```ts
13
13
  import { isBoolean, isTrue, isFalse, isTruthy, isFalsey } from "shelving/util";
14
14
 
15
- isBoolean(true); // true
16
- isBoolean(1); // false — 1 is not a boolean
17
- isTrue(true); // true
18
- isFalse(false); // true
15
+ isBoolean(true); // true
16
+ isBoolean(1); // false — 1 is not a boolean
17
+ isTrue(true); // true
18
+ isFalse(false); // true
19
19
  isTruthy("hello"); // true — any truthy value
20
- isFalsey(0); // true — any falsy value
20
+ isFalsey(0); // true — any falsy value
21
21
  ```
22
22
 
23
23
  ### Assertions
@@ -25,11 +25,11 @@ isFalsey(0); // true — any falsy value
25
25
  ```ts
26
26
  import { assertBoolean, assertTrue, assertFalse, assertTruthy, assertFalsy } from "shelving/util";
27
27
 
28
- assertBoolean(value); // throws RequiredError if not a boolean
29
- assertTrue(value); // throws RequiredError if not exactly true
30
- assertFalse(value); // throws RequiredError if not exactly false
31
- assertTruthy(value); // throws RequiredError if falsy
32
- assertFalsy(value); // throws RequiredError if truthy
28
+ assertBoolean(value); // throws RequiredError if not a boolean
29
+ assertTrue(value); // throws RequiredError if not exactly true
30
+ assertFalse(value); // throws RequiredError if not exactly false
31
+ assertTruthy(value); // throws RequiredError if falsy
32
+ assertFalsy(value); // throws RequiredError if truthy
33
33
  ```
34
34
 
35
35
 
@@ -10,15 +10,15 @@ Type guards for `ArrayBuffer`, `ArrayBufferView`, and typed arrays. Use these wh
10
10
  ```ts
11
11
  import { isBuffer, isBufferView, isTypedArray } from "shelving/util";
12
12
 
13
- isBuffer(new ArrayBuffer(8)); // true
14
- isBuffer(new Uint8Array(8)); // false — it's a view, not a buffer
13
+ isBuffer(new ArrayBuffer(8)); // true
14
+ isBuffer(new Uint8Array(8)); // false — it's a view, not a buffer
15
15
 
16
- isBufferView(new Uint8Array(8)); // true
17
- isBufferView(new DataView(buf)); // true
16
+ isBufferView(new Uint8Array(8)); // true
17
+ isBufferView(new DataView(buf)); // true
18
18
  isBufferView(new ArrayBuffer(8)); // false
19
19
 
20
20
  isTypedArray(new Float32Array(4)); // true
21
- isTypedArray(new DataView(buf)); // false — DataView is a view but not a typed array
21
+ isTypedArray(new DataView(buf)); // false — DataView is a view but not a typed array
22
22
  ```
23
23
 
24
24
  The `TypedArray` type exported from this file covers all numeric typed array classes (`Uint8Array`, `Uint16Array`, `Uint32Array`, `Int8Array`, `Int16Array`, `Int32Array`, `Float32Array`, `Float64Array`).
@@ -15,11 +15,11 @@ Type guards, conversion, and assertion for `Uint8Array<ArrayBuffer>` byte sequen
15
15
  ```ts
16
16
  import { isBytes, assertBytes } from "shelving/util";
17
17
 
18
- isBytes(new Uint8Array(4)); // true
18
+ isBytes(new Uint8Array(4)); // true
19
19
  isBytes(new Uint8Array(4).buffer); // false — that's an ArrayBuffer
20
20
 
21
- assertBytes(value); // throws RequiredError if not a Bytes
22
- assertBytes(value, 16, 64); // also enforces byte-length bounds
21
+ assertBytes(value); // throws RequiredError if not a Bytes
22
+ assertBytes(value, 16, 64); // also enforces byte-length bounds
23
23
  ```
24
24
 
25
25
  ### Converting to bytes
@@ -27,13 +27,13 @@ assertBytes(value, 16, 64); // also enforces byte-length bounds
27
27
  ```ts
28
28
  import { getBytes, requireBytes } from "shelving/util";
29
29
 
30
- getBytes("hello"); // Uint8Array (UTF-8)
31
- getBytes(new ArrayBuffer(8)); // Uint8Array wrapping the buffer
32
- getBytes(new Uint8Array([1, 2, 3])); // returned as-is
33
- getBytes(42); // undefined
30
+ getBytes("hello"); // Uint8Array (UTF-8)
31
+ getBytes(new ArrayBuffer(8)); // Uint8Array wrapping the buffer
32
+ getBytes(new Uint8Array([1, 2, 3])); // returned as-is
33
+ getBytes(42); // undefined
34
34
 
35
- requireBytes("hello"); // same as getBytes but throws on failure
36
- requireBytes(value, 8); // also requires at least 8 bytes
35
+ requireBytes("hello"); // same as getBytes but throws on failure
36
+ requireBytes(value, 8); // also requires at least 8 bytes
37
37
  ```
38
38
 
39
39
 
@@ -12,11 +12,11 @@ Type utilities and runtime helpers for working with class constructors and insta
12
12
  ```ts
13
13
  import { isConstructor, isInstance, assertInstance } from "shelving/util";
14
14
 
15
- isConstructor(class Foo {}); // true
16
- isConstructor(function () {}); // false — regular function, not a class
15
+ isConstructor(class Foo {}); // true
16
+ isConstructor(function () {}); // false — regular function, not a class
17
17
 
18
- isInstance(new Map(), Map); // true
19
- isInstance({}, Map); // false
18
+ isInstance(new Map(), Map); // true
19
+ isInstance({}, Map); // false
20
20
 
21
21
  assertInstance(value, MyClass); // throws RequiredError if not an instance
22
22
  ```
@@ -27,8 +27,12 @@ assertInstance(value, MyClass); // throws RequiredError if not an instance
27
27
  import { getGetter, getSetter } from "shelving/util";
28
28
 
29
29
  class MyClass {
30
- get name() { return this._name; }
31
- set name(v) { this._name = v; }
30
+ get name() {
31
+ return this._name;
32
+ }
33
+ set name(v) {
34
+ this._name = v;
35
+ }
32
36
  }
33
37
 
34
38
  const obj = new MyClass();
@@ -16,11 +16,11 @@ A `Color` class and accompanying helpers for parsing, representing, and converti
16
16
  ```ts
17
17
  import { getColor, requireColor } from "shelving/util";
18
18
 
19
- const c = getColor("#ff6600"); // Color instance
20
- const c2 = getColor("F60"); // 3-digit shorthand, no '#'
21
- getColor("not-a-color"); // undefined
19
+ const c = getColor("#ff6600"); // Color instance
20
+ const c2 = getColor("F60"); // 3-digit shorthand, no '#'
21
+ getColor("not-a-color"); // undefined
22
22
 
23
- requireColor("#ff6600"); // same but throws RequiredError on failure
23
+ requireColor("#ff6600"); // same but throws RequiredError on failure
24
24
  ```
25
25
 
26
26
  ### Converting and inspecting
@@ -29,12 +29,12 @@ requireColor("#ff6600"); // same but throws RequiredError on failure
29
29
  import { getColor } from "shelving/util";
30
30
 
31
31
  const c = getColor("#3399ff")!;
32
- c.hex; // "#3399ff"
33
- c.rgb; // "rgb(51, 153, 255)"
34
- c.rgba; // "rgba(51, 153, 255, 1)"
35
- c.luminance; // number
36
- c.isLight; // boolean
37
- c.isDark; // boolean
32
+ c.hex; // "#3399ff"
33
+ c.rgb; // "rgb(51, 153, 255)"
34
+ c.rgba; // "rgba(51, 153, 255, 1)"
35
+ c.luminance; // number
36
+ c.isLight; // boolean
37
+ c.isDark; // boolean
38
38
  ```
39
39
 
40
40
  ### Type guard and assertion
@@ -42,8 +42,8 @@ c.isDark; // boolean
42
42
  ```ts
43
43
  import { isColor, assertColor } from "shelving/util";
44
44
 
45
- isColor(value); // true if Color instance
46
- assertColor(value); // throws RequiredError if not
45
+ isColor(value); // true if Color instance
46
+ assertColor(value); // throws RequiredError if not
47
47
  ```
48
48
 
49
49
  ### Using the class directly
@@ -53,7 +53,7 @@ import { Color } from "shelving/util";
53
53
 
54
54
  const white = new Color(255, 255, 255);
55
55
  const transparent = new Color(0, 0, 0, 0);
56
- Color.from("#abc"); // same as getColor
56
+ Color.from("#abc"); // same as getColor
57
57
  ```
58
58
 
59
59
 
@@ -48,8 +48,8 @@ const formatted = `42${NNBSP}°C`;
48
48
  import { ABORT, NONE, SKIP } from "shelving/util";
49
49
 
50
50
  function process(value: unknown): string | typeof ABORT {
51
- if (cancelled) return ABORT;
52
- return String(value);
51
+ if (cancelled) return ABORT;
52
+ return String(value);
53
53
  }
54
54
  ```
55
55
 
@@ -23,7 +23,7 @@ const stored = await hashPassword("correct-horse-battery");
23
23
 
24
24
  // On sign-in — compare the plain-text password against the stored hash.
25
25
  const ok = await verifyPassword("correct-horse-battery", stored); // true
26
- const bad = await verifyPassword("wrong-password", stored); // false
26
+ const bad = await verifyPassword("wrong-password", stored); // false
27
27
  ```
28
28
 
29
29
  ### Generating random bytes
@@ -15,8 +15,8 @@ Validate ISO 4217 currency codes and retrieve display metadata (symbol, smallest
15
15
  ```ts
16
16
  import { getCurrencyCode, requireCurrencyCode, CURRENCY_CODES } from "shelving/util";
17
17
 
18
- getCurrencyCode("gbp"); // "GBP"
19
- getCurrencyCode("XYZ"); // undefined
18
+ getCurrencyCode("gbp"); // "GBP"
19
+ getCurrencyCode("XYZ"); // undefined
20
20
 
21
21
  requireCurrencyCode("GBP"); // "GBP"
22
22
  requireCurrencyCode("XYZ"); // throws RequiredError
package/docs/util/data.md CHANGED
@@ -17,8 +17,8 @@ The `Data` type and its helpers are the foundation of Shelving's data layer. A `
17
17
  import { isData, assertData } from "shelving/util";
18
18
 
19
19
  isData({ name: "Alice" }); // true
20
- isData(new Map()); // false
21
- isData(null); // false
20
+ isData(new Map()); // false
21
+ isData(null); // false
22
22
 
23
23
  assertData(value); // throws RequiredError if value is not a plain object
24
24
  ```
@@ -30,10 +30,10 @@ import { isDataProp, assertDataProp, getDataProps, getDataKeys } from "shelving/
30
30
 
31
31
  const doc = { name: "Alice", age: 30 };
32
32
 
33
- isDataProp(doc, "name"); // true
33
+ isDataProp(doc, "name"); // true
34
34
  isDataProp(doc, "email"); // false
35
35
 
36
- getDataKeys(doc); // ["name", "age"]
36
+ getDataKeys(doc); // ["name", "age"]
37
37
  getDataProps(doc); // [["name", "Alice"], ["age", 30]]
38
38
  ```
39
39
 
@@ -44,9 +44,9 @@ import { getDataProp, splitDataPath, joinDataPath } from "shelving/util";
44
44
 
45
45
  const doc = { user: { address: { city: "London" } } };
46
46
 
47
- getDataProp(doc, "user.address.city"); // "London"
48
- getDataProp(doc, ["user", "address", "city"]); // "London"
49
- getDataProp(doc, "user.missing.key"); // undefined
47
+ getDataProp(doc, "user.address.city"); // "London"
48
+ getDataProp(doc, ["user", "address", "city"]); // "London"
49
+ getDataProp(doc, "user.missing.key"); // undefined
50
50
 
51
51
  splitDataPath("user.address.city"); // ["user", "address", "city"]
52
52
  joinDataPath(["user", "address", "city"]); // "user.address.city"
@@ -56,17 +56,17 @@ joinDataPath(["user", "address", "city"]); // "user.address.city"
56
56
 
57
57
  `data.ts` exports a rich set of mapped types for working with typed data objects:
58
58
 
59
- | Type | Purpose |
60
- | ---- | ------- |
61
- | `Data` | Base plain-object type |
62
- | `PartialData<T>` | All keys optional |
63
- | `DataKey<T>` | Union of string keys |
64
- | `DataValue<T>` | Union of value types |
65
- | `LeafData<T>` | Flat object with only leaf paths |
66
- | `LeafDataPath<T>` | Union of dotted leaf paths |
67
- | `BranchData<T>` | Flat object including intermediate object paths |
68
- | `NestedData` | One level of nesting: `{ Group: { key: value } }` |
69
- | `FlatData<T>` | Flattened union of nested data |
59
+ | Type | Purpose |
60
+ | ----------------- | ------------------------------------------------- |
61
+ | `Data` | Base plain-object type |
62
+ | `PartialData<T>` | All keys optional |
63
+ | `DataKey<T>` | Union of string keys |
64
+ | `DataValue<T>` | Union of value types |
65
+ | `LeafData<T>` | Flat object with only leaf paths |
66
+ | `LeafDataPath<T>` | Union of dotted leaf paths |
67
+ | `BranchData<T>` | Flat object including intermediate object paths |
68
+ | `NestedData` | One level of nesting: `{ Group: { key: value } }` |
69
+ | `FlatData<T>` | Flattened union of nested data |
70
70
 
71
71
  ```ts
72
72
  import type { Data, LeafDataPath } from "shelving/util";
package/docs/util/date.md CHANGED
@@ -3,7 +3,7 @@
3
3
  - Kind: module
4
4
  - Import: `import { … } from "shelving/util/date";`
5
5
 
6
- Parse, validate, format, and manipulate dates. The central idea is `PossibleDate` — a value that *could* be a date — which the helpers accept everywhere so you rarely need to call `new Date()` yourself.
6
+ Parse, validate, format, and manipulate dates. The central idea is `PossibleDate` — a value that _could_ be a date — which the helpers accept everywhere so you rarely need to call `new Date()` yourself.
7
7
 
8
8
  - `getDate()` accepts `Date`, number (ms since epoch), date/time strings, and the convenience strings `"now"`, `"today"`, `"tomorrow"`, `"yesterday"`.
9
9
  - All string output is **local time**, not UTC — `getDateString()` produces `"2015-09-12"`, not an ISO UTC string.
@@ -17,16 +17,16 @@ Parse, validate, format, and manipulate dates. The central idea is `PossibleDate
17
17
  ```ts
18
18
  import { getDate, requireDate, isDate, assertDate } from "shelving/util";
19
19
 
20
- getDate("now"); // current Date
21
- getDate("today"); // midnight today
22
- getDate("tomorrow"); // midnight tomorrow
23
- getDate("2024-03-15"); // Date at that local date
24
- getDate("18:30"); // today at 18:30
25
- getDate(1710000000000); // Date from Unix ms timestamp
26
- getDate("not a date"); // undefined
20
+ getDate("now"); // current Date
21
+ getDate("today"); // midnight today
22
+ getDate("tomorrow"); // midnight tomorrow
23
+ getDate("2024-03-15"); // Date at that local date
24
+ getDate("18:30"); // today at 18:30
25
+ getDate(1710000000000); // Date from Unix ms timestamp
26
+ getDate("not a date"); // undefined
27
27
 
28
28
  requireDate("2024-03-15"); // Date or throws RequiredError
29
- isDate(new Date("bad")); // false
29
+ isDate(new Date("bad")); // false
30
30
  ```
31
31
 
32
32
  ### Formatting
@@ -35,9 +35,9 @@ isDate(new Date("bad")); // false
35
35
  import { getDateString, getTimeString, getDateTimeString } from "shelving/util";
36
36
  import { requireDateString, requireTimeString, requireDateTimeString } from "shelving/util";
37
37
 
38
- getDateString("now"); // "2024-03-15"
39
- getTimeString("now"); // "18:30:00"
40
- getDateTimeString("now"); // "2024-03-15T18:30:00"
38
+ getDateString("now"); // "2024-03-15"
39
+ getTimeString("now"); // "18:30:00"
40
+ getDateTimeString("now"); // "2024-03-15T18:30:00"
41
41
 
42
42
  // Throwing variants — useful when you know the value is valid:
43
43
  requireDateString("2024-01-01"); // "2024-01-01"
@@ -49,7 +49,7 @@ requireDateString("2024-01-01"); // "2024-01-01"
49
49
  import { getTimestamp, requireTimestamp } from "shelving/util";
50
50
 
51
51
  getTimestamp("2024-01-01"); // 1704067200000 (ms since epoch)
52
- requireTimestamp("now"); // current time in ms
52
+ requireTimestamp("now"); // current time in ms
53
53
  ```
54
54
 
55
55
  ### Anchor dates
@@ -57,11 +57,11 @@ requireTimestamp("now"); // current time in ms
57
57
  ```ts
58
58
  import { getNow, getToday, getTomorrow, getYesterday, getMidnight, getMonday, getMonthStart } from "shelving/util";
59
59
 
60
- getNow(); // current moment
61
- getToday(); // midnight today
60
+ getNow(); // current moment
61
+ getToday(); // midnight today
62
62
  getMidnight("2024-03-15"); // midnight on that date
63
- getMonday(); // midnight on Monday of current week
64
- getMonthStart(); // midnight on the 1st of current month
63
+ getMonday(); // midnight on Monday of current week
64
+ getMonthStart(); // midnight on the 1st of current month
65
65
  ```
66
66
 
67
67
  ### Day of week
@@ -70,7 +70,7 @@ getMonthStart(); // midnight on the 1st of current month
70
70
  import { getDay, DAYS } from "shelving/util";
71
71
 
72
72
  getDay("2024-03-15"); // "Friday"
73
- DAYS[0]; // "Sunday"
73
+ DAYS[0]; // "Sunday"
74
74
  ```
75
75
 
76
76
  ### Date arithmetic
@@ -78,10 +78,10 @@ DAYS[0]; // "Sunday"
78
78
  ```ts
79
79
  import { addDays, addWeeks, addMonths, addYears, addHours, addMinutes, addSeconds, addMilliseconds } from "shelving/util";
80
80
 
81
- addDays(7, "2024-03-01"); // 2024-03-08
82
- addMonths(1, "2024-01-31"); // 2024-02-29 (leap year) or 2024-02-28
83
- addYears(-1, "2024-02-29"); // 2023-02-28 (clamped, not a leap year)
84
- addHours(2, "now"); // 2 hours from now
81
+ addDays(7, "2024-03-01"); // 2024-03-08
82
+ addMonths(1, "2024-01-31"); // 2024-02-29 (leap year) or 2024-02-28
83
+ addYears(-1, "2024-02-29"); // 2023-02-28 (clamped, not a leap year)
84
+ addHours(2, "now"); // 2 hours from now
85
85
  ```
86
86
 
87
87
 
@@ -20,12 +20,12 @@ Convert any JavaScript value to a readable debug string. Use these when building
20
20
  ```ts
21
21
  import { debug } from "shelving/util";
22
22
 
23
- debug(null); // "null"
24
- debug(42); // "42"
25
- debug("hello\nworld"); // '"hello\\nworld"'
23
+ debug(null); // "null"
24
+ debug(42); // "42"
25
+ debug("hello\nworld"); // '"hello\\nworld"'
26
26
  debug(new Date("2024-01-01")); // "2024-01-01T00:00:00.000Z"
27
- debug([1, 2, 3]); // "[\n\t1,\n\t2,\n\t3\n]"
28
- debug({ a: 1 }, 0); // "{}" (depth 0 suppresses contents)
27
+ debug([1, 2, 3]); // "[\n\t1,\n\t2,\n\t3\n]"
28
+ debug({ a: 1 }, 0); // "{}" (depth 0 suppresses contents)
29
29
  ```
30
30
 
31
31
  ### Strings, objects, arrays, maps, sets
@@ -33,9 +33,9 @@ debug({ a: 1 }, 0); // "{}" (depth 0 suppresses contents)
33
33
  ```ts
34
34
  import { debugString, debugObject, debugArray, debugMap, debugSet } from "shelving/util";
35
35
 
36
- debugString('say "hi"'); // '"say \\"hi\\""'
37
- debugObject({ x: 1 }); // "{\n\t\"x\": 1\n}"
38
- debugArray([1, 2]); // "[\n\t1,\n\t2\n]"
36
+ debugString('say "hi"'); // '"say \\"hi\\""'
37
+ debugObject({ x: 1 }); // "{\n\t\"x\": 1\n}"
38
+ debugArray([1, 2]); // "[\n\t1,\n\t2\n]"
39
39
  ```
40
40
 
41
41
  ### HTTP requests and responses
@@ -44,8 +44,8 @@ debugArray([1, 2]); // "[\n\t1,\n\t2\n]"
44
44
  import { debugRequest, debugResponse, debugHeaders } from "shelving/util";
45
45
  import { debugFullRequest, debugFullResponse } from "shelving/util";
46
46
 
47
- debugRequest(req); // "GET https://example.com/api"
48
- debugResponse(res); // "200 OK"
47
+ debugRequest(req); // "GET https://example.com/api"
48
+ debugResponse(res); // "200 OK"
49
49
 
50
50
  // Async — includes headers and body:
51
51
  const full = await debugFullRequest(req);
@@ -57,8 +57,8 @@ const full2 = await debugFullResponse(res);
57
57
  ```ts
58
58
  import { indent } from "shelving/util";
59
59
 
60
- indent("single line"); // " single line" (leading space)
61
- indent("line1\nline2"); // "\n\tline1\n\tline2"
60
+ indent("single line"); // " single line" (leading space)
61
+ indent("line1\nline2"); // "\n\tline1\n\tline2"
62
62
  ```
63
63
 
64
64