@c9up/rune 0.1.6 → 0.1.8

package/src/index.ts

@@ -4,10 +4,33 @@
  * @implements FR38, FR39, FR40, FR41, FR42
  */
 
-export { RuneError } from "./errors.js";
+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 type {
+	AsyncCompiledRule,
+	AsyncRuleValidator,
 	CompiledRule,
+	CreateRuleOptions,
+	DatabaseLookup,
+	DatabaseResolver,
+	DatabaseRuleOptions,
 	FieldContext,
+	Infer,
 	RuleChain,
 	RuleValidator,
 	ValidateOptions,
@@ -18,9 +41,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/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";