@c9up/rune 0.1.7 → 0.1.9

package/dist/Schema.d.ts

@@ -3,6 +3,9 @@
  *
  * @implements FR38, FR39, FR40, FR41
  */
+import { type CompareUnit, type DateFormat } from "./date.js";
+import { RuneValidationError } from "./errors.js";
+import { type AlphaOptions, type EmailOptions, type NormalizeEmailOptions, type NormalizeUrlOptions, type UrlOptions, type VatOptions } from "./formats.js";
 import type { MessagesProviderContract } from "./MessagesProvider.js";
 export type ValidationMessageParams = Record<string, string | number | boolean>;
 export type ValidationTranslator = (key: string, params?: ValidationMessageParams) => string | undefined;
@@ -34,8 +37,26 @@ export interface FieldContext {
     meta: Record<string, unknown>;
     /** `true` while no error has been reported for this field yet. */
     isValid: boolean;
-    /** Report a validation failure for this field. */
-    report(message: string, rule: string): void;
+    /** Last path segment — `city` for `address.city` (VineJS `name`). */
+    name: string;
+    /** Dotted path with numeric segments replaced by `*` (`tags.*.name`). */
+    wildCardPath: string;
+    /** `true` when this value sits inside an array. */
+    isArrayMember: boolean;
+    /** `true` when the value is neither `undefined` nor `null`. */
+    isDefined: boolean;
+    /** `true` when the value passed its type rule. */
+    isValidDataType: boolean;
+    /** The full dotted path — same value as {@link field}, VineJS spelling. */
+    getFieldPath(): string;
+    /** Replace the value under validation (VineJS `mutate`). */
+    mutate(newValue: unknown): void;
+    /**
+     * Report a validation failure. `field` and `args` are optional (VineJS
+     * passes four arguments); omitting them reports against this field with no
+     * interpolation data.
+     */
+    report(message: string, rule: string, field?: string | FieldContext, args?: Record<string, unknown>): void;
 }
 /**
  * A `.use()` rule validator — VineJS shape `(value, options, field)`. Report
@@ -45,6 +66,13 @@ export type RuleValidator<Options = undefined> = (value: unknown, options: Optio
 /** A compiled `.use()` rule produced by {@link createRule}. */
 export interface CompiledRule {
     readonly __rune: "rule";
+    /** Run even on `undefined`/`null` (VineJS implicit rules). */
+    readonly implicit?: boolean;
+    readonly name?: string;
+    /** Modifier applied to this field's JSON Schema node. */
+    readonly toJSONSchema?: JsonSchemaModifier;
+    /** The options the rule was built with, handed to {@link toJSONSchema}. */
+    readonly ruleOptions?: unknown;
     run(value: unknown, field: FieldContext): void;
 }
 /**
@@ -62,8 +90,61 @@ export interface CompiledRule {
  *       passwordConfirmation: rules.string().use(sameAs('password')),
  *     })
  */
-export declare function createRule(validator: RuleValidator<undefined>): () => CompiledRule;
-export declare function createRule<Options>(validator: RuleValidator<Options>): (options: Options) => CompiledRule;
+/**
+ * Options accepted by {@link createRule} / {@link createAsyncRule} — VineJS
+ * `vine.createRule(fn, { implicit, isAsync })`.
+ */
+export interface CreateRuleOptions {
+    /**
+     * Run the rule even when the value is `undefined` or `null`. Non-implicit
+     * rules are skipped on an absent value, which is why a `required`-style
+     * custom rule could not be written before.
+     */
+    implicit?: boolean;
+    /** Rule name reported in errors when the validator does not pass one. */
+    name?: string;
+    /**
+     * VineJS `toJSONSchema?: JsonSchemaModifier` — a FUNCTION receiving the node
+     * built so far (plus the rule's options) and returning the modified node.
+     * A static fragment could only ever add keys; a modifier can also narrow or
+     * replace what the base rules produced.
+     */
+    toJSONSchema?: JsonSchemaModifier;
+    /**
+     * Declare the rule asynchronous (VineJS `{ isAsync: true }`).
+     * {@link createAsyncRule} sets it; passing it to {@link createRule} routes
+     * the rule to the async builder instead of silently producing a sync rule
+     * whose Promise nobody awaits.
+     */
+    isAsync?: boolean;
+}
+export declare function createRule(validator: RuleValidator<undefined>, options?: CreateRuleOptions): () => CompiledRule;
+export declare function createRule<Options>(validator: RuleValidator<Options>, options?: CreateRuleOptions): (options: Options) => CompiledRule;
+/**
+ * An async `.useAsync()` rule validator — same shape as {@link RuleValidator}
+ * but may return a Promise. Runs only under {@link ValidationSchema.validateResultAsync}.
+ */
+export type AsyncRuleValidator<Options = undefined> = (value: unknown, options: Options, field: FieldContext) => void | Promise<void>;
+/** A compiled async rule produced by {@link createAsyncRule}. */
+export interface AsyncCompiledRule {
+    readonly __rune: "asyncRule";
+    /** Run even on `undefined`/`null` (VineJS implicit rules). */
+    readonly implicit?: boolean;
+    readonly name?: string;
+    /** Modifier applied to this field's JSON Schema node. */
+    readonly toJSONSchema?: JsonSchemaModifier;
+    /** The options the rule was built with, handed to {@link toJSONSchema}. */
+    readonly ruleOptions?: unknown;
+    run(value: unknown, field: FieldContext): Promise<void>;
+}
+/**
+ * Async counterpart of {@link createRule} — for rules that must await (DB lookups
+ * etc.). Attach with `chain.useAsync(rule(options))`; the schema must then be run
+ * with `validateResultAsync`. This is how DB-backed `unique`/`exists` rules are built
+ * (the validator does the query), keeping rune framework-agnostic.
+ */
+export declare function createAsyncRule(validator: AsyncRuleValidator<undefined>, options?: CreateRuleOptions): () => AsyncCompiledRule;
+export declare function createAsyncRule<Options>(validator: AsyncRuleValidator<Options>, options?: CreateRuleOptions): (options: Options) => AsyncCompiledRule;
 /**
  * Validation result — discriminated union that narrows `data` to the schema's
  * `T` when `valid` is `true`, removing the need for callers to cast or guard
@@ -88,17 +169,105 @@ export interface ValidateOptions {
      * provider takes precedence over a globally bound translator).
      */
     messagesProvider?: MessagesProviderContract;
+    /**
+     * VineJS `errorReporter: () => ErrorReporterContract` — a FACTORY returning a
+     * reporter, so a transcribed Adonis reporter works as-is. A plain
+     * `(error) => void` observer is also accepted.
+     *
+     * The two are told apart by ARITY (a factory takes no argument), never by
+     * calling one speculatively to see what comes back.
+     *
+     * Either way the reporter OBSERVES: the validation result is never changed by
+     * it, so a reporter cannot mask a failure.
+     */
+    errorReporter?: ErrorReporterFactory | ((error: ValidationError) => void);
 }
+/**
+ * VineJS `JsonSchemaModifier`: receives the JSON Schema node assembled from the
+ * declarative rules and returns the node to use instead.
+ */
+export type JsonSchemaModifier = (node: Record<string, unknown>, options?: unknown) => Record<string, unknown>;
+/** VineJS `ErrorReporterContract`. */
+export interface ErrorReporterContract {
+    /** `true` once at least one error has been reported. */
+    hasErrors: boolean;
+    /** Build the exception a caller may throw. */
+    createError(): Error;
+    /** Report one failure. */
+    report(message: string, rule: string, field: FieldContext | string, args?: Record<string, unknown>): unknown;
+}
+/** A zero-argument factory producing a fresh {@link ErrorReporterContract}. */
+export type ErrorReporterFactory = () => ErrorReporterContract;
 export interface ValidationSchema<T = Record<string, unknown>> {
     fields: Record<string, RuleChain>;
-    /** Result-based validation (superset) — never throws. */
-    validate(data: unknown, options?: ValidateOptions): ValidationResult<T>;
+    /**
+     * The object schema the validator was built from — always a chain, so
+     * `validator.schema.partial()` / `.pick()` / `.omit()` work as in VineJS
+     * whichever form `create()` received. The raw field map stays on
+     * {@link fields}.
+     */
+    schema: RuleChain;
+    /**
+     * Standard Schema v1 contract, so a consumer can validate through the
+     * vendor-neutral protocol instead of rune's own API.
+     */
+    "~standard": {
+        version: 1;
+        vendor: string;
+        /** Standard JSON Schema v1 props (VineJS 4.3+). */
+        jsonSchema: {
+            input(): Record<string, unknown>;
+            output(): Record<string, unknown>;
+        };
+        validate(value: unknown): Promise<{
+            value: T;
+        } | {
+            issues: ReadonlyArray<{
+                message: string;
+                path: string[];
+            }>;
+        }>;
+    };
+    /**
+     * Error reporter for this validator (VineJS `validator.errorReporter`). A
+     * per-call option still wins; this wins over the process-wide one.
+     */
+    errorReporter: ErrorReporterFactory | ((error: ValidationError) => void) | null;
+    /** Introspection of the compiled schema — VineJS `{ schema, refs }` shape. */
+    toJSON(): {
+        schema: SchemaIntrospection;
+        refs: string[];
+    };
+    /** JSON Schema for the compiled validator (VineJS `toJSONSchema`). */
+    toJSONSchema(): Record<string, unknown>;
+    /**
+     * Validate and return the payload, throwing {@link RuneValidationError} on
+     * failure — the VineJS/Adonis contract (`validator.validate(data)`), async
+     * so a schema carrying `unique`/`exists` behaves like any other.
+     *
+     * The never-throwing, synchronous form rune also offers is
+     * {@link validateResult}.
+     */
+    validate(data: unknown, options?: ValidateOptions): Promise<T>;
+    /** Result-based validation (rune superset) — synchronous, never throws. */
+    validateResult(data: unknown, options?: ValidateOptions): ValidationResult<T>;
+    /** Result-based validation awaiting async rules — never throws. */
+    validateResultAsync(data: unknown, options?: ValidateOptions): Promise<ValidationResult<T>>;
     /**
      * Throwing validation (VineJS/Adonis parity). Returns the validated data on
      * success; throws {@link RuneValidationError} (`E_VALIDATION_ERROR`, HTTP 422)
      * with a structured `.messages` array on failure.
      */
     validateOrThrow(data: unknown, options?: ValidateOptions): T;
+    /**
+     * Non-throwing validation returning `[error, null] | [null, data]`
+     * (VineJS `tryValidate`).
+     */
+    tryValidate(data: unknown, options?: ValidateOptions): Promise<[RuneValidationError, null] | [null, T]>;
+    /** Synchronous counterpart of {@link tryValidate} (rune superset). */
+    tryValidateSync(data: unknown, options?: ValidateOptions): [RuneValidationError, null] | [null, T];
+    /** Throwing async validation (see {@link validateResultAsync} + {@link validateOrThrow}). */
+    validateOrThrowAsync(data: unknown, options?: ValidateOptions): Promise<T>;
 }
 /** Context threaded through validation so field rules can reach root/parent/meta. */
 interface RunContext {
@@ -106,7 +275,171 @@ interface RunContext {
     parent: Record<string, unknown> | unknown[];
     meta: Record<string, unknown>;
     messagesProvider?: MessagesProviderContract;
+    errorReporter?: (error: ValidationError) => void;
+}
+/**
+ * An async rule run deferred by the (synchronous) traversal and awaited by
+ * `validateResultAsync`. Collected at EVERY depth — top-level fields, nested object
+ * fields and array items alike.
+ */
+interface PendingAsync {
+    chain: RuleChain;
+    field: string;
+    value: unknown;
+    ctx: RunContext;
+}
+/** Bind (or clear) the process-wide error reporter. */
+export declare function setGlobalErrorReporter(reporter: ErrorReporterFactory | ((error: ValidationError) => void) | null): void;
+/** Read the process-wide error reporter. */
+export declare function getGlobalErrorReporter(): ErrorReporterFactory | ((error: ValidationError) => void) | null;
+/** Host lookup seam backing `activeUrl()` — see that rule's note on why. */
+export interface HostResolver {
+    /** Resolve `true` when the hostname resolves (DNS, or whatever you decide). */
+    resolves(hostname: string): Promise<boolean>;
+}
+/** Toggle the global `"" -> null` conversion (VineJS `convertEmptyStringsToNull`). */
+export declare function setConvertEmptyStringsToNull(enabled: boolean): void;
+/** Read the global `"" -> null` conversion flag. */
+export declare function getConvertEmptyStringsToNull(): boolean;
+/** Bind (or clear, with `null`) the resolver backing `activeUrl()`. */
+export declare function bindHostResolver(resolver: HostResolver | null): void;
+/** Bind (or clear) the process-wide messages provider. */
+export declare function setGlobalMessagesProvider(provider: MessagesProviderContract | null): void;
+/** Read the process-wide messages provider. */
+export declare function getGlobalMessagesProvider(): MessagesProviderContract | null;
+/** Bind (or clear, with `null`) the global `rules.date()` output mapper. */
+export declare function setDateTransform(fn: ((value: Date) => unknown) | null): void;
+/**
+ * A database lookup seam for the Lucid-style `unique` / `exists` rules.
+ *
+ * rune stays framework-agnostic, so it never imports a driver: the host binds
+ * one resolver at boot (as `bindRosetta` does for translations) and the rules
+ * then take Lucid's `{ table, column, where }` options instead of a hand-written
+ * callback. The callback form is kept — it is what the resolver is built from.
+ */
+export interface DatabaseResolver {
+    /** Resolve `true` when at least one row matches. */
+    exists(query: DatabaseLookup): Promise<boolean>;
+}
+/** The lookup handed to a {@link DatabaseResolver} (Lucid `unique`/`exists`). */
+export interface DatabaseLookup {
+    table: string;
+    column: string;
+    value: unknown;
+    /** Extra equality filters, e.g. `{ tenant_id: 3 }` (Lucid `where`). */
+    where?: Record<string, unknown>;
+    /** Rows to ignore, e.g. `{ id: 7 }` when updating (Lucid `whereNot`). */
+    whereNot?: Record<string, unknown>;
+}
+/** Bind (or clear, with `null`) the resolver backing `unique()` / `exists()`. */
+export declare function bindDatabase(resolver: DatabaseResolver | null): void;
+/** Options form of `unique()` / `exists()` — Lucid's shape. */
+export interface DatabaseRuleOptions {
+    table: string;
+    column?: string;
+    where?: Record<string, unknown>;
+    whereNot?: Record<string, unknown>;
 }
+/** Options accepted by every date comparison (VineJS `{ compare, format }`). */
+export interface DateCompareOptions {
+    /** Granularity of the comparison. Defaults to `"day"`, like VineJS. */
+    compare?: CompareUnit;
+    /** Format used to parse the operand / sibling, when it is a string. */
+    format?: string;
+}
+/**
+ * The structural shape `file()` accepts. An Adonis bodyparser `MultipartFile`
+ * satisfies it without rune having to know the type.
+ */
+export interface FileLike {
+    size: number;
+    /**
+     * MIME type as REPORTED by the upload. Trust it only with
+     * `verifyContent()`, which checks it against the real bytes.
+     */
+    type?: string;
+    /** Adonis bodyparser's temp path — a byte source for `verifyContent()`. */
+    tmpPath?: string;
+    /** Alternative byte-source paths. */
+    filePath?: string;
+    path?: string;
+    /** In-memory bytes, when the upload was buffered. */
+    buffer?: Uint8Array;
+    extname?: string | null;
+    clientName?: string;
+    name?: string;
+}
+/**
+ * Parse a size limit — a byte count, or Adonis's `"2mb"` / `"512kb"` spelling.
+ * Throws on an unreadable unit rather than falling back to "unlimited": a cap
+ * that silently stops capping is worse than no cap at all.
+ */
+export declare function parseByteSize(size: number | string): number;
+/**
+ * What a `parse()` callback receives besides the value — VineJS's
+ * `ParseFn = (value, ctx: Pick<FieldContext, 'data' | 'parent' | 'meta'>)`.
+ */
+export type ParseContext = Pick<FieldContext, "data" | "parent" | "meta">;
+/**
+ * A conditional set of properties merged into an object (VineJS `vine.group`).
+ * The first branch whose predicate matches contributes its shape; `otherwise`
+ * is the unconditional fallback.
+ */
+export interface ConditionalGroup {
+    readonly __rune: "group";
+    branches: ReadonlyArray<{
+        predicate: ((data: Record<string, unknown>) => boolean) | null;
+        shape: Record<string, RuleChain>;
+    }>;
+}
+/**
+ * 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, {
+    rules: string[];
+    optional: boolean;
+    nullable: boolean;
+}>;
+/** Build a conditional group (VineJS `vine.group([...])`). */
+export declare function group(branches: ReadonlyArray<{
+    predicate: ((data: Record<string, unknown>) => boolean) | null;
+    shape: Record<string, RuleChain>;
+}>): ConditionalGroup;
+/** A predicate-guarded group branch (`vine.group.if`). */
+export declare function groupIf(predicate: (data: Record<string, unknown>) => boolean, shape: Record<string, RuleChain>): {
+    predicate: (data: Record<string, unknown>) => boolean;
+    shape: Record<string, RuleChain>;
+};
+/** The unconditional fallback branch (`vine.group.else` / `.otherwise`). */
+export declare function groupElse(shape: Record<string, RuleChain>): {
+    predicate: null;
+    shape: Record<string, RuleChain>;
+};
+/** A union branch guarded by a predicate — `vine.union.if(...)`. */
+export interface ConditionalBranch {
+    /** `null` for an unconditional branch (`union.else`). */
+    predicate: ((value: unknown, field: FieldContext) => boolean) | null;
+    chain: RuleChain;
+}
+/** What `union()` accepts: a bare chain, or a guarded branch. */
+export type UnionBranch = RuleChain | ConditionalBranch;
+/**
+ * Guarded union branch (VineJS `vine.union.if`). The predicate picks the branch;
+ * the chosen branch's OWN errors are reported, which is what makes a union
+ * diagnosable — "matches nothing" tells the caller nothing about which shape it
+ * nearly matched.
+ */
+export declare function unionIf(predicate: (value: unknown, field: FieldContext) => boolean, chain: RuleChain): ConditionalBranch;
+/** Fallback union branch (VineJS `vine.union.else`). */
+export declare function unionElse(chain: RuleChain): ConditionalBranch;
 /** Extract the phantom output type of a chain. */
 type OutputOf<C> = C extends RuleChain<infer O> ? O : never;
 /** Keys whose output includes `undefined` become optional in the inferred shape. */
@@ -144,8 +477,19 @@ export type Infer<S> = Prettify<{
  * An explicit generic is still accepted for back-compat
  * (`schema<MyType>({ ... })`), overriding inference.
  */
-export declare function schema<S extends Record<string, RuleChain>>(fields: S): ValidationSchema<Infer<S>>;
-export declare function schema<T = Record<string, unknown>>(fields: Record<string, RuleChain>): ValidationSchema<T>;
+export declare function schema<S extends Record<string, RuleChain>>(fields: S, objectChain?: RuleChain): ValidationSchema<Infer<S>>;
+export declare function schema<T = Record<string, unknown>>(fields: Record<string, RuleChain>, objectChain?: RuleChain): ValidationSchema<T>;
+/**
+ * VineJS's `vine.create(...)`. Same thing as {@link schema} — the Adonis
+ * spelling is provided so a validator reads the same in both frameworks.
+ */
+/**
+ * VineJS's `vine.create(...)`. Accepts either a map of fields (rune's native
+ * spelling) or the `RuleChain` produced by `rune.object({...})`, because
+ * `vine.create(vine.object({...}))` is the form Adonis documents.
+ */
+export declare function create<S extends Record<string, RuleChain>>(fields: S): ValidationSchema<Infer<S>>;
+export declare function create(chain: RuleChain): ValidationSchema;
 export declare function setValidationTranslator(translator?: ValidationTranslator): void;
 export declare function bindRosetta(rosetta: {
     t(key: string, params?: ValidationMessageParams): string;
@@ -156,10 +500,24 @@ 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;
+    /**
+     * Keep this rule off the Rust path even though its NAME is in
+     * {@link NATIVE_RULES}. Set by options the native engine does not know about
+     * (`uuid({ version })`, a callback list for `in` / `notIn`): the engine would
+     * run the rule without them and silently answer a different question.
+     */
+    tsOnly?: boolean;
+    /** Modifier this rule applies to its field's JSON Schema node. */
+    toJSONSchema?: JsonSchemaModifier;
 }
 /** A conditional-required condition (VineJS `requiredWhen` family). */
 interface RequiredCondition {
@@ -171,6 +529,11 @@ interface RequiredCondition {
 /** Phantom brand carrying the inferred output type (never assigned at runtime). */
 declare const OUTPUT: unique symbol;
 /** Rule chain — fluent, phantom-typed validation builder. */
+/**
+ * The value list accepted by `in` / `notIn` / `enum` — static, or computed at
+ * validation time (VineJS parity).
+ */
+export type AllowedValues = ReadonlyArray<string | number | boolean> | ((field: FieldContext) => ReadonlyArray<string | number | boolean>);
 export declare class RuleChain<Output = unknown> {
     #private;
     /** Phantom output type — drives {@link Infer}; never read at runtime. */
@@ -186,8 +549,30 @@ export declare class RuleChain<Output = unknown> {
     }>;
     /** Public read access to `.use()` rules (used to keep such schemas off the native path). */
     get useRules(): readonly CompiledRule[];
+    /** Public read access to async rules (`unique`/`exists`/`useAsync`) — run by `validateResultAsync`. */
+    get asyncRules(): readonly AsyncCompiledRule[];
+    /**
+     * Does this chain — or anything nested under it (object fields, array items) —
+     * carry async rules? The schema-level detection used to inspect only the
+     * top-level chains, so a nested `unique`/`exists` was invisible: `validate()`
+     * did not throw and the async pass never ran the rule, silently accepting
+     * an unchecked value.
+     */
+    get hasAsyncRulesDeep(): boolean;
+    /** Does this object keep keys its shape does not declare? */
+    get allowsUnknown(): boolean;
+    /** Free-form JSON Schema metadata attached with `meta()`. */
+    get metadata(): Record<string, unknown> | null;
+    /** The item chain of an `array()`, if declared. */
+    get arrayItem(): RuleChain | null;
+    /** The positional chains of a `tuple()`, if declared. */
+    get tupleItems(): RuleChain[] | null;
+    /** The value chain of a `record()`, if declared. */
+    get recordValue(): RuleChain | null;
+    /** Whether this chain stops at its first failing rule (VineJS `bail`). */
+    get bails(): boolean;
     /** Public read access to `.parse()` pre-transforms (kept off the native path). */
-    get preTransforms(): ReadonlyArray<(value: unknown) => unknown>;
+    get preTransforms(): ReadonlyArray<(value: unknown, ctx: ParseContext) => unknown>;
     /** Whether this chain carries a `requiredWhen`-family condition. */
     get hasConditionalRequired(): boolean;
     /** Mark field as optional (absent / `undefined` allowed). */
@@ -204,12 +589,210 @@ export declare class RuleChain<Output = unknown> {
     array<Item extends RuleChain>(itemChain?: Item): RuleChain<OutputOf<Item>[]>;
     /** Must be a string. */
     string(): RuleChain<string>;
-    /** Must be a number. */
-    number(): RuleChain<number>;
-    /** Must be a boolean. */
-    boolean(): RuleChain<boolean>;
-    /** Must equal one of `values` (enum). Narrows the output to the union. */
-    enum<const V extends readonly (string | number | boolean)[]>(values: V): RuleChain<V[number]>;
+    /**
+     * Must be a number. Like VineJS, a numeric STRING is coerced (`"32"` → `32`)
+     * — HTML form bodies and query strings carry numbers as text, so requiring
+     * `typeof v === "number"` rejected the values Adonis accepts. Pass
+     * `{ strict: true }` to refuse anything that is not already a number.
+     */
+    number(options?: {
+        strict?: boolean;
+    }): RuleChain<number>;
+    /**
+     * Must be a boolean. Like VineJS, `"true"`, `"false"`, `"on"`, `"off"`,
+     * `"1"`, `"0"`, `1` and `0` are coerced; `{ strict: true }` refuses them.
+     */
+    boolean(options?: {
+        strict?: boolean;
+    }): RuleChain<boolean>;
+    /**
+     * Must be a date (VineJS `vine.date()`). ISO 8601 by default; pass `formats`
+     * for unix timestamps (`x` = ms, `X` = seconds) or a token format such as
+     * `DD/MM/YYYY`. Parsing is calendar-strict — `2026-02-31` is rejected.
+     *
+     * The validated output is a `Date`; bind {@link setDateTransform} to map it
+     * to your own type once at boot.
+     */
+    date(options?: {
+        formats?: DateFormat[];
+    }): RuleChain<Date>;
+    /** Must be strictly after `operand` (`'today'`, an ISO string, or a `Date`). */
+    after(operand: unknown, options?: DateCompareOptions): this;
+    /** Must be strictly before `operand`. */
+    before(operand: unknown, options?: DateCompareOptions): this;
+    /** Must be after `operand`, or equal to it. */
+    afterOrEqual(operand: unknown, options?: DateCompareOptions): this;
+    /** Must be before `operand`, or equal to it. */
+    beforeOrEqual(operand: unknown, options?: DateCompareOptions): this;
+    /** Must be after the date held by a sibling field (VineJS `afterField`). */
+    afterField(otherField: string, options?: DateCompareOptions): this;
+    /** Must be before the date held by a sibling field. */
+    beforeField(otherField: string, options?: DateCompareOptions): this;
+    /** Must be the same instant as `operand` (VineJS `equals`). */
+    equals(operand: unknown, options?: DateCompareOptions): this;
+    /** Must be after the sibling's date, or the same instant (VineJS `afterOrSameAs`). */
+    afterOrSameAs(otherField: string, options?: DateCompareOptions): this;
+    /** Must be before the sibling's date, or the same instant. */
+    beforeOrSameAs(otherField: string, options?: DateCompareOptions): this;
+    /** Must fall on a Saturday or Sunday (VineJS `weekend`). */
+    weekend(): this;
+    /** Must fall on a Monday-to-Friday day (VineJS `weekday`). */
+    weekday(): this;
+    /**
+     * Keep keys the object shape does not declare (VineJS
+     * `allowUnknownProperties`). Off by default: dropping undeclared keys is what
+     * makes a validated payload safe to hand to a mass assignment.
+     */
+    allowUnknownProperties(): this;
+    /**
+     * Convert the object's KEYS to camelCase in the output (VineJS
+     * `object.toCamelCase()`), so a snake_case payload hydrates camelCase
+     * properties. Distinct from the string `toCamelCase()`, which rewrites a
+     * VALUE — that one was never a substitute for this.
+     */
+    toCamelCaseKeys(): this;
+    /**
+     * Merge extra properties into this object's shape (VineJS `merge`). Accepts a
+     * plain shape or a {@link ConditionalGroup} whose branch is chosen per
+     * payload — `vine.group` in VineJS.
+     */
+    merge(extra: Record<string, RuleChain> | ConditionalGroup): this;
+    /** The nested shape declared by `object()`, if any (VineJS `getProperties`). */
+    getProperties(): Record<string, RuleChain> | null;
+    /** Independent copy of this chain (VineJS `clone`). */
+    clone(): RuleChain<Output>;
+    /**
+     * A CLONED subset of the object's properties (VineJS `pick`).
+     *
+     * Returns a properties record, not a schema — VineJS types it
+     * `Pick<Properties, Keys>` precisely so it composes by spread:
+     * `rules.any().object({ ...userShape.pick(["id"]) })`. Returning a chain here
+     * broke that idiom.
+     */
+    pick<K extends string>(keys: readonly K[]): Record<string, RuleChain>;
+    /** A cloned copy of the properties EXCLUDING `keys` (VineJS `omit`). */
+    omit<K extends string>(keys: readonly K[]): Record<string, RuleChain>;
+    /** Make every property of an object shape optional (VineJS `partial`). */
+    partial(keys?: readonly string[]): RuleChain<Output>;
+    /**
+     * Must be an "accepted" value — `true`, `1`, `"1"`, `"on"`, `"yes"`,
+     * `"true"` (VineJS `accepted`, for checkbox-style consent fields).
+     */
+    accepted(): RuleChain<true>;
+    /**
+     * Object with arbitrary keys, every value validated by `valueChain`
+     * (VineJS `record`).
+     */
+    record<Item extends RuleChain>(valueChain: Item): RuleChain<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;
+    /**
+     * Fixed-length array with a schema per position (VineJS `tuple`). Extra
+     * items are rejected — a tuple that silently ignores a trailing element is
+     * how unvalidated data slips through.
+     */
+    tuple<const Items extends readonly RuleChain[]>(items: Items): RuleChain<{
+        [K in keyof Items]: OutputOf<Items[K]>;
+    }>;
+    /**
+     * Value must satisfy at least one of `chains`.
+     *
+     * Two forms, both supported:
+     *
+     * - guarded (VineJS parity): `union([rules.union.if(pred, chain), …,
+     *   rules.union.else(fallback)])` — the predicate SELECTS the branch and
+     *   that branch's own errors are reported, so a failure says which shape was
+     *   meant and why it did not fit.
+     * - 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;
+    union(chains: readonly UnionBranch[]): this;
+    /**
+     * Must be an uploaded file (VineJS/Adonis `vine.file()`).
+     *
+     * Named deviation: Adonis validates a bodyparser `MultipartFile`, which rune
+     * cannot import and stay agnostic. It checks the STRUCTURE instead — any
+     * object exposing `size` and a name/extension — so an Adonis MultipartFile
+     * satisfies it, and so does any other upload representation.
+     *
+     * `size` is a byte count; `extnames` are compared lowercase, without the dot.
+     */
+    file(options?: {
+        size?: number | string;
+        extnames?: readonly string[];
+        /**
+         * Skip the magic-number check. Default `true` — Adonis derives `extname`
+         * from the real bytes before validation, so trusting the declaration is
+         * NOT the safe default: a `.exe` renamed `.png` satisfies every
+         * declarative check, since all of them come from the uploader.
+         */
+        verifyContent?: boolean;
+    }): RuleChain<FileLike>;
+    /**
+     * Uploaded file with VineJS `nativeFile` options — `minSize`, `maxSize`,
+     * `mimeTypes`. Same structural contract as {@link file}: rune never reads
+     * bytes, so the MIME type is the one the upload REPORTS.
+     */
+    nativeFile(options?: {
+        minSize?: number | string;
+        maxSize?: number | string;
+        mimeTypes?: readonly string[];
+    }): RuleChain<FileLike>;
+    /** Minimum upload size (VineJS `nativeFile().minSize()`). */
+    minSize(size: number | string): this;
+    /** Maximum upload size (VineJS `nativeFile().maxSize()`). */
+    maxSize(size: number | string): this;
+    /**
+     * Allowed MIME types (VineJS `nativeFile().mimeTypes()`). The type is the one
+     * the upload REPORTS — rune never reads bytes, see {@link file}.
+     */
+    mimeTypes(types: readonly string[]): this;
+    /**
+     * Verify the file's REAL type against its magic number (Adonis parity).
+     *
+     * A `.exe` renamed `.jpg` passes every declarative check — size, extension,
+     * reported MIME — because all three come from the uploader. This reads the
+     * leading bytes and refuses a mismatch.
+     *
+     * Async by nature (it touches the filesystem), so the schema must run with
+     * `validateResultAsync` / `validate`. Needs a byte source on the file object
+     * (`buffer`, `tmpPath`, `filePath` or `path`) — an Adonis `MultipartFile`
+     * carries `tmpPath`. With NO source it FAILS: a content check that cannot
+     * run must never look like one that passed.
+     */
+    verifyContent(): this;
+    /**
+     * 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 | ((field: FieldContext) => V)): RuleChain<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;
     /** Must equal a literal value. */
     literal<V extends string | number | boolean>(value: V): RuleChain<V>;
     /** Minimum length (string) or minimum value (number). Alias of min/minLength. */
@@ -223,25 +806,133 @@ export declare class RuleChain<Output = unknown> {
     /** Exact length for a string or array (VineJS `fixedLength`). */
     fixedLength(n: number): this;
     /** Must be a valid email. */
-    email(): this;
+    email(options?: EmailOptions): this;
     /** Must match a regular expression (TS-only — never dispatched to Rust). */
     regex(pattern: RegExp): this;
     /** Must be a valid URL (TS-only — uses the WHATWG URL parser). */
-    url(): this;
-    /** Must be a valid UUID. */
-    uuid(): this;
+    url(options?: UrlOptions): this;
+    /**
+     * The host must actually resolve (VineJS `activeUrl`).
+     *
+     * The only rule needing the network, which rune cannot do and stay agnostic
+     * and zero-dependency — so it runs through a resolver bound once at boot,
+     * exactly like `unique()`. Async by nature: run the schema with
+     * `validateResultAsync`. Unbound it THROWS, rather than passing a host nobody
+     * checked.
+     */
+    activeUrl(): this;
+    /**
+     * Must be a valid UUID, optionally restricted to given versions
+     * (VineJS `uuid({ version: [4] })`, versions 1 through 8).
+     */
+    uuid(options?: {
+        version?: number | number[];
+    }): this;
+    /** Must be a ULID (VineJS `ulid`). */
+    ulid(): this;
+    /** Must be a JSON Web Token — three dot-separated base64url segments. */
+    jwt(): this;
+    /** Must contain only ASCII characters (VineJS `ascii`). */
+    ascii(): this;
+    /** Must be a CSS hex colour code, with or without the leading `#`. */
+    hexCode(): this;
+    /** Must be an IP address. Pass `version` to require v4 or v6 specifically. */
+    ipAddress(options?: {
+        version?: 4 | 6;
+    }): this;
+    /** Must pass the Luhn checksum (VineJS `creditCard`). */
+    creditCard(): this;
+    /** Must be an IBAN passing the ISO 13616 mod-97 check. */
+    iban(): this;
+    /** Must be a `"lat,lng"` pair within the valid ranges. */
+    coordinates(): this;
+    /**
+     * 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;
+    /**
+     * Must be a postal code for `countryCode`. Throws for a country rune has no
+     * pattern for, rather than accepting the value unchecked.
+     */
+    postalCode(options: {
+        countryCode: string | string[];
+    } | ((field: FieldContext) => {
+        countryCode: string | string[];
+    })): this;
+    /**
+     * Must be a valid VAT number (VineJS 4.2 `vat`). Accepts a country list or a
+     * callback resolving it per payload.
+     *
+     * Checksums are run where the country defines a short, well-defined one
+     * (BE, DE, NL, IT, PT, LU, CH); the others are FORMAT-only, which is stated
+     * rather than implied. An unknown country LEVES rather than accepting the
+     * value unchecked.
+     */
+    vat(options: VatOptions | ((field: FieldContext) => VatOptions)): this;
+    /** Must differ from a sibling field (VineJS `notSameAs`). */
+    notSameAs(otherField: string): this;
+    /** Array items must be unique — optionally compared on `field` (VineJS `distinct`). */
+    distinct(field?: string | string[]): this;
+    /** Must be less than or equal to zero (VineJS `nonPositive`). */
+    nonPositive(): this;
+    /** Array must hold at least one item (VineJS `notEmpty`). */
+    notEmpty(): this;
+    /** Drop `null`, `undefined` and `""` items before the item rules run. */
+    compact(): this;
+    /** Number must have no fractional part (VineJS `withoutDecimals`). */
+    withoutDecimals(): this;
+    /** Must be a passport number for `countryCode`. Throws for an uncovered country. */
+    passport(options: {
+        countryCode: string | string[];
+    }): this;
+    /** Lowercase the value (VineJS `toLowerCase`). */
+    toLowerCase(): this;
+    /** Uppercase the value (VineJS `toUpperCase`). */
+    toUpperCase(): this;
+    /**
+     * VineJS `toCamelCase()`, on both shapes it exists for:
+     *
+     * - on an `object()` chain it camelCases the object's KEYS
+     *   (`VineObject.toCamelCase`);
+     * - on any other chain it camelCases the string VALUE (`VineString`).
+     *
+     * One name, because Vine has one name. Dispatching on whether a nested shape
+     * was declared is what keeps a transcribed validator behaving the same.
+     */
+    toCamelCase(): this;
+    /** HTML-escape `& < > " '` (VineJS `escape`). */
+    escape(): this;
+    /** Normalise an email address (VineJS `normalizeEmail`). */
+    normalizeEmail(options?: NormalizeEmailOptions): this;
+    /** Normalise a URL (VineJS `normalizeUrl`). */
+    normalizeUrl(options?: NormalizeUrlOptions): this;
     /** Must contain only ASCII letters. */
-    alpha(): this;
+    alpha(options?: AlphaOptions): this;
     /** Must contain only ASCII letters and digits. */
-    alphaNumeric(): this;
+    alphaNumeric(options?: AlphaOptions): this;
     /** String must start with `substring`. */
     startsWith(substring: string): this;
     /** String must end with `substring`. */
     endsWith(substring: string): this;
-    /** Value must be one of `values`. */
-    in(values: ReadonlyArray<string | number | boolean>): this;
+    /**
+     * Value must be one of `values`.
+     *
+     * VineJS also accepts a callback so the list can be computed at validation
+     * time (tenant-scoped roles, values read from config…). A static array is
+     * snapshotted; a callback is invoked on every check.
+     */
+    in(values: AllowedValues): this;
     /** Value must NOT be one of `values`. */
-    notIn(values: ReadonlyArray<string | number | boolean>): this;
+    notIn(values: AllowedValues): this;
     /** Number must be positive (> 0) and finite. */
     positive(): this;
     /** Number must be negative (< 0) and finite. */
@@ -249,13 +940,14 @@ export declare class RuleChain<Output = unknown> {
     /** Number must be >= 0 and finite. */
     nonNegative(): this;
     /** Number must fall within `[min, max]` (inclusive). */
-    range(min: number, max: number): this;
+    range(bounds: [min: number, max: number]): this;
     /** Number must have at most `digits` decimal places (TS-only). */
-    decimal(digits: number): this;
+    decimal(digits: number | [number, number]): this;
     /** Must equal a sibling field (VineJS `sameAs`). Cross-field → TS-only. */
     sameAs(otherField: string): this;
     /** Must equal its `<field>_confirmation` sibling (VineJS `confirmed`). */
     confirmed(options?: {
+        as?: string;
         confirmationField?: string;
     }): this;
     /** Required only when `otherField` is present (non-null) — else optional. */
@@ -273,7 +965,7 @@ export declare class RuleChain<Output = unknown> {
      */
     transform<U>(fn: (value: unknown, field: FieldContext) => U): RuleChain<U>;
     /** Pre-validation transform of the raw input (VineJS `parse`). */
-    parse(fn: (value: unknown) => unknown): this;
+    parse(fn: (value: unknown, ctx: ParseContext) => unknown): this;
     /** Custom validation rule. */
     custom(name: string, validate: (value: unknown) => boolean, message?: string): this;
     /**
@@ -281,14 +973,72 @@ export declare class RuleChain<Output = unknown> {
      * 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: CompiledRule): this;
-    /** Set custom error message for the last rule. */
+    use(rule: CompiledRule | AsyncCompiledRule): this;
+    /**
+     * Attach an async rule (from {@link createAsyncRule}). The schema must then be
+     * run with `validateResultAsync` — sync `validate()` throws for such a schema.
+     */
+    useAsync(rule: AsyncCompiledRule): this;
+    /**
+     * DB-backed uniqueness rule (Adonis Lucid `unique`). `check(value, field)`
+     * resolves `true` when the value is unique (valid). rune stays agnostic — the
+     * check does the query (e.g. against atlas). Requires the async path (`validateResultAsync` / `validate`).
+     *
+     *     rules.string().email().unique(async (value) => {
+     *       const row = await db.from('users').where('email', value).first()
+     *       return !row
+     *     })
+     */
+    unique(check: (value: unknown, field: FieldContext) => boolean | Promise<boolean>, message?: string): this;
+    unique(options: DatabaseRuleOptions, message?: string): this;
+    /**
+     * DB-backed existence rule (Adonis Lucid `exists`). `check(value, field)`
+     * resolves `true` when a matching row exists (valid). Requires the async path (`validateResultAsync` / `validate`).
+     */
+    exists(check: (value: unknown, field: FieldContext) => boolean | Promise<boolean>, message?: string): this;
+    exists(options: DatabaseRuleOptions, message?: string): this;
+    /**
+     * Attach free-form JSON Schema metadata (VineJS `meta()`) — `title`,
+     * `description`, `examples`, `deprecated`… Merged verbatim into the field's
+     * node by `toJSONSchema()`.
+     */
+    meta(metadata: Record<string, unknown>): this;
+    /**
+     * Set a custom error message for the rule that was just added.
+     *
+     * "The last rule" spans all three registers: value rules (`#rules`),
+     * cross-field `.use()` rules (`sameAs`, `confirmed`, `afterField`,
+     * `notSameAs`) and async rules (`unique`, `exists`, `useAsync`). Targeting
+     * `#rules` alone silently retargeted the PREVIOUS value rule — or threw
+     * `NO_RULE` — whenever the preceding call was a cross-field or async rule.
+     */
     message(msg: string): this;
-    /** Internal: validate a field value and return errors + transformed value. */
-    _validateWithTransform(field: string, rawValue: unknown, ctx?: RunContext): {
+    /**
+     * Register a TYPE rule from outside the chain — used by the `optional()` and
+     * `null()` factories, which are types in their own right.
+     * @internal
+     */
+    pushTypeRule(rule: RuleDef): void;
+    /** Re-type this chain in place, without cloning. @internal */
+    retypeTo<U>(): RuleChain<U>;
+    /**
+     * Internal: validate a field value and return errors + transformed value.
+     *
+     * `pending` is the async-rule collector. The traversal itself stays sync (it
+     * is shared with `validate()`); when a collector is supplied, every chain in
+     * the tree that carries async rules and passed its sync rules records itself
+     * for the async path to await. Without it, nested async rules never ran.
+     */
+    _validateWithTransform(field: string, rawValue: unknown, ctx?: RunContext, pending?: PendingAsync[]): {
         errors: ValidationError[];
         transformed: unknown;
     };
+    /**
+     * Run this chain's async rules on the (already sync-validated) value, awaiting
+     * each in order. Returns the errors they reported. Used by `validateResultAsync`.
+     * @internal
+     */
+    _runAsyncRules(field: string, transformed: unknown, ctx: RunContext): Promise<ValidationError[]>;
     /** Internal: validate a field value against all rules. */
     _validate(field: string, value: unknown): ValidationError[];
     /** Internal: apply transforms. */
@@ -296,15 +1046,61 @@ export declare class RuleChain<Output = unknown> {
 }
 /** No-op alias of {@link schema} — VineJS `vine.compile()` API parity. */
 export declare function compile<T extends ValidationSchema>(s: T): T;
+export declare function compile(chain: RuleChain): ValidationSchema;
 /** Entry point for building rules. */
 export declare const rules: {
     string: () => RuleChain<string>;
-    number: () => RuleChain<number>;
-    boolean: () => RuleChain<boolean>;
+    number: (options?: {
+        strict?: boolean;
+    }) => RuleChain<number>;
+    boolean: (options?: {
+        strict?: boolean;
+    }) => RuleChain<boolean>;
     any: () => RuleChain<unknown>;
+    date: (options?: {
+        formats?: DateFormat[];
+    }) => RuleChain<Date>;
+    accepted: () => RuleChain<true>;
+    file: (options?: {
+        size?: number | string;
+        extnames?: readonly string[];
+        verifyContent?: boolean;
+    }) => RuleChain<FileLike>;
+    nativeFile: (options?: {
+        minSize?: number | string;
+        maxSize?: number | string;
+        mimeTypes?: readonly string[];
+    }) => RuleChain<FileLike>;
+    record: <Item extends RuleChain>(valueChain: Item) => RuleChain<Record<string, OutputOf<Item>>>;
+    tuple: <const Items extends readonly RuleChain[]>(items: Items) => RuleChain<{ [K in keyof Items]: OutputOf<Items[K]>; }>;
+    union: ((chains: readonly UnionBranch[]) => RuleChain) & {
+        if: typeof unionIf;
+        else: typeof unionElse;
+        otherwise: typeof unionElse;
+    };
+    /**
+     * Union discriminated by the value's TYPE (VineJS `unionOfTypes`): the first
+     * branch whose own type rule accepts the value wins.
+     */
+    /**
+     * Make every property of a shape optional (VineJS `vine.helpers.optional`).
+     * A properties TRANSFORMER, like `pick`/`omit` — it returns a record to
+     * spread, not a schema.
+     */
+    /**
+     * A field that must be ABSENT (VineJS `vine.optional()` → `VineOptional`,
+     * `builder.d.ts:135`). Mostly a `unionOfTypes` branch. Distinct from
+     * `.optional()` on a chain, which relaxes an existing type — this one IS the
+     * type. The properties transformer that used to squat this name moved to
+     * `helpers.optional`, where VineJS keeps it.
+     */
+    optional: () => RuleChain<undefined>;
+    /** A field that must be `null` (VineJS `vine.null()` → `VineNull`). */
+    null: () => RuleChain<null>;
+    unionOfTypes: (chains: readonly RuleChain[]) => RuleChain;
     object: <Sh extends Record<string, RuleChain>>(shape: Sh) => RuleChain<Infer<Sh>>;
     array: <Item extends RuleChain>(item?: Item) => RuleChain<OutputOf<Item>[]>;
-    enum: <const V extends readonly (string | number | boolean)[]>(values: V) => RuleChain<V[number]>;
+    enum: <const V extends readonly (string | number | boolean)[]>(values: V | ((field: FieldContext) => V)) => RuleChain<V[number]>;
     literal: <V extends string | number | boolean>(value: V) => RuleChain<V>;
 };
 export {};