Skip to content

Commit eac45a9

Browse files
committed
Add Compatible parsing strategy to README
1 parent 2cc32f4 commit eac45a9

File tree

1 file changed

+33
-4
lines changed

1 file changed

+33
-4
lines changed

README.md

Lines changed: 33 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,6 @@ Serialization uses
2121
[`URLSearchParams.toString()`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/toString#return_value)
2222
which encodes most non-alphanumeric characters.
2323

24-
Serialization is guaranteed to be well-defined within each type, i.e.,
25-
if the type of value for a given key in the query string is fixed and known by
26-
the consumer parsing the string, it can be unambigously parsed back to the original primitive value.
27-
2824
- The primitive `null` is serialized to an empty value,
2925
e.g., `{ foo: null }` serializes to `foo=`.
3026
- Any `undefined` values are removed,
@@ -67,6 +63,39 @@ the consumer parsing the string, it can be unambigously parsed back to the origi
6763
- Serialization of functions or other objects is
6864
is not supported and will throw an `UnserializableParamError`.
6965

66+
### Compatible parsing strategy
67+
68+
Serialization is guaranteed to be well-defined within each type, i.e.,
69+
if the value-type for a given key in the query string is fixed and known by
70+
the consumer parsing the string, it can be unambigously parsed back to the original primitive value:
71+
72+
- A parser can implement a inverse function to the serialization if it uses a schema which,
73+
for each node, defines a type matching exactly one of the primitive or nested types below.
74+
- Any node may be marked optional, i.e., `undefined`, which corresponds to the absence of the key in the query string.
75+
- The parser may choose `Temporal.Instant` as an equivalent alternative to `Date`.
76+
- Object keys must not include a `.`.
77+
78+
##### Primitive
79+
80+
- `string | null`.
81+
- Excludes zero-length strings.
82+
- `number | null`.
83+
- `bigint | null`.
84+
- `boolean | null`.
85+
- `Date | null`.
86+
- `Array<string | number | bigint | boolean | Date>`.
87+
- Excludes zero-length strings.
88+
- Arrays must use a single value-type.
89+
- Otherwise, the array may be a tuple which may use a different value-type per slot.
90+
91+
#### Nested
92+
93+
- `object | null`.
94+
- Must meet the same constraints as the top level schema.
95+
- `Record | null`.
96+
- The record type must use a `string` type for the key,
97+
and a single primitive or single nested type for the value.
98+
7099
## Installation
71100

72101
Add this as a dependency to your project using [npm] with

0 commit comments

Comments
 (0)