hanzio 3.1.1 → 3.3.0

package/src/crypto/node.ts

@@ -0,0 +1,90 @@
+// Synchronous twin of `createSealer`, on `node:crypto`, for code that cannot
+// await: formatters, getters, Prisma result extensions. Same options, same
+// envelope, so either sealer opens what the other sealed.
+
+import {
+	createCipheriv,
+	createDecipheriv,
+	hkdfSync,
+	randomBytes
+} from 'node:crypto'
+import {
+	type Envelope,
+	formatEnvelope,
+	jsonToSeal,
+	parseEnvelope,
+	type SealerOptions,
+	SealerError,
+	sealerKeyInputs
+} from './sealer'
+
+export { SealerError, type SealerErrorCode, type SealerOptions } from './sealer'
+
+export type SealerSync = {
+	seal(plaintext: string): string
+	open(sealed: string): string
+	sealJson(value: unknown): string
+	openJson<T = unknown>(sealed: unknown): T
+}
+
+const ALGORITHM = 'aes-256-gcm'
+
+/**
+ * AES-256-GCM sealing with a random 96-bit IV per value, synchronously.
+ *
+ * @example
+ * const secrets = createSealerSync({ secret: process.env.APP_SECRET!, info: 'app.credentials.v1' })
+ * const stored = secrets.sealJson({ accessToken })
+ * const { accessToken } = secrets.openJson<{ accessToken: string }>(stored)
+ */
+export function createSealerSync(options: SealerOptions): SealerSync {
+	const { secret, contexts } = sealerKeyInputs(options)
+
+	const keys: Buffer[] = []
+	const getKey = (index: number) => {
+		let key = keys[index]
+		if (!key) {
+			const { salt, info } = contexts[index] as (typeof contexts)[number]
+			key = Buffer.from(hkdfSync('sha256', secret, salt, info, 32))
+			keys[index] = key
+		}
+		return key
+	}
+
+	const seal = (plaintext: string) => {
+		const iv = randomBytes(12)
+		const cipher = createCipheriv(ALGORITHM, getKey(0), iv)
+		const ciphertext = Buffer.concat([
+			cipher.update(plaintext, 'utf8'),
+			cipher.final()
+		])
+		return formatEnvelope(iv, cipher.getAuthTag(), ciphertext)
+	}
+
+	const openEnvelope = ({ iv, tag, ciphertext }: Envelope) => {
+		for (let index = 0; index < contexts.length; index++) {
+			try {
+				const decipher = createDecipheriv(ALGORITHM, getKey(index), iv)
+				decipher.setAuthTag(tag)
+				return Buffer.concat([
+					decipher.update(ciphertext),
+					decipher.final()
+				]).toString('utf8')
+			} catch (_error) {}
+		}
+		throw new SealerError('decrypt_failed')
+	}
+
+	return {
+		seal,
+		open(sealed) {
+			const envelope = parseEnvelope(sealed, options.passthroughUnsealed)
+			return envelope ? openEnvelope(envelope) : sealed
+		},
+		sealJson: (value) => seal(jsonToSeal(value)),
+		openJson<T = unknown>(sealed: unknown) {
+			const envelope = parseEnvelope(sealed, options.passthroughUnsealed)
+			return (envelope ? JSON.parse(openEnvelope(envelope)) : sealed) as T
+		}
+	}
+}

package/src/crypto/sealer.ts

@@ -15,13 +15,24 @@ export type SealerOptions = {
 	salt?: string
 	/** HKDF info; use a distinct value per purpose. Default: `'hanzio.sealer.aes-256-gcm.v1'` */
 	info?: string
+	/**
+	 * Older `{ salt, info }` pairs that `open` also tries, so values sealed before
+	 * a rename stay readable. `seal` always uses `salt` and `info`.
+	 */
+	fallbacks?: readonly { salt?: string; info?: string }[]
+	/**
+	 * `open` and `openJson` return a value that was never sealed unchanged
+	 * (`{}`, a legacy plaintext) instead of throwing. Malformed envelopes and
+	 * other envelope versions still throw.
+	 */
+	passthroughUnsealed?: boolean
 }
 
 export type Sealer = {
 	seal(plaintext: string): Promise<string>
 	open(sealed: string): Promise<string>
 	sealJson(value: unknown): Promise<string>
-	openJson<T = unknown>(sealed: string): Promise<T>
+	openJson<T = unknown>(sealed: unknown): Promise<T>
 }
 
 export type SealerErrorCode =
@@ -50,26 +61,92 @@ const IV_BYTES = 12
 const TAG_BYTES = 16
 const DEFAULT_INFO = 'hanzio.sealer.aes-256-gcm.v1'
 
+// The helpers below are shared with the `node:crypto` sealer in `./node`.
+
+/** The secret's bytes and every HKDF context `open` tries, primary first. */
+export function sealerKeyInputs(options: SealerOptions) {
+	const secret = toBytes(options.secret)
+	if (secret.length === 0) {
+		throw new TypeError('Sealer secret must not be empty')
+	}
+	const contexts = [options, ...(options.fallbacks ?? [])].map(
+		({ salt = '', info = DEFAULT_INFO }) => ({ salt, info })
+	)
+	return { secret, contexts }
+}
+
+export function formatEnvelope(
+	iv: Uint8Array,
+	tag: Uint8Array,
+	ciphertext: Uint8Array
+): string {
+	return `${PREFIX}${encodeBase64Url(iv)}.${encodeBase64Url(tag)}.${encodeBase64Url(ciphertext)}`
+}
+
+export type Envelope = {
+	iv: Uint8Array<ArrayBuffer>
+	tag: Uint8Array<ArrayBuffer>
+	ciphertext: Uint8Array<ArrayBuffer>
+}
+
+/** `null` means `sealed` was never sealed and `passthroughUnsealed` allows it. */
+export function parseEnvelope(
+	sealed: unknown,
+	passthroughUnsealed = false
+): Envelope | null {
+	if (typeof sealed !== 'string' || !sealed.startsWith(PREFIX)) {
+		const isEnvelope = typeof sealed === 'string' && /^enc:v\d+:/.test(sealed)
+		if (isEnvelope) throw new SealerError('unsupported_version')
+		if (passthroughUnsealed) return null
+		throw new SealerError('malformed')
+	}
+
+	const parts = sealed.slice(PREFIX.length).split('.')
+	let envelope: Envelope
+	try {
+		if (parts.length !== 3) throw new Error()
+		envelope = {
+			iv: decodeBase64Url(parts[0] as string),
+			tag: decodeBase64Url(parts[1] as string),
+			ciphertext: decodeBase64Url(parts[2] as string)
+		}
+	} catch (_error) {
+		throw new SealerError('malformed')
+	}
+	if (envelope.iv.length !== IV_BYTES || envelope.tag.length !== TAG_BYTES) {
+		throw new SealerError('malformed')
+	}
+	return envelope
+}
+
+export function jsonToSeal(value: unknown): string {
+	const json = JSON.stringify(value)
+	if (json === undefined) {
+		throw new TypeError('sealJson value is not JSON-serializable')
+	}
+	return json
+}
+
 /**
  * AES-256-GCM sealing with a random 96-bit IV per value. Envelope:
- * `enc:v1:<b64url(iv)>.<b64url(tag)>.<b64url(ciphertext)>`.
+ * `enc:v1:<b64url(iv)>.<b64url(tag)>.<b64url(ciphertext)>`. Async, on Web
+ * Crypto; `hanzio/crypto/node` has a synchronous twin with the same envelope.
  */
 export function createSealer(options: SealerOptions): Sealer {
-	const { secret, salt = '', info = DEFAULT_INFO } = options
-	const secretBytes = toBytes(secret)
-	if (secretBytes.length === 0) {
-		throw new TypeError('Sealer secret must not be empty')
-	}
-
-	let keyPromise: Promise<CryptoKey> | undefined
-	const getKey = () => {
-		if (!keyPromise) {
-			keyPromise = deriveKey(secretBytes, salt, info)
-			keyPromise.catch(() => {
-				keyPromise = undefined
+	const { secret, contexts } = sealerKeyInputs(options)
+
+	const keys: (Promise<CryptoKey> | undefined)[] = []
+	const getKey = (index: number) => {
+		let key = keys[index]
+		if (!key) {
+			const context = contexts[index] as (typeof contexts)[number]
+			key = deriveKey(secret, context.salt, context.info)
+			keys[index] = key
+			key.catch(() => {
+				keys[index] = undefined
 			})
 		}
-		return keyPromise
+		return key
 	}
 
 	const seal = async (plaintext: string): Promise<string> => {
@@ -77,69 +154,50 @@ export function createSealer(options: SealerOptions): Sealer {
 		const encrypted = new Uint8Array(
 			await getSubtleCrypto().encrypt(
 				{ name: 'AES-GCM', iv },
-				await getKey(),
+				await getKey(0),
 				utf8Encode(plaintext)
 			)
 		)
 		const tagStart = encrypted.length - TAG_BYTES
-		return `${PREFIX}${encodeBase64Url(iv)}.${encodeBase64Url(encrypted.subarray(tagStart))}.${encodeBase64Url(encrypted.subarray(0, tagStart))}`
+		return formatEnvelope(
+			iv,
+			encrypted.subarray(tagStart),
+			encrypted.subarray(0, tagStart)
+		)
 	}
 
-	const open = async (sealed: string): Promise<string> => {
-		if (typeof sealed !== 'string' || !sealed.startsWith(PREFIX)) {
-			const isOtherVersion =
-				typeof sealed === 'string' && /^enc:v\d+:/.test(sealed)
-			throw new SealerError(
-				isOtherVersion ? 'unsupported_version' : 'malformed'
-			)
-		}
-
-		const parts = sealed.slice(PREFIX.length).split('.')
-		let iv: Uint8Array<ArrayBuffer>
-		let tag: Uint8Array
-		let ciphertext: Uint8Array
-		try {
-			if (parts.length !== 3) throw new Error()
-			iv = decodeBase64Url(parts[0] as string)
-			tag = decodeBase64Url(parts[1] as string)
-			ciphertext = decodeBase64Url(parts[2] as string)
-		} catch (_error) {
-			throw new SealerError('malformed')
-		}
-		if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) {
-			throw new SealerError('malformed')
-		}
-
+	const openEnvelope = async ({ iv, tag, ciphertext }: Envelope) => {
 		const encrypted = new Uint8Array(ciphertext.length + TAG_BYTES)
 		encrypted.set(ciphertext)
 		encrypted.set(tag, ciphertext.length)
 
-		const key = await getKey()
-		let plaintext: ArrayBuffer
-		try {
-			plaintext = await getSubtleCrypto().decrypt(
-				{ name: 'AES-GCM', iv },
-				key,
-				encrypted
-			)
-		} catch (_error) {
-			throw new SealerError('decrypt_failed')
+		for (let index = 0; index < contexts.length; index++) {
+			const key = await getKey(index)
+			try {
+				return utf8Decode(
+					await getSubtleCrypto().decrypt(
+						{ name: 'AES-GCM', iv },
+						key,
+						encrypted
+					)
+				)
+			} catch (_error) {}
 		}
-		return utf8Decode(plaintext)
+		throw new SealerError('decrypt_failed')
+	}
+
+	const open = async (sealed: string): Promise<string> => {
+		const envelope = parseEnvelope(sealed, options.passthroughUnsealed)
+		return envelope ? openEnvelope(envelope) : sealed
 	}
 
 	return {
 		seal,
 		open,
-		async sealJson(value) {
-			const json = JSON.stringify(value)
-			if (json === undefined) {
-				throw new TypeError('sealJson value is not JSON-serializable')
-			}
-			return seal(json)
-		},
-		async openJson<T = unknown>(sealed: string) {
-			return JSON.parse(await open(sealed)) as T
+		sealJson: async (value) => seal(jsonToSeal(value)),
+		async openJson<T = unknown>(sealed: unknown) {
+			const envelope = parseEnvelope(sealed, options.passthroughUnsealed)
+			return (envelope ? JSON.parse(await openEnvelope(envelope)) : sealed) as T
 		}
 	}
 }

package/src/format/README.md

@@ -87,6 +87,13 @@ formatDateTime(date, 'en-GB') // '5 Mar 2026, 07:04' (newer ICU: '5 Mar 2026 at
 Presets: `'DD/MM/YYYY'`, `'DD/MM/YYYY HH:mm'`, `'HH:mm'`, `'ddd'`, `'D MMM'`,
 `'D MMM YYYY'`, `'dddd, MMMM D'`, `'MMMM YYYY'`.
 
+For any other layout, pass `Intl.DateTimeFormat` options instead of a preset:
+
+```ts
+formatDate(date, { weekday: 'long', day: 'numeric', month: 'long' }, 'en-GB') // 'Thursday 5 March'
+formatDate(date, { dateStyle: 'short', timeZone: 'Europe/Copenhagen' }, 'da-DK') // '05.03.2026'
+```
+
 `formatCompactTime(date, locale, { now? })` is an activity timestamp for list
 rows: the time today, "yesterday", else the date (with the year when it is not
 this year). `formatDayDivider(date, locale, { now? })` labels a chat timeline:

package/src/format/index.ts

@@ -401,13 +401,17 @@ const DATE_PRESETS = {
  */
 export type DatePreset = keyof typeof DATE_PRESETS
 
-/** A date in one of the `DatePreset` layouts, in local time. */
+/**
+ * A date in one of the `DatePreset` layouts, or with any
+ * `Intl.DateTimeFormat` options, in local time unless they set `timeZone`.
+ */
 export function formatDate(
 	date: DateInput,
-	preset: DatePreset,
+	format: DatePreset | Intl.DateTimeFormatOptions,
 	locale: string
 ): string {
-	return getDateTimeFormat(locale, DATE_PRESETS[preset]).format(toTime(date))
+	const options = typeof format === 'string' ? DATE_PRESETS[format] : format
+	return getDateTimeFormat(locale, options).format(toTime(date))
 }
 
 /** Medium date and short time: "5 Mar 2026, 14:30" (en-GB). */
@@ -519,8 +523,10 @@ export function pluralize(
  */
 export function withLocale(getLocale: () => string) {
 	return {
-		formatDate: (date: DateInput, preset: DatePreset) =>
-			formatDate(date, preset, getLocale()),
+		formatDate: (
+			date: DateInput,
+			format: DatePreset | Intl.DateTimeFormatOptions
+		) => formatDate(date, format, getLocale()),
 		formatDateTime: (date: DateInput) => formatDateTime(date, getLocale()),
 		formatCompactTime: (date: DateInput) =>
 			formatCompactTime(date, getLocale()),

package/src/i18n/README.md

@@ -203,7 +203,9 @@ Both read `i18n.config.ts` (or `.mts`, `.js`, `.mjs`, or `--config <file>`)
 from the current directory; paths in it are relative to the config file.
 `defineI18nConfig` rejects a `baseLocale`, `disjointNamespaces` catalog or
 `identical.allowKeys` locale the config does not declare. A
-`.ts` config needs Bun, or a Node version that strips types. The bin is built
+`.ts` config needs Bun or Node 22.18+. Its relative imports may leave out the
+extension or `/index`, as TypeScript's bundler resolution allows, so
+`npx hanzio-i18n check` works without `bun --bun`. The bin is built
 on [`hanzio/cli`](../cli/README.md), so it needs `zod` installed; `--help`
 lists its options and it exits 1 on catalog problems, 2 on bad arguments.
 

package/src/i18n/cli.ts

@@ -5,6 +5,7 @@
 // a Node version that strips types.
 
 import { existsSync } from 'node:fs'
+import * as nodeModule from 'node:module'
 import { dirname, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { z } from 'zod'
@@ -25,6 +26,44 @@ const CONFIG_NAMES = [
 
 type Loaded = { config: I18nConfig; root: string }
 
+// Node resolves a config's imports like a browser: `./src/locales` fails
+// because it names neither a file nor an extension. Bun resolves it like a
+// bundler. These are the suffixes TypeScript's bundler resolution tries.
+const BUNDLER_SUFFIXES = [
+	'.ts',
+	'.mts',
+	'.js',
+	'.mjs',
+	'/index.ts',
+	'/index.mts',
+	'/index.js',
+	'/index.mjs'
+]
+
+function resolveLikeBundlers() {
+	// Missing under Bun, which needs no help, and under Node before 22.15.
+	nodeModule.registerHooks?.({
+		resolve(specifier, context, nextResolve) {
+			try {
+				return nextResolve(specifier, context)
+			} catch (error) {
+				const code = (error as { code?: string }).code
+				const retry =
+					specifier.startsWith('.') &&
+					(code === 'ERR_MODULE_NOT_FOUND' ||
+						code === 'ERR_UNSUPPORTED_DIR_IMPORT')
+				if (!retry) throw error
+				for (const suffix of BUNDLER_SUFFIXES) {
+					try {
+						return nextResolve(specifier + suffix, context)
+					} catch {}
+				}
+				throw error
+			}
+		}
+	})
+}
+
 async function loadConfig(file: string | undefined): Promise<Loaded> {
 	const path = file
 		? resolve(file)
@@ -33,6 +72,7 @@ async function loadConfig(file: string | undefined): Promise<Loaded> {
 		throw new CliError(
 			`No i18n config found: pass --config or add ${CONFIG_NAMES[0]}.`
 		)
+	resolveLikeBundlers()
 	const loaded = (await import(pathToFileURL(path).href)) as {
 		default?: I18nConfig
 	}

package/src/redis/README.md

@@ -89,17 +89,19 @@ Metrics and logs are hooks:
 ```ts
 const withLimit = createRedisConcurrencyLimit({
 	...options,
-	logger, // throttled warnings; defaults to console
-	onWait: (stage) => {
-		const timer = waitHistogram.startTimer({ pool: 'openai', stage })
+	logger, // logger.warn(message, { key, error }), throttled; defaults to console
+	metricLabel: 'openai', // defaults to key
+	onWait: (stage, label) => {
+		const timer = waitHistogram.startTimer({ pool: label, stage })
 		return () => timer.stop()
-	}
+	},
+	onQueueDepth: (queueDepth, label) => queueDepthGauge.register(label, queueDepth)
 })
-queueDepthGauge.observe(() => withLimit.queueDepth())
 ```
 
-A limiter created per tenant or per host should report under a shared pool
-label, not its key, and must be `dispose()`d when discarded.
+A limiter created per tenant or per host should share one `metricLabel`, not
+default to its key, and must be `dispose()`d when discarded. `dispose()` runs
+the function `onQueueDepth` returned, so the gauge stops reading the limiter.
 
 ## Lua scripts
 

package/src/redis/concurrency-limit.ts

@@ -176,10 +176,23 @@ export type RedisConcurrencyLimitOptions = {
 	maxStartsPerSecond?: number
 	failOpenAfterMs?: number
 	commandTimeoutMs?: number
-	/** Receives throttled warnings. Defaults to `console`. */
-	logger?: Pick<Console, 'warn'>
+	/** Receives throttled warnings with `{ key, error }`. Defaults to `console`. */
+	logger?: { warn(message: string, attributes: Record<string, unknown>): void }
+	/** The label `onWait` and `onQueueDepth` report under. Default: `key`. */
+	metricLabel?: string
 	/** Called when a caller starts queueing; the returned function runs once it stops. */
-	onWait?: (stage: ConcurrencyLimitStage) => (() => void) | void
+	onWait?: (
+		stage: ConcurrencyLimitStage,
+		metricLabel: string
+	) => (() => void) | void
+	/**
+	 * Called once with `queueDepth`, to register a gauge; the returned function
+	 * runs on `dispose()`.
+	 */
+	onQueueDepth?: (
+		queueDepth: () => number,
+		metricLabel: string
+	) => (() => void) | void
 }
 
 export type RedisConcurrencyLimit = {
@@ -216,10 +229,11 @@ export type RedisConcurrencyLimit = {
  * That verdict is shared per limiter: once tripped, later calls degrade
  * immediately while a background probe watches for Redis to come back.
  *
- * `onWait` and `queueDepth` feed metrics. A limiter minted per tenant or per
- * customer host should report under a shared pool label rather than its key,
- * or every key ever touched leaves a permanent series. Call `dispose()` when
- * such a limiter is discarded, and unregister any gauge reading `queueDepth`.
+ * `onWait` and `onQueueDepth` feed metrics under `metricLabel`. A limiter
+ * minted per tenant or per customer host should share one pool label rather
+ * than default to its key, or every key ever touched leaves a permanent
+ * series. Call `dispose()` when such a limiter is discarded; it also runs the
+ * unregister function `onQueueDepth` returned.
  *
  * @example
  * const withLimit = createRedisConcurrencyLimit({
@@ -236,6 +250,7 @@ export function createRedisConcurrencyLimit(
 	if (!Number.isInteger(input.max) || input.max < 1)
 		throw new Error(`max must be a positive integer, got ${input.max}`)
 	const logger = input.logger ?? console
+	const metricLabel = input.metricLabel ?? input.key
 	const commandTimeoutMs = input.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS
 	const send = withCommandTimeout(input.send, commandTimeoutMs)
 	const ttlMs = String(input.slotTtlMs)
@@ -399,7 +414,7 @@ export function createRedisConcurrencyLimit(
 			depth: () => queue.length,
 			/** Resolves true once the token holds a slot, false when failing open. */
 			acquire(token: string) {
-				const stopWait = input.onWait?.(stage)
+				const stopWait = input.onWait?.(stage, metricLabel)
 				const granted = new Promise<boolean>((resolve) => {
 					queue.push({ token, settle: resolve })
 				})
@@ -437,6 +452,7 @@ export function createRedisConcurrencyLimit(
 				)
 
 	const queueDepth = () => slotPump.depth() + (startPump?.depth() ?? 0)
+	let unregisterQueueDepth = input.onQueueDepth?.(queueDepth, metricLabel)
 
 	// -------------------------------------------------------------- heartbeat
 
@@ -573,6 +589,8 @@ export function createRedisConcurrencyLimit(
 	 * before it resolves - so there is nothing left to heartbeat.
 	 */
 	function dispose() {
+		unregisterQueueDepth?.()
+		unregisterQueueDepth = undefined
 		if (probeTimer) {
 			clearTimeout(probeTimer)
 			probeTimer = null

package/src/string/index.ts

@@ -8,7 +8,7 @@ export type JsonValue =
 	| JsonObject
 	| JsonArray
 export type JsonObject = { [key: string]: JsonValue | undefined }
-export type JsonArray = Array<JsonValue | undefined>
+export type JsonArray = JsonValue[]
 
 /**
  * Parses the first number-like token in a string. Only a `-` directly before

package/src/testing/README.md

@@ -33,9 +33,18 @@ await moduleMocker.mock(path.resolve(import.meta.dir, '../lib/posthog.ts'), () =
 afterAll(() => moduleMocker.clear())
 ```
 
-Bun resolves a relative specifier from the file that registers the mock, which
-would be hanzio's. Pass absolute paths or package names, or give the
-constructor a resolver for your own shorthand:
+Bun resolves a specifier from the file that registers the mock, which would be
+hanzio's: a relative path points into hanzio, and under isolated installs a
+package name can find another copy or none. Pass your source root, and the
+mocker resolves package names from there and other paths relative to it:
+
+```ts
+const moduleMocker = new ModuleMocker(path.resolve(import.meta.dir, '..'))
+await moduleMocker.mock('lib/posthog.ts', () => ({ captureException: mock() }))
+await moduleMocker.mock('ai', () => ({ generateText: mock() }))
+```
+
+Or give the constructor a resolver for your own shorthand:
 
 ```ts
 const moduleMocker = new ModuleMocker((specifier) =>

package/src/testing/module-mocker.ts

@@ -1,5 +1,27 @@
+import { isAbsolute } from 'node:path'
+
 type ModuleExports = Record<string, unknown>
 
+/**
+ * Package names resolve from `baseDir`, so a mock targets the copy your code
+ * imports even under isolated installs; anything else is a path relative to it.
+ */
+function resolveFrom(baseDir: string) {
+	return (specifier: string) => {
+		if (isAbsolute(specifier)) return specifier
+		if (specifier.startsWith('.')) return Bun.resolveSync(specifier, baseDir)
+		try {
+			return Bun.resolveSync(specifier, baseDir)
+		} catch (error) {
+			try {
+				return Bun.resolveSync(`./${specifier}`, baseDir)
+			} catch {
+				throw error
+			}
+		}
+	}
+}
+
 /**
  * `mock.module` that can be undone. Bun replaces a mocked module for the whole
  * process and `mock.restore()` does not bring it back
@@ -10,24 +32,31 @@ type ModuleExports = Record<string, unknown>
  * keep working, and `clear()` re-registers the originals. Call it in
  * `afterEach` or `afterAll`.
  *
- * Bun resolves specifiers relative to the file that registers the mock, so
- * pass absolute paths or package names. A `resolve` function maps your own
- * shorthand (an `@/` alias, a source-root-relative path) to absolute paths.
+ * Without an argument, pass absolute paths. Pass your source root to resolve
+ * against it: package names from there (so mocks hit the same copy your code
+ * imports), and `./lib/x` or `lib/x` relative to it. A function maps your own
+ * shorthand, such as an `@/` alias, to absolute paths instead.
  *
  * @example
- * const moduleMocker = new ModuleMocker((specifier) =>
- *   specifier.startsWith('@/') ? path.resolve(srcDir, specifier.slice(2)) : specifier
- * )
- * await moduleMocker.mock('@/lib/posthog', () => ({ captureException: mock() }))
+ * const moduleMocker = new ModuleMocker(srcDir)
+ * await moduleMocker.mock('lib/posthog.ts', () => ({ captureException: mock() }))
+ * await moduleMocker.mock('ai', () => ({ generateText: mock() }))
  * afterAll(() => moduleMocker.clear())
  */
 export class ModuleMocker {
 	private restorers: (() => void)[] = []
 
+	private readonly resolve: (specifier: string) => string
+
 	constructor(
-		private readonly resolve: (specifier: string) => string = (specifier) =>
+		baseDirOrResolve: string | ((specifier: string) => string) = (specifier) =>
 			specifier
-	) {}
+	) {
+		this.resolve =
+			typeof baseDirOrResolve === 'string'
+				? resolveFrom(baseDirOrResolve)
+				: baseDirOrResolve
+	}
 
 	async mock(
 		specifier: string,
@@ -44,7 +73,8 @@ export class ModuleMocker {
 	}
 
 	clear(): void {
-		for (const restore of this.restorers) restore()
+		// Newest first, so a module mocked twice ends on its real exports.
+		for (const restore of this.restorers.toReversed()) restore()
 		this.restorers = []
 	}
 }

package/src/testing/prisma.ts

@@ -1,6 +1,11 @@
 import type { Mock, mock } from 'bun:test'
 
-export type PrismaMethodMock = Mock<(...args: unknown[]) => Promise<unknown>>
+/**
+ * `never[]` parameters let `mockImplementation` take a callback that types its
+ * arguments; the plain call signature keeps the mock callable with any.
+ */
+export type PrismaMethodMock = Mock<(...args: never[]) => Promise<unknown>> &
+	((...args: unknown[]) => Promise<unknown>)
 
 /**
  * A Prisma client where every model delegate and every method is a Bun mock,