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
@@ -19,10 +19,16 @@ Helpers for working with `AsyncIterable` sequences — repeating, driving, mergi
19
19
  import { runSequence } from "shelving/util";
20
20
 
21
21
  const stop = runSequence(
22
- myAsyncIterable,
23
- value => { console.log("next:", value); },
24
- err => { console.error("error:", err); },
25
- final => { console.log("done:", final); },
22
+ myAsyncIterable,
23
+ value => {
24
+ console.log("next:", value);
25
+ },
26
+ err => {
27
+ console.error("error:", err);
28
+ },
29
+ final => {
30
+ console.log("done:", final);
31
+ },
26
32
  );
27
33
 
28
34
  // Later, cancel it:
@@ -37,7 +43,7 @@ import { repeatUntil } from "shelving/util";
37
43
  const abortPromise = new Promise<void>(resolve => setTimeout(resolve, 5000));
38
44
 
39
45
  for await (const value of repeatUntil(myAsyncIterable, abortPromise)) {
40
- console.log(value); // stops after 5 seconds
46
+ console.log(value); // stops after 5 seconds
41
47
  }
42
48
  ```
43
49
 
@@ -47,7 +53,7 @@ for await (const value of repeatUntil(myAsyncIterable, abortPromise)) {
47
53
  import { repeatDelay } from "shelving/util";
48
54
 
49
55
  for await (const count of repeatDelay(1000)) {
50
- console.log("tick", count); // fires every 1 second, forever
56
+ console.log("tick", count); // fires every 1 second, forever
51
57
  }
52
58
  ```
53
59
 
@@ -57,7 +63,7 @@ for await (const count of repeatDelay(1000)) {
57
63
  import { callSequence } from "shelving/util";
58
64
 
59
65
  for await (const item of callSequence(myAsyncIterable, item => analytics.track(item))) {
60
- // item is yielded unchanged after the callback runs
66
+ // item is yielded unchanged after the callback runs
61
67
  }
62
68
  ```
63
69
 
@@ -67,7 +73,7 @@ for await (const item of callSequence(myAsyncIterable, item => analytics.track(i
67
73
  import { mergeSequences } from "shelving/util";
68
74
 
69
75
  for await (const item of mergeSequences(sequenceA, sequenceB)) {
70
- // exhausts sequenceA, then exhausts sequenceB
76
+ // exhausts sequenceA, then exhausts sequenceB
71
77
  }
72
78
  ```
73
79
 
@@ -76,8 +82,8 @@ for await (const item of mergeSequences(sequenceA, sequenceB)) {
76
82
  ```ts
77
83
  import { isSequence } from "shelving/util";
78
84
 
79
- isSequence(myAsyncIterable); // true
80
- isSequence([1, 2, 3]); // false (sync iterables are not async iterables)
85
+ isSequence(myAsyncIterable); // true
86
+ isSequence([1, 2, 3]); // false (sync iterables are not async iterables)
81
87
  ```
82
88
 
83
89
 
@@ -25,11 +25,11 @@ A single `serialise()` function that converts any JavaScript value to a stable,
25
25
  import { serialise } from "shelving/util";
26
26
 
27
27
  // Primitives
28
- serialise(true); // "true"
29
- serialise(42); // "42"
30
- serialise("hello"); // '"hello"'
31
- serialise(null); // "null"
32
- serialise(undefined); // '{"$type":"undefined"}'
28
+ serialise(true); // "true"
29
+ serialise(42); // "42"
30
+ serialise("hello"); // '"hello"'
31
+ serialise(null); // "null"
32
+ serialise(undefined); // '{"$type":"undefined"}'
33
33
 
34
34
  // Arrays
35
35
  serialise([1, "two", null]); // '[1,"two",null]'
@@ -41,7 +41,7 @@ serialise({ b: 2, a: 1 }); // '{"a":1,"b":2}'
41
41
  serialise(new Date("2024-01-01")); // '{"$type":"Date","value":"Mon Jan 01 2024 ..."}'
42
42
 
43
43
  // Symbols and functions
44
- serialise(Symbol("tag")); // '{"$type":"symbol","description":"tag"}'
44
+ serialise(Symbol("tag")); // '{"$type":"symbol","description":"tag"}'
45
45
  serialise(function foo() {}); // '{"$type":"function","name":"foo"}'
46
46
  ```
47
47
 
package/docs/util/set.md CHANGED
@@ -18,11 +18,11 @@ Typed helpers for working with JavaScript `Set` objects. Covers type guards, con
18
18
  ```ts
19
19
  import { isSet, assertSet, getSet } from "shelving/util";
20
20
 
21
- isSet(new Set([1, 2])); // true
22
- isSet([1, 2]); // false
23
- assertSet("oops"); // throws RequiredError
21
+ isSet(new Set([1, 2])); // true
22
+ isSet([1, 2]); // false
23
+ assertSet("oops"); // throws RequiredError
24
24
 
25
- getSet([1, 2, 2, 3]); // Set { 1, 2, 3 } (deduplicates)
25
+ getSet([1, 2, 2, 3]); // Set { 1, 2, 3 } (deduplicates)
26
26
  getSet(new Set([1, 2])); // same reference returned
27
27
  ```
28
28
 
@@ -33,8 +33,8 @@ import { isSetItem, assertSetItem } from "shelving/util";
33
33
 
34
34
  const roles = new Set(["admin", "editor"]);
35
35
 
36
- isSetItem(roles, "admin"); // true
37
- isSetItem(roles, "guest"); // false
36
+ isSetItem(roles, "admin"); // true
37
+ isSetItem(roles, "guest"); // false
38
38
  assertSetItem(roles, "guest"); // throws RequiredError
39
39
  ```
40
40
 
@@ -45,9 +45,9 @@ import { addSetItem, addSetItems, deleteSetItems } from "shelving/util";
45
45
 
46
46
  const s: Set<string> = new Set();
47
47
 
48
- addSetItem(s, "a"); // adds "a", returns "a"
49
- addSetItems(s, "b", "c"); // adds "b" and "c"
50
- deleteSetItems(s, "a", "b"); // removes "a" and "b"
48
+ addSetItem(s, "a"); // adds "a", returns "a"
49
+ addSetItems(s, "b", "c"); // adds "b" and "c"
50
+ deleteSetItems(s, "a", "b"); // removes "a" and "b"
51
51
  ```
52
52
 
53
53
  ### Limiting a set
@@ -56,7 +56,7 @@ deleteSetItems(s, "a", "b"); // removes "a" and "b"
56
56
  import { limitSet } from "shelving/util";
57
57
 
58
58
  const s = new Set([1, 2, 3, 4, 5]);
59
- limitSet(s, 3); // Set { 1, 2, 3 }
59
+ limitSet(s, 3); // Set { 1, 2, 3 }
60
60
  limitSet(s, 10); // same Set reference (no copy needed)
61
61
  ```
62
62
 
package/docs/util/sort.md CHANGED
@@ -19,12 +19,12 @@ A quicksort implementation and type-aware comparators that handle mixed-type val
19
19
  ```ts
20
20
  import { sortArray } from "shelving/util";
21
21
 
22
- sortArray([3, 1, 2]); // [1, 2, 3]
23
- sortArray(["banana", "apple"]); // ["apple", "banana"]
24
- sortArray([true, null, 1, "a"]); // [1, "a", true, null] (cross-type order)
22
+ sortArray([3, 1, 2]); // [1, 2, 3]
23
+ sortArray(["banana", "apple"]); // ["apple", "banana"]
24
+ sortArray([true, null, 1, "a"]); // [1, "a", true, null] (cross-type order)
25
25
 
26
26
  // Iterable input is materialised to an array
27
- sortArray(new Set([3, 1, 2])); // [1, 2, 3]
27
+ sortArray(new Set([3, 1, 2])); // [1, 2, 3]
28
28
  ```
29
29
 
30
30
  ### Sorting descending
@@ -32,7 +32,7 @@ sortArray(new Set([3, 1, 2])); // [1, 2, 3]
32
32
  ```ts
33
33
  import { sortArray, compareDescending } from "shelving/util";
34
34
 
35
- sortArray([1, 3, 2], compareDescending); // [3, 2, 1]
35
+ sortArray([1, 3, 2], compareDescending); // [3, 2, 1]
36
36
  ```
37
37
 
38
38
  ### Custom comparator with extra arguments
@@ -43,8 +43,7 @@ import type { Compare } from "shelving/util";
43
43
 
44
44
  type Item = { name: string; score: number };
45
45
 
46
- const byField: Compare<Item, [keyof Item]> = (a, b, field) =>
47
- String(a[field]).localeCompare(String(b[field]));
46
+ const byField: Compare<Item, [keyof Item]> = (a, b, field) => String(a[field]).localeCompare(String(b[field]));
48
47
 
49
48
  sortArray(items, byField, "score");
50
49
  sortArray(items, byField, "name");
@@ -55,10 +54,10 @@ sortArray(items, byField, "name");
55
54
  ```ts
56
55
  import { compareAscending, compareDescending } from "shelving/util";
57
56
 
58
- compareAscending(1, 2); // negative (1 comes before 2)
59
- compareAscending("b", "a"); // positive ("b" comes after "a")
60
- compareAscending(1, 1); // 0
61
- compareDescending(1, 2); // positive (reversed)
57
+ compareAscending(1, 2); // negative (1 comes before 2)
58
+ compareAscending("b", "a"); // positive ("b" comes after "a")
59
+ compareAscending(1, 1); // 0
60
+ compareDescending(1, 2); // positive (reversed)
62
61
  ```
63
62
 
64
63
 
@@ -17,24 +17,28 @@ Two helpers for traversing a chain of `Sourceable` objects — objects with a `.
17
17
  import { getSource, requireSource } from "shelving/util";
18
18
  import type { Sourceable } from "shelving/util";
19
19
 
20
- class Database { query() { /* ... */ } }
20
+ class Database {
21
+ query() {
22
+ /* ... */
23
+ }
24
+ }
21
25
 
22
26
  class CachedDatabase implements Sourceable<Database> {
23
- constructor(readonly source: Database) {}
27
+ constructor(readonly source: Database) {}
24
28
  }
25
29
 
26
30
  class LoggedDatabase implements Sourceable<CachedDatabase> {
27
- constructor(readonly source: CachedDatabase) {}
31
+ constructor(readonly source: CachedDatabase) {}
28
32
  }
29
33
 
30
34
  const db = new LoggedDatabase(new CachedDatabase(new Database()));
31
35
 
32
- getSource(Database, db); // the inner Database instance
36
+ getSource(Database, db); // the inner Database instance
33
37
  getSource(CachedDatabase, db); // the CachedDatabase instance
34
- getSource(Database, {}); // undefined (no .source chain)
38
+ getSource(Database, {}); // undefined (no .source chain)
35
39
 
36
- requireSource(Database, db); // the inner Database instance
37
- requireSource(Database, "oops"); // throws RequiredError
40
+ requireSource(Database, db); // the inner Database instance
41
+ requireSource(Database, "oops"); // throws RequiredError
38
42
  ```
39
43
 
40
44
 
@@ -13,13 +13,13 @@ Manage processes that have a start callback and an optional stop callback. `Star
13
13
  import { Starter } from "shelving/util";
14
14
 
15
15
  const starter = new Starter(() => {
16
- const id = setInterval(tick, 1000);
17
- return () => clearInterval(id); // returned function is the stop callback
16
+ const id = setInterval(tick, 1000);
17
+ return () => clearInterval(id); // returned function is the stop callback
18
18
  });
19
19
 
20
20
  starter.start(); // begins the interval
21
21
  starter.start(); // no-op — already started
22
- starter.stop(); // calls the stop callback
22
+ starter.stop(); // calls the stop callback
23
23
  ```
24
24
 
25
25
  ### Using as a disposable
@@ -28,9 +28,9 @@ starter.stop(); // calls the stop callback
28
28
 
29
29
  ```ts
30
30
  {
31
- using starter = new Starter(myStartCallback);
32
- starter.start();
33
- // starter.stop() called automatically when block exits
31
+ using starter = new Starter(myStartCallback);
32
+ starter.start();
33
+ // starter.stop() called automatically when block exits
34
34
  }
35
35
  ```
36
36
 
@@ -40,8 +40,8 @@ starter.stop(); // calls the stop callback
40
40
  import { getStarter, type PossibleStarter } from "shelving/util";
41
41
 
42
42
  function setup(s: PossibleStarter<[]>) {
43
- const starter = getStarter(s); // wraps a function; passes a Starter through unchanged
44
- starter.start();
43
+ const starter = getStarter(s); // wraps a function; passes a Starter through unchanged
44
+ starter.start();
45
45
  }
46
46
  ```
47
47
 
@@ -20,13 +20,13 @@ Core helpers for checking, converting, sanitising, and transforming strings. Use
20
20
  ```ts
21
21
  import { isString, getString, requireString } from "shelving/util";
22
22
 
23
- isString("hi"); // true
24
- isString(42); // false
23
+ isString("hi"); // true
24
+ isString(42); // false
25
25
 
26
- getString(42); // "42"
27
- getString(true); // "true"
26
+ getString(42); // "42"
27
+ getString(true); // "true"
28
28
  getString(new Date()); // ISO string e.g. "2024-01-15T00:00:00.000Z"
29
- getString({}); // undefined
29
+ getString({}); // undefined
30
30
  ```
31
31
 
32
32
  ### Length checks
@@ -35,7 +35,7 @@ getString({}); // undefined
35
35
  import { isStringLength, assertStringLength } from "shelving/util";
36
36
 
37
37
  isStringLength("hello", 1, 10); // true
38
- isStringLength("", 1); // false
38
+ isStringLength("", 1); // false
39
39
  ```
40
40
 
41
41
  ### Sanitising user input
@@ -43,7 +43,7 @@ isStringLength("", 1); // false
43
43
  ```ts
44
44
  import { sanitizeText, sanitizeMultilineText } from "shelving/util";
45
45
 
46
- sanitizeText(" Hello\x00 World "); // "Hello World"
46
+ sanitizeText(" Hello\x00 World "); // "Hello World"
47
47
  sanitizeMultilineText("line1\r\nline2\n\n\nline3"); // "line1\nline2\n\nline3"
48
48
  ```
49
49
 
@@ -53,10 +53,10 @@ sanitizeMultilineText("line1\r\nline2\n\n\nline3"); // "line1\nline2\n\nline3"
53
53
  import { simplifyString, getSlug, requireSlug, getRef } from "shelving/util";
54
54
 
55
55
  simplifyString("Héllo Wörld! 😂"); // "hello world"
56
- getSlug("Hello World!"); // "hello-world"
57
- getSlug("!!!"); // undefined (empty after simplification)
58
- requireSlug("!!!"); // throws RequiredError
59
- getRef("Hello World"); // "helloworld" (no separator)
56
+ getSlug("Hello World!"); // "hello-world"
57
+ getSlug("!!!"); // undefined (empty after simplification)
58
+ requireSlug("!!!"); // throws RequiredError
59
+ getRef("Hello World"); // "helloworld" (no separator)
60
60
  ```
61
61
 
62
62
  ### Word splitting and limiting
@@ -64,10 +64,10 @@ getRef("Hello World"); // "helloworld" (no separator)
64
64
  ```ts
65
65
  import { getWords, limitString, splitString, getFirstLine } from "shelving/util";
66
66
 
67
- getWords(`hello "world foo" bar`); // ["hello", "world foo", "bar"]
67
+ getWords(`hello "world foo" bar`); // ["hello", "world foo", "bar"]
68
68
  limitString("A long string here", 10); // "A long…"
69
- splitString("a/b/c", "/", 2); // ["a", "b/c"] — excess joins last segment
70
- getFirstLine("line one\nline two"); // "line one"
69
+ splitString("a/b/c", "/", 2); // ["a", "b/c"] — excess joins last segment
70
+ getFirstLine("line one\nline two"); // "line one"
71
71
  ```
72
72
 
73
73
  ### Joining
@@ -71,9 +71,9 @@ renderTemplate("{name}-{date}", { name: "Dave" });
71
71
  ```ts
72
72
  import { getPlaceholders } from "shelving/util";
73
73
 
74
- getPlaceholders("{username}@{domain}"); // ["username", "domain"]
75
- getPlaceholders(":country/:city"); // ["country", "city"]
76
- getPlaceholders("*-*"); // ["0", "1"]
74
+ getPlaceholders("{username}@{domain}"); // ["username", "domain"]
75
+ getPlaceholders(":country/:city"); // ["country", "city"]
76
+ getPlaceholders("*-*"); // ["0", "1"]
77
77
  ```
78
78
 
79
79
 
@@ -19,11 +19,11 @@ import { Timeout } from "shelving/util";
19
19
  // Create with a default callback and delay.
20
20
  const t = new Timeout(() => console.log("done!"), 500);
21
21
 
22
- t.set(); // starts a 500 ms timer
23
- t.set(); // cancels the previous timer, starts a fresh 500 ms timer
24
- t.exists; // true
25
- t.clear(); // cancels the timer
26
- t.exists; // false
22
+ t.set(); // starts a 500 ms timer
23
+ t.set(); // cancels the previous timer, starts a fresh 500 ms timer
24
+ t.exists; // true
25
+ t.clear(); // cancels the timer
26
+ t.exists; // false
27
27
 
28
28
  // Override callback or delay per call.
29
29
  t.set(() => save(), 1000);
@@ -33,10 +33,7 @@ import { mapProps, transformObject } from "shelving/util";
33
33
  mapProps({ a: 1, b: 2 }, ([, v]) => v * 10); // { a: 10, b: 20 }
34
34
 
35
35
  // Selectively transform named properties; same ref returned if nothing changed.
36
- const result = transformObject(
37
- { name: "dave", age: 30 },
38
- { name: s => s.toUpperCase() },
39
- ); // { name: "DAVE", age: 30 }
36
+ const result = transformObject({ name: "dave", age: 30 }, { name: s => s.toUpperCase() }); // { name: "DAVE", age: 30 }
40
37
  ```
41
38
 
42
39
  ### Dictionaries
@@ -54,7 +51,10 @@ import { mapEntries, mapEntryValues } from "shelving/util";
54
51
 
55
52
  // mapEntries passes the full [key, value] entry to the transform.
56
53
  // mapEntryValues passes only the value.
57
- const entries: [string, number][] = [["a", 1], ["b", 2]];
54
+ const entries: [string, number][] = [
55
+ ["a", 1],
56
+ ["b", 2],
57
+ ];
58
58
  Array.from(mapEntryValues(entries, v => v * 2)); // [["a", 2], ["b", 4]]
59
59
  ```
60
60
 
@@ -64,7 +64,7 @@ Array.from(mapEntryValues(entries, v => v * 2)); // [["a", 2], ["b", 4]]
64
64
  import { mapSequence } from "shelving/util";
65
65
 
66
66
  async function* process(stream: AsyncIterable<string>) {
67
- yield* mapSequence(stream, line => line.trim());
67
+ yield* mapSequence(stream, line => line.trim());
68
68
  }
69
69
  ```
70
70
 
package/docs/util/tree.md CHANGED
@@ -23,12 +23,12 @@ import { flattenTree } from "shelving/util";
23
23
  const map = flattenTree(root);
24
24
 
25
25
  // Flat keys — what cross-references (`extends` / `overrides`) and README links resolve through.
26
- map.get("Store"); // the `Store` element
27
- map.get("Store.get"); // the `Store.get` member (qualified `Class.member` key)
28
- map.get("Store")?.props.path; // "/store/Store" — its stamped canonical URL
26
+ map.get("Store"); // the `Store` element
27
+ map.get("Store.get"); // the `Store.get` member (qualified `Class.member` key)
28
+ map.get("Store")?.props.path; // "/store/Store" — its stamped canonical URL
29
29
 
30
30
  // Canonical path keys — what the router resolves a URL to.
31
- map.get("/store/Store"); // the same `Store` element
31
+ map.get("/store/Store"); // the same `Store` element
32
32
  map.get("/store/Store")?.props.children; // …with its (stamped) children, so the map doubles as the tree
33
33
 
34
34
  // Merge several trees into one lookup (later writers win on the rare key collision).
@@ -42,15 +42,15 @@ import type { DocumentationElement } from "shelving/util";
42
42
 
43
43
  // A tree-documentation element carries structured API docs.
44
44
  const el: DocumentationElement = {
45
- type: "tree-documentation",
46
- key: "getFirst",
47
- props: {
48
- name: "getFirst",
49
- kind: "function",
50
- signatures: ["getFirst<T>(arr: T[]): T | undefined"],
51
- params: [{ name: "arr", type: "T[]" }],
52
- returns: [{ type: "T | undefined" }],
53
- },
45
+ type: "tree-documentation",
46
+ key: "getFirst",
47
+ props: {
48
+ name: "getFirst",
49
+ kind: "function",
50
+ signatures: ["getFirst<T>(arr: T[]): T | undefined"],
51
+ params: [{ name: "arr", type: "T[]" }],
52
+ returns: [{ type: "T | undefined" }],
53
+ },
54
54
  };
55
55
  ```
56
56
 
@@ -11,10 +11,10 @@ Small set of guards and assertions for `undefined`. Useful in filter pipelines a
11
11
  import { isUndefined, isDefined, assertDefined, requireDefined, notUndefined, getUndefined } from "shelving/util";
12
12
 
13
13
  isUndefined(undefined); // true
14
- isUndefined(null); // false
14
+ isUndefined(null); // false
15
15
 
16
- isDefined(0); // true
17
- isDefined(undefined); // false
16
+ isDefined(0); // true
17
+ isDefined(undefined); // false
18
18
 
19
19
  // Filter undefined values from an array:
20
20
  const values = [1, undefined, 3, undefined, 5];
@@ -20,11 +20,11 @@ These helpers model physical units of measure — mass, length, speed, area, vol
20
20
  import { MASS_UNITS, LENGTH_UNITS, TEMPERATURE_UNITS, SPEED_UNITS } from "shelving/util";
21
21
 
22
22
  // Via the UnitList directly.
23
- MASS_UNITS.convert(1, "kilogram", "pound"); // ≈ 2.205
23
+ MASS_UNITS.convert(1, "kilogram", "pound"); // ≈ 2.205
24
24
 
25
25
  // Via a Unit instance.
26
26
  const km = LENGTH_UNITS.require("kilometer");
27
- km.to(5, "mile"); // ≈ 3.107
27
+ km.to(5, "mile"); // ≈ 3.107
28
28
  km.from(26.2, "mile"); // ≈ 42.165
29
29
 
30
30
  // Temperature (function-based conversion).
@@ -36,28 +36,28 @@ TEMPERATURE_UNITS.convert(100, "celsius", "fahrenheit"); // 212
36
36
  ```ts
37
37
  import { MASS_UNITS, VOLUME_UNITS } from "shelving/util";
38
38
 
39
- MASS_UNITS.require("kilogram").format(2.5); // "2.5 kg"
39
+ MASS_UNITS.require("kilogram").format(2.5); // "2.5 kg"
40
40
  VOLUME_UNITS.require("liter").format(1, { unitDisplay: "long" }); // "1 liter"
41
41
 
42
42
  // US and imperial volume units are marked, e.g. "1 US pt" and "1 pt Imp.".
43
- VOLUME_UNITS.require("imperial-pint").format(1); // "1 pt Imp."
43
+ VOLUME_UNITS.require("imperial-pint").format(1); // "1 pt Imp."
44
44
 
45
45
  // Short name on its own, e.g. for a dropdown of units.
46
- MASS_UNITS.require("kilogram").formatAbbr(); // "kg"
46
+ MASS_UNITS.require("kilogram").formatAbbr(); // "kg"
47
47
  ```
48
48
 
49
49
  ### Available unit lists and key types
50
50
 
51
- | Export | Key type |
52
- | --- | --- |
53
- | `PERCENT_UNITS` | `PercentUnitKey` |
54
- | `POINT_UNITS` | `PointUnitKey` |
55
- | `ANGLE_UNITS` | `AngleUnitKey` |
56
- | `MASS_UNITS` | `MassUnitKey` |
57
- | `LENGTH_UNITS` | `LengthUnitKey` |
58
- | `SPEED_UNITS` | `SpeedUnitKey` |
59
- | `AREA_UNITS` | `AreaUnitKey` |
60
- | `VOLUME_UNITS` | `VolumeUnitKey` |
51
+ | Export | Key type |
52
+ | ------------------- | -------------------- |
53
+ | `PERCENT_UNITS` | `PercentUnitKey` |
54
+ | `POINT_UNITS` | `PointUnitKey` |
55
+ | `ANGLE_UNITS` | `AngleUnitKey` |
56
+ | `MASS_UNITS` | `MassUnitKey` |
57
+ | `LENGTH_UNITS` | `LengthUnitKey` |
58
+ | `SPEED_UNITS` | `SpeedUnitKey` |
59
+ | `AREA_UNITS` | `AreaUnitKey` |
60
+ | `VOLUME_UNITS` | `VolumeUnitKey` |
61
61
  | `TEMPERATURE_UNITS` | `TemperatureUnitKey` |
62
62
 
63
63
 
@@ -17,13 +17,13 @@
17
17
 
18
18
  ### Key prefix syntax
19
19
 
20
- | Key syntax | Action |
21
- | --- | --- |
22
- | `key` or `=key` | Set field to value |
23
- | `+=key` | Increment number |
24
- | `-=key` | Decrement number |
25
- | `+[]key` | Add item(s) to array |
26
- | `-[]key` | Remove item(s) from array |
20
+ | Key syntax | Action |
21
+ | --------------- | ------------------------- |
22
+ | `key` or `=key` | Set field to value |
23
+ | `+=key` | Increment number |
24
+ | `-=key` | Decrement number |
25
+ | `+[]key` | Add item(s) to array |
26
+ | `-[]key` | Remove item(s) from array |
27
27
 
28
28
  Use plain `key` for most sets. Use `=key` when TypeScript inference gets confused by deeply-nested paths — the `=` prefix forces leaf-only matching and is more precise.
29
29
 
@@ -34,13 +34,13 @@ import { updateData } from "shelving/util";
34
34
 
35
35
  const doc = { title: "Draft", count: 5, tags: ["a", "b"] };
36
36
 
37
- updateData(doc, { title: "Published" }); // { title: "Published", count: 5, tags: [...] }
38
- updateData(doc, { "=title": "Final" }); // same effect, more precise
39
- updateData(doc, { "+=count": 3 }); // { ..., count: 8, ... }
40
- updateData(doc, { "-=count": 1 }); // { ..., count: 4, ... }
41
- updateData(doc, { "+[]tags": "c" }); // { ..., tags: ["a", "b", "c"] }
42
- updateData(doc, { "-[]tags": "a" }); // { ..., tags: ["b"] }
43
- updateData(doc, { "+[]tags": ["c", "d"] }); // add multiple at once
37
+ updateData(doc, { title: "Published" }); // { title: "Published", count: 5, tags: [...] }
38
+ updateData(doc, { "=title": "Final" }); // same effect, more precise
39
+ updateData(doc, { "+=count": 3 }); // { ..., count: 8, ... }
40
+ updateData(doc, { "-=count": 1 }); // { ..., count: 4, ... }
41
+ updateData(doc, { "+[]tags": "c" }); // { ..., tags: ["a", "b", "c"] }
42
+ updateData(doc, { "-[]tags": "a" }); // { ..., tags: ["b"] }
43
+ updateData(doc, { "+[]tags": ["c", "d"] }); // add multiple at once
44
44
  ```
45
45
 
46
46
  ### Nested paths
@@ -50,8 +50,8 @@ import { updateData } from "shelving/util";
50
50
 
51
51
  const doc = { user: { name: "Alice", score: 10 } };
52
52
 
53
- updateData(doc, { "=user.name": "Bob" }); // { user: { name: "Bob", score: 10 } }
54
- updateData(doc, { "+=user.score": 5 }); // { user: { name: "Alice", score: 15 } }
53
+ updateData(doc, { "=user.name": "Bob" }); // { user: { name: "Bob", score: 10 } }
54
+ updateData(doc, { "+=user.score": 5 }); // { user: { name: "Alice", score: 15 } }
55
55
  ```
56
56
 
57
57
  ### Inspecting updates
package/docs/util/uri.md CHANGED
@@ -20,12 +20,12 @@ These helpers work with any valid URI — including non-hierarchical ones like `
20
20
  ```ts
21
21
  import { getURI, requireURI, isURI, assertURI } from "shelving/util";
22
22
 
23
- getURI("https://example.com/path"); // ImmutableURI
24
- getURI("not-a-uri"); // undefined
25
- getURI(null); // undefined
23
+ getURI("https://example.com/path"); // ImmutableURI
24
+ getURI("not-a-uri"); // undefined
25
+ getURI(null); // undefined
26
26
 
27
- requireURI("https://example.com"); // ImmutableURI or throws RequiredError
28
- isURI(new URL("https://x.com")); // true
27
+ requireURI("https://example.com"); // ImmutableURI or throws RequiredError
28
+ isURI(new URL("https://x.com")); // true
29
29
  ```
30
30
 
31
31
  ### Reading query params
@@ -35,10 +35,10 @@ import { getURIParams, getURIParam, requireURIParam } from "shelving/util";
35
35
 
36
36
  const uri = "https://example.com/search?q=shelving&page=2";
37
37
 
38
- getURIParams(uri); // { q: "shelving", page: "2" }
39
- getURIParam(uri, "q"); // "shelving"
40
- getURIParam(uri, "missing"); // undefined
41
- requireURIParam(uri, "q"); // "shelving"
38
+ getURIParams(uri); // { q: "shelving", page: "2" }
39
+ getURIParam(uri, "q"); // "shelving"
40
+ getURIParam(uri, "missing"); // undefined
41
+ requireURIParam(uri, "q"); // "shelving"
42
42
  requireURIParam(uri, "missing"); // throws RequiredError
43
43
  ```
44
44
 
@@ -49,10 +49,10 @@ import { withURIParam, withURIParams, omitURIParams, clearURIParams } from "shel
49
49
 
50
50
  const base = "https://example.com/search?q=shelving";
51
51
 
52
- withURIParam(base, "page", 2); // "https://example.com/search?q=shelving&page=2"
52
+ withURIParam(base, "page", 2); // "https://example.com/search?q=shelving&page=2"
53
53
  withURIParams(base, { page: 3, lang: "en" }); // adds both params
54
- omitURIParams(base, "q"); // "https://example.com/search"
55
- clearURIParams(base); // "https://example.com/search"
54
+ omitURIParams(base, "q"); // "https://example.com/search"
55
+ clearURIParams(base); // "https://example.com/search"
56
56
  ```
57
57
 
58
58
  ### Working with URI schemes