@c9up/rune 0.1.5 → 0.1.7

package/dist/Schema.js

@@ -3,13 +3,34 @@
  *
  * @implements FR38, FR39, FR40, FR41
  */
-import { RuneError } from "./errors.js";
+var _a;
+import { RuneError, RuneValidationError } from "./errors.js";
 import { isNativeAvailable, validateNative, warnNativeUnavailableOnce, } from "./native.js";
+export function createRule(validator) {
+    return (options) => ({
+        __rune: "rule",
+        run(value, field) {
+            validator(value, options, field);
+        },
+    });
+}
+/** Default context for internal callers that don't supply one (no root available). */
+const EMPTY_RUN_CONTEXT = { data: {}, parent: {}, meta: {} };
 /** Type guard: narrows `unknown` to a plain object (non-null, non-array, typeof 'object'). */
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** Rules the Rust validation engine can handle natively. */
+/**
+ * Rules the Rust validation engine (`crates/rune-engine/src/engine.rs`)
+ * ACTUALLY implements. A schema built from only these rules can be validated
+ * natively; anything else routes to the TS path (`rule.validate`).
+ *
+ * CRITICAL: a rule name here that the Rust engine does not implement is a
+ * SILENT VALIDATION BYPASS — the engine's `_ => {}` arm skips unknown rules, so
+ * the constraint never runs. Every entry MUST have a matching arm in engine.rs.
+ * The TS chain rules (minLength/uuid/alpha/in/enum/range/…) live only in the TS
+ * validator, so they are deliberately absent here.
+ */
 const STANDARD_RULES = new Set([
     "string",
     "number",
@@ -18,8 +39,22 @@ const STANDARD_RULES = new Set([
     "max",
     "email",
     "positive",
+    "minLength",
+    "maxLength",
+    "fixedLength",
+    "uuid",
+    "alpha",
+    "alphaNumeric",
+    "startsWith",
+    "endsWith",
+    "in",
+    "notIn",
+    "enum",
+    "negative",
+    "nonNegative",
+    "range",
 ]);
-/** Default messages for standard rules — used to detect custom-message overrides. */
+/** Default messages for standard rules — used only for translator-key fallback. */
 const STANDARD_MSGS = {
     string: "Must be a string",
     number: "Must be a number",
@@ -28,6 +63,20 @@ const STANDARD_MSGS = {
     max: "Maximum",
     email: "Must be a valid email",
     positive: "Must be positive",
+    minLength: "Too short",
+    maxLength: "Too long",
+    fixedLength: "Wrong length",
+    alpha: "Must contain only letters",
+    alphaNumeric: "Must contain only letters and numbers",
+    startsWith: "Invalid prefix",
+    endsWith: "Invalid suffix",
+    uuid: "Must be a valid UUID",
+    in: "Invalid value",
+    notIn: "Invalid value",
+    enum: "Invalid value",
+    range: "Out of range",
+    negative: "Must be negative",
+    nonNegative: "Must be positive or zero",
 };
 const TYPE_RULE_NAMES = new Set([
     "string",
@@ -37,15 +86,8 @@ const TYPE_RULE_NAMES = new Set([
     "array",
 ]);
 let validationTranslator;
-function hasDefaultMessage(rule) {
-    if (rule.name === "min" || rule.name === "max") {
-        if (typeof rule.param !== "number")
-            return false;
-        const expected = `${rule.name === "min" ? "Minimum" : "Maximum"} ${rule.param}`;
-        return rule.message === expected;
-    }
-    const defaultMsg = STANDARD_MSGS[rule.name];
-    return defaultMsg !== undefined && rule.message === defaultMsg;
+function hasCustomMessage(rule) {
+    return rule.hasCustomMessage === true;
 }
 function resolveValidationMessage(key, fallback, params) {
     const translated = validationTranslator?.(key, params);
@@ -54,95 +96,133 @@ function resolveValidationMessage(key, fallback, params) {
     }
     return fallback;
 }
-function resolveRuleMessage(field, rule) {
-    const fallback = rule.message;
-    if (!STANDARD_RULES.has(rule.name)) {
-        return fallback;
+/** Args carried on a rule, exposed to i18n/providers via message interpolation. */
+function ruleArgs(rule) {
+    return rule.args;
+}
+/**
+ * Resolve the final message for a failing rule. Precedence:
+ *   1. explicit `.message()` override (always wins),
+ *   2. a per-call {@link MessagesProviderContract} (VineJS parity),
+ *   3. a globally bound translator (rune's rosetta superset),
+ *   4. the rule's raw default message.
+ */
+function resolveRuleMessage(field, rule, ctx) {
+    if (hasCustomMessage(rule)) {
+        return rule.message;
+    }
+    const args = ruleArgs(rule);
+    if (ctx.messagesProvider) {
+        return ctx.messagesProvider.getMessage(rule.message, rule.name, field, args);
     }
-    if (!hasDefaultMessage(rule)) {
-        return fallback;
+    if (!STANDARD_RULES.has(rule.name)) {
+        return rule.message;
     }
     const params = { field };
-    if (rule.name === "min" && typeof rule.param === "number") {
-        params.min = rule.param;
+    if (typeof rule.param === "number") {
+        if (rule.name === "min" || rule.name === "minLength")
+            params.min = rule.param;
+        if (rule.name === "max" || rule.name === "maxLength")
+            params.max = rule.param;
     }
-    if (rule.name === "max" && typeof rule.param === "number") {
-        params.max = rule.param;
+    return resolveValidationMessage(`validation.${rule.name}`, rule.message, params);
+}
+/** Resolve the "required" message through provider → translator → fallback. */
+function resolveRequiredMessage(field, ctx) {
+    if (ctx.messagesProvider) {
+        return ctx.messagesProvider.getMessage(`${field} is required`, "required", field);
     }
-    return resolveValidationMessage(`validation.${rule.name}`, fallback, params);
+    return resolveValidationMessage("validation.required", `${field} is required`, { field });
 }
 /** Compute once: does any field rule prevent dispatching to Rust? */
 function detectHasCustomRules(fields) {
     return Object.values(fields).some((chain) => {
+        if (chain.useRules.length > 0)
+            return true; // .use() rule — TS-only (Rust can't run JS)
+        if (chain.hasConditionalRequired)
+            return true; // requiredWhen — TS-only
+        if (chain.preTransforms.length > 0)
+            return true; // .parse() — TS-only
+        if (chain.transforms.length > 0)
+            return true; // .transform() — Rust gets only the NAME, can't run a JS fn
+        if (chain.isNullable)
+            return true; // .nullable() — the flag is not sent to the Rust engine
         return chain.rules.some((r) => {
             if (!STANDARD_RULES.has(r.name))
                 return true; // custom rule
-            if (!hasDefaultMessage(r))
+            if (hasCustomMessage(r))
                 return true; // custom message
             return false;
         });
     });
 }
-/**
- * Create a validation schema.
- *
- * Pass `T` explicitly when the caller wants `result.data` typed as a concrete
- * shape after `result.valid === true` narrows the union — runtime validation
- * is unchanged, the generic only types the success branch.
- *
- *     const RegisterValidator = schema<{ email: string; password: string }>({
- *       email: rules.string().email(),
- *       password: rules.string().min(8),
- *     });
- *
- * The default `Record<string, unknown>` matches the historical untyped surface
- * so existing call sites that read `result.data` field-by-field with their
- * own narrowing continue to compile.
- */
 export function schema(fields) {
     // Computed once at construction time, not per validate() call.
     const hasCustomRules = detectHasCustomRules(fields);
-    return {
-        fields,
-        validate(data) {
-            if (!isPlainObject(data)) {
-                return {
-                    valid: false,
-                    errors: [
-                        {
-                            field: "_root",
-                            rule: "type",
-                            message: "Input must be an object",
-                        },
-                    ],
-                };
-            }
-            if (!hasCustomRules && !validationTranslator) {
-                if (isNativeAvailable()) {
-                    return validateWithRust(fields, data);
-                }
-                // This schema would have used the native engine, but it isn't
-                // loaded — surface the platform-dependent TS fallback once instead
-                // of diverging silently. (Schemas with custom rules / a translator
-                // always run on TS by design and don't warn.)
-                warnNativeUnavailableOnce();
-            }
-            const errors = [];
-            const validated = {};
-            for (const [field, chain] of Object.entries(fields)) {
-                const value = data[field];
-                const result = chain._validateWithTransform(field, value);
-                errors.push(...result.errors);
-                if (result.errors.length === 0 && value !== undefined) {
-                    validated[field] = result.transformed;
-                }
+    function validate(data, options) {
+        if (!isPlainObject(data)) {
+            return {
+                valid: false,
+                errors: [
+                    { field: "_root", rule: "type", message: "Input must be an object" },
+                ],
+            };
+        }
+        const provider = options?.messagesProvider;
+        if (!hasCustomRules && !validationTranslator && !provider) {
+            if (isNativeAvailable()) {
+                return validateWithRust(fields, data);
             }
-            if (errors.length === 0) {
-                return { valid: true, errors, data: validated };
+            // 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();
+        }
+        const errors = [];
+        const validated = {};
+        const rootCtx = {
+            data,
+            parent: data,
+            meta: options?.meta ?? {},
+            messagesProvider: provider,
+        };
+        for (const [field, chain] of Object.entries(fields)) {
+            const value = data[field];
+            const result = chain._validateWithTransform(field, value, rootCtx);
+            errors.push(...result.errors);
+            // Gate on the TRANSFORMED result, not the raw input: a pre-transform
+            // (`parse(() => 42)`) can produce a value for an absent field, and that
+            // value must land in `data` — testing the raw `value` dropped it.
+            if (result.errors.length === 0 && result.transformed !== undefined) {
+                validated[field] = result.transformed;
             }
-            return { valid: false, errors };
-        },
+        }
+        if (errors.length === 0) {
+            return { valid: true, errors, data: validated };
+        }
+        return { valid: false, errors };
+    }
+    function validateOrThrow(data, options) {
+        const result = validate(data, options);
+        if (result.valid) {
+            return result.data;
+        }
+        throw new RuneValidationError(result.errors.map(toErrorNode));
+    }
+    return { fields, validate, validateOrThrow };
+}
+/** Map an internal {@link ValidationError} to a {@link RuneErrorNode}. */
+function toErrorNode(error) {
+    const node = {
+        message: error.message,
+        rule: error.rule,
+        field: error.field,
     };
+    if (error.index !== undefined)
+        node.index = error.index;
+    if (error.meta !== undefined)
+        node.meta = error.meta;
+    return node;
 }
 export function setValidationTranslator(translator) {
     validationTranslator = translator;
@@ -150,13 +230,20 @@ export function setValidationTranslator(translator) {
 export function bindRosetta(rosetta) {
     setValidationTranslator((key, params) => rosetta.t(key, params));
 }
-/** Rule chain — fluent validation builder. */
+/** UUID (any version/variant) — identical to the Rust engine's pattern. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Rule chain — fluent, phantom-typed validation builder. */
 export class RuleChain {
     #rules = [];
     #isOptional = false;
+    #isNullable = false;
+    #bail = false;
     #transforms = [];
+    #preTransforms = [];
     #nestedSchema = null;
     #arrayItemChain = null;
+    #useRules = [];
+    #requiredConditions = [];
     /** Public read access to rules (for OpenAPI generation, Rust bridge). */
     get rules() {
         return this.#rules;
@@ -164,23 +251,75 @@ export class RuleChain {
     get isOptionalField() {
         return this.#isOptional;
     }
+    /** Public read access to the `.nullable()` flag (keeps such schemas off the native path). */
+    get isNullable() {
+        return this.#isNullable;
+    }
     get transforms() {
         return this.#transforms;
     }
-    /** Mark field as optional. */
+    /** Public read access to `.use()` rules (used to keep such schemas off the native path). */
+    get useRules() {
+        return this.#useRules;
+    }
+    /** Public read access to `.parse()` pre-transforms (kept off the native path). */
+    get preTransforms() {
+        return this.#preTransforms;
+    }
+    /** Whether this chain carries a `requiredWhen`-family condition. */
+    get hasConditionalRequired() {
+        return this.#requiredConditions.length > 0;
+    }
+    /**
+     * Re-type this chain to a new phantom output while carrying its runtime state
+     * forward. Cast-free: `new RuleChain<U>()` is genuinely `RuleChain<U>` because
+     * the brand is `declare`-only. State arrays are copied so the abandoned source
+     * chain can't be mutated through the new one.
+     */
+    #retype() {
+        const next = new _a();
+        next.#rules = [...this.#rules];
+        next.#isOptional = this.#isOptional;
+        next.#isNullable = this.#isNullable;
+        next.#bail = this.#bail;
+        next.#transforms = [...this.#transforms];
+        next.#preTransforms = [...this.#preTransforms];
+        next.#nestedSchema = this.#nestedSchema;
+        next.#arrayItemChain = this.#arrayItemChain;
+        next.#useRules = [...this.#useRules];
+        next.#requiredConditions = [...this.#requiredConditions];
+        return next;
+    }
+    /** Mark field as optional (absent / `undefined` allowed). */
     optional() {
         this.#isOptional = true;
         return this;
     }
+    /** Mark field as nullable (`null` allowed, kept in the output). */
+    nullable() {
+        this.#isNullable = true;
+        return this;
+    }
+    /** Mark field as both optional and nullable. */
+    nullish() {
+        this.#isOptional = true;
+        this.#isNullable = true;
+        return this;
+    }
+    /** Stop at the first failing rule for this field (VineJS bail). */
+    bail(enabled = true) {
+        this.#bail = enabled;
+        return this;
+    }
     /** Must be an object matching a nested schema. */
     object(shape) {
         this.#rules.push({
             name: "object",
-            validate: (v) => typeof v === "object" && v !== null && !Array.isArray(v),
+            validate: (v) => isPlainObject(v),
             message: "Must be an object",
         });
         this.#nestedSchema = shape;
-        return this;
+        return this.#retype();
     }
     /** Must be an array. Items validated by the provided chain. */
     array(itemChain) {
@@ -190,7 +329,7 @@ export class RuleChain {
             message: "Must be an array",
         });
         this.#arrayItemChain = itemChain ?? null;
-        return this;
+        return this.#retype();
     }
     /** Must be a string. */
     string() {
@@ -199,7 +338,7 @@ export class RuleChain {
             validate: (v) => typeof v === "string",
             message: "Must be a string",
         });
-        return this;
+        return this.#retype();
     }
     /** Must be a number. */
     number() {
@@ -208,7 +347,7 @@ export class RuleChain {
             validate: (v) => typeof v === "number" && !Number.isNaN(v) && Number.isFinite(v),
             message: "Must be a number",
         });
-        return this;
+        return this.#retype();
     }
     /** Must be a boolean. */
     boolean() {
@@ -217,13 +356,35 @@ export class RuleChain {
             validate: (v) => typeof v === "boolean",
             message: "Must be a boolean",
         });
-        return this;
+        return this.#retype();
+    }
+    /** Must equal one of `values` (enum). Narrows the output to the union. */
+    enum(values) {
+        const allowed = [...values];
+        this.#rules.push({
+            name: "enum",
+            args: { values: allowed },
+            validate: (v) => allowed.includes(asPrimitive(v)),
+            message: "Invalid value",
+        });
+        return this.#retype();
+    }
+    /** Must equal a literal value. */
+    literal(value) {
+        this.#rules.push({
+            name: "literal",
+            args: { expectedValue: value },
+            validate: (v) => v === value,
+            message: `Must be ${String(value)}`,
+        });
+        return this.#retype();
     }
-    /** Minimum length (string) or minimum value (number). */
+    /** Minimum length (string) or minimum value (number). Alias of min/minLength. */
     min(n) {
         this.#rules.push({
             name: "min",
             param: n,
+            args: { min: n },
             validate: (v) => typeof v === "string"
                 ? [...v].length >= n
                 : typeof v === "number"
@@ -233,11 +394,12 @@ export class RuleChain {
         });
         return this;
     }
-    /** Maximum length (string) or maximum value (number). */
+    /** Maximum length (string) or maximum value (number). Alias of max/maxLength. */
     max(n) {
         this.#rules.push({
             name: "max",
             param: n,
+            args: { max: n },
             validate: (v) => typeof v === "string"
                 ? [...v].length <= n
                 : typeof v === "number"
@@ -247,20 +409,141 @@ export class RuleChain {
         });
         return this;
     }
+    /** Minimum length for a string or array (VineJS `minLength`). */
+    minLength(n) {
+        this.#rules.push({
+            name: "minLength",
+            param: n,
+            args: { min: n },
+            validate: (v) => sizedLength(v) >= n,
+            message: `Must have at least ${n} characters`,
+        });
+        return this;
+    }
+    /** Maximum length for a string or array (VineJS `maxLength`). */
+    maxLength(n) {
+        this.#rules.push({
+            name: "maxLength",
+            param: n,
+            args: { max: n },
+            validate: (v) => {
+                const len = sizedLength(v);
+                return len >= 0 && len <= n;
+            },
+            message: `Must not exceed ${n} characters`,
+        });
+        return this;
+    }
+    /** Exact length for a string or array (VineJS `fixedLength`). */
+    fixedLength(n) {
+        this.#rules.push({
+            name: "fixedLength",
+            param: n,
+            args: { size: n },
+            validate: (v) => sizedLength(v) === n,
+            message: `Must be exactly ${n} characters`,
+        });
+        return this;
+    }
     /** Must be a valid email. */
     email() {
         this.#rules.push({
             name: "email",
-            // Mirror the Rust engine's regex exactly (crates/rune-engine/src/engine.rs)
-            // so the SAME schema validates identically whether or not the native
-            // binary loaded: no whitespace anywhere (the old TS rule rejected only
-            // \r\n, silently accepting interior spaces), a single @, dotted domain.
+            // Mirror the Rust engine's regex exactly so the SAME schema validates
+            // identically whether or not the native binary loaded.
             validate: (v) => typeof v === "string" && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v),
             message: "Must be a valid email",
         });
         return this;
     }
-    /** Must be positive (> 0) and finite. */
+    /** Must match a regular expression (TS-only — never dispatched to Rust). */
+    regex(pattern) {
+        this.#rules.push({
+            name: "regex",
+            validate: (v) => typeof v === "string" && pattern.test(v),
+            message: "Invalid format",
+        });
+        return this;
+    }
+    /** Must be a valid URL (TS-only — uses the WHATWG URL parser). */
+    url() {
+        this.#rules.push({
+            name: "url",
+            validate: (v) => typeof v === "string" && isValidUrl(v),
+            message: "Must be a valid URL",
+        });
+        return this;
+    }
+    /** Must be a valid UUID. */
+    uuid() {
+        this.#rules.push({
+            name: "uuid",
+            validate: (v) => typeof v === "string" && UUID_RE.test(v),
+            message: "Must be a valid UUID",
+        });
+        return this;
+    }
+    /** Must contain only ASCII letters. */
+    alpha() {
+        this.#rules.push({
+            name: "alpha",
+            validate: (v) => typeof v === "string" && v.length > 0 && /^[a-zA-Z]+$/.test(v),
+            message: "Must contain only letters",
+        });
+        return this;
+    }
+    /** Must contain only ASCII letters and digits. */
+    alphaNumeric() {
+        this.#rules.push({
+            name: "alphaNumeric",
+            validate: (v) => typeof v === "string" && v.length > 0 && /^[a-zA-Z0-9]+$/.test(v),
+            message: "Must contain only letters and numbers",
+        });
+        return this;
+    }
+    /** String must start with `substring`. */
+    startsWith(substring) {
+        this.#rules.push({
+            name: "startsWith",
+            args: { substring },
+            validate: (v) => typeof v === "string" && v.startsWith(substring),
+            message: `Must start with ${substring}`,
+        });
+        return this;
+    }
+    /** String must end with `substring`. */
+    endsWith(substring) {
+        this.#rules.push({
+            name: "endsWith",
+            args: { substring },
+            validate: (v) => typeof v === "string" && v.endsWith(substring),
+            message: `Must end with ${substring}`,
+        });
+        return this;
+    }
+    /** Value must be one of `values`. */
+    in(values) {
+        const allowed = [...values];
+        this.#rules.push({
+            name: "in",
+            args: { values: allowed },
+            validate: (v) => allowed.includes(asPrimitive(v)),
+            message: "Invalid value",
+        });
+        return this;
+    }
+    /** Value must NOT be one of `values`. */
+    notIn(values) {
+        const denied = [...values];
+        this.#rules.push({
+            name: "notIn",
+            args: { values: denied },
+            validate: (v) => !denied.includes(asPrimitive(v)),
+            message: "Invalid value",
+        });
+        return this;
+    }
+    /** Number must be positive (> 0) and finite. */
     positive() {
         this.#rules.push({
             name: "positive",
@@ -269,6 +552,96 @@ export class RuleChain {
         });
         return this;
     }
+    /** Number must be negative (< 0) and finite. */
+    negative() {
+        this.#rules.push({
+            name: "negative",
+            validate: (v) => typeof v === "number" && Number.isFinite(v) && v < 0,
+            message: "Must be negative",
+        });
+        return this;
+    }
+    /** Number must be >= 0 and finite. */
+    nonNegative() {
+        this.#rules.push({
+            name: "nonNegative",
+            validate: (v) => typeof v === "number" && Number.isFinite(v) && v >= 0,
+            message: "Must be positive or zero",
+        });
+        return this;
+    }
+    /** Number must fall within `[min, max]` (inclusive). */
+    range(min, max) {
+        this.#rules.push({
+            name: "range",
+            args: { min, max },
+            validate: (v) => typeof v === "number" && Number.isFinite(v) && v >= min && v <= max,
+            message: `Must be between ${min} and ${max}`,
+        });
+        return this;
+    }
+    /** Number must have at most `digits` decimal places (TS-only). */
+    decimal(digits) {
+        this.#rules.push({
+            name: "decimal",
+            args: { digits },
+            validate: (v) => {
+                if (typeof v !== "number" || !Number.isFinite(v))
+                    return false;
+                const parts = String(v).split(".");
+                return (parts[1]?.length ?? 0) <= digits;
+            },
+            message: `Must have at most ${digits} decimal places`,
+        });
+        return this;
+    }
+    /** Must equal a sibling field (VineJS `sameAs`). Cross-field → TS-only. */
+    sameAs(otherField) {
+        this.#useRules.push({
+            __rune: "rule",
+            run: (value, field) => {
+                const other = readSibling(field, otherField);
+                if (value !== other) {
+                    field.report(`Must match ${otherField}`, "sameAs");
+                }
+            },
+        });
+        return this;
+    }
+    /** Must equal its `<field>_confirmation` sibling (VineJS `confirmed`). */
+    confirmed(options) {
+        this.#useRules.push({
+            __rune: "rule",
+            run: (value, field) => {
+                const leaf = field.field.split(".").pop() ?? field.field;
+                const other = options?.confirmationField ?? `${leaf}_confirmation`;
+                if (value !== readSibling(field, other)) {
+                    field.report("Confirmation does not match", "confirmed");
+                }
+            },
+        });
+        return this;
+    }
+    /** Required only when `otherField` is present (non-null) — else optional. */
+    requiredIfExists(otherField) {
+        this.#requiredConditions.push({ kind: "exists", otherField });
+        return this;
+    }
+    /** Required only when `otherField` is absent/null — else optional. */
+    requiredIfMissing(otherField) {
+        this.#requiredConditions.push({ kind: "missing", otherField });
+        return this;
+    }
+    /** Required only when `otherField <op> value` holds — else optional. */
+    requiredWhen(otherField, operator, value) {
+        this.#requiredConditions.push({
+            kind: "when",
+            otherField,
+            operator,
+            value,
+        });
+        return this;
+    }
     /** Trim whitespace (transform). */
     trim() {
         this.#transforms.push({
@@ -277,6 +650,21 @@ export class RuleChain {
         });
         return this;
     }
+    /**
+     * Post-validation transform changing the output type (VineJS `transform`).
+     * `value` is `unknown` — narrow it in the callback (the no-cast rule forbids
+     * lying about a dynamically-produced value's static type).
+     */
+    transform(fn) {
+        const next = this.#retype();
+        next.#transforms.push({ name: "transform", fn: (v, f) => fn(v, f) });
+        return next;
+    }
+    /** Pre-validation transform of the raw input (VineJS `parse`). */
+    parse(fn) {
+        this.#preTransforms.push(fn);
+        return this;
+    }
     /** Custom validation rule. */
     custom(name, validate, message) {
         this.#rules.push({
@@ -286,86 +674,153 @@ export class RuleChain {
         });
         return this;
     }
+    /**
+     * Attach a `.use()` rule (from {@link createRule}). Unlike `custom`, the rule
+     * receives a {@link FieldContext} with the root `data` and `parent`, so it can
+     * validate across fields. Runs after this field's type/value rules.
+     */
+    use(rule) {
+        if (rule?.__rune !== "rule" || typeof rule.run !== "function") {
+            throw new RuneError("INVALID_RULE", "use() expects a compiled rule — call the factory first", { hint: "use(myRule()) or use(myRule(options)), not use(myRule)" });
+        }
+        this.#useRules.push(rule);
+        return this;
+    }
     /** Set custom error message for the last rule. */
     message(msg) {
         if (this.#rules.length === 0) {
             throw new RuneError("NO_RULE", "message() must be called after a rule");
         }
-        this.#rules[this.#rules.length - 1].message = msg;
+        const last = this.#rules[this.#rules.length - 1];
+        last.message = msg;
+        last.hasCustomMessage = true;
         return this;
     }
+    /** Whether the field is required given the surrounding data (conditionals). */
+    #isRequired(ctx) {
+        if (this.#requiredConditions.length === 0)
+            return true;
+        return this.#requiredConditions.some((cond) => evalRequiredCondition(cond, ctx));
+    }
     /** Internal: validate a field value and return errors + transformed value. */
-    _validateWithTransform(field, value) {
-        if (value === undefined || value === null) {
-            if (this.#isOptional)
+    _validateWithTransform(field, rawValue, ctx = EMPTY_RUN_CONTEXT) {
+        // 0. Pre-validation parse() transforms run on the raw value first.
+        let value = rawValue;
+        for (const pre of this.#preTransforms) {
+            value = pre(value);
+        }
+        if (value === undefined) {
+            if (this.#isOptional || !this.#isRequired(ctx)) {
                 return { errors: [], transformed: value };
-            return { errors: [this.#requiredError(field)], transformed: value };
+            }
+            return { errors: [this.#requiredError(field, ctx)], transformed: value };
+        }
+        if (value === null) {
+            // rune treats a `null` value as "absent" for optional/nullable/
+            // non-required fields (a deliberate, cross-engine-conformance-tested
+            // choice — see the Rust↔TS parity suite). `.nullable()` additionally
+            // keeps it in the output. This unifies null/undefined for optional
+            // fields, a documented deviation from VineJS's stricter split.
+            if (this.#isNullable || this.#isOptional || !this.#isRequired(ctx)) {
+                return { errors: [], transformed: value };
+            }
+            return { errors: [this.#requiredError(field, ctx)], transformed: value };
         }
         // 1. Type rules first on the raw value — bail on type mismatch.
-        const typeError = this.#runTypeRules(field, value);
+        const typeError = this.#runTypeRules(field, value, ctx);
         if (typeError)
             return { errors: [typeError], transformed: value };
         // 2. Apply transforms (trim, etc.), then run value rules on the result.
-        let transformed = this.#applyTransformsTo(value);
-        const errors = this.#runValueRules(field, transformed);
+        let transformed = this.#applyTransformsTo(value, field, ctx);
+        const errors = this.#runValueRules(field, transformed, ctx);
+        // 3. Vine-style .use() rules — run with a FieldContext exposing the root
+        //    `data` and `parent`, so a rule can validate across fields.
+        if (this.#useRules.length > 0 && !(this.#bail && errors.length > 0)) {
+            this.#runUseRules(field, transformed, ctx, errors);
+        }
         // 4. Nested object validation (only if type check passed — not arrays)
-        if (this.#nestedSchema &&
-            typeof transformed === "object" &&
-            transformed !== null &&
-            !Array.isArray(transformed)) {
-            transformed = { ...transformed };
+        if (this.#nestedSchema && isPlainObject(transformed)) {
+            const obj = { ...transformed };
+            transformed = obj;
             for (const [nestedField, chain] of Object.entries(this.#nestedSchema)) {
-                const nestedValue = transformed[nestedField];
-                const nestedResult = chain._validateWithTransform(`${field}.${nestedField}`, nestedValue);
+                const nestedResult = chain._validateWithTransform(`${field}.${nestedField}`, obj[nestedField], { ...ctx, parent: obj });
                 errors.push(...nestedResult.errors);
                 if (nestedResult.transformed !== undefined) {
-                    transformed[nestedField] =
-                        nestedResult.transformed;
+                    obj[nestedField] = nestedResult.transformed;
                 }
             }
         }
         // 5. Array item validation
         if (this.#arrayItemChain && Array.isArray(transformed)) {
-            transformed = [...transformed];
-            for (let i = 0; i < transformed.length; i++) {
-                const itemResult = this.#arrayItemChain._validateWithTransform(`${field}.${i}`, transformed[i]);
+            const arr = [...transformed];
+            transformed = arr;
+            for (let i = 0; i < arr.length; i++) {
+                const itemResult = this.#arrayItemChain._validateWithTransform(`${field}.${i}`, arr[i], { ...ctx, parent: arr });
+                for (const e of itemResult.errors) {
+                    if (e.index === undefined)
+                        e.index = i;
+                }
                 errors.push(...itemResult.errors);
                 if (itemResult.transformed !== undefined) {
-                    transformed[i] = itemResult.transformed;
+                    arr[i] = itemResult.transformed;
                 }
             }
         }
         return { errors, transformed };
     }
-    #requiredError(field) {
+    /** Run `.use()` rules on the transformed value with a fresh FieldContext. */
+    #runUseRules(field, transformed, ctx, errors) {
+        const fieldCtx = {
+            value: transformed,
+            data: ctx.data,
+            parent: ctx.parent,
+            field,
+            meta: ctx.meta,
+            isValid: errors.length === 0,
+            report(message, rule) {
+                errors.push({ field, rule, message });
+            },
+        };
+        for (const rule of this.#useRules) {
+            fieldCtx.isValid = errors.length === 0;
+            rule.run(transformed, fieldCtx);
+        }
+    }
+    #requiredError(field, ctx) {
         return {
             field,
             rule: "required",
-            message: resolveValidationMessage("validation.required", `${field} is required`, { field }),
+            message: resolveRequiredMessage(field, ctx),
         };
     }
     /** Run the type rules (string/number/…) on the raw value; first failure bails. */
-    #runTypeRules(field, value) {
+    #runTypeRules(field, value, ctx) {
         for (const rule of this.#rules) {
             if (TYPE_RULE_NAMES.has(rule.name) && !rule.validate(value)) {
                 return {
                     field,
                     rule: rule.name,
-                    message: resolveRuleMessage(field, rule),
+                    message: resolveRuleMessage(field, rule, ctx),
+                    ...(ruleArgs(rule) ? { meta: ruleArgs(rule) } : {}),
                 };
             }
         }
         return null;
     }
     /** Run the non-type rules (min/max/email/…) on the transformed value. */
-    #runValueRules(field, transformed) {
+    #runValueRules(field, transformed, ctx) {
         const errors = [];
         for (const rule of this.#rules) {
-            if (!TYPE_RULE_NAMES.has(rule.name) && !rule.validate(transformed)) {
+            if (TYPE_RULE_NAMES.has(rule.name))
+                continue;
+            if (this.#bail && errors.length > 0)
+                break;
+            if (!rule.validate(transformed)) {
                 errors.push({
                     field,
                     rule: rule.name,
-                    message: resolveRuleMessage(field, rule),
+                    message: resolveRuleMessage(field, rule, ctx),
+                    ...(ruleArgs(rule) ? { meta: ruleArgs(rule) } : {}),
                 });
             }
         }
@@ -377,40 +832,139 @@ export class RuleChain {
     }
     /** Internal: apply transforms. */
     _transform(value) {
-        return this.#applyTransformsTo(value);
+        return this.#applyTransformsTo(value, "", EMPTY_RUN_CONTEXT);
     }
-    #applyTransformsTo(value) {
+    #applyTransformsTo(value, field, ctx) {
         let result = value;
         for (const transform of this.#transforms) {
-            result = transform.fn(result);
+            LAST_FIELD.value = result;
+            LAST_FIELD.data = ctx.data;
+            LAST_FIELD.parent = ctx.parent;
+            LAST_FIELD.field = field;
+            LAST_FIELD.meta = ctx.meta;
+            result = transform.fn(result, LAST_FIELD);
         }
         return result;
     }
 }
+_a = RuleChain;
+/**
+ * Scratch FieldContext reused for `.transform()` callbacks — transforms run
+ * inline in {@link RuleChain.#applyTransformsTo}, which repopulates it before
+ * each call. A shared object avoids per-transform allocation; it is never
+ * retained across calls.
+ */
+const LAST_FIELD = {
+    value: undefined,
+    data: {},
+    parent: {},
+    field: "",
+    meta: {},
+    isValid: true,
+    report() { },
+};
+/** Coerce a value to a comparable primitive for `in`/`enum` membership. */
+function asPrimitive(value) {
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    // Non-primitive values can never be a member of a primitive set; return a
+    // sentinel that no allowed entry equals.
+    return Symbol.iterator.toString();
+}
+/** Code-point length for a string, element count for an array, else -1. */
+function sizedLength(value) {
+    if (typeof value === "string")
+        return [...value].length;
+    if (Array.isArray(value))
+        return value.length;
+    return -1;
+}
+/** WHATWG URL validity — accepts only http/https to avoid `mailto:` etc. */
+function isValidUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/** Read a sibling field's value from the immediate parent (object only). */
+function readSibling(field, name) {
+    const parent = field.parent;
+    if (Array.isArray(parent))
+        return undefined;
+    return parent[name];
+}
+/** Evaluate whether a `requiredWhen`-family condition makes the field required. */
+function evalRequiredCondition(cond, ctx) {
+    const other = isPlainObject(ctx.parent)
+        ? ctx.parent[cond.otherField]
+        : ctx.data[cond.otherField];
+    const present = other !== undefined && other !== null;
+    if (cond.kind === "exists")
+        return present;
+    if (cond.kind === "missing")
+        return !present;
+    switch (cond.operator) {
+        case "=":
+            return other === cond.value;
+        case "!=":
+            return other !== cond.value;
+        case ">":
+            return typeof other === "number" && typeof cond.value === "number"
+                ? other > cond.value
+                : false;
+        case "<":
+            return typeof other === "number" && typeof cond.value === "number"
+                ? other < cond.value
+                : false;
+        case ">=":
+            return typeof other === "number" && typeof cond.value === "number"
+                ? other >= cond.value
+                : false;
+        case "<=":
+            return typeof other === "number" && typeof cond.value === "number"
+                ? other <= cond.value
+                : false;
+        case "in":
+            return Array.isArray(cond.value) && cond.value.includes(other);
+        case "notIn":
+            return Array.isArray(cond.value) && !cond.value.includes(other);
+        default:
+            return false;
+    }
+}
+/** No-op alias of {@link schema} — VineJS `vine.compile()` API parity. */
+export function compile(s) {
+    return s;
+}
 /** Entry point for building rules. */
 export const rules = {
     string: () => new RuleChain().string(),
     number: () => new RuleChain().number(),
     boolean: () => new RuleChain().boolean(),
     any: () => new RuleChain(),
+    object: (shape) => new RuleChain().object(shape),
+    array: (item) => new RuleChain().array(item),
+    enum: (values) => new RuleChain().enum(values),
+    literal: (value) => new RuleChain().literal(value),
 };
 /** Serialize schema + data and validate via Rust NAPI. */
 function validateWithRust(fields, data) {
     const schemaDesc = {};
     for (const [field, chain] of Object.entries(fields)) {
-        const rules = chain.rules.map((r) => ({
+        const ruleDescs = chain.rules.map((r) => ({
             name: r.name,
-            // Serialize THIS rule's own param. Previously a find-first lookup by
-            // rule name returned the first matching rule's param, so min(3).min(5)
-            // sent both Rust entries as min=3, dropping the 5 bound (audit 2026-06-13).
-            params: r.name === "min"
-                ? { min: r.param }
-                : r.name === "max"
-                    ? { max: r.param }
-                    : null,
+            // Serialize THIS rule's own args (per-rule, so min(3).min(5) keeps both
+            // bounds — a find-first lookup previously collapsed them).
+            params: r.args ?? null,
         }));
         schemaDesc[field] = {
-            rules,
+            rules: ruleDescs,
             optional: chain.isOptionalField,
             transforms: chain.transforms.map((t) => t.name),
         };