Skip to content

Commit cba8449

Browse files
ryan-williamsclaude
andcommitted
Update README: hook options, pointParam, useMultiUrlStates, missing utilities
- Update hook signatures to show `options?: UseUrlStateOptions` with `debounce` - Add `useMultiUrlStates` to API Reference - Add Point Params section with string/binary encoding examples - Add `floatParam` and `pointParam` to Binary Encoding table - Add `clearParams` and `notifyLocationChange` to Core Utilities Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 319feed commit cba8449

File tree

1 file changed

+36
-6
lines changed

1 file changed

+36
-6
lines changed

README.md

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,22 @@ const [lat, setLat] = useUrlState('lat', floatParam({
252252
}))
253253
```
254254

255+
### Point Params
256+
257+
Encode 2D points compactly:
258+
259+
```typescript
260+
import { pointParam } from 'use-prms'
261+
262+
// String encoding (human-readable)
263+
const [pos, setPos] = useUrlState('p', pointParam({ encoding: 'string', decimals: 2 }))
264+
// ?p=1.23+5.68 → { x: 1.23, y: 5.68 }
265+
266+
// Binary encoding (more compact, default)
267+
const [pos, setPos] = useUrlState('p', pointParam({ precision: 22 }))
268+
// ?p=<base64> → { x: 1.234, y: 5.678 }
269+
```
270+
255271
### Custom Alphabets
256272

257273
Choose between standard base64url or ASCII-sorted alphabet:
@@ -302,32 +318,42 @@ Same API, different URL location. Useful when query strings conflict with server
302318

303319
## API Reference <a id="api"></a>
304320

305-
### `useUrlState<T>(key: string, param: Param<T>, push?: boolean)`
321+
### `useUrlState<T>(key, param, options?)`
306322

307323
React hook for managing a single URL parameter.
308324

309325
- `key`: Query parameter key
310326
- `param`: Param encoder/decoder
311-
- `push`: Use pushState (true) or replaceState (false, default)
327+
- `options`: `UseUrlStateOptions | boolean` (boolean is legacy shorthand for `push`)
328+
- `push?`: Use pushState (true) or replaceState (false, default)
329+
- `debounce?`: Debounce URL writes in ms (state updates immediately)
312330
- Returns: `[value: T, setValue: (value: T) => void]`
313331

314-
### `useUrlStates<P>(params: P, push?: boolean)`
332+
### `useUrlStates<P>(params, options?)`
315333

316334
React hook for managing multiple URL parameters together.
317335

318336
- `params`: Object mapping keys to Param types
319-
- `push`: Use pushState (true) or replaceState (false, default)
337+
- `options`: Same as `useUrlState`
320338
- Returns: `{ values, setValues }`
321339

322-
### `useMultiUrlState<T>(key: string, param: MultiParam<T>, push?: boolean)`
340+
### `useMultiUrlState<T>(key, param, options?)`
323341

324342
React hook for managing a multi-value URL parameter (repeated keys).
325343

326344
- `key`: Query parameter key
327345
- `param`: MultiParam encoder/decoder
328-
- `push`: Use pushState (true) or replaceState (false, default)
346+
- `options`: Same as `useUrlState`
329347
- Returns: `[value: T, setValue: (value: T) => void]`
330348

349+
### `useMultiUrlStates<P>(params, options?)`
350+
351+
React hook for managing multiple multi-value URL parameters together.
352+
353+
- `params`: Object mapping keys to MultiParam types
354+
- `options`: Same as `useUrlState`
355+
- Returns: `{ values, setValues }`
356+
331357
### `Param<T>`
332358

333359
Bidirectional encoder/decoder interface:
@@ -380,6 +406,8 @@ type MultiParam<T> = {
380406
| Export | Description |
381407
|--------|-------------|
382408
| `BitBuffer` | Bit-level buffer for packing/unpacking arbitrary bit widths |
409+
| `floatParam(opts)` | Float with configurable encoding (string or base64) and precision |
410+
| `pointParam(opts?)` | 2D point (`{ x, y }`) with string or packed binary encoding |
383411
| `binaryParam(opts)` | Create param from `toBytes`/`fromBytes` converters |
384412
| `base64Param(toBytes, fromBytes)` | Shorthand for `binaryParam` |
385413
| `base64Encode(bytes, opts?)` | Encode `Uint8Array` to base64 string |
@@ -394,6 +422,8 @@ type MultiParam<T> = {
394422
- `parseMultiParams(source)`: Parse URL to multi-value params object
395423
- `getCurrentParams()`: Get current URL params (browser only)
396424
- `updateUrl(params, push?)`: Update URL without reloading (browser only)
425+
- `clearParams(strategy?)`: Clear all URL params (`'query'` or `'hash'`)
426+
- `notifyLocationChange()`: Manually notify hooks of a URL change (for edge cases like direct `location` assignment)
397427
398428
## Examples <a id="examples"></a>
399429

0 commit comments

Comments
 (0)