Skip to content

Commit c669da0

Browse files
ryan-williamsclaude
andcommitted
Update README with paginationParam, codeParam, codesParam docs
- Add Compact Code Mapping section with `codeParam`/`codesParam` examples - Add Pagination section with offset+pageSize encoding examples - Add Built-in Param Types table (all 12 params) - Add Built-in MultiParam Types table (`multiIntParam`, `multiFloatParam`) - Note deprecation of `serializeParams`/`parseParams` - Document `serializeMultiParams`/`parseMultiParams` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 42a31cb commit c669da0

File tree

1 file changed

+62
-3
lines changed

1 file changed

+62
-3
lines changed

README.md

Lines changed: 62 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -90,10 +90,42 @@ const [ids, setIds] = useUrlParam('ids', numberArrayParam([]))
9090

9191
### Multi-value Arrays (repeated keys)
9292
```typescript
93-
import { useMultiUrlParam, multiStringParam } from '@rdub/use-url-params'
93+
import { useMultiUrlParam, multiStringParam, multiIntParam } from '@rdub/use-url-params'
9494

9595
const [tags, setTags] = useMultiUrlParam('tag', multiStringParam())
9696
// ?tag=foo&tag=bar&tag=baz → ["foo", "bar", "baz"]
97+
98+
const [ids, setIds] = useMultiUrlParam('id', multiIntParam())
99+
// ?id=1&id=2&id=3 → [1, 2, 3]
100+
101+
// Also available: multiFloatParam()
102+
```
103+
104+
### Compact Code Mapping
105+
```typescript
106+
// Single value with short codes
107+
const [metric, setMetric] = useUrlParam('y', codeParam('Rides', {
108+
Rides: 'r',
109+
Minutes: 'm',
110+
}))
111+
// ?y=m → "Minutes", omitted for default "Rides"
112+
113+
// Multi-value with short codes (omits when all selected)
114+
const [regions, setRegions] = useUrlParam('r', codesParam(
115+
['NYC', 'JC', 'HOB'],
116+
{ NYC: 'n', JC: 'j', HOB: 'h' }
117+
))
118+
// ?r=nj → ["NYC", "JC"], omitted when all three selected
119+
```
120+
121+
### Pagination
122+
```typescript
123+
const [page, setPage] = useUrlParam('p', paginationParam(20))
124+
// Encodes offset + pageSize compactly using + as delimiter:
125+
// { offset: 0, pageSize: 20 } → (omitted)
126+
// { offset: 0, pageSize: 50 } → ?p=+50
127+
// { offset: 100, pageSize: 20 } → ?p=100
128+
// { offset: 100, pageSize: 50 } → ?p=100+50
97129
```
98130

99131
## Custom Params
@@ -235,10 +267,37 @@ type MultiParam<T> = {
235267
}
236268
```
237269
270+
### Built-in Param Types
271+
272+
| Param | Type | Description |
273+
|-------|------|-------------|
274+
| `boolParam` | `Param<boolean>` | `?key` = true, absent = false |
275+
| `stringParam(init?)` | `Param<string \| undefined>` | Optional string |
276+
| `defStringParam(init)` | `Param<string>` | Required string with default |
277+
| `intParam(init)` | `Param<number>` | Integer with default |
278+
| `floatParam(init)` | `Param<number>` | Float with default |
279+
| `optIntParam` | `Param<number \| null>` | Optional integer |
280+
| `enumParam(init, values)` | `Param<T>` | Validated enum |
281+
| `stringsParam(init?, delim?)` | `Param<string[]>` | Delimiter-separated strings |
282+
| `numberArrayParam(init?)` | `Param<number[]>` | Comma-separated numbers |
283+
| `codeParam(init, codeMap)` | `Param<T>` | Enum with short URL codes |
284+
| `codesParam(allValues, codeMap, sep?)` | `Param<T[]>` | Multi-value with short codes |
285+
| `paginationParam(defaultSize, validSizes?)` | `Param<Pagination>` | Offset + page size |
286+
287+
### Built-in MultiParam Types
288+
289+
| Param | Type | Description |
290+
|-------|------|-------------|
291+
| `multiStringParam(init?)` | `MultiParam<string[]>` | Repeated string params |
292+
| `multiIntParam(init?)` | `MultiParam<number[]>` | Repeated integer params |
293+
| `multiFloatParam(init?)` | `MultiParam<number[]>` | Repeated float params |
294+
238295
### Core Utilities
239296
240-
- `serializeParams(params)`: Convert params object to URL query string
241-
- `parseParams(source)`: Parse URL string or URLSearchParams to object
297+
- `serializeParams(params)`: Convert params object to URL query string *(deprecated, use `serializeMultiParams`)*
298+
- `parseParams(source)`: Parse URL string or URLSearchParams to object *(deprecated, use `parseMultiParams`)*
299+
- `serializeMultiParams(params)`: Convert multi-value params to URL query string
300+
- `parseMultiParams(source)`: Parse URL to multi-value params object
242301
- `getCurrentParams()`: Get current URL params (browser only)
243302
- `updateUrl(params, push?)`: Update URL without reloading (browser only)
244303

0 commit comments

Comments
 (0)