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.
- package/docs/api/APIProvider.md +2 -2
- package/docs/api/CachedAPIProvider.md +6 -8
- package/docs/api/ClientAPIProvider.md +5 -5
- package/docs/api/DebugAPIProvider.md +3 -5
- package/docs/api/HydratingAPIProvider.md +2 -2
- package/docs/api/JSONAPIProvider.md +3 -5
- package/docs/api/LoggingAPIProvider.md +7 -9
- package/docs/api/MockAPIProvider.md +4 -4
- package/docs/api/MockEndpointAPIProvider.md +5 -7
- package/docs/api/ThroughAPIProvider.md +15 -10
- package/docs/api/ValidationAPIProvider.md +3 -5
- package/docs/api/XMLAPIProvider.md +3 -3
- package/docs/api.md +48 -44
- package/docs/bun.md +9 -9
- package/docs/db/DBProvider.md +6 -6
- package/docs/db/MemoryDBProvider.md +3 -3
- package/docs/db/PostgresProvider.md +6 -4
- package/docs/db/SQLProvider.md +6 -3
- package/docs/db/SQLiteProvider.md +9 -4
- package/docs/db/StorageDBProvider.md +2 -2
- package/docs/db/ThroughDBProvider.md +6 -6
- package/docs/db/UndoDBProvider.md +2 -2
- package/docs/db.md +32 -32
- package/docs/error/NetworkError.md +5 -5
- package/docs/error/RequestError.md +4 -4
- package/docs/error/RequiredError.md +2 -2
- package/docs/error/ResponseError.md +1 -1
- package/docs/error/UnexpectedError.md +1 -1
- package/docs/error/UnsupportedError.md +3 -3
- package/docs/error/ValueError.md +2 -2
- package/docs/error.md +20 -19
- package/docs/extract.md +14 -14
- package/docs/firebase.md +6 -6
- package/docs/guides/building-with-shelving.md +113 -85
- package/docs/guides/styleguide.md +29 -29
- package/docs/index.md +3 -2
- package/docs/llms-full.txt +2541 -2295
- package/docs/markup.md +15 -17
- package/docs/react/createAPIContext.md +12 -12
- package/docs/react/createDBContext.md +21 -15
- package/docs/react/useInstance.md +2 -2
- package/docs/react/useLazy.md +1 -1
- package/docs/react/useMap.md +10 -6
- package/docs/react/useReduce.md +2 -2
- package/docs/react/useSequence.md +2 -2
- package/docs/react/useStore.md +10 -10
- package/docs/react.md +22 -16
- package/docs/schema/ArraySchema.md +6 -6
- package/docs/schema/BooleanSchema.md +5 -5
- package/docs/schema/ChoiceSchema.md +1 -1
- package/docs/schema/CurrencyAmountSchema.md +2 -2
- package/docs/schema/DataSchema.md +5 -5
- package/docs/schema/NullableSchema.md +4 -4
- package/docs/schema/NumberSchema.md +4 -4
- package/docs/schema/OptionalSchema.md +1 -1
- package/docs/schema/StringSchema.md +7 -7
- package/docs/schema.md +21 -21
- package/docs/sequence/DeferredSequence.md +1 -1
- package/docs/sequence/InspectSequence.md +8 -6
- package/docs/sequence/LazySequence.md +3 -3
- package/docs/sequence/Sequence.md +6 -6
- package/docs/sequence/ThroughSequence.md +4 -2
- package/docs/sequence.md +3 -3
- package/docs/store/ArrayStore.md +6 -6
- package/docs/store/BooleanStore.md +2 -2
- package/docs/store/BusyStore.md +1 -1
- package/docs/store/DataStore.md +5 -5
- package/docs/store/DictionaryStore.md +4 -4
- package/docs/store/FetchStore.md +6 -6
- package/docs/store/PathStore.md +4 -4
- package/docs/store/PayloadFetchStore.md +1 -5
- package/docs/store/Store.md +8 -6
- package/docs/store/URLStore.md +5 -5
- package/docs/store.md +15 -15
- package/docs/test.md +6 -6
- package/docs/ui/App.md +99 -69
- package/docs/ui/AppLayout.md +35 -26
- package/docs/ui/BackButton.md +13 -11
- package/docs/ui/Button.md +73 -64
- package/docs/ui/Card.md +23 -22
- package/docs/ui/Catcher.md +3 -3
- package/docs/ui/ClassProps.md +1 -1
- package/docs/ui/Code.md +11 -11
- package/docs/ui/CollapseTransition.md +5 -5
- package/docs/ui/Deleted.md +6 -6
- package/docs/ui/Details.md +13 -13
- package/docs/ui/Dialog.md +42 -28
- package/docs/ui/Dialogs.md +4 -0
- package/docs/ui/DocumentationButtons.md +2 -2
- package/docs/ui/DocumentationCard.md +2 -2
- package/docs/ui/DocumentationFrame.md +4 -4
- package/docs/ui/DocumentationLive.md +11 -11
- package/docs/ui/DocumentationPage.md +3 -3
- package/docs/ui/Emphasis.md +4 -4
- package/docs/ui/Empty.md +2 -2
- package/docs/ui/FadeTransition.md +9 -9
- package/docs/ui/Field.md +14 -14
- package/docs/ui/FixedLayout.md +27 -25
- package/docs/ui/Form.md +41 -39
- package/docs/ui/FormStore.md +6 -2
- package/docs/ui/Grid.md +21 -9
- package/docs/ui/HTML.md +10 -8
- package/docs/ui/Head.md +2 -3
- package/docs/ui/Heading.md +12 -12
- package/docs/ui/HorizontalTransition.md +10 -10
- package/docs/ui/Icon.md +4 -4
- package/docs/ui/ImageInput.md +12 -12
- package/docs/ui/Inserted.md +6 -6
- package/docs/ui/Link.md +11 -11
- package/docs/ui/List.md +7 -7
- package/docs/ui/Loading.md +6 -6
- package/docs/ui/Mark.md +11 -9
- package/docs/ui/Markup.md +4 -4
- package/docs/ui/Menu.md +24 -24
- package/docs/ui/MenuItem.md +29 -29
- package/docs/ui/Modal.md +57 -45
- package/docs/ui/Navigation.md +28 -26
- package/docs/ui/NavigationStore.md +18 -18
- package/docs/ui/Notice.md +15 -15
- package/docs/ui/Notices.md +17 -17
- package/docs/ui/Page.md +13 -13
- package/docs/ui/Panel.md +8 -8
- package/docs/ui/Paragraph.md +5 -5
- package/docs/ui/Progress.md +11 -11
- package/docs/ui/Prose.md +6 -6
- package/docs/ui/QueryRadiosInput.md +2 -2
- package/docs/ui/RouteCache.md +27 -27
- package/docs/ui/Router.md +70 -61
- package/docs/ui/SchemaInput.md +20 -20
- package/docs/ui/Scroll.md +16 -16
- package/docs/ui/Section.md +13 -10
- package/docs/ui/SidebarLayout.md +27 -27
- package/docs/ui/Small.md +4 -4
- package/docs/ui/Span.md +3 -1
- package/docs/ui/StackButton.md +13 -7
- package/docs/ui/Strong.md +4 -4
- package/docs/ui/Subheading.md +12 -12
- package/docs/ui/TINT_CLASS.md +11 -11
- package/docs/ui/Table.md +40 -29
- package/docs/ui/Tag.md +15 -15
- package/docs/ui/Title.md +13 -13
- package/docs/ui/Transition.md +22 -22
- package/docs/ui/TreeApp.md +8 -8
- package/docs/ui/TreeMarkup.md +2 -2
- package/docs/ui/TreeMenu.md +3 -3
- package/docs/ui/TreeSidebar.md +1 -1
- package/docs/ui/VerticalTransition.md +8 -8
- package/docs/ui/getClass.md +10 -10
- package/docs/ui/getColorClass.md +23 -23
- package/docs/ui/getDurationClass.md +5 -5
- package/docs/ui/getGridClass.md +2 -2
- package/docs/ui/getHeightClass.md +4 -4
- package/docs/ui/getRadiusClass.md +9 -9
- package/docs/ui/getShadowClass.md +6 -6
- package/docs/ui/getSpaceClass.md +13 -13
- package/docs/ui/getStrokeClass.md +6 -6
- package/docs/ui/getTypographyClass.md +38 -38
- package/docs/ui/getWidthClass.md +4 -4
- package/docs/ui/notify.md +11 -11
- package/docs/ui/requireContext.md +1 -1
- package/docs/ui.md +4 -4
- package/docs/util/array.md +35 -29
- package/docs/util/async.md +2 -2
- package/docs/util/base64.md +7 -7
- package/docs/util/boolean.md +10 -10
- package/docs/util/buffer.md +5 -5
- package/docs/util/bytes.md +9 -9
- package/docs/util/class.md +10 -6
- package/docs/util/color.md +13 -13
- package/docs/util/constants.md +2 -2
- package/docs/util/crypto.md +1 -1
- package/docs/util/currency.md +2 -2
- package/docs/util/data.md +18 -18
- package/docs/util/date.md +22 -22
- package/docs/util/debug/debug.md +12 -12
- package/docs/util/dictionary.md +21 -18
- package/docs/util/diff.md +6 -6
- package/docs/util/dispose/dispose.md +5 -5
- package/docs/util/duration.md +9 -9
- package/docs/util/element.md +1 -1
- package/docs/util/entity.md +6 -6
- package/docs/util/entry.md +21 -8
- package/docs/util/env.md +2 -2
- package/docs/util/equal.md +16 -16
- package/docs/util/error.md +4 -4
- package/docs/util/file.md +8 -8
- package/docs/util/filter.md +9 -5
- package/docs/util/format.md +18 -18
- package/docs/util/function.md +4 -4
- package/docs/util/geo.md +13 -13
- package/docs/util/hash.md +3 -3
- package/docs/util/http.md +1 -1
- package/docs/util/hydrate/hydrate.md +7 -4
- package/docs/util/item.md +4 -4
- package/docs/util/iterate.md +11 -11
- package/docs/util/jwt.md +1 -6
- package/docs/util/link.md +5 -5
- package/docs/util/map.md +17 -11
- package/docs/util/merge.md +2 -5
- package/docs/util/null.md +20 -10
- package/docs/util/number.md +16 -16
- package/docs/util/object.md +25 -22
- package/docs/util/path.md +17 -17
- package/docs/util/query.md +23 -25
- package/docs/util/random.md +7 -7
- package/docs/util/regexp.md +16 -16
- package/docs/util/sequence.md +16 -10
- package/docs/util/serialise/serialise.md +6 -6
- package/docs/util/set.md +10 -10
- package/docs/util/sort.md +10 -11
- package/docs/util/source.md +11 -7
- package/docs/util/start.md +8 -8
- package/docs/util/string.md +14 -14
- package/docs/util/template.md +3 -3
- package/docs/util/timeout.md +5 -5
- package/docs/util/transform.md +6 -6
- package/docs/util/tree.md +13 -13
- package/docs/util/undefined.md +3 -3
- package/docs/util/units.md +15 -15
- package/docs/util/update.md +16 -16
- package/docs/util/uri.md +12 -12
- package/docs/util/url.md +11 -11
- package/docs/util/uuid.md +3 -3
- package/docs/util/validate.md +14 -9
- package/package.json +3 -3
- package/skills/shelving/SKILL.md +1 -0
- package/ui/README.md +4 -4
- package/ui/app/App.md +99 -69
- package/ui/block/Card.md +23 -22
- package/ui/block/Details.md +13 -13
- package/ui/block/Grid.md +21 -9
- package/ui/block/Heading.md +12 -12
- package/ui/block/List.md +7 -7
- package/ui/block/Panel.md +8 -8
- package/ui/block/Paragraph.md +5 -5
- package/ui/block/Prose.md +6 -6
- package/ui/block/Section.md +13 -10
- package/ui/block/Subheading.md +12 -12
- package/ui/block/Title.md +13 -13
- package/ui/button/Button.md +73 -64
- package/ui/dialog/Dialog.md +42 -28
- package/ui/dialog/Dialogs.d.ts +4 -0
- package/ui/dialog/Dialogs.js +4 -0
- package/ui/dialog/Dialogs.tsx +4 -0
- package/ui/dialog/Modal.md +57 -45
- package/ui/docs/DocumentationButtons.md +2 -2
- package/ui/docs/DocumentationCard.md +2 -2
- package/ui/docs/DocumentationFrame.md +4 -4
- package/ui/docs/DocumentationLive.md +11 -11
- package/ui/docs/DocumentationPage.md +3 -3
- package/ui/form/Field.md +14 -14
- package/ui/form/Form.md +41 -39
- package/ui/form/FormStore.md +6 -2
- package/ui/form/Progress.md +11 -11
- package/ui/inline/Code.md +11 -11
- package/ui/inline/Deleted.md +6 -6
- package/ui/inline/Emphasis.md +4 -4
- package/ui/inline/Inserted.md +6 -6
- package/ui/inline/Link.md +11 -11
- package/ui/inline/Mark.md +11 -9
- package/ui/inline/Small.md +4 -4
- package/ui/inline/Span.md +3 -1
- package/ui/inline/Strong.md +4 -4
- package/ui/input/ImageInput.md +12 -12
- package/ui/input/QueryRadiosInput.md +2 -2
- package/ui/input/SchemaInput.md +20 -20
- package/ui/layout/AppLayout.md +35 -26
- package/ui/layout/AppLayout.module.css +3 -16
- package/ui/layout/FixedLayout.md +27 -25
- package/ui/layout/SidebarLayout.md +27 -27
- package/ui/layout/SidebarLayout.module.css +1 -0
- package/ui/menu/Menu.md +24 -24
- package/ui/menu/MenuItem.md +29 -29
- package/ui/misc/Catcher.md +3 -3
- package/ui/misc/Icon.md +4 -4
- package/ui/misc/Loading.md +6 -6
- package/ui/misc/Markup.md +4 -4
- package/ui/misc/Tag.md +15 -15
- package/ui/notice/Empty.md +2 -2
- package/ui/notice/Notice.md +15 -15
- package/ui/notice/Notices.md +17 -17
- package/ui/page/HTML.md +10 -8
- package/ui/page/Head.md +2 -3
- package/ui/page/Page.md +13 -13
- package/ui/router/BackButton.md +13 -11
- package/ui/router/Navigation.md +28 -26
- package/ui/router/NavigationStore.md +18 -18
- package/ui/router/RouteCache.md +27 -27
- package/ui/router/Router.md +70 -61
- package/ui/router/StackButton.md +13 -7
- package/ui/style/Scroll.md +16 -16
- package/ui/style/TINT_CLASS.md +11 -11
- package/ui/style/getColorClass.md +23 -23
- package/ui/style/getDurationClass.md +5 -5
- package/ui/style/getGridClass.md +2 -2
- package/ui/style/getHeightClass.md +4 -4
- package/ui/style/getRadiusClass.md +9 -9
- package/ui/style/getShadowClass.md +6 -6
- package/ui/style/getSpaceClass.md +13 -13
- package/ui/style/getStrokeClass.md +6 -6
- package/ui/style/getTypographyClass.md +38 -38
- package/ui/style/getWidthClass.md +4 -4
- package/ui/table/Table.md +40 -30
- package/ui/transition/CollapseTransition.md +5 -5
- package/ui/transition/FadeTransition.md +9 -9
- package/ui/transition/HorizontalTransition.md +10 -10
- package/ui/transition/Transition.md +22 -22
- package/ui/transition/VerticalTransition.md +8 -8
- package/ui/tree/TreeApp.md +8 -8
- package/ui/tree/TreeMarkup.md +2 -2
- package/ui/tree/TreeMenu.md +3 -3
- package/ui/tree/TreeSidebar.md +1 -1
- package/ui/util/ClassProps.md +1 -1
- package/ui/util/getClass.md +10 -10
- package/ui/util/notify.md +11 -11
- package/ui/util/requireContext.md +1 -1
package/docs/util/dictionary.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
- Kind: module
|
|
4
4
|
- Import: `import { … } from "shelving/util/dictionary";`
|
|
5
5
|
|
|
6
|
-
Typed helpers for working with `{ [key: string]: T }` objects — called
|
|
6
|
+
Typed helpers for working with `{ [key: string]: T }` objects — called _dictionaries_ to distinguish them from the more permissive `Data` type. Mirrors the naming conventions of the array and object helpers: `with*` for immutable updates, `set*`/`delete*` for mutable by-reference mutations.
|
|
7
7
|
|
|
8
8
|
- `ImmutableDictionary<T>` and `MutableDictionary<T>` are the two variants; all immutable helpers return the same reference when nothing changed.
|
|
9
9
|
- `requireDictionary()` converts an iterable of `[key, value]` pairs into a plain object — useful when you receive entries from a `Map` or other iterable source.
|
|
@@ -17,12 +17,15 @@ Typed helpers for working with `{ [key: string]: T }` objects — called *dictio
|
|
|
17
17
|
```ts
|
|
18
18
|
import { isDictionary, assertDictionary, requireDictionary } from "shelving/util";
|
|
19
19
|
|
|
20
|
-
isDictionary({ a: 1 });
|
|
20
|
+
isDictionary({ a: 1 }); // true
|
|
21
21
|
isDictionary(new Map()); // false
|
|
22
22
|
|
|
23
23
|
// Convert an iterable of entries to a dictionary:
|
|
24
|
-
requireDictionary([
|
|
25
|
-
|
|
24
|
+
requireDictionary([
|
|
25
|
+
["a", 1],
|
|
26
|
+
["b", 2],
|
|
27
|
+
]); // { a: 1, b: 2 }
|
|
28
|
+
requireDictionary({ a: 1 }); // { a: 1 } (already a dictionary)
|
|
26
29
|
```
|
|
27
30
|
|
|
28
31
|
### Reading items
|
|
@@ -32,13 +35,13 @@ import { getDictionaryItem, requireDictionaryItem, isDictionaryItem, getDictiona
|
|
|
32
35
|
|
|
33
36
|
const dict = { uk: "London", fr: "Paris" };
|
|
34
37
|
|
|
35
|
-
getDictionaryItem(dict, "uk");
|
|
36
|
-
getDictionaryItem(dict, "de");
|
|
37
|
-
requireDictionaryItem(dict, "uk");
|
|
38
|
-
requireDictionaryItem(dict, "de");
|
|
38
|
+
getDictionaryItem(dict, "uk"); // "London"
|
|
39
|
+
getDictionaryItem(dict, "de"); // undefined
|
|
40
|
+
requireDictionaryItem(dict, "uk"); // "London"
|
|
41
|
+
requireDictionaryItem(dict, "de"); // throws RequiredError
|
|
39
42
|
|
|
40
|
-
isDictionaryItem(dict, "fr");
|
|
41
|
-
getDictionaryItems(dict);
|
|
43
|
+
isDictionaryItem(dict, "fr"); // true
|
|
44
|
+
getDictionaryItems(dict); // [["uk", "London"], ["fr", "Paris"]]
|
|
42
45
|
```
|
|
43
46
|
|
|
44
47
|
### Immutable updates
|
|
@@ -48,11 +51,11 @@ import { withDictionaryItem, withDictionaryItems, omitDictionaryItem, omitDictio
|
|
|
48
51
|
|
|
49
52
|
const dict = { a: 1, b: 2, c: 3 };
|
|
50
53
|
|
|
51
|
-
withDictionaryItem(dict, "d", 4);
|
|
54
|
+
withDictionaryItem(dict, "d", 4); // { a:1, b:2, c:3, d:4 }
|
|
52
55
|
withDictionaryItems(dict, { b: 99, d: 4 }); // { a:1, b:99, c:3, d:4 }
|
|
53
|
-
omitDictionaryItem(dict, "b");
|
|
54
|
-
omitDictionaryItems(dict, "a", "c");
|
|
55
|
-
pickDictionaryItems(dict, "a", "c");
|
|
56
|
+
omitDictionaryItem(dict, "b"); // { a:1, c:3 }
|
|
57
|
+
omitDictionaryItems(dict, "a", "c"); // { b:2 }
|
|
58
|
+
pickDictionaryItems(dict, "a", "c"); // { a:1, c:3 }
|
|
56
59
|
```
|
|
57
60
|
|
|
58
61
|
### Mutable updates (by reference)
|
|
@@ -62,10 +65,10 @@ import { setDictionaryItem, setDictionaryItems, deleteDictionaryItem, deleteDict
|
|
|
62
65
|
|
|
63
66
|
const dict: MutableDictionary<number> = { a: 1, b: 2 };
|
|
64
67
|
|
|
65
|
-
setDictionaryItem(dict, "c", 3);
|
|
66
|
-
setDictionaryItems(dict, { d: 4 });
|
|
67
|
-
deleteDictionaryItem(dict, "a");
|
|
68
|
-
deleteDictionaryItems(dict, "b", "c");
|
|
68
|
+
setDictionaryItem(dict, "c", 3); // dict is now { a:1, b:2, c:3 }
|
|
69
|
+
setDictionaryItems(dict, { d: 4 }); // dict is now { a:1, b:2, c:3, d:4 }
|
|
70
|
+
deleteDictionaryItem(dict, "a"); // dict is now { b:2, c:3, d:4 }
|
|
71
|
+
deleteDictionaryItems(dict, "b", "c"); // dict is now { d:4 }
|
|
69
72
|
```
|
|
70
73
|
|
|
71
74
|
|
package/docs/util/diff.md
CHANGED
|
@@ -18,10 +18,10 @@ Compute the minimal transformation needed to turn one value into another. Used i
|
|
|
18
18
|
```ts
|
|
19
19
|
import { deepDiff, SAME } from "shelving/util";
|
|
20
20
|
|
|
21
|
-
deepDiff(1, 1);
|
|
22
|
-
deepDiff("a", "b");
|
|
23
|
-
deepDiff([1, 2], [1, 2]);
|
|
24
|
-
deepDiff([1, 2], [1, 3]);
|
|
21
|
+
deepDiff(1, 1); // SAME
|
|
22
|
+
deepDiff("a", "b"); // "b"
|
|
23
|
+
deepDiff([1, 2], [1, 2]); // SAME
|
|
24
|
+
deepDiff([1, 2], [1, 3]); // [1, 3] (full array)
|
|
25
25
|
```
|
|
26
26
|
|
|
27
27
|
### Object diff
|
|
@@ -29,7 +29,7 @@ deepDiff([1, 2], [1, 3]); // [1, 3] (full array)
|
|
|
29
29
|
```ts
|
|
30
30
|
import { deepDiff, deepDiffObject, SAME } from "shelving/util";
|
|
31
31
|
|
|
32
|
-
const left
|
|
32
|
+
const left = { a: 1, b: 2, c: 3 };
|
|
33
33
|
const right = { a: 1, b: 99 };
|
|
34
34
|
|
|
35
35
|
deepDiff(left, right);
|
|
@@ -44,7 +44,7 @@ deepDiff(left, left); // SAME
|
|
|
44
44
|
import { deepDiffArray, SAME } from "shelving/util";
|
|
45
45
|
|
|
46
46
|
deepDiffArray([1, 2, 3], [1, 2, 3]); // SAME
|
|
47
|
-
deepDiffArray([1, 2], [1, 3]);
|
|
47
|
+
deepDiffArray([1, 2], [1, 3]); // [1, 3]
|
|
48
48
|
```
|
|
49
49
|
|
|
50
50
|
### Checking for changes
|
|
@@ -43,7 +43,7 @@ dispose(resourceA, resourceB, resourceC);
|
|
|
43
43
|
```ts
|
|
44
44
|
import { isDisposable, isAsyncDisposable } from "shelving/util";
|
|
45
45
|
|
|
46
|
-
isDisposable(obj);
|
|
46
|
+
isDisposable(obj); // true if obj[Symbol.dispose] is a function
|
|
47
47
|
isAsyncDisposable(obj); // true if obj[Symbol.asyncDispose] is a function
|
|
48
48
|
```
|
|
49
49
|
|
|
@@ -54,10 +54,10 @@ import { DisposableMap } from "shelving/util";
|
|
|
54
54
|
|
|
55
55
|
const cache = new DisposableMap<string, Connection>();
|
|
56
56
|
|
|
57
|
-
cache.set("db", openConnection());
|
|
58
|
-
cache.set("db", reopenConnection());
|
|
59
|
-
cache.delete("db");
|
|
60
|
-
cache[Symbol.dispose]();
|
|
57
|
+
cache.set("db", openConnection()); // stored
|
|
58
|
+
cache.set("db", reopenConnection()); // old connection disposed automatically
|
|
59
|
+
cache.delete("db"); // connection disposed
|
|
60
|
+
cache[Symbol.dispose](); // all remaining connections disposed
|
|
61
61
|
```
|
|
62
62
|
|
|
63
63
|
### DisposableSet
|
package/docs/util/duration.md
CHANGED
|
@@ -26,9 +26,9 @@ const now = "now";
|
|
|
26
26
|
getDuration(now, launch);
|
|
27
27
|
// { years: 0, months: 0, weeks: 1, days: 3, hours: 5, minutes: 0, seconds: 0, milliseconds: 0 }
|
|
28
28
|
|
|
29
|
-
getDaysUntil(launch);
|
|
29
|
+
getDaysUntil(launch); // e.g. 10 (calendar days from today)
|
|
30
30
|
getMonthsAgo(new Date("2024-01-15")); // e.g. 16
|
|
31
|
-
getMilliseconds(now, launch);
|
|
31
|
+
getMilliseconds(now, launch); // raw ms difference
|
|
32
32
|
```
|
|
33
33
|
|
|
34
34
|
### Checking relative position
|
|
@@ -36,9 +36,9 @@ getMilliseconds(now, launch); // raw ms difference
|
|
|
36
36
|
```ts
|
|
37
37
|
import { isPast, isFuture, isToday } from "shelving/util";
|
|
38
38
|
|
|
39
|
-
isPast(new Date("2020-01-01"));
|
|
39
|
+
isPast(new Date("2020-01-01")); // true
|
|
40
40
|
isFuture(new Date("2099-12-31")); // true
|
|
41
|
-
isToday(new Date());
|
|
41
|
+
isToday(new Date()); // true
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
### Formatting for display
|
|
@@ -46,10 +46,10 @@ isToday(new Date()); // true
|
|
|
46
46
|
```ts
|
|
47
47
|
import { formatWhen, formatUntil, formatAgo, formatDuration } from "shelving/util";
|
|
48
48
|
|
|
49
|
-
formatWhen(new Date(Date.now() + 5 * 60_000));
|
|
50
|
-
formatWhen(new Date(Date.now() - 10_000));
|
|
51
|
-
formatAgo(new Date("2024-01-01"));
|
|
52
|
-
formatUntil(new Date("2026-01-01"));
|
|
49
|
+
formatWhen(new Date(Date.now() + 5 * 60_000)); // "in 5min"
|
|
50
|
+
formatWhen(new Date(Date.now() - 10_000)); // "just now"
|
|
51
|
+
formatAgo(new Date("2024-01-01")); // e.g. "16mo"
|
|
52
|
+
formatUntil(new Date("2026-01-01")); // e.g. "7mo"
|
|
53
53
|
|
|
54
54
|
formatDuration({ years: 1, months: 2, days: 3 }); // "1 year, 2 months, 3 days"
|
|
55
55
|
formatDuration({ hours: 2, minutes: 30 }, { style: "narrow" }); // "2hr 30min"
|
|
@@ -61,7 +61,7 @@ formatDuration({ hours: 2, minutes: 30 }, { style: "narrow" }); // "2hr 30min"
|
|
|
61
61
|
import { getBestDurationUnit, DURATION_UNITS } from "shelving/util";
|
|
62
62
|
|
|
63
63
|
const unit = getBestDurationUnit(3 * 24 * 60 * 60 * 1000); // → "day" Unit
|
|
64
|
-
unit.format(unit.from(3 * 24 * 60 * 60 * 1000));
|
|
64
|
+
unit.format(unit.from(3 * 24 * 60 * 60 * 1000)); // "3d"
|
|
65
65
|
```
|
|
66
66
|
|
|
67
67
|
|
package/docs/util/element.md
CHANGED
|
@@ -20,7 +20,7 @@ import { walkElements, filterElements, queryElements } from "shelving/util";
|
|
|
20
20
|
|
|
21
21
|
// Flatten any Elements shape to a flat iterable.
|
|
22
22
|
for (const el of walkElements(someElements)) {
|
|
23
|
-
|
|
23
|
+
console.log(el.type, el.key);
|
|
24
24
|
}
|
|
25
25
|
|
|
26
26
|
// Filter by a match function.
|
package/docs/util/entity.md
CHANGED
|
@@ -12,12 +12,12 @@ An **entity** is a compact `"type:id"` string that encodes both the kind of reso
|
|
|
12
12
|
```ts
|
|
13
13
|
import { getEntity, requireEntity, EMPTY_ENTITY } from "shelving/util";
|
|
14
14
|
|
|
15
|
-
getEntity("challenge:a1b2c3");
|
|
16
|
-
getEntity(null);
|
|
17
|
-
getEntity("bad-value");
|
|
15
|
+
getEntity("challenge:a1b2c3"); // ["challenge", "a1b2c3"]
|
|
16
|
+
getEntity(null); // [undefined, undefined] (EMPTY_ENTITY)
|
|
17
|
+
getEntity("bad-value"); // [undefined, undefined] (EMPTY_ENTITY)
|
|
18
18
|
|
|
19
19
|
requireEntity("challenge:a1b2c3"); // ["challenge", "a1b2c3"]
|
|
20
|
-
requireEntity("bad-value");
|
|
20
|
+
requireEntity("bad-value"); // throws RequiredError
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
### Using the `Entity<T>` type
|
|
@@ -28,8 +28,8 @@ import type { Entity, EntityType } from "shelving/util";
|
|
|
28
28
|
type ChallengeEntity = Entity<"challenge">; // "challenge:${string}"
|
|
29
29
|
|
|
30
30
|
function handleEntity(e: ChallengeEntity) {
|
|
31
|
-
|
|
32
|
-
|
|
31
|
+
const [type, id] = requireEntity(e);
|
|
32
|
+
// type is narrowed to "challenge"
|
|
33
33
|
}
|
|
34
34
|
```
|
|
35
35
|
|
package/docs/util/entry.md
CHANGED
|
@@ -13,17 +13,30 @@ An **entry** is a `readonly [key, value]` pair — the shape produced by `Map.en
|
|
|
13
13
|
import { getEntries, getEntryKeys, getEntryValues } from "shelving/util";
|
|
14
14
|
|
|
15
15
|
const obj = { a: 1, b: 2 };
|
|
16
|
-
const map = new Map([
|
|
16
|
+
const map = new Map([
|
|
17
|
+
["c", 3],
|
|
18
|
+
["d", 4],
|
|
19
|
+
]);
|
|
17
20
|
const arr = [10, 20, 30];
|
|
18
21
|
const set = new Set(["x", "y"]);
|
|
19
22
|
|
|
20
23
|
// getEntries accepts objects, Maps, arrays, Sets, or any Entry iterable — including multiple at once.
|
|
21
|
-
for (const [k, v] of getEntries(obj, map)) {
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
24
|
+
for (const [k, v] of getEntries(obj, map)) {
|
|
25
|
+
/* ... */
|
|
26
|
+
}
|
|
27
|
+
for (const [i, v] of getEntries(arr)) {
|
|
28
|
+
/* ... */
|
|
29
|
+
}
|
|
30
|
+
for (const [k] of getEntries(set)) {
|
|
31
|
+
/* ... */
|
|
32
|
+
} // Sets yield [value, value] entries
|
|
33
|
+
|
|
34
|
+
for (const k of getEntryKeys(getEntries(obj))) {
|
|
35
|
+
/* k = "a", "b" */
|
|
36
|
+
}
|
|
37
|
+
for (const v of getEntryValues(getEntries(map))) {
|
|
38
|
+
/* v = 3, 4 */
|
|
39
|
+
}
|
|
27
40
|
```
|
|
28
41
|
|
|
29
42
|
### Extracting from a single entry
|
|
@@ -32,7 +45,7 @@ for (const v of getEntryValues(getEntries(map))) { /* v = 3, 4 */ }
|
|
|
32
45
|
import { getEntryKey, getEntryValue } from "shelving/util";
|
|
33
46
|
|
|
34
47
|
const entry = ["name", "Alice"] as const;
|
|
35
|
-
getEntryKey(entry);
|
|
48
|
+
getEntryKey(entry); // "name"
|
|
36
49
|
getEntryValue(entry); // "Alice"
|
|
37
50
|
```
|
|
38
51
|
|
package/docs/util/env.md
CHANGED
|
@@ -16,13 +16,13 @@ These helpers read `process.env` safely across Node, edge runtimes, and browser
|
|
|
16
16
|
import { getEnv, requireEnv, getEnvBoolean, requireEnvBoolean } from "shelving/util";
|
|
17
17
|
|
|
18
18
|
// Safe read — returns undefined if missing.
|
|
19
|
-
const port = getEnv("PORT");
|
|
19
|
+
const port = getEnv("PORT"); // "3000" | undefined
|
|
20
20
|
|
|
21
21
|
// Throws RequiredError if missing.
|
|
22
22
|
const secret = requireEnv("API_SECRET"); // "abc123" or throws
|
|
23
23
|
|
|
24
24
|
// Boolean env var — returns true/false/undefined.
|
|
25
|
-
const debug = getEnvBoolean("DEBUG");
|
|
25
|
+
const debug = getEnvBoolean("DEBUG"); // true | false | undefined
|
|
26
26
|
|
|
27
27
|
// Throws if the value isn't a recognised boolean.
|
|
28
28
|
const verbose = requireEnvBoolean("VERBOSE"); // true | false or throws
|
package/docs/util/equal.md
CHANGED
|
@@ -21,14 +21,14 @@ Strict and structural equality predicates used throughout the library. The three
|
|
|
21
21
|
```ts
|
|
22
22
|
import { isEqual, isShallowEqual, isDeepEqual } from "shelving/util";
|
|
23
23
|
|
|
24
|
-
isEqual(1, 1);
|
|
25
|
-
isEqual("a", "b");
|
|
24
|
+
isEqual(1, 1); // true
|
|
25
|
+
isEqual("a", "b"); // false
|
|
26
26
|
|
|
27
|
-
isShallowEqual({ a: 1 }, { a: 1 });
|
|
27
|
+
isShallowEqual({ a: 1 }, { a: 1 }); // true
|
|
28
28
|
isShallowEqual({ a: { b: 1 } }, { a: { b: 1 } }); // false (nested object not ===)
|
|
29
29
|
|
|
30
|
-
isDeepEqual({ a: { b: 1 } }, { a: { b: 1 } });
|
|
31
|
-
isDeepEqual([1, [2, 3]], [1, [2, 3]]);
|
|
30
|
+
isDeepEqual({ a: { b: 1 } }, { a: { b: 1 } }); // true
|
|
31
|
+
isDeepEqual([1, [2, 3]], [1, [2, 3]]); // true
|
|
32
32
|
```
|
|
33
33
|
|
|
34
34
|
### Object and array checks
|
|
@@ -36,12 +36,12 @@ isDeepEqual([1, [2, 3]], [1, [2, 3]]); // true
|
|
|
36
36
|
```ts
|
|
37
37
|
import { isObjectEqual, isObjectMatch, isArrayEqual, isMapEqual } from "shelving/util";
|
|
38
38
|
|
|
39
|
-
isObjectEqual({ a: 1, b: 2 }, { a: 1, b: 2 });
|
|
40
|
-
isObjectEqual({ a: 1, b: 2 }, { a: 1 });
|
|
41
|
-
isObjectMatch({ a: 1, b: 2 }, { a: 1 });
|
|
39
|
+
isObjectEqual({ a: 1, b: 2 }, { a: 1, b: 2 }); // true (exact key match)
|
|
40
|
+
isObjectEqual({ a: 1, b: 2 }, { a: 1 }); // false (extra key in left)
|
|
41
|
+
isObjectMatch({ a: 1, b: 2 }, { a: 1 }); // true (subset match)
|
|
42
42
|
|
|
43
|
-
isArrayEqual([1, 2, 3], [1, 2, 3]);
|
|
44
|
-
isArrayEqual([1, 2], [1, 2, 3]);
|
|
43
|
+
isArrayEqual([1, 2, 3], [1, 2, 3]); // true
|
|
44
|
+
isArrayEqual([1, 2], [1, 2, 3]); // false
|
|
45
45
|
|
|
46
46
|
// Pass isDeepEqual as recursor for nested structure.
|
|
47
47
|
isObjectEqual({ x: [1, 2] }, { x: [1, 2] }, isDeepEqual); // true
|
|
@@ -52,8 +52,8 @@ isObjectEqual({ x: [1, 2] }, { x: [1, 2] }, isDeepEqual); // true
|
|
|
52
52
|
```ts
|
|
53
53
|
import { isInArray, isArrayWith } from "shelving/util";
|
|
54
54
|
|
|
55
|
-
isInArray("y", ["x", "y", "z"]);
|
|
56
|
-
isArrayWith(["x", "y"], "x");
|
|
55
|
+
isInArray("y", ["x", "y", "z"]); // true — is "y" in the array?
|
|
56
|
+
isArrayWith(["x", "y"], "x"); // true — is the left value an array containing "x"?
|
|
57
57
|
```
|
|
58
58
|
|
|
59
59
|
### Comparison predicates
|
|
@@ -61,9 +61,9 @@ isArrayWith(["x", "y"], "x"); // true — is the left value an array conta
|
|
|
61
61
|
```ts
|
|
62
62
|
import { isLess, isGreater, isEqualLess, isEqualGreater } from "shelving/util";
|
|
63
63
|
|
|
64
|
-
isLess(3, 5);
|
|
65
|
-
isGreater(5, 3);
|
|
66
|
-
isEqualLess(5, 5);
|
|
64
|
+
isLess(3, 5); // true
|
|
65
|
+
isGreater(5, 3); // true
|
|
66
|
+
isEqualLess(5, 5); // true
|
|
67
67
|
```
|
|
68
68
|
|
|
69
69
|
### Assertions
|
|
@@ -72,7 +72,7 @@ isEqualLess(5, 5); // true
|
|
|
72
72
|
import { assertEqual, assertNot } from "shelving/util";
|
|
73
73
|
|
|
74
74
|
assertEqual(value, expectedValue); // asserts value === expectedValue, narrows type
|
|
75
|
-
assertNot(value, null);
|
|
75
|
+
assertNot(value, null); // asserts value !== null, narrows type
|
|
76
76
|
```
|
|
77
77
|
|
|
78
78
|
|
package/docs/util/error.md
CHANGED
|
@@ -21,14 +21,14 @@ These are **not** the typed error classes — see `shelving/error` for `Required
|
|
|
21
21
|
import { isError, getMessage, requireMessage, logError } from "shelving/util";
|
|
22
22
|
|
|
23
23
|
isError(new Error("boom")); // true
|
|
24
|
-
isError("boom");
|
|
24
|
+
isError("boom"); // false
|
|
25
25
|
|
|
26
26
|
getMessage(new Error("boom")); // "boom"
|
|
27
|
-
getMessage("boom");
|
|
28
|
-
getMessage(42);
|
|
27
|
+
getMessage("boom"); // "boom"
|
|
28
|
+
getMessage(42); // undefined
|
|
29
29
|
|
|
30
30
|
requireMessage(new Error("oops")); // "oops"
|
|
31
|
-
requireMessage(42);
|
|
31
|
+
requireMessage(42); // throws RequiredError
|
|
32
32
|
|
|
33
33
|
logError(new Error("fatal")); // console.error(...)
|
|
34
34
|
```
|
package/docs/util/file.md
CHANGED
|
@@ -16,17 +16,17 @@ Tiny helpers for splitting filenames into base name and extension. They exist so
|
|
|
16
16
|
```ts
|
|
17
17
|
import { splitFileExtension, getFileExtension, requireFileExtension } from "shelving/util";
|
|
18
18
|
|
|
19
|
-
splitFileExtension("array.ts");
|
|
19
|
+
splitFileExtension("array.ts"); // ["array", "ts"]
|
|
20
20
|
splitFileExtension("archive.tar.gz"); // ["archive.tar", "gz"]
|
|
21
|
-
splitFileExtension("no-ext");
|
|
22
|
-
splitFileExtension(".gitignore");
|
|
23
|
-
splitFileExtension(undefined);
|
|
21
|
+
splitFileExtension("no-ext"); // ["no-ext", undefined]
|
|
22
|
+
splitFileExtension(".gitignore"); // [undefined, "gitignore"]
|
|
23
|
+
splitFileExtension(undefined); // [undefined, undefined]
|
|
24
24
|
|
|
25
|
-
getFileExtension("index.html");
|
|
26
|
-
getFileExtension("no-ext");
|
|
25
|
+
getFileExtension("index.html"); // "html"
|
|
26
|
+
getFileExtension("no-ext"); // undefined
|
|
27
27
|
|
|
28
|
-
requireFileExtension("style.css");
|
|
29
|
-
requireFileExtension("no-ext");
|
|
28
|
+
requireFileExtension("style.css"); // "css"
|
|
29
|
+
requireFileExtension("no-ext"); // throws RequiredError
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
|
package/docs/util/filter.md
CHANGED
|
@@ -24,13 +24,17 @@ const strings = Array.from(filterItems(["a", 1, "b", 2], isString));
|
|
|
24
24
|
|
|
25
25
|
// Immutable array filter — same ref when nothing changes.
|
|
26
26
|
const arr = ["a", "b", "c"];
|
|
27
|
-
const filtered = filterArray(arr,
|
|
28
|
-
filterArray(arr, () => true) === arr;
|
|
27
|
+
const filtered = filterArray(arr, s => s !== "b"); // ["a", "c"]
|
|
28
|
+
filterArray(arr, () => true) === arr; // true (same reference)
|
|
29
29
|
|
|
30
30
|
// Async stream filter.
|
|
31
|
-
async function* source() {
|
|
32
|
-
|
|
33
|
-
|
|
31
|
+
async function* source() {
|
|
32
|
+
yield 1;
|
|
33
|
+
yield 2;
|
|
34
|
+
yield 3;
|
|
35
|
+
}
|
|
36
|
+
for await (const n of filterSequence(source(), n => n > 1)) {
|
|
37
|
+
console.log(n); // 2, 3
|
|
34
38
|
}
|
|
35
39
|
```
|
|
36
40
|
|
package/docs/util/format.md
CHANGED
|
@@ -19,10 +19,10 @@ A collection of helpers for converting typed values into user-readable strings.
|
|
|
19
19
|
```ts
|
|
20
20
|
import { formatNumber, formatRange, formatCurrency, formatPercent } from "shelving/util";
|
|
21
21
|
|
|
22
|
-
formatNumber(1234567.89);
|
|
23
|
-
formatRange(10, 20);
|
|
24
|
-
formatCurrency(9.99, "GBP");
|
|
25
|
-
formatPercent(33.3);
|
|
22
|
+
formatNumber(1234567.89); // "1,234,567.89" (locale-dependent)
|
|
23
|
+
formatRange(10, 20); // "10–20"
|
|
24
|
+
formatCurrency(9.99, "GBP"); // "£9.99"
|
|
25
|
+
formatPercent(33.3); // "33%"
|
|
26
26
|
formatPercent(33.3, 100, { maximumFractionDigits: 1 }); // "33.3%"
|
|
27
27
|
```
|
|
28
28
|
|
|
@@ -31,13 +31,13 @@ formatPercent(33.3, 100, { maximumFractionDigits: 1 }); // "33.3%"
|
|
|
31
31
|
```ts
|
|
32
32
|
import { formatUnit, formatUnitAbbr } from "shelving/util";
|
|
33
33
|
|
|
34
|
-
formatUnit(5, "kilometer");
|
|
34
|
+
formatUnit(5, "kilometer"); // "5 km" (browser-supported unit)
|
|
35
35
|
formatUnit(12, "widget", { unitDisplay: "long", one: "widget", many: "widgets" });
|
|
36
36
|
// "12 widgets"
|
|
37
37
|
|
|
38
38
|
// Short name on its own, with no number.
|
|
39
|
-
formatUnitAbbr("kilometer");
|
|
40
|
-
formatUnitAbbr("widget", { abbr: "wdg" });
|
|
39
|
+
formatUnitAbbr("kilometer"); // "km"
|
|
40
|
+
formatUnitAbbr("widget", { abbr: "wdg" }); // "wdg"
|
|
41
41
|
```
|
|
42
42
|
|
|
43
43
|
### Dates and times
|
|
@@ -45,8 +45,8 @@ formatUnitAbbr("widget", { abbr: "wdg" }); // "wdg"
|
|
|
45
45
|
```ts
|
|
46
46
|
import { formatDate, formatTime, formatDateTime } from "shelving/util";
|
|
47
47
|
|
|
48
|
-
formatDate(new Date("2024-06-01"));
|
|
49
|
-
formatTime(new Date("2024-06-01T14:30:00"));
|
|
48
|
+
formatDate(new Date("2024-06-01")); // "6/1/2024" (locale-dependent)
|
|
49
|
+
formatTime(new Date("2024-06-01T14:30:00")); // "02:30 PM"
|
|
50
50
|
formatDateTime(new Date("2024-06-01T14:30:00")); // "6/1/2024, 02:30 PM"
|
|
51
51
|
```
|
|
52
52
|
|
|
@@ -55,12 +55,12 @@ formatDateTime(new Date("2024-06-01T14:30:00")); // "6/1/2024, 02:30 PM"
|
|
|
55
55
|
```ts
|
|
56
56
|
import { formatBoolean, formatValue } from "shelving/util";
|
|
57
57
|
|
|
58
|
-
formatBoolean(true);
|
|
59
|
-
formatBoolean(false);
|
|
58
|
+
formatBoolean(true); // "Yes"
|
|
59
|
+
formatBoolean(false); // "No"
|
|
60
60
|
|
|
61
|
-
formatValue(null);
|
|
62
|
-
formatValue(42);
|
|
63
|
-
formatValue([1, 2, 3]);
|
|
61
|
+
formatValue(null); // "None"
|
|
62
|
+
formatValue(42); // "42"
|
|
63
|
+
formatValue([1, 2, 3]); // "1, 2, and 3"
|
|
64
64
|
formatValue({ name: "Alice" }); // "Alice"
|
|
65
65
|
```
|
|
66
66
|
|
|
@@ -69,9 +69,9 @@ formatValue({ name: "Alice" }); // "Alice"
|
|
|
69
69
|
```ts
|
|
70
70
|
import { formatArray, formatObject } from "shelving/util";
|
|
71
71
|
|
|
72
|
-
formatArray(["apples", "oranges", "pears"]);
|
|
72
|
+
formatArray(["apples", "oranges", "pears"]); // "apples, oranges, and pears"
|
|
73
73
|
formatArray(["apples", "oranges"], { type: "disjunction" }); // "apples or oranges"
|
|
74
|
-
formatObject({ name: "Widget" });
|
|
74
|
+
formatObject({ name: "Widget" }); // "Widget"
|
|
75
75
|
```
|
|
76
76
|
|
|
77
77
|
### URLs and URIs
|
|
@@ -79,8 +79,8 @@ formatObject({ name: "Widget" }); // "Widget"
|
|
|
79
79
|
```ts
|
|
80
80
|
import { formatURI, formatURL } from "shelving/util";
|
|
81
81
|
|
|
82
|
-
formatURI("mailto:dave@shax.com");
|
|
83
|
-
formatURL("https://example.com/page?ref=123");
|
|
82
|
+
formatURI("mailto:dave@shax.com"); // "dave@shax.com"
|
|
83
|
+
formatURL("https://example.com/page?ref=123"); // "example.com/page"
|
|
84
84
|
```
|
|
85
85
|
|
|
86
86
|
|
package/docs/util/function.md
CHANGED
|
@@ -17,8 +17,8 @@ Core type definitions and small utilities for working with functions. This file
|
|
|
17
17
|
```ts
|
|
18
18
|
import { isFunction, assertFunction } from "shelving/util";
|
|
19
19
|
|
|
20
|
-
isFunction(() => {});
|
|
21
|
-
isFunction("hello");
|
|
20
|
+
isFunction(() => {}); // true
|
|
21
|
+
isFunction("hello"); // false
|
|
22
22
|
|
|
23
23
|
assertFunction(callback); // throws RequiredError if not a function
|
|
24
24
|
```
|
|
@@ -42,8 +42,8 @@ const result = transform(value); // returns value unchanged
|
|
|
42
42
|
import type { Callback, ValueCallback, ErrorCallback } from "shelving/util";
|
|
43
43
|
|
|
44
44
|
const onDone: Callback = () => console.log("done");
|
|
45
|
-
const onValue: ValueCallback<string> =
|
|
46
|
-
const onError: ErrorCallback =
|
|
45
|
+
const onValue: ValueCallback<string> = v => console.log(v);
|
|
46
|
+
const onError: ErrorCallback = err => console.error(err);
|
|
47
47
|
```
|
|
48
48
|
|
|
49
49
|
|
package/docs/util/geo.md
CHANGED
|
@@ -17,15 +17,15 @@ Country codes, names, and address formatting. Provides the `COUNTRIES` lookup (I
|
|
|
17
17
|
```ts
|
|
18
18
|
import { getCountry, requireCountry, formatCountry } from "shelving/util";
|
|
19
19
|
|
|
20
|
-
getCountry("gb");
|
|
21
|
-
getCountry("XX");
|
|
22
|
-
getCountry("detect");
|
|
20
|
+
getCountry("gb"); // "GB"
|
|
21
|
+
getCountry("XX"); // undefined (unknown code)
|
|
22
|
+
getCountry("detect"); // "US" (inferred from navigator.language in browser)
|
|
23
23
|
|
|
24
|
-
requireCountry("gb");
|
|
25
|
-
requireCountry("XX");
|
|
24
|
+
requireCountry("gb"); // "GB"
|
|
25
|
+
requireCountry("XX"); // throws RequiredError
|
|
26
26
|
|
|
27
|
-
formatCountry("GB");
|
|
28
|
-
formatCountry("XX");
|
|
27
|
+
formatCountry("GB"); // "United Kingdom"
|
|
28
|
+
formatCountry("XX"); // "XX" (passthrough for unknown codes)
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
### Formatting addresses
|
|
@@ -34,12 +34,12 @@ formatCountry("XX"); // "XX" (passthrough for unknown codes)
|
|
|
34
34
|
import { formatAddress } from "shelving/util";
|
|
35
35
|
|
|
36
36
|
const addr = {
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
37
|
+
address1: "10 Downing Street",
|
|
38
|
+
address2: "",
|
|
39
|
+
city: "London",
|
|
40
|
+
state: "England",
|
|
41
|
+
postcode: "SW1A 2AA",
|
|
42
|
+
country: "GB",
|
|
43
43
|
};
|
|
44
44
|
|
|
45
45
|
formatAddress(addr);
|
package/docs/util/hash.md
CHANGED
|
@@ -15,11 +15,11 @@ Lightweight, deterministic string-to-number hashing. Useful for consistently map
|
|
|
15
15
|
```ts
|
|
16
16
|
import { hashString, hashStringBetween } from "shelving/util";
|
|
17
17
|
|
|
18
|
-
hashString("alice");
|
|
19
|
-
hashString("bob");
|
|
18
|
+
hashString("alice"); // 510 (stable across calls)
|
|
19
|
+
hashString("bob"); // 307
|
|
20
20
|
|
|
21
21
|
// Map a username to one of 10 avatar colours.
|
|
22
|
-
const colorIndex = hashStringBetween("alice", 0, 10);
|
|
22
|
+
const colorIndex = hashStringBetween("alice", 0, 10); // 0–9
|
|
23
23
|
```
|
|
24
24
|
|
|
25
25
|
|
package/docs/util/http.md
CHANGED
|
@@ -21,7 +21,7 @@ import { createRequest, createJSONRequest, createHeadRequest } from "shelving/ut
|
|
|
21
21
|
|
|
22
22
|
// Smart constructor — picks content type from payload.
|
|
23
23
|
createRequest("POST", "https://api.example.com/items", { name: "Widget" });
|
|
24
|
-
createRequest("GET",
|
|
24
|
+
createRequest("GET", "https://api.example.com/items", { status: "active" });
|
|
25
25
|
// GET → appends ?status=active to URL
|
|
26
26
|
|
|
27
27
|
// Explicit JSON request.
|
|
@@ -26,7 +26,10 @@ Serialise and deserialise class instances across a network boundary. `dehydrate(
|
|
|
26
26
|
import { hydrate, dehydrate, type Hydrations } from "shelving/util";
|
|
27
27
|
|
|
28
28
|
class Money {
|
|
29
|
-
|
|
29
|
+
constructor(
|
|
30
|
+
readonly amount: number,
|
|
31
|
+
readonly currency: string,
|
|
32
|
+
) {}
|
|
30
33
|
}
|
|
31
34
|
|
|
32
35
|
const HYDRATIONS: Hydrations = { Money };
|
|
@@ -36,9 +39,9 @@ const HYDRATIONS: Hydrations = { Money };
|
|
|
36
39
|
|
|
37
40
|
```ts
|
|
38
41
|
const serverValue = {
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
+
price: new Money(9.99, "GBP"),
|
|
43
|
+
tags: new Set(["sale", "new"]),
|
|
44
|
+
createdAt: new Date("2024-01-01"),
|
|
42
45
|
};
|
|
43
46
|
|
|
44
47
|
const plain = dehydrate(serverValue, HYDRATIONS);
|