hanzio 2.1.0 → 2.2.0

package/src/sitemap/README.md

@@ -0,0 +1,61 @@
+---
+description: Discover and crawl XML sitemaps for URL discovery; uses the local p-queue utility for concurrency.
+---
+
+# hanzio/sitemap
+
+`getDomainSitemap(domain, options)` finds a domain's sitemaps (the `Sitemap:` lines in robots.txt first, then common locations like `/sitemap.xml`) and crawls them with bounded parallelism using the local `hanzio/p-queue` utility.
+
+- A document whose root element is `<sitemapindex>` is treated as a list of child sitemaps. A document whose root element is `<urlset>` is treated as a list of pages.
+- `<loc>` values are XML-entity decoded, and CDATA is supported.
+- Gzipped sitemaps (`.xml.gz`) are decompressed with `DecompressionStream`.
+- Every request has its own timeout (`AbortSignal.timeout`).
+
+Requires runtime `fetch`, `AbortSignal.timeout` and `DecompressionStream` (Node 18+, Bun, modern browsers), or pass your own `fetch`.
+
+```ts
+import { getDomainSitemap, getDomainSitemapEntries } from 'hanzio/sitemap'
+
+const urls = await getDomainSitemap('example.com', {
+	filterIndexes: 'posts', // substring, RegExp or (url) => boolean
+	filterUrls: /\/blog\//,
+	maxUrls: 1000
+})
+
+// With lastmod
+const entries = await getDomainSitemapEntries('example.com')
+// [{ loc: 'https://example.com/a', lastmod: '2024-01-05' }, ...]
+```
+
+## Options (`SitemapOptions`)
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `filterIndexes` | none | Only follow child sitemaps that match (substring, RegExp or predicate). |
+| `filterUrls` | none | Only keep page URLs that match. |
+| `concurrency` | `10` | The maximum number of sitemap fetches that run at the same time. |
+| `maxDepth` | `5` | The maximum sitemap-index nesting depth. |
+| `maxUrls` | none | Stop crawling after this many URLs have been collected. |
+| `timeout` | `10000` | The timeout for each request, in ms. |
+| `userAgent` | `'SitemapCrawler/1.0'` | The `User-Agent` header sent with each request. |
+| `fetch` | `globalThis.fetch` | A custom fetch implementation. |
+| `onError` | `console.warn` | `(url, error) => void`, called when a robots.txt or sitemap request fails. |
+| `respectRobots` | `false` | Drop page URLs that robots.txt disallows for `userAgent` (reuses the robots.txt fetched for discovery). A missing or failed robots.txt allows everything. |
+
+Both functions throw `No sitemaps found for the domain` when discovery finds nothing.
+
+## robots.txt
+
+`parseRobotsTxt(body, userAgent = '*')` returns the rules for one crawler, following RFC 9309: the groups that name its product token (case-insensitive, so `MyBot/2.0` matches `User-agent: mybot`), merged, or else the `User-agent: *` groups. Directive names are case-insensitive and `#` comments are ignored. `sitemaps` lists every `Sitemap:` line.
+
+`isAllowedByRobots(rules, url)` checks an absolute URL or a path (plus query string). The longest matching pattern wins, `Allow` wins a tie, `*` matches any characters and a trailing `$` anchors the end. An empty `Disallow:` allows everything, and `/robots.txt` is always allowed.
+
+```ts
+import { isAllowedByRobots, parseRobotsTxt } from 'hanzio/sitemap'
+
+const rules = parseRobotsTxt(body, 'MyBot/1.0')
+// { allow: ['/cart/help'], disallow: ['/cart/'], sitemaps: [...], crawlDelaySec?: 5 }
+
+isAllowedByRobots(rules, 'https://example.com/cart/add?id=1') // false
+isAllowedByRobots(rules, '/cart/help') // true
+```

package/src/storage/README.md

@@ -0,0 +1,71 @@
+---
+description: Typed persisted values over localStorage/sessionStorage or async stores like React Native AsyncStorage, with fallbacks that never throw.
+---
+
+# hanzio/storage
+
+`createStorageItem` wraps one key in `localStorage` (or any `SyncStorageLike`) as a typed value. It never throws:
+
+- A missing, corrupt (bad JSON) or invalid (`parse` throws) value reads as `fallback`.
+- When the storage throws (quota exceeded, Safari private mode, sandboxed iframes), the latest `set`/`remove` is kept in memory for that item, so reads stay consistent for the session.
+- Without an accessible `globalThis.localStorage` (SSR, Node, Bun, blocked access) it uses a shared in-memory store.
+
+```ts
+import { z } from 'zod'
+import { createStorageItem } from 'hanzio/storage'
+
+const PanelPrefs = z.object({ open: z.boolean(), width: z.number() })
+
+const panelPrefs = createStorageItem({
+	key: 'panel-prefs',
+	fallback: { open: false, width: 320 },
+	parse: PanelPrefs.parse
+})
+
+panelPrefs.get() // { open: false, width: 320 }
+panelPrefs.set({ open: true, width: 400 })
+panelPrefs.remove()
+
+// Another tab changed it (the `storage` event). Returns an unsubscribe function.
+const stop = panelPrefs.subscribe((prefs) => console.log(prefs))
+```
+
+Use `sessionStorage` or plain strings:
+
+```ts
+const sendOnEnter = createStorageItem({
+	key: 'send-on-enter',
+	fallback: false,
+	storage: sessionStorage,
+	serialize: String,
+	deserialize: (raw) => raw === 'true'
+})
+```
+
+## Async stores
+
+`createAsyncStorageItem` takes the same options, but `storage` is required and the methods return promises. It never rejects.
+
+```ts
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import { createAsyncStorageItem } from 'hanzio/storage'
+
+const readIds = createAsyncStorageItem({
+	key: '@notification_read_session_ids',
+	fallback: [] as string[],
+	storage: AsyncStorage,
+	parse: z.array(z.string()).parse
+})
+
+await readIds.set([...(await readIds.get()), 'abc'])
+```
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `createStorageItem(options)` | `{ key, get, set, remove, subscribe }` over a `SyncStorageLike` (default `localStorage`). |
+| `createAsyncStorageItem(options)` | `{ key, get, set, remove }` over an `AsyncStorageLike`. |
+| `createMemoryStorage()` | A `Map`-backed `SyncStorageLike`, for tests and SSR. |
+
+Options: `key`, `fallback`, `storage`, `parse` (validate the deserialized value; throwing means `fallback`), `serialize` (default `JSON.stringify`), `deserialize` (default `JSON.parse`).

package/src/typedswitch/README.md

@@ -0,0 +1,319 @@
+# typedswitch
+
+A type-safe, exhaustive switch expression for TypeScript. Handle discriminated unions and string literals with full type inference, compile-time exhaustiveness checking, and async support.
+
+## Installation
+
+```bash
+npm install typedswitch
+```
+
+```bash
+pnpm add typedswitch
+```
+
+```bash
+bun add typedswitch
+```
+
+## Features
+
+- **Full type inference** — Return types are automatically inferred from your handlers
+- **Exhaustiveness checking** — TypeScript ensures all cases are handled at compile time
+- **Discriminated union support** — Works with any discriminant key, not just `type`
+- **Async-aware** — Async handlers preserve their `Promise` return type
+- **Default handlers** — Handle remaining cases with a fallback
+- **Return type constraints** — Enforce that all handlers return a specific type
+- **`assertNever`** — Exhaustiveness checking for regular `switch` statements
+
+## Usage
+
+### String/Enum Input
+
+Switch on a string literal or enum value directly:
+
+```typescript
+import { typedSwitch } from 'typedswitch'
+
+type Status = 'success' | 'error' | 'pending'
+
+const status: Status = 'success'
+
+// All cases required — TypeScript enforces exhaustiveness
+const message = typedSwitch(status, {
+  success: () => 'Operation completed!',
+  error: () => 'Something went wrong',
+  pending: () => 'Please wait...',
+})
+// message: string
+```
+
+Each handler receives the narrowed value:
+
+```typescript
+const result = typedSwitch(status, {
+  success: (val) => val.toUpperCase(), // val: 'success'
+  error: (val) => val.toUpperCase(),   // val: 'error'
+  pending: (val) => val.toUpperCase(), // val: 'pending'
+})
+```
+
+### Discriminated Union Input
+
+Switch on objects with a string, number, or boolean discriminant property (like `type`, `kind`, `status`, etc.):
+
+```typescript
+type Event =
+  | { type: 'click'; x: number; y: number }
+  | { type: 'scroll'; offset: number }
+  | { type: 'keypress'; key: string }
+
+const event: Event = { type: 'click', x: 100, y: 200 }
+
+// Specify the discriminant key as the second argument
+const description = typedSwitch(event, 'type', {
+  click: (e) => `Clicked at (${e.x}, ${e.y})`,   // e: { type: 'click'; x: number; y: number }
+  scroll: (e) => `Scrolled ${e.offset}px`,       // e: { type: 'scroll'; offset: number }
+  keypress: (e) => `Pressed ${e.key}`,           // e: { type: 'keypress'; key: string }
+})
+// description: string
+```
+
+Works with any discriminant key:
+
+```typescript
+type Order =
+  | { status: 'pending'; createdAt: Date }
+  | { status: 'completed'; completedAt: Date }
+  | { status: 'cancelled'; reason: string }
+
+const order: Order = { status: 'completed', completedAt: new Date() }
+
+const info = typedSwitch(order, 'status', {
+  pending: (o) => `Created: ${o.createdAt}`,
+  completed: (o) => `Done: ${o.completedAt}`,
+  cancelled: (o) => `Cancelled: ${o.reason}`,
+})
+```
+
+Number and boolean discriminants work too. Cases are keyed by `String(value)`:
+
+```typescript
+type Response =
+  | { code: 200; body: string }
+  | { code: 404; path: string }
+
+typedSwitch(response, 'code', {
+  200: (r) => r.body,              // r: { code: 200; body: string }
+  404: (r) => `Missing ${r.path}`, // r: { code: 404; path: string }
+})
+
+type Result = { ok: true; value: number } | { ok: false; error: string }
+
+typedSwitch(result, 'ok', {
+  true: (r) => r.value,
+  false: (r) => r.error,
+})
+```
+
+### Default Handler
+
+Handle a subset of cases and catch the rest with a default handler:
+
+```typescript
+type Status = 'success' | 'error' | 'pending' | 'cancelled'
+
+const status: Status = 'cancelled'
+
+// Only handle specific cases, default handles the rest
+const message = typedSwitch(
+  status,
+  {
+    success: () => 'Done!',
+    error: () => 'Failed!',
+  },
+  (val) => `Unhandled status: ${val}`  // val: 'pending' | 'cancelled' (unhandled cases only)
+)
+// message: string
+```
+
+Only required, defined handlers narrow the default handler's input. Optional
+handlers (including reusable `PartialStringSwitchCases` and
+`PartialObjectSwitchCases` maps) can be absent, so their cases remain in the
+default handler's input type.
+
+Works with discriminated unions too:
+
+```typescript
+const description = typedSwitch(
+  event,
+  'type',
+  {
+    click: (e) => `Clicked at (${e.x}, ${e.y})`,
+  },
+  (e) => `Unhandled event: ${e.type}`  // e: scroll or keypress event (unhandled members only)
+)
+```
+
+### Async Handlers
+
+Mix sync and async handlers freely. `typedSwitch` returns the selected handler's value directly, so async branches preserve their `Promise` return type while sync branches remain sync:
+
+```typescript
+// All sync — returns string
+const syncResult = typedSwitch(status, {
+  success: () => 'ok',
+  error: () => 'err',
+  pending: () => 'wait',
+})
+// syncResult: string
+
+// All async — returns Promise<string>
+const asyncResult = typedSwitch(status, {
+  success: async () => {
+    const data = await fetchData()
+    return data.message
+  },
+  error: async () => 'err',
+  pending: async () => 'wait',
+})
+// asyncResult: Promise<string>
+
+const message = await asyncResult
+
+// Mixed sync/async — returns string | Promise<string>
+const mixedResult = typedSwitch(status, {
+  success: () => 'ok',
+  error: async () => 'err',
+  pending: () => 'wait',
+})
+```
+
+### Return Type Inference
+
+Return types are inferred from all handlers as a union:
+
+```typescript
+const result = typedSwitch(status, {
+  success: () => ({ ok: true, data: 'hello' }),
+  error: () => ({ ok: false, code: 500 }),
+  pending: () => null,
+})
+// result: { ok: true; data: string } | { ok: false; code: number } | null
+```
+
+### Return Type Constraints
+
+Enforce that all handlers return a type extending a constraint with `typedSwitch<Constraint>(...)`. The `<Constraint>` is optional; omit it when you want TypeScript to infer the return types freely.
+
+```typescript
+interface HasId {
+  id: string
+}
+
+// All handlers must return something with { id: string }
+const result = typedSwitch<HasId>(status, {
+  success: () => ({ id: '123', name: 'John' }),     // ✓ OK
+  error: () => ({ id: '456', code: 500 }),          // ✓ OK
+  pending: () => ({ id: '789' }),                   // ✓ OK
+})
+// result: HasId
+
+// This would be a compile error:
+typedSwitch<HasId>(status, {
+  success: () => ({ name: 'John' }),  // ✗ Error: missing 'id'
+  error: () => ({ id: '456' }),
+  pending: () => ({ id: '789' }),
+})
+```
+
+Constraints also work with discriminated unions and default handlers:
+
+```typescript
+const result = typedSwitch<HasId>(
+  event,
+  'type',
+  {
+    click: () => ({ id: 'click-1', x: 10, y: 20 }),
+    scroll: () => ({ id: 'scroll-1', offset: 100 }),
+    keypress: () => ({ id: 'key-1', key: 'Enter' }),
+  }
+)
+```
+
+## Error Handling
+
+When a case is unhandled at runtime (e.g., due to unsafe casts), `typedSwitch` throws a descriptive error:
+
+```typescript
+const status = 'unknown' as Status
+
+typedSwitch(status, {
+  success: () => 'ok',
+  error: () => 'err',
+})
+// Throws: "Unhandled case: unknown. Available cases: success, error"
+```
+
+For discriminated unions:
+
+```typescript
+// Throws: "Unhandled case: unknown (discriminant key: "type"). Available cases: click, scroll, keypress"
+```
+
+Object discriminants must be strings, numbers, or booleans. Missing or other discriminant values throw a runtime error if they reach `typedSwitch`.
+
+## `assertNever`
+
+For regular `switch` statements, put `assertNever` in the `default` branch. It fails to compile if a case is missing, and throws at runtime if an unexpected value gets through:
+
+```typescript
+import { assertNever } from 'typedswitch'
+
+function label(status: Status) {
+  switch (status) {
+    case 'success': return 'Done'
+    case 'error': return 'Failed'
+    case 'pending': return 'Waiting'
+    default: return assertNever(status) // compile error if a case is missing
+  }
+}
+```
+
+## API Reference
+
+### `typedSwitch(value, cases)`
+
+Switch on a string literal with exhaustive case handling.
+
+### `typedSwitch(value, cases, defaultHandler)`
+
+Switch on a string literal with partial cases and a default fallback.
+
+### `typedSwitch(object, key, cases)`
+
+Switch on a discriminated union using the specified discriminant key (string, number, or boolean values).
+
+### `typedSwitch(object, key, cases, defaultHandler)`
+
+Switch on a discriminated union with partial cases and a default fallback.
+
+### `typedSwitch<Constraint>(value, cases)`
+
+Switch on a string literal while enforcing that each handler returns `Constraint` or `Promise<Constraint>`.
+
+### `typedSwitch<Constraint>(object, key, cases)`
+
+Switch on a discriminated union while enforcing that each handler returns `Constraint` or `Promise<Constraint>`.
+
+### `assertNever(value, message?)`
+
+Takes a `never` value and always throws (`Unexpected value: ${value}` or `message`). Use it for exhaustive `switch` statements.
+
+### Exported Helper Types
+
+`StringSwitchCases`, `PartialStringSwitchCases`, `ObjectSwitchCases`, and `PartialObjectSwitchCases` are exported for users who want to annotate reusable case maps.
+
+## License
+
+MIT