@c9up/rune 0.1.8 → 0.1.10

package/src/Schema.ts

@@ -54,9 +54,9 @@ import {
 	readHead,
 } from "./magic.js";
 import {
+	assertNativeAvailable,
 	isNativeAvailable,
 	validateNative,
-	warnNativeUnavailableOnce,
 } from "./native.js";
 
 export type ValidationMessageParams = Record<string, string | number | boolean>;
@@ -188,6 +188,18 @@ export interface CreateRuleOptions {
 	isAsync?: boolean;
 }
 
+// `isAsync: true` genuinely produces an AsyncCompiledRule — a different
+// discriminant (`__rune: "asyncRule"`) that `.use()` routes to the awaited
+// register. Saying otherwise, as a cast did, told the compiler the opposite of
+// what runs.
+export function createRule(
+	validator: AsyncRuleValidator<undefined>,
+	options: CreateRuleOptions & { isAsync: true },
+): () => AsyncCompiledRule;
+export function createRule<Options>(
+	validator: AsyncRuleValidator<Options>,
+	options: CreateRuleOptions & { isAsync: true },
+): (options: Options) => AsyncCompiledRule;
 export function createRule(
 	validator: RuleValidator<undefined>,
 	options?: CreateRuleOptions,
@@ -197,18 +209,18 @@ export function createRule<Options>(
 	options?: CreateRuleOptions,
 ): (options: Options) => CompiledRule;
 export function createRule<Options>(
-	validator: RuleValidator<Options>,
+	validator: RuleValidator<Options> | AsyncRuleValidator<Options>,
 	ruleOptions?: CreateRuleOptions,
-): (options: Options) => CompiledRule {
+): (options: Options) => CompiledRule | AsyncCompiledRule {
 	if (ruleOptions?.isAsync) {
 		// VineJS expresses "async" as an option on createRule, so honour it by
 		// BUILDING the async rule rather than refusing: `.use()` routes an
 		// async-marked rule to the awaited register.
-		const asyncBuilder = createAsyncRule(
-			validator as unknown as AsyncRuleValidator<Options>,
-			{ ...ruleOptions, isAsync: undefined },
-		);
-		return asyncBuilder as unknown as (options: Options) => CompiledRule;
+		const asyncBuilder = createAsyncRule(validator, {
+			...ruleOptions,
+			isAsync: undefined,
+		});
+		return asyncBuilder;
 	}
 	return (options: Options): CompiledRule => ({
 		__rune: "rule",
@@ -816,6 +828,21 @@ export interface ConditionalGroup {
 	}>;
 }
 
+/**
+ * Called when no union branch matched (VineJS `UnionNoMatchCallback`). Report
+ * through the field context; reporting nothing suppresses the generic error.
+ */
+export type UnionNoMatchCallback = (
+	value: unknown,
+	field: FieldContext,
+) => void;
+
+/**
+ * Called with a record's keys (VineJS `RecordKeysCallback`). Report through the
+ * field context; reporting nothing accepts the key set.
+ */
+export type RecordKeysCallback = (keys: string[], field: FieldContext) => void;
+
 /** Per-field introspection returned inside `toJSON().schema`. */
 export type SchemaIntrospection = Record<
 	string,
@@ -1405,10 +1432,10 @@ export function schema(
 				reporterError = nativeReporter?.createError;
 				return native;
 			}
-			// This schema would have used the native engine, but it isn't loaded —
-			// surface the platform-dependent TS fallback once instead of diverging
-			// silently.
-			warnNativeUnavailableOnce();
+			// This schema carries nothing the engine cannot run, so the engine is
+			// what must run it. Falling back to the TypeScript validator here made
+			// the verdict depend on whether a binary loaded.
+			assertNativeAvailable();
 		}
 
 		const errors: ValidationError[] = [];
@@ -1739,7 +1766,12 @@ export interface RuleDef {
 	param?: number;
 	/** Interpolation args exposed to i18n/messages providers (e.g. `{ min: 3 }`). */
 	args?: Record<string, unknown>;
-	validate: (value: unknown) => boolean;
+	/**
+	 * `field` is the context VineJS hands a rule — a callback-valued rule
+	 * (`in`, `notIn`, `enum`) reads `meta`/`parent` off it to compute its list
+	 * per request. Rules that do not need it simply declare one parameter.
+	 */
+	validate: (value: unknown, field: FieldContext) => boolean;
 	message: string;
 	/** Set when `.message()` overrode this rule's default text. */
 	hasCustomMessage?: boolean;
@@ -1776,12 +1808,12 @@ const UUID_RE =
  */
 export type AllowedValues =
 	| ReadonlyArray<string | number | boolean>
-	| (() => ReadonlyArray<string | number | boolean>);
+	| ((field: FieldContext) => ReadonlyArray<string | number | boolean>);
 
 /** Normalise a static list or a callback into a getter. */
 function allowedValuesResolver(
 	values: AllowedValues,
-): () => ReadonlyArray<string | number | boolean> {
+): (field: FieldContext) => ReadonlyArray<string | number | boolean> {
 	if (typeof values === "function") return values;
 	const snapshot = [...values];
 	return () => snapshot;
@@ -1829,8 +1861,14 @@ export class RuleChain<Output = unknown> {
 	#camelCaseKeys = false;
 	#groups: ConditionalGroup[] = [];
 	#recordValueChain: RuleChain | null = null;
+	#enumChoices:
+		| ReadonlyArray<string | number | boolean>
+		| ((field: FieldContext) => ReadonlyArray<string | number | boolean>)
+		| null = null;
+	#recordKeysCheck: RecordKeysCallback | null = null;
 	#tupleChains: RuleChain[] | null = null;
 	#unionChains: ConditionalBranch[] | null = null;
+	#unionNoMatch: UnionNoMatchCallback | null = null;
 	#useRules: CompiledRule[] = [];
 	#asyncRules: AsyncCompiledRule[] = [];
 	/** Last rule added, whichever register it landed in — the `message()` target. */
@@ -1950,8 +1988,11 @@ export class RuleChain<Output = unknown> {
 		next.#camelCaseKeys = this.#camelCaseKeys;
 		next.#groups = [...this.#groups];
 		next.#recordValueChain = this.#recordValueChain;
+		next.#enumChoices = this.#enumChoices;
+		next.#recordKeysCheck = this.#recordKeysCheck;
 		next.#tupleChains = this.#tupleChains;
 		next.#unionChains = this.#unionChains;
+		next.#unionNoMatch = this.#unionNoMatch;
 		next.#ruleMessages = new Map(this.#ruleMessages);
 		next.#lastRule = this.#lastRule;
 		next.#preTransforms = [...this.#preTransforms];
@@ -2406,6 +2447,18 @@ export class RuleChain<Output = unknown> {
 		return this.#retype<Record<string, OutputOf<Item>>>();
 	}
 
+	/**
+	 * Check the record's KEYS, not its values (VineJS `record().validateKeys()`).
+	 *
+	 * The callback receives every key at once and reports through the field
+	 * context — the set is what matters when keys must be exclusive, exhaustive,
+	 * or drawn from a list only known at runtime.
+	 */
+	validateKeys(callback: RecordKeysCallback): this {
+		this.#recordKeysCheck = callback;
+		return this;
+	}
+
 	/**
 	 * Fixed-length array with a schema per position (VineJS `tuple`). Extra
 	 * items are rejected — a tuple that silently ignores a trailing element is
@@ -2436,6 +2489,20 @@ export class RuleChain<Output = unknown> {
 	 * - bare chains: tried in order, first match wins, and a total miss reports a
 	 *   single `union` error rather than every losing branch's noise.
 	 */
+	/**
+	 * What to do when NO union branch matched (VineJS `union().otherwise()`).
+	 *
+	 * The callback receives the value and the field, and reports the error it
+	 * wants — the point being that "matches nothing" is a useless message when
+	 * the caller knows which shapes were on offer. Reporting nothing from the
+	 * callback suppresses the generic error entirely, which is how a union
+	 * folded into a larger check stays quiet.
+	 */
+	otherwise(callback: UnionNoMatchCallback): this {
+		this.#unionNoMatch = callback;
+		return this;
+	}
+
 	union(chains: readonly UnionBranch[]): this {
 		this.#unionChains = chains.map(toUnionBranch);
 		// Marker rule: its name is not in NATIVE_RULES, which is what keeps a
@@ -2669,20 +2736,45 @@ export class RuleChain<Output = unknown> {
 		return this;
 	}
 
-	/** Must equal one of `values` (enum). Narrows the output to the union. */
+	/**
+	 * Must equal one of `values` (enum). Narrows the output to the union.
+	 *
+	 * `values` may be a callback receiving the field, which is how a list that
+	 * depends on the request — the roles this tenant allows, the statuses this
+	 * user may set — is computed per validation instead of frozen at import.
+	 */
 	enum<const V extends readonly (string | number | boolean)[]>(
-		values: V,
+		values: V | ((field: FieldContext) => V),
 	): RuleChain<V[number]> {
-		const allowed = [...values];
+		const lazy = typeof values === "function";
+		const resolve = allowedValuesResolver(values);
+		this.#enumChoices = lazy ? values : [...values];
 		this.#pushRule({
 			name: "enum",
-			args: { values: allowed },
-			validate: (v) => allowed.includes(asPrimitive(v)),
+			args: lazy ? {} : { values: [...values] },
+			// A computed list is per-call; the native engine only ever sees a
+			// static array, so it must not run this rule.
+			tsOnly: lazy,
+			validate: (v, field) => resolve(field).includes(asPrimitive(v)),
 			message: "Invalid value",
 		});
 		return this.#retype<V[number]>();
 	}
 
+	/**
+	 * The choices this enum was declared with (VineJS `getChoices()`) — the list
+	 * itself, or the callback when it is computed per request.
+	 *
+	 * Reading them back is what lets a form render the same options the
+	 * validator will accept, from one declaration instead of two.
+	 */
+	getChoices():
+		| ReadonlyArray<string | number | boolean>
+		| ((field: FieldContext) => ReadonlyArray<string | number | boolean>)
+		| undefined {
+		return this.#enumChoices ?? undefined;
+	}
+
 	/** Must equal a literal value. */
 	literal<V extends string | number | boolean>(value: V): RuleChain<V> {
 		this.#pushRule({
@@ -2922,8 +3014,13 @@ export class RuleChain<Output = unknown> {
 	}
 
 	/**
-	 * Must be a mobile number in E.164 form. Named deviation from VineJS: rune
-	 * carries no per-locale numbering plans, so there is no `locale` option.
+	 * Must be a mobile number (VineJS/Adonis `mobile()`).
+	 *
+	 * With no `locale`, the number must be in E.164 form. With one or more,
+	 * it must match one of their numbering plans, as in VineJS. rune carries
+	 * its own plans rather than validator.js', so it knows fewer locales — an
+	 * unknown one raises `UNSUPPORTED_LOCALE` at schema build, naming the ones
+	 * it does know, rather than silently accepting anything at request time.
 	 */
 	mobile(options?: { locale?: string | string[]; strictMode?: boolean }): this {
 		const locales = options?.locale ? [options.locale].flat() : null;
@@ -3308,7 +3405,7 @@ export class RuleChain<Output = unknown> {
 			// A callback list is computed per call — the native engine only ever
 			// sees a static array, so it must not run this rule.
 			tsOnly: typeof values === "function",
-			validate: (v) => resolve().includes(asPrimitive(v)),
+			validate: (v, field) => resolve(field).includes(asPrimitive(v)),
 			message: "Invalid value",
 		});
 		return this;
@@ -3321,7 +3418,7 @@ export class RuleChain<Output = unknown> {
 			name: "notIn",
 			args: typeof values === "function" ? {} : { values: [...values] },
 			tsOnly: typeof values === "function",
-			validate: (v) => !resolve().includes(asPrimitive(v)),
+			validate: (v, field) => !resolve(field).includes(asPrimitive(v)),
 			message: "Invalid value",
 		});
 		return this;
@@ -3904,6 +4001,14 @@ export class RuleChain<Output = unknown> {
 		}
 
 		// 4b. Record values — same shape as the nested-object walk, arbitrary keys.
+		if (this.#recordKeysCheck && isPlainObject(transformed)) {
+			// Keys first: a key-level rule that rejects the shape makes the
+			// per-value errors that would follow noise.
+			this.#recordKeysCheck(
+				Object.keys(transformed),
+				this.#makeFieldContext(field, transformed, ctx, errors, () => {}),
+			);
+		}
 		if (this.#recordValueChain && isPlainObject(transformed)) {
 			const obj: Record<string, unknown> = { ...transformed };
 			transformed = obj;
@@ -3985,19 +4090,30 @@ export class RuleChain<Output = unknown> {
 				}
 			}
 			if (!matched) {
-				errors.push({
-					field,
-					rule: "union",
-					message: resolveRuleMessage(
+				if (this.#unionNoMatch) {
+					// The callback owns the reporting: whatever it pushes is the
+					// error, and pushing nothing means it handled the case itself.
+					const reported: ValidationError[] = [];
+					this.#unionNoMatch(
+						transformed,
+						this.#makeFieldContext(field, transformed, ctx, reported, () => {}),
+					);
+					errors.push(...reported);
+				} else {
+					errors.push({
 						field,
-						{
-							name: "union",
-							validate: () => false,
-							message: "Does not match any allowed shape",
-						},
-						ctx,
-					),
-				});
+						rule: "union",
+						message: resolveRuleMessage(
+							field,
+							{
+								name: "union",
+								validate: () => false,
+								message: "Does not match any allowed shape",
+							},
+							ctx,
+						),
+					});
+				}
 			}
 		}
 
@@ -4126,8 +4242,14 @@ export class RuleChain<Output = unknown> {
 		value: unknown,
 		ctx: RunContext,
 	): ValidationError | null {
+		let context: FieldContext | undefined;
+		const fieldContext = (): FieldContext =>
+			(context ??= this.#makeFieldContext(field, value, ctx, [], () => {}));
 		for (const rule of this.#rules) {
-			if (TYPE_RULE_NAMES.has(rule.name) && !rule.validate(value)) {
+			if (
+				TYPE_RULE_NAMES.has(rule.name) &&
+				!rule.validate(value, fieldContext())
+			) {
 				return {
 					field,
 					rule: rule.name,
@@ -4146,10 +4268,21 @@ export class RuleChain<Output = unknown> {
 		ctx: RunContext,
 	): ValidationError[] {
 		const errors: ValidationError[] = [];
+		// Built once and only if a rule actually reads it: most rules take the
+		// value alone, and a context per rule per field is pure waste.
+		let context: FieldContext | undefined;
+		const fieldContext = (): FieldContext =>
+			(context ??= this.#makeFieldContext(
+				field,
+				transformed,
+				ctx,
+				[],
+				() => {},
+			));
 		for (const rule of this.#rules) {
 			if (TYPE_RULE_NAMES.has(rule.name)) continue;
 			if (this.#bail && errors.length > 0) break;
-			if (!rule.validate(transformed)) {
+			if (!rule.validate(transformed, fieldContext())) {
 				errors.push({
 					field,
 					rule: rule.name,
@@ -4400,7 +4533,10 @@ export const rules = {
 				const typeRule = chain.rules.find((rule) =>
 					TYPE_RULE_NAMES.has(rule.name),
 				);
-				return unionIf((value) => typeRule?.validate(value) === true, chain);
+				return unionIf(
+					(value, field) => typeRule?.validate(value, field) === true,
+					chain,
+				);
 			}),
 		);
 	},
@@ -4410,7 +4546,7 @@ export const rules = {
 	array: <Item extends RuleChain>(item?: Item): RuleChain<OutputOf<Item>[]> =>
 		new RuleChain().array(item),
 	enum: <const V extends readonly (string | number | boolean)[]>(
-		values: V,
+		values: V | ((field: FieldContext) => V),
 	): RuleChain<V[number]> => new RuleChain().enum(values),
 	literal: <V extends string | number | boolean>(value: V): RuleChain<V> =>
 		new RuleChain().literal(value),

package/src/formats.ts

@@ -157,9 +157,8 @@ export function isPostalCode(v: string, countryCode: string): boolean | null {
 }
 
 /**
- * Mobile numbers in E.164 form. Named deviation from VineJS: rune does NOT
- * carry per-locale numbering plans, so `locale` is not accepted — a caller that
- * needs one writes a `.regex()` or a custom rule.
+ * Mobile numbers in E.164 form — the locale-less check. Per-locale plans live
+ * in `MOBILE_LOCALES`; see {@link isMobileForLocale}.
  */
 export const isMobile = (v: string): boolean =>
 	E164_RE.test(v.replace(/[ .-]/g, ""));
@@ -490,12 +489,62 @@ export interface EmailOptions {
 	domain_specific_validation?: boolean;
 }
 
+/** Hard bound on anything handed to the email parser (RFC 5322 line limit). */
+const MAX_EMAIL_INPUT = 998;
+
 /** Unquoted local part: dot-separated atoms of RFC 5322 atext. */
 const ATEXT = "[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+";
 const DOT_ATOM_RE = new RegExp(`^${ATEXT}(?:\\.${ATEXT})*$`);
 /** Quoted local part: `"anything but bare quote/backslash, or escaped"`. */
 const QUOTED_LOCAL_RE = /^"(?:[^"\\]|\\.)*"$/;
-const DISPLAY_NAME_RE = /^\s*(?:"(?:[^"\\]|\\.)*"|[^<>@]*?)\s*<(.+)>\s*$/;
+/**
+ * Split `Display Name <address@host>` into its address.
+ *
+ * Parsed rather than matched: the obvious pattern —
+ * `^\s*(?:"..."|[^<>@]*?)\s*<(.+)>\s*$` — lets `\s*` and `[^<>@]*?` both
+ * claim a space, so an input of N spaces has N ways to be split and the engine
+ * tries them all. Measured at O(n³): 8 KB of spaces blocked the event loop for
+ * 67 seconds, which turns any route validating an email into a denial of
+ * service. This walk is linear and answers the same question.
+ *
+ * Returns the address, or null when the input is not in display-name form.
+ */
+function displayNameAddress(input: string): string | null {
+	const trimmed = input.trim();
+	if (!trimmed.endsWith(">")) return null;
+
+	let open: number;
+	if (trimmed.startsWith('"')) {
+		// A quoted display name may contain anything, `<` included, so the
+		// address opens at the first `<` AFTER the closing quote.
+		const closingQuote = closingQuoteIndex(trimmed);
+		if (closingQuote === -1) return null;
+		open = trimmed.indexOf("<", closingQuote + 1);
+		if (open === -1) return null;
+		if (trimmed.slice(closingQuote + 1, open).trim() !== "") return null;
+	} else {
+		open = trimmed.indexOf("<");
+		if (open === -1) return null;
+		// An unquoted display name carries none of `<`, `>` or `@` — the same
+		// restriction the pattern expressed.
+		if (/[<>@]/.test(trimmed.slice(0, open))) return null;
+	}
+
+	const address = trimmed.slice(open + 1, -1);
+	return address.length > 0 ? address : null;
+}
+
+/** Index of the quote closing the one at position 0, or -1. */
+function closingQuoteIndex(input: string): number {
+	for (let i = 1; i < input.length; i++) {
+		if (input[i] === "\\") {
+			i++;
+			continue;
+		}
+		if (input[i] === '"') return i;
+	}
+	return -1;
+}
 
 /** A single DNS label: alphanumerics and inner hyphens, 1..63 chars. */
 function isDnsLabel(label: string): boolean {
@@ -525,9 +574,15 @@ function isIpDomainLiteral(domain: string): boolean {
 export function isEmail(value: string, options: EmailOptions = {}): boolean {
 	let candidate = value;
 
+	// Bound the input BEFORE any parsing. A caller may opt out of the 254-char
+	// address cap, but never out of a bound: an unbounded string reaching the
+	// parser is how a validator becomes an outage. RFC 5322 caps a whole line
+	// at 998 octets, so a display-name form has no business being longer.
+	if (value.length > MAX_EMAIL_INPUT) return false;
+
 	if (options.allow_display_name) {
-		const match = DISPLAY_NAME_RE.exec(candidate);
-		if (match) candidate = match[1];
+		const address = displayNameAddress(candidate);
+		if (address !== null) candidate = address;
 	} else if (/[<>]/.test(candidate)) {
 		return false;
 	}

package/src/index.ts

@@ -21,6 +21,11 @@ export type {
 } from "./formats.js";
 export type { MessagesProviderContract } from "./MessagesProvider.js";
 export { SimpleMessagesProvider } from "./MessagesProvider.js";
+export {
+	assertNativeAvailable,
+	isNativeAvailable,
+	RuneNativeRequiredError,
+} from "./native.js";
 export type {
 	AsyncCompiledRule,
 	AsyncRuleValidator,
@@ -31,8 +36,10 @@ export type {
 	DatabaseRuleOptions,
 	FieldContext,
 	Infer,
+	RecordKeysCallback,
 	RuleChain,
 	RuleValidator,
+	UnionNoMatchCallback,
 	ValidateOptions,
 	ValidationError,
 	ValidationMessageParams,

package/src/native.ts

@@ -58,28 +58,43 @@ export function isNativeAvailable(): boolean {
 	return native !== undefined;
 }
 
-let warnedFallback = false;
+/** Why the engine could not be loaded, phrased for whoever has to fix it. */
+function unavailableReason(): string {
+	const target = `${platform}-${arch}`;
+	if (loadError !== undefined) {
+		return `failed to load (${loadError instanceof Error ? loadError.message : String(loadError)})`;
+	}
+	return platformMap[target] !== undefined
+		? "binary not found"
+		: `no prebuilt binary for ${target}`;
+}
+
+/** Raised when a schema needs the Rust engine and it is not there. */
+export class RuneNativeRequiredError extends Error {
+	readonly code = "RUNE_NAPI_REQUIRED" as const;
+	constructor() {
+		super(
+			`[RUNE_NAPI_REQUIRED] The Rust validation engine is required but not loaded — ${unavailableReason()}.\n` +
+				"Install the prebuilt binary for this platform, or build it with `pnpm build:napi`.",
+		);
+		this.name = "RuneNativeRequiredError";
+	}
+}
 
 /**
- * Surface — exactly once per process — that the native engine is unavailable so
- * the schema is falling back to the TypeScript validator. The two paths can
- * differ subtly, so a silent fallback makes validation results depend on whether
- * the prebuilt binary loaded (platform-dependent). Callers invoke this only when
- * they WOULD have used the native engine (no custom rules / translator).
+ * Refuse to validate without the native engine.
+ *
+ * There is a TypeScript validator, and it used to take over silently with a
+ * one-time warning. That made a schema's verdict depend on whether a prebuilt
+ * binary happened to load: two deployments of the same code could disagree on
+ * whether a payload is valid, and the one that fell back lost the reason to
+ * have Rust at all. A schema the engine can run is now run BY the engine or
+ * not at all.
+ *
+ * The TypeScript path stays for what the engine genuinely cannot do — custom
+ * rules, a translator, a messages provider — where it is the only
+ * implementation, not a second one.
  */
-export function warnNativeUnavailableOnce(): void {
-	if (warnedFallback) return;
-	warnedFallback = true;
-	const target = `${platform}-${arch}`;
-	const reason =
-		loadError !== undefined
-			? `failed to load (${loadError instanceof Error ? loadError.message : String(loadError)})`
-			: platformMap[target] !== undefined
-				? "binary not found"
-				: `no prebuilt binary for ${target}`;
-	console.warn(
-		`[rune] native validation engine unavailable — ${reason}. Falling back to the ` +
-			"TypeScript validator, whose results can differ subtly from the Rust engine — " +
-			"validation is platform-dependent for this process.",
-	);
+export function assertNativeAvailable(): void {
+	if (native === undefined) throw new RuneNativeRequiredError();
 }