@c9up/rune 0.1.7 → 0.1.9

package/src/index.ts

@@ -4,15 +4,42 @@
  * @implements FR38, FR39, FR40, FR41, FR42
  */
 
+export type { DateFormat } from "./date.js";
+/**
+ * Namespace import, mirroring `import { errors } from '@vinejs/vine'` — Adonis
+ * code catches on `errors.E_VALIDATION_ERROR`, so the namespace has to exist at
+ * the root and not only on the subpath.
+ */
+export * as errors from "./errors.js";
 export { RuneError, RuneValidationError } from "./errors.js";
+export type {
+	AlphaOptions,
+	EmailOptions,
+	NormalizeEmailOptions,
+	NormalizeUrlOptions,
+	UrlOptions,
+} 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,
 	CompiledRule,
+	CreateRuleOptions,
+	DatabaseLookup,
+	DatabaseResolver,
+	DatabaseRuleOptions,
 	FieldContext,
 	Infer,
+	RecordKeysCallback,
 	RuleChain,
 	RuleValidator,
+	UnionNoMatchCallback,
 	ValidateOptions,
 	ValidationError,
 	ValidationMessageParams,
@@ -21,9 +48,251 @@ export type {
 	ValidationTranslator,
 } from "./Schema.js";
 export {
+	bindDatabase,
+	bindHostResolver,
+	bindRosetta,
+	compile,
+	create,
+	createAsyncRule,
+	createRule,
+	rules,
+	schema,
+	setConvertEmptyStringsToNull,
+	setDateTransform,
+	setGlobalErrorReporter,
+	setValidationTranslator,
+} from "./Schema.js";
+
+import type { MessagesProviderContract } from "./MessagesProvider.js";
+import type { RuleChain, ValidateOptions } from "./Schema.js";
+import {
+	bindDatabase,
+	bindHostResolver,
 	bindRosetta,
+	compile,
+	create,
+	createAsyncRule,
 	createRule,
+	getConvertEmptyStringsToNull,
+	getGlobalErrorReporter,
+	getGlobalMessagesProvider,
+	group,
+	groupElse,
+	groupIf,
 	rules,
 	schema,
+	setConvertEmptyStringsToNull,
+	setDateTransform,
+	setGlobalErrorReporter,
+	setGlobalMessagesProvider,
 	setValidationTranslator,
 } from "./Schema.js";
+
+/**
+ * A validator whose entry points REQUIRE `{ meta }`.
+ *
+ * VineJS refuses `validate(data)` once `withMetaData<T>()` declared metadata as
+ * required; keeping `meta` optional meant the guard existed at runtime but the
+ * compiler still waved the missing-metadata call through.
+ */
+type WithRequiredMeta<V, M> = {
+	[K in keyof V]: V[K] extends (data: infer D, options?: infer O) => infer R
+		? (data: D, options: Omit<O & object, "meta"> & { meta: M }) => R
+		: V[K];
+};
+
+/**
+ * Default export, mirroring `import vine from '@vinejs/vine'`.
+ *
+ * Named `rune`, not `vine` — the deviation is the package name, nothing else:
+ * the type factories (`rune.string()`, `rune.date()`, …) and the validator
+ * factories (`rune.create`, `rune.compile`) sit on one object exactly like
+ * VineJS, so an Adonis validator transcribes line for line.
+ */
+const rune = {
+	...rules,
+	schema,
+	create,
+	compile,
+	createRule,
+	createAsyncRule,
+	// `group` carries its branch factories, mirroring `vine.group.if/else`.
+	group: Object.assign(group, {
+		if: groupIf,
+		else: groupElse,
+		otherwise: groupElse,
+	}),
+	bindDatabase,
+	bindHostResolver,
+	bindRosetta,
+	setDateTransform,
+	setValidationTranslator,
+	/**
+	 * Convert `""` to `null` before validating (VineJS
+	 * `convertEmptyStringsToNull`). An HTML form posts empty inputs as `""`, and
+	 * an optional field should read that as "absent", not as a present empty
+	 * string that fails `minLength`.
+	 */
+	set convertEmptyStringsToNull(enabled: boolean) {
+		setConvertEmptyStringsToNull(enabled);
+	},
+	get convertEmptyStringsToNull(): boolean {
+		return getConvertEmptyStringsToNull();
+	},
+	/**
+	 * Predicate helpers VineJS exposes as `vine.helpers`, for writing custom
+	 * rules without reimplementing the same three checks each time.
+	 */
+	helpers: {
+		/** `true` for `true`, `1`, `"1"`, `"true"`, `"on"`, `"yes"`. */
+		isTrue: (value: unknown): boolean =>
+			value === true ||
+			value === 1 ||
+			(typeof value === "string" &&
+				["1", "true", "on", "yes"].includes(value.toLowerCase())),
+		/** `true` for `false`, `0`, `"0"`, `"false"`, `"off"`, `"no"`. */
+		isFalse: (value: unknown): boolean =>
+			value === false ||
+			value === 0 ||
+			(typeof value === "string" &&
+				["0", "false", "off", "no"].includes(value.toLowerCase())),
+		/** Neither `undefined` nor `null` (an empty string IS defined). */
+		exists: (value: unknown): boolean => value !== undefined && value !== null,
+		/** `undefined` or `null`. */
+		isMissing: (value: unknown): boolean =>
+			value === undefined || value === null,
+		/** A plain object, not an array and not `null`. */
+		isObject: (value: unknown): value is Record<string, unknown> =>
+			typeof value === "object" && value !== null && !Array.isArray(value),
+		/** An array. */
+		isArray: Array.isArray,
+		/** Every listed key is present on the object (VineJS `helpers.hasKeys`). */
+		hasKeys: (value: unknown, keys: readonly string[]): boolean =>
+			typeof value === "object" &&
+			value !== null &&
+			keys.every((key) => key in value),
+		/**
+		 * No duplicate in the data set, optionally compared on one or more fields
+		 * (VineJS `helpers.isDistinct`). `null` / `undefined` items are ignored,
+		 * and items missing a compared key are SKIPPED, so two absent values are
+		 * not a duplicate of each other.
+		 */
+		isDistinct: (
+			dataSet: readonly unknown[],
+			fields?: string | string[],
+		): boolean => {
+			const list = fields === undefined ? null : [fields].flat();
+			const keys: string[] = [];
+			for (const item of dataSet) {
+				if (item === null || item === undefined) continue;
+				if (list === null) {
+					keys.push(JSON.stringify(item));
+					continue;
+				}
+				if (typeof item !== "object" || item === null) continue;
+				const record: Record<string, unknown> = { ...item };
+				if (list.some((k) => record[k] === undefined || record[k] === null)) {
+					continue;
+				}
+				keys.push(JSON.stringify(list.map((k) => record[k])));
+			}
+			return new Set(keys).size === keys.length;
+		},
+		/** Read a dotted path off the validated data (VineJS `helpers.getNestedValue`). */
+		getNestedValue: (
+			key: string,
+			field: { data: Record<string, unknown> },
+		): unknown => {
+			let cursor: unknown = field.data;
+			for (const segment of key.split(".")) {
+				if (typeof cursor !== "object" || cursor === null) return undefined;
+				cursor = (cursor as Record<string, unknown>)[segment];
+			}
+			return cursor;
+		},
+		/** Make every property of a shape optional (VineJS `helpers.optional`). */
+		optional: (props: Record<string, RuleChain>): Record<string, RuleChain> =>
+			Object.fromEntries(
+				Object.entries(props).map(([key, chain]) => [
+					key,
+					chain.clone().optional(),
+				]),
+			),
+	},
+	/** One-shot validation, VineJS `vine.validate({ schema, data })`. */
+	validate<T extends Record<string, RuleChain>>(
+		options: { schema: T | RuleChain; data: unknown } & ValidateOptions,
+	) {
+		// Spread the whole ValidateOptions rather than re-listing its keys: the
+		// hand-listed version silently dropped `errorReporter` when it was added.
+		const { schema: fields, data, ...validateOptions } = options;
+		return create(fields as T).validate(data, validateOptions);
+	},
+	/** One-shot non-throwing validation, VineJS `vine.tryValidate`. */
+	tryValidate<T extends Record<string, RuleChain>>(
+		options: { schema: T | RuleChain; data: unknown } & ValidateOptions,
+	) {
+		// Spread the whole ValidateOptions rather than re-listing its keys: the
+		// hand-listed version silently dropped `errorReporter` when it was added.
+		const { schema: fields, data, ...validateOptions } = options;
+		return create(fields as T).tryValidate(data, validateOptions);
+	},
+	/**
+	 * Type the `meta` passed to `validate(data, { meta })` (VineJS
+	 * `withMetaData`). Purely a typing seam — rune carries meta on the call.
+	 */
+	withMetaData<M extends Record<string, unknown>>(
+		validateMeta?: (meta: M) => void,
+	): {
+		create<T extends Record<string, RuleChain>>(
+			fields: T,
+		): WithRequiredMeta<ReturnType<typeof create<T>>, M>;
+	} {
+		return {
+			create<T extends Record<string, RuleChain>>(fields: T) {
+				const validator = create(fields);
+				if (!validateMeta) {
+					return validator as WithRequiredMeta<ReturnType<typeof create<T>>, M>;
+				}
+				// The callback runs BEFORE the payload: meta that is wrong makes
+				// every rule reading it meaningless, so failing early is the only
+				// honest outcome.
+				const guard = <A extends unknown[], R>(
+					run: (...args: A) => R,
+				): ((...args: A) => R) => {
+					return (...args: A): R => {
+						const options = args[1] as { meta?: M } | undefined;
+						validateMeta((options?.meta ?? {}) as M);
+						return run(...args);
+					};
+				};
+				return {
+					...validator,
+					validate: guard(validator.validate),
+					validateResult: guard(validator.validateResult),
+					validateResultAsync: guard(validator.validateResultAsync),
+					validateOrThrow: guard(validator.validateOrThrow),
+					validateOrThrowAsync: guard(validator.validateOrThrowAsync),
+					tryValidate: guard(validator.tryValidate),
+					tryValidateSync: guard(validator.tryValidateSync),
+				} as WithRequiredMeta<ReturnType<typeof create<T>>, M>;
+			},
+		};
+	},
+	/** Process-wide error reporter (VineJS `vine.errorReporter`). */
+	set errorReporter(reporter: Parameters<typeof setGlobalErrorReporter>[0],) {
+		setGlobalErrorReporter(reporter);
+	},
+	get errorReporter(): ReturnType<typeof getGlobalErrorReporter> {
+		return getGlobalErrorReporter();
+	},
+	/** Bind the global messages provider (VineJS `vine.messagesProvider`). */
+	set messagesProvider(provider: MessagesProviderContract | null) {
+		setGlobalMessagesProvider(provider);
+	},
+	get messagesProvider(): MessagesProviderContract | null {
+		return getGlobalMessagesProvider();
+	},
+};
+
+export default rune;

package/src/magic.ts

@@ -0,0 +1,181 @@
+/**
+ * Content-based file type detection — magic numbers.
+ *
+ * Adonis rejects a `.exe` renamed to `.jpg` because its bodyparser sniffs the
+ * real bytes. rune validates a structural object, so on its own it can only
+ * trust what the upload DECLARES. This module closes that gap when a byte
+ * source is reachable: no external dependency, just the signature table and
+ * `node:fs` to read the first bytes.
+ *
+ * Signatures are matched at their documented offsets, longest-first, so a
+ * container that shares a prefix with another format is not mistaken for it.
+ */
+
+import { open } from "node:fs/promises";
+
+/** One magic-number signature. */
+interface Signature {
+	/** File extension, lowercase, no dot. */
+	ext: string;
+	/** Canonical MIME type. */
+	mime: string;
+	/** Byte offset the pattern starts at. */
+	offset: number;
+	/** Bytes to match; `null` matches any byte at that position. */
+	bytes: ReadonlyArray<number | null>;
+}
+
+const ascii = (text: string): number[] =>
+	[...text].map((char) => char.charCodeAt(0));
+
+/**
+ * Ordered longest-pattern-first within an offset group. `zip` sits LAST of the
+ * PK family because docx/xlsx/pptx are zip containers: matching `zip` first
+ * would label every Office document a zip.
+ */
+const SIGNATURES: readonly Signature[] = [
+	{
+		ext: "png",
+		mime: "image/png",
+		offset: 0,
+		bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+	},
+	{ ext: "jpg", mime: "image/jpeg", offset: 0, bytes: [0xff, 0xd8, 0xff] },
+	{ ext: "gif", mime: "image/gif", offset: 0, bytes: ascii("GIF8") },
+	{ ext: "bmp", mime: "image/bmp", offset: 0, bytes: ascii("BM") },
+	{ ext: "webp", mime: "image/webp", offset: 8, bytes: ascii("WEBP") },
+	{ ext: "avif", mime: "image/avif", offset: 4, bytes: ascii("ftypavif") },
+	{ ext: "heic", mime: "image/heic", offset: 4, bytes: ascii("ftypheic") },
+	{
+		ext: "tif",
+		mime: "image/tiff",
+		offset: 0,
+		bytes: [0x49, 0x49, 0x2a, 0x00],
+	},
+	{
+		ext: "tif",
+		mime: "image/tiff",
+		offset: 0,
+		bytes: [0x4d, 0x4d, 0x00, 0x2a],
+	},
+	{
+		ext: "ico",
+		mime: "image/x-icon",
+		offset: 0,
+		bytes: [0x00, 0x00, 0x01, 0x00],
+	},
+	{ ext: "pdf", mime: "application/pdf", offset: 0, bytes: ascii("%PDF-") },
+	{ ext: "mp4", mime: "video/mp4", offset: 4, bytes: ascii("ftyp") },
+	{
+		ext: "webm",
+		mime: "video/webm",
+		offset: 0,
+		bytes: [0x1a, 0x45, 0xdf, 0xa3],
+	},
+	{ ext: "ogg", mime: "audio/ogg", offset: 0, bytes: ascii("OggS") },
+	{ ext: "wav", mime: "audio/wav", offset: 8, bytes: ascii("WAVE") },
+	{ ext: "mp3", mime: "audio/mpeg", offset: 0, bytes: ascii("ID3") },
+	{ ext: "mp3", mime: "audio/mpeg", offset: 0, bytes: [0xff, 0xfb] },
+	{ ext: "flac", mime: "audio/flac", offset: 0, bytes: ascii("fLaC") },
+	{ ext: "gz", mime: "application/gzip", offset: 0, bytes: [0x1f, 0x8b] },
+	{ ext: "bz2", mime: "application/x-bzip2", offset: 0, bytes: ascii("BZh") },
+	{
+		ext: "7z",
+		mime: "application/x-7z-compressed",
+		offset: 0,
+		bytes: [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c],
+	},
+	{ ext: "rar", mime: "application/vnd.rar", offset: 0, bytes: ascii("Rar!") },
+	{
+		ext: "zip",
+		mime: "application/zip",
+		offset: 0,
+		bytes: [0x50, 0x4b, 0x03, 0x04],
+	},
+	// Executables — the whole point of sniffing: these must never pass as media.
+	{
+		ext: "exe",
+		mime: "application/vnd.microsoft.portable-executable",
+		offset: 0,
+		bytes: ascii("MZ"),
+	},
+	{
+		ext: "elf",
+		mime: "application/x-elf",
+		offset: 0,
+		bytes: [0x7f, 0x45, 0x4c, 0x46],
+	},
+	{
+		ext: "class",
+		mime: "application/java-vm",
+		offset: 0,
+		bytes: [0xca, 0xfe, 0xba, 0xbe],
+	},
+	{
+		ext: "wasm",
+		mime: "application/wasm",
+		offset: 0,
+		bytes: [0x00, 0x61, 0x73, 0x6d],
+	},
+];
+
+/** How many leading bytes are enough for every signature above. */
+export const MAGIC_HEAD_BYTES = 32;
+
+/** The detected type of a byte head, or `null` when nothing matches. */
+export interface DetectedType {
+	ext: string;
+	mime: string;
+}
+
+/** Does `head` carry `signature` at its documented offset? */
+function matches(head: Uint8Array, signature: Signature): boolean {
+	if (head.length < signature.offset + signature.bytes.length) return false;
+	return signature.bytes.every((byte, index) => {
+		if (byte === null) return true;
+		return head[signature.offset + index] === byte;
+	});
+}
+
+/**
+ * Detect the type of a byte head. Returns `null` when no signature matches —
+ * never a guess: an unrecognised head must be reported as unrecognised, not
+ * silently accepted as whatever was declared.
+ */
+export function detectFileType(head: Uint8Array): DetectedType | null {
+	for (const signature of SIGNATURES) {
+		if (matches(head, signature))
+			return { ext: signature.ext, mime: signature.mime };
+	}
+	return null;
+}
+
+/** Read the leading bytes of a file. */
+export async function readHead(
+	path: string,
+	length = MAGIC_HEAD_BYTES,
+): Promise<Uint8Array> {
+	const handle = await open(path, "r");
+	try {
+		const buffer = new Uint8Array(length);
+		const { bytesRead } = await handle.read(buffer, 0, length, 0);
+		return buffer.subarray(0, bytesRead);
+	} finally {
+		await handle.close();
+	}
+}
+
+/** Extensions that a given detected type legitimately covers. */
+const ALIASES: Record<string, readonly string[]> = {
+	jpg: ["jpg", "jpeg"],
+	tif: ["tif", "tiff"],
+	// A zip container is what an Office document actually is on the wire.
+	zip: ["zip", "docx", "xlsx", "pptx", "odt", "ods", "odp", "epub", "jar"],
+	mp4: ["mp4", "m4v", "m4a", "mov"],
+};
+
+/** Is `declared` an acceptable spelling of `detected`? */
+export function extensionMatches(detected: string, declared: string): boolean {
+	const normalized = declared.replace(/^\./, "").toLowerCase();
+	return (ALIASES[detected] ?? [detected]).includes(normalized);
+}

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();
 }

package/src/types.ts

@@ -0,0 +1,55 @@
+/**
+ * @module @c9up/rune/types
+ * @description
+ * Type-only surface, mirroring `@vinejs/vine/types`.
+ *
+ * A separate subpath so a consumer can `import type { FieldContext } from
+ * "@c9up/rune/types"` exactly as it would from Vine — importing types through
+ * the value entrypoint pulls the whole module graph into a file that only
+ * needed a signature.
+ */
+
+export type { DateFormat } from "./date.js";
+export type {
+	AlphaOptions,
+	EmailOptions,
+	NormalizeEmailOptions,
+	NormalizeUrlOptions,
+	UrlOptions,
+} from "./formats.js";
+export type {
+	MessageArgs,
+	MessagesProviderContract,
+	ValidationFields,
+	ValidationMessages,
+} from "./MessagesProvider.js";
+export type {
+	AsyncCompiledRule,
+	AsyncRuleValidator,
+	CompiledRule,
+	ConditionalBranch,
+	ConditionalGroup,
+	CreateRuleOptions,
+	DatabaseLookup,
+	DatabaseResolver,
+	DatabaseRuleOptions,
+	ErrorReporterContract,
+	ErrorReporterFactory,
+	FieldContext,
+	FileLike,
+	HostResolver,
+	Infer,
+	JsonSchemaModifier,
+	ParseContext,
+	RuleChain,
+	RuleDef,
+	RuleValidator,
+	SchemaIntrospection,
+	UnionBranch,
+	ValidateOptions,
+	ValidationError,
+	ValidationMessageParams,
+	ValidationResult,
+	ValidationSchema,
+	ValidationTranslator,
+} from "./Schema.js";