hanzio 2.0.0 → 2.2.0

package/src/secrets/core.ts

@@ -68,6 +68,15 @@ export type SecretSet<K extends string, Parsed = Record<K, string>> = {
 	reload: (options?: SecretRequestOptions) => Promise<SecretSet<K, Parsed>>
 }
 
+/** A declaration that must be loaded explicitly before its values can be read. */
+export type LazySecretSet<
+	K extends string,
+	Parsed = Record<K, string>
+> = SecretSet<K, Parsed> & {
+	/** Initialize once. Concurrent calls share a load; use reload to refresh. */
+	load: (options?: SecretRequestOptions) => Promise<LazySecretSet<K, Parsed>>
+}
+
 // Shared across bundled entry points and package copies in the same JS realm.
 // Only helper-written values are registered; original environment overrides aren't.
 const registryKey = Symbol.for('hanzio.secrets.environmentWrites.v1')
@@ -118,21 +127,19 @@ function readOverrides<K extends string>(
 	) as Partial<Record<K, string>>
 }
 
-export async function defineSecretSet<
+export function createSecretSet<
 	const Keys extends readonly string[],
 	Parsed = Record<Keys[number], string>
 >(
 	keys: Keys,
 	options: CustomLoaderDefineSecretSetOptions<Keys[number], Parsed>,
 	environmentVariables?: EnvironmentVariables
-): Promise<SecretSet<Keys[number], Parsed>> {
+): LazySecretSet<Keys[number], Parsed> {
 	type K = Keys[number]
 
 	const keySet = [...new Set(keys)] as K[]
-	const environment = resolveSecretEnvironment(
-		options.environment,
-		environmentVariables
-	)
+	let environment: string | undefined
+	let initialized = false
 	const logger =
 		options.logger === false ? undefined : (options.logger ?? defaultLogger)
 
@@ -157,7 +164,8 @@ export async function defineSecretSet<
 	// Build, validate, and commit one snapshot under the caller’s deadline.
 	const loadSnapshot = async (
 		request: SecretRequestOptions,
-		signal: AbortSignal
+		signal: AbortSignal,
+		environment: string
 	) => {
 		// Fetch only keys that lack genuine local overrides.
 		const local = readOverrides(keySet, environmentVariables)
@@ -261,6 +269,7 @@ export async function defineSecretSet<
 		cached = next
 		parsed = nextParsed
 		sources = nextSources
+		initialized = true
 	}
 
 	const load = (request: SecretRequestOptions = {}): Promise<void> => {
@@ -273,12 +282,18 @@ export async function defineSecretSet<
 			const start = Date.now()
 
 			try {
+				environment ??= resolveSecretEnvironment(
+					options.environment,
+					environmentVariables
+				)
+				const resolvedEnvironment = environment
+
 				await withSecretDeadline(
 					{
 						timeoutMs: request.timeoutMs ?? options.timeoutMs,
 						signal: request.signal ?? options.signal
 					},
-					(signal) => loadSnapshot(request, signal)
+					(signal) => loadSnapshot(request, signal, resolvedEnvironment)
 				)
 
 				// Report the sources of committed values, not attempted fetches.
@@ -293,7 +308,7 @@ export async function defineSecretSet<
 				const counts = Object.fromEntries(sourceCounts)
 
 				log('info', 'Loaded secrets', {
-					environment,
+					environment: resolvedEnvironment,
 					count: keySet.length,
 					durationMs: Date.now() - start,
 					source: Object.keys(counts).join(' + ') || 'none',
@@ -306,7 +321,7 @@ export async function defineSecretSet<
 						: new SecretLoadError('LOADER', 'Secret loading failed.')
 
 				log('error', 'Secret loading failed', {
-					environment,
+					environment: environment ?? 'unresolved',
 					count: keySet.length,
 					durationMs: Date.now() - start,
 					code: safe.code
@@ -321,8 +336,19 @@ export async function defineSecretSet<
 		return inFlight
 	}
 
-	const secretSet: SecretSet<K, Parsed> = {
+	const assertLoaded = () => {
+		if (!initialized) {
+			throw new SecretLoadError(
+				'CONFIGURATION',
+				'Secret set has not been loaded. Await load() before reading values.'
+			)
+		}
+	}
+
+	const secretSet: LazySecretSet<K, Parsed> = {
 		secret(key) {
+			assertLoaded()
+
 			if (!Object.hasOwn(cached, key)) {
 				throw new SecretLoadError('MISSING_SECRETS', `Secret ${key} not found`)
 			}
@@ -331,9 +357,29 @@ export async function defineSecretSet<
 		},
 
 		// Return copies so consumers cannot mutate the internal snapshots.
-		secrets: () => ({ ...cached }),
-		parsed: () => structuredClone(parsed),
-		sources: () => ({ ...sources }),
+		secrets() {
+			assertLoaded()
+
+			return { ...cached }
+		},
+		parsed() {
+			assertLoaded()
+
+			return structuredClone(parsed)
+		},
+		sources() {
+			assertLoaded()
+
+			return { ...sources }
+		},
+
+		async load(request) {
+			if (!initialized) {
+				await load(request)
+			}
+
+			return secretSet
+		},
 
 		async reload(request) {
 			await load(request)
@@ -342,7 +388,17 @@ export async function defineSecretSet<
 		}
 	}
 
-	await load()
-
 	return secretSet
 }
+
+/** Compatibility API: declares and loads a complete snapshot before returning. */
+export async function defineSecretSet<
+	const Keys extends readonly string[],
+	Parsed = Record<Keys[number], string>
+>(
+	keys: Keys,
+	options: CustomLoaderDefineSecretSetOptions<Keys[number], Parsed>,
+	environmentVariables?: EnvironmentVariables
+): Promise<SecretSet<Keys[number], Parsed>> {
+	return createSecretSet(keys, options, environmentVariables).load()
+}

package/src/secrets/index.ts

@@ -1,5 +1,6 @@
 import {
-	defineSecretSet as defineCoreSecretSet,
+	createSecretSet as createCoreSecretSet,
+	type LazySecretSet,
 	type CommonSecretSetOptions,
 	type CustomLoaderDefineSecretSetOptions,
 	type SecretSet,
@@ -51,13 +52,13 @@ export function getSecretEnvironment(): SecretEnvironment {
 	) as SecretEnvironment
 }
 
-export async function defineSecretSet<
+export function createSecretSet<
 	const Keys extends readonly string[],
 	Parsed = Record<Keys[number], string>
 >(
 	keys: Keys,
 	options: DefineSecretSetOptions<Keys[number], Parsed>
-): Promise<SecretSet<Keys[number], Parsed>> {
+): LazySecretSet<Keys[number], Parsed> {
 	let loader: SecretSetLoader<Keys[number]>
 
 	if (!options.loader) {
@@ -69,7 +70,7 @@ export async function defineSecretSet<
 	}
 
 	// Supply process.env only from this Node/Bun entry point, keeping the core portable.
-	return defineCoreSecretSet(
+	return createCoreSecretSet(
 		keys,
 		{ ...options, loader },
 		getProcessEnvironment()
@@ -92,3 +93,14 @@ function createDefaultInfisicalLoader<K extends string, Parsed>(
 				options.clientSecretEnvKey ?? 'INFISICAL_CLIENT_SECRET'
 		})
 }
+
+/** Compatibility API: load immediately and fail before application startup. */
+export async function defineSecretSet<
+	const Keys extends readonly string[],
+	Parsed = Record<Keys[number], string>
+>(
+	keys: Keys,
+	options: DefineSecretSetOptions<Keys[number], Parsed>
+): Promise<SecretSet<Keys[number], Parsed>> {
+	return createSecretSet(keys, options).load()
+}

package/src/secrets/public-config.ts

@@ -0,0 +1,47 @@
+import type { SecretSet } from './core'
+import { SecretLoadError } from './errors'
+
+/**
+ * Read only explicitly listed public values. No process globals, secret loader,
+ * environment writes, or async initialization; safe in frontend tooling.
+ * Validate application-specific formats with your schema after secrets().
+ */
+export function readPublicConfig<const Keys extends readonly string[]>(
+	keys: Keys,
+	values: Readonly<Record<string, string | undefined>>
+): Pick<SecretSet<Keys[number]>, 'secret' | 'secrets'> {
+	type K = Keys[number]
+
+	const snapshot = Object.fromEntries(
+		keys.map((key) => [
+			key,
+			Object.hasOwn(values, key) ? values[key] : undefined
+		])
+	)
+	const missing = keys.filter(
+		(key) => typeof snapshot[key] !== 'string' || !snapshot[key]
+	)
+
+	if (missing.length) {
+		throw new SecretLoadError(
+			'MISSING_SECRETS',
+			`Missing required public configuration: ${missing.join(', ')}`
+		)
+	}
+
+	const configured = snapshot as Record<K, string>
+
+	return {
+		secret(key) {
+			if (!Object.hasOwn(configured, key)) {
+				throw new SecretLoadError(
+					'CONFIGURATION',
+					`Public key ${key} is not configured.`
+				)
+			}
+
+			return configured[key]
+		},
+		secrets: () => ({ ...configured })
+	}
+}

package/src/secrets/vite.ts

@@ -57,3 +57,5 @@ export function viteSecretSetPlugin<K extends string>(
 		config: () => ({ define: getViteDefine(secretSet, options) })
 	}
 }
+
+export { readPublicConfig } from './public-config'

package/src/secrets/worker.ts

@@ -2,3 +2,5 @@
 export * from './core'
 export { cloudflareWorkerEnvLoader } from './worker-loader'
 export type { SecretRequestOptions } from './deadline'
+
+export { readPublicConfig } from './public-config'

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`).