better-call 0.0.0-experimental.06264e12

package/dist/schema.d.cts

@@ -0,0 +1,225 @@
+import { LiteralString, Prettify } from "./types.cjs";
+//#region src/schema.d.ts
+type Rules = {
+  /** Strings: length. Numbers: value. */
+  min?: number;
+  /** Strings: length. Numbers: value. */
+  max?: number;
+  /** Strings only: exact length. */
+  length?: number;
+  regex?: RegExp;
+  email?: boolean;
+  url?: boolean;
+  startsWith?: string;
+  endsWith?: string;
+  /** Numbers only. */
+  int?: boolean;
+  /** Allowed values. */
+  enum?: readonly unknown[];
+  /** Escape hatch - return true, or a message to fail with. */
+  check?: (value: any) => boolean | string;
+};
+interface TypeDefination<T, O, D = never> extends Rules {
+  name: LiteralString;
+  type?: T;
+  output?: O;
+  shape?: unknown;
+  /** `function` types only: the declared input of the expected fn -
+   * plain closures get it validated at their door on every call. */
+  fnInput?: unknown;
+  /** Used when the incoming value is `undefined`. */
+  default?: D;
+  /** When true, `undefined` passes straight through unvalidated. */
+  optional?: boolean;
+  transform?: (value: any) => O;
+}
+type TypeOptions<T, O> = {
+  transform?: (value: T) => O;
+};
+type WithDefault<D> = {
+  default?: D;
+};
+type WithOptional<Opt> = {
+  optional?: Opt;
+};
+/**
+ * `optional` widens the output; `default` keeps it narrow because a value
+ * is always produced. Declaring both means optional to send, never absent.
+ */
+type OutOf<O, D, Opt> = [Opt] extends [true] ? [D] extends [never] ? O | undefined : O : O;
+/** Either marker makes the key omittable in `InferArgs`. */
+type DefOf<D, Opt> = [Opt] extends [true] ? [D] extends [never] ? undefined : D : D;
+type StringOptions<E extends string, O> = TypeOptions<E, O> & Pick<Rules, "min" | "max" | "length" | "regex" | "email" | "url" | "startsWith" | "endsWith" | "check"> & {
+  enum?: readonly E[];
+};
+type ArrayOptions<E, O> = TypeOptions<FieldOut<E>[], O> & Pick<Rules, "min" | "max" | "length" | "check">;
+type NumberOptions<O> = TypeOptions<number, O> & Pick<Rules, "min" | "max" | "int" | "check"> & {
+  enum?: readonly number[];
+};
+type InferType<T> = T extends TypeDefination<infer T2, any, any> ? T2 : never;
+type InferOutput<T> = T extends TypeDefination<any, infer O, any> ? O : never;
+type DefineInput<I> = Prettify<{ [K in keyof I]: FieldIn<I[K]>; }>;
+/** Keys whose field is OPTIONAL with no default: absent from the output
+ * too, so they mark `?`. A defaulted field always produces a value and
+ * stays required. */
+type OutOptional<O> = { [K in keyof O]: [DefaultOf<O[K]>] extends [never] ? never : [DefaultOf<O[K]>] extends [undefined] ? K : never; }[keyof O];
+type DefineOutput<O> = Prettify<{ [K in keyof O as K extends OutOptional<O> ? never : K]: FieldOut<O[K]>; } & { [K in keyof O as K extends OutOptional<O> ? K : never]?: FieldOut<O[K]>; }>;
+/**
+ * A handler-less `v.fn({ input, output })` used as a schema describes
+ * "a fn from `input` to `output`" - the VALUE is the fn itself. Two
+ * views of the same signature:
+ *
+ * `SchemaFnIn` is the PROVIDER's side - what a caller must hand over.
+ * Like any handler, their fn receives the PARSED input (validation runs
+ * at its door) and returns the declared output, sync or async.
+ *
+ * `SchemaFnOut` is the CONSUMER's side (`c.input.x`) - the handler calls
+ * it with RAW args, exactly like calling the fn it stands in for.
+ *
+ * No declared input means the signature is UNSPECIFIED, not zero-arg -
+ * any fn fits (`create: v.fn`), so the args stay open.
+ */
+type SchemaFnIn<FI, FO> = (...args: unknown extends FI ? any[] : [input: InferInput<FI>]) => unknown extends FO ? any : InferInput<OutputSchemaOf<FO>> | Promise<InferInput<OutputSchemaOf<FO>>>;
+type SchemaFnOut<FI, FO> = (...args: unknown extends FI ? any[] : [input: InferArgs<FI>]) => unknown extends FO ? any : InferInput<OutputSchemaOf<FO>> | Promise<InferInput<OutputSchemaOf<FO>>>;
+/**
+ * A fn schema whose input IS a var carries that var's name as an optional
+ * phantom (`$fnVar`, tuple-wrapped so a plain fn can never false-match).
+ * Scope resolution reads it to WIDEN the fn's args with everything the
+ * scope mounts on that var - see `WidenSchemaFns`. Optional, so any plain
+ * closure still satisfies the type.
+ */
+type FnVarBrand<FI> = FI extends {
+  $var: true;
+  name: infer N extends string;
+} ? {
+  readonly $fnVar?: [N];
+} : unknown;
+/**
+ * A declared `output` comes in two forms: a bare schema (the signature
+ * AND the exit check), or the wrapper `{ def?, validation? }` splitting
+ * what the fn PROMISES from what gets CHECKED - `{ def }` documents
+ * without paying runtime validation, `{ def, validation }` checks with a
+ * different (usually looser) schema than it documents. The wrapper is
+ * recognized by its keys, so an output that IS an object with only
+ * `def`/`validation` fields must be written `v.object({...})`.
+ *
+ * `OutputSchemaOf` is the type-level unwrap - the schema the fn's return
+ * type (and its rendered signature) comes from.
+ */
+type OutputSchemaOf<O> = Exclude<keyof O, "def" | "validation"> extends never ? O extends {
+  def: infer D;
+} ? D : O extends {
+  validation: infer Vl;
+} ? Vl : O : O;
+/** The runtime unwrap: `def` is the documented schema (falls back to
+ * `validation`), `validation` is what the exit check runs - undefined
+ * means no check. A bare schema is both. */
+declare const outputContract: (output: unknown) => {
+  def?: unknown;
+  validation?: unknown;
+};
+/**
+ * One input field, in four flavours:
+ *  - a `v.var()`, whose shape comes from the var's own `schema`
+ *  - a handler-less `v.fn(...)` builder, which types the field as a FN
+ *  - a type from `v.string()` / `v.object()` / ...
+ *  - a bare nested record, which recurses
+ *
+ * The record case has to come last: a TypeDefination is itself a record,
+ * and so is a builder.
+ */
+type FieldOut<F> = F extends {
+  $var: true;
+  schema?: infer S;
+} ? InferInput<NonNullable<S>> : F extends {
+  $fnSchema: {
+    input?: infer FI;
+    output?: infer FO;
+  };
+} ? SchemaFnOut<FI, FO> & FnVarBrand<FI> : F extends TypeDefination<any, infer O, any> ? O : F extends Record<string, unknown> ? Prettify<{ [K in keyof F]: FieldOut<F[K]>; }> : never;
+type FieldIn<F> = F extends {
+  $var: true;
+  schema?: infer S;
+} ? InferArgs<NonNullable<S>> : F extends {
+  $fnSchema: {
+    input?: infer FI;
+    output?: infer FO;
+  };
+} ? SchemaFnIn<FI, FO> & FnVarBrand<FI> : F extends TypeDefination<infer T, any, any> ? T : F extends Record<string, unknown> ? ArgsShape<F> : never;
+/**
+ * A field's declared default, looked through a var to its schema. Only a
+ * TYPE's default counts - a var's own default is its initial value, not a
+ * licence to omit the input. The `$fnSchema` guard mirrors `asType`'s
+ * ordering: a bare `v.fn` is CALLABLE, and any callable duck-matches
+ * TypeDefination (`.name` comes with every function), which would read a
+ * phantom default off it and wrongly mark the field optional.
+ */
+type DefaultOf<F> = F extends {
+  $var: true;
+  schema?: infer S;
+} ? NonNullable<S> extends TypeDefination<any, any, infer D> ? D : never : F extends {
+  $fnSchema: unknown;
+} ? never : F extends TypeDefination<any, any, infer D> ? D : never;
+type Defaulted<I> = { [K in keyof I]: [DefaultOf<I[K]>] extends [never] ? never : K; }[keyof I];
+/** Defaulted keys are optional to send, but always present in the handler. */
+type ArgsShape<I> = Prettify<{ [K in keyof I as K extends Defaulted<I> ? never : K]: FieldIn<I[K]>; } & { [K in keyof I as K extends Defaulted<I> ? K : never]?: FieldIn<I[K]>; }>;
+/**
+ * Post-transform shape - what a handler sees. The `$var` branch must come
+ * first: a var's `name` property duck-matches TypeDefination, and falling
+ * into that branch reads the var's VALUE type instead of its schema. A
+ * TUPLE input maps position by position - the fn takes that many args.
+ */
+type InferInput<I> = I extends {
+  $var: true;
+  schema?: infer S;
+} ? InferInput<NonNullable<S>> : I extends {
+  $fnSchema: {
+    input?: infer FI;
+    output?: infer FO;
+  };
+} ? SchemaFnOut<FI, FO> & FnVarBrand<FI> : I extends readonly unknown[] ? { -readonly [K in keyof I]: InferInput<I[K]>; } : I extends TypeDefination<any, infer O, any> ? O : Prettify<{ [K in keyof I]: FieldOut<I[K]>; }>;
+/** Pre-transform shape - what a caller sends. Same branch order. */
+type InferArgs<I> = I extends {
+  $var: true;
+  schema?: infer S;
+} ? InferArgs<NonNullable<S>> : I extends {
+  $fnSchema: {
+    input?: infer FI;
+    output?: infer FO;
+  };
+} ? SchemaFnIn<FI, FO> & FnVarBrand<FI> : I extends readonly unknown[] ? { -readonly [K in keyof I]: InferArgs<I[K]>; } : I extends TypeDefination<infer T, any, any> ? T : ArgsShape<I>;
+declare const isType: (value: any) => value is TypeDefination<any, any>;
+/** A handler-less `v.fn(...)` builder doubles as a schema: the value it
+ * describes is a FN with the declared signature. The builder FN itself is
+ * branded too, so bare `v.fn` reads as "any function". */
+declare const isFnSchema: (value: any) => value is {
+  $fnSchema: {
+    input?: unknown;
+    output?: unknown;
+  };
+};
+declare const asType: (value: any) => TypeDefination<any, any>;
+declare const typeOf: (value: unknown) => "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function" | "null" | "array" | "NaN";
+declare const isVar: (value: any) => boolean;
+declare const validate: (def: TypeDefination<any, any, any>, value: unknown, path: string) => any;
+declare const vTypes: {
+  /** An `enum` narrows both sides to the literal union: `v.string({
+   * enum: ["a", "b"] })` types as `"a" | "b"`, not `string`. */
+  string: <const E extends string = string, O = E, D = never, Opt extends boolean = false>(options?: StringOptions<E, O> & WithDefault<D> & WithOptional<Opt>) => TypeDefination<E, OutOf<O, D, Opt>, DefOf<D, Opt>>;
+  number: <O = number, D = never, Opt extends boolean = false>(options?: NumberOptions<O> & WithDefault<D> & WithOptional<Opt>) => TypeDefination<number, OutOf<O, D, Opt>, DefOf<D, Opt>>;
+  boolean: <O = boolean, D = never, Opt extends boolean = false>(options?: TypeOptions<boolean, O> & WithDefault<D> & WithOptional<Opt>) => TypeDefination<boolean, OutOf<O, D, Opt>, DefOf<D, Opt>>;
+  /** A Date INSTANCE - checked with `instanceof`, never parsed. */
+  date: <O = Date, D = never, Opt extends boolean = false>(options?: TypeOptions<Date, O> & WithDefault<D> & WithOptional<Opt>) => TypeDefination<Date, OutOf<O, D, Opt>, DefOf<D, Opt>>;
+  /** Passthrough - validated as-is, never coerced or stripped. */
+  any: <T = unknown, D = never, Opt extends boolean = false>(options?: TypeOptions<T, T> & WithDefault<D> & WithOptional<Opt>) => TypeDefination<T, OutOf<T, D, Opt>, DefOf<D, Opt>>;
+  /** With a SHAPE every field validates; with NO shape (`v.object()`)
+   * any object passes, as-is. */
+  object: <S = undefined, O = { [K_1 in keyof S as K_1 extends OutOptional<S> ? never : K_1]: FieldOut<S[K_1]>; } & { [K_2 in keyof S as K_2 extends OutOptional<S> ? K_2 : never]?: FieldOut<S[K_2]> | undefined; } extends (infer T) ? { [K in keyof T]: T[K]; } : never, D = never, Opt extends boolean = false>(shape?: S, options?: TypeOptions<DefineOutput<S>, O> & WithDefault<D> & WithOptional<Opt>) => [S] extends [undefined] ? TypeDefination<Record<string, any>, Record<string, any>> : TypeDefination<ArgsShape<S>, OutOf<O, D, Opt>, DefOf<D, Opt>>;
+  /** With an ELEMENT every item validates - all failures report
+   * together, like object fields; with NO element (`v.array()`) any
+   * array passes, as-is. `min`/`max`/`length` count items. */
+  array: <E = undefined, O = FieldOut<E>[], D = never, Opt extends boolean = false>(element?: E, options?: ArrayOptions<E, O> & WithDefault<D> & WithOptional<Opt>) => [E] extends [undefined] ? TypeDefination<any[], OutOf<any[], D, Opt>, DefOf<D, Opt>> : TypeDefination<FieldIn<E>[], OutOf<O, D, Opt>, DefOf<D, Opt>>;
+};
+//#endregion
+export { DefineInput, DefineOutput, FnVarBrand, InferArgs, InferInput, InferOutput, InferType, OutputSchemaOf, Rules, TypeDefination, TypeOptions, asType, isFnSchema, isType, isVar, outputContract, typeOf, vTypes, validate };
+//# sourceMappingURL=schema.d.cts.map

package/dist/schema.d.mts

@@ -0,0 +1,225 @@
+import { LiteralString, Prettify } from "./types.mjs";
+//#region src/schema.d.ts
+type Rules = {
+  /** Strings: length. Numbers: value. */
+  min?: number;
+  /** Strings: length. Numbers: value. */
+  max?: number;
+  /** Strings only: exact length. */
+  length?: number;
+  regex?: RegExp;
+  email?: boolean;
+  url?: boolean;
+  startsWith?: string;
+  endsWith?: string;
+  /** Numbers only. */
+  int?: boolean;
+  /** Allowed values. */
+  enum?: readonly unknown[];
+  /** Escape hatch - return true, or a message to fail with. */
+  check?: (value: any) => boolean | string;
+};
+interface TypeDefination<T, O, D = never> extends Rules {
+  name: LiteralString;
+  type?: T;
+  output?: O;
+  shape?: unknown;
+  /** `function` types only: the declared input of the expected fn -
+   * plain closures get it validated at their door on every call. */
+  fnInput?: unknown;
+  /** Used when the incoming value is `undefined`. */
+  default?: D;
+  /** When true, `undefined` passes straight through unvalidated. */
+  optional?: boolean;
+  transform?: (value: any) => O;
+}
+type TypeOptions<T, O> = {
+  transform?: (value: T) => O;
+};
+type WithDefault<D> = {
+  default?: D;
+};
+type WithOptional<Opt> = {
+  optional?: Opt;
+};
+/**
+ * `optional` widens the output; `default` keeps it narrow because a value
+ * is always produced. Declaring both means optional to send, never absent.
+ */
+type OutOf<O, D, Opt> = [Opt] extends [true] ? [D] extends [never] ? O | undefined : O : O;
+/** Either marker makes the key omittable in `InferArgs`. */
+type DefOf<D, Opt> = [Opt] extends [true] ? [D] extends [never] ? undefined : D : D;
+type StringOptions<E extends string, O> = TypeOptions<E, O> & Pick<Rules, "min" | "max" | "length" | "regex" | "email" | "url" | "startsWith" | "endsWith" | "check"> & {
+  enum?: readonly E[];
+};
+type ArrayOptions<E, O> = TypeOptions<FieldOut<E>[], O> & Pick<Rules, "min" | "max" | "length" | "check">;
+type NumberOptions<O> = TypeOptions<number, O> & Pick<Rules, "min" | "max" | "int" | "check"> & {
+  enum?: readonly number[];
+};
+type InferType<T> = T extends TypeDefination<infer T2, any, any> ? T2 : never;
+type InferOutput<T> = T extends TypeDefination<any, infer O, any> ? O : never;
+type DefineInput<I> = Prettify<{ [K in keyof I]: FieldIn<I[K]>; }>;
+/** Keys whose field is OPTIONAL with no default: absent from the output
+ * too, so they mark `?`. A defaulted field always produces a value and
+ * stays required. */
+type OutOptional<O> = { [K in keyof O]: [DefaultOf<O[K]>] extends [never] ? never : [DefaultOf<O[K]>] extends [undefined] ? K : never; }[keyof O];
+type DefineOutput<O> = Prettify<{ [K in keyof O as K extends OutOptional<O> ? never : K]: FieldOut<O[K]>; } & { [K in keyof O as K extends OutOptional<O> ? K : never]?: FieldOut<O[K]>; }>;
+/**
+ * A handler-less `v.fn({ input, output })` used as a schema describes
+ * "a fn from `input` to `output`" - the VALUE is the fn itself. Two
+ * views of the same signature:
+ *
+ * `SchemaFnIn` is the PROVIDER's side - what a caller must hand over.
+ * Like any handler, their fn receives the PARSED input (validation runs
+ * at its door) and returns the declared output, sync or async.
+ *
+ * `SchemaFnOut` is the CONSUMER's side (`c.input.x`) - the handler calls
+ * it with RAW args, exactly like calling the fn it stands in for.
+ *
+ * No declared input means the signature is UNSPECIFIED, not zero-arg -
+ * any fn fits (`create: v.fn`), so the args stay open.
+ */
+type SchemaFnIn<FI, FO> = (...args: unknown extends FI ? any[] : [input: InferInput<FI>]) => unknown extends FO ? any : InferInput<OutputSchemaOf<FO>> | Promise<InferInput<OutputSchemaOf<FO>>>;
+type SchemaFnOut<FI, FO> = (...args: unknown extends FI ? any[] : [input: InferArgs<FI>]) => unknown extends FO ? any : InferInput<OutputSchemaOf<FO>> | Promise<InferInput<OutputSchemaOf<FO>>>;
+/**
+ * A fn schema whose input IS a var carries that var's name as an optional
+ * phantom (`$fnVar`, tuple-wrapped so a plain fn can never false-match).
+ * Scope resolution reads it to WIDEN the fn's args with everything the
+ * scope mounts on that var - see `WidenSchemaFns`. Optional, so any plain
+ * closure still satisfies the type.
+ */
+type FnVarBrand<FI> = FI extends {
+  $var: true;
+  name: infer N extends string;
+} ? {
+  readonly $fnVar?: [N];
+} : unknown;
+/**
+ * A declared `output` comes in two forms: a bare schema (the signature
+ * AND the exit check), or the wrapper `{ def?, validation? }` splitting
+ * what the fn PROMISES from what gets CHECKED - `{ def }` documents
+ * without paying runtime validation, `{ def, validation }` checks with a
+ * different (usually looser) schema than it documents. The wrapper is
+ * recognized by its keys, so an output that IS an object with only
+ * `def`/`validation` fields must be written `v.object({...})`.
+ *
+ * `OutputSchemaOf` is the type-level unwrap - the schema the fn's return
+ * type (and its rendered signature) comes from.
+ */
+type OutputSchemaOf<O> = Exclude<keyof O, "def" | "validation"> extends never ? O extends {
+  def: infer D;
+} ? D : O extends {
+  validation: infer Vl;
+} ? Vl : O : O;
+/** The runtime unwrap: `def` is the documented schema (falls back to
+ * `validation`), `validation` is what the exit check runs - undefined
+ * means no check. A bare schema is both. */
+declare const outputContract: (output: unknown) => {
+  def?: unknown;
+  validation?: unknown;
+};
+/**
+ * One input field, in four flavours:
+ *  - a `v.var()`, whose shape comes from the var's own `schema`
+ *  - a handler-less `v.fn(...)` builder, which types the field as a FN
+ *  - a type from `v.string()` / `v.object()` / ...
+ *  - a bare nested record, which recurses
+ *
+ * The record case has to come last: a TypeDefination is itself a record,
+ * and so is a builder.
+ */
+type FieldOut<F> = F extends {
+  $var: true;
+  schema?: infer S;
+} ? InferInput<NonNullable<S>> : F extends {
+  $fnSchema: {
+    input?: infer FI;
+    output?: infer FO;
+  };
+} ? SchemaFnOut<FI, FO> & FnVarBrand<FI> : F extends TypeDefination<any, infer O, any> ? O : F extends Record<string, unknown> ? Prettify<{ [K in keyof F]: FieldOut<F[K]>; }> : never;
+type FieldIn<F> = F extends {
+  $var: true;
+  schema?: infer S;
+} ? InferArgs<NonNullable<S>> : F extends {
+  $fnSchema: {
+    input?: infer FI;
+    output?: infer FO;
+  };
+} ? SchemaFnIn<FI, FO> & FnVarBrand<FI> : F extends TypeDefination<infer T, any, any> ? T : F extends Record<string, unknown> ? ArgsShape<F> : never;
+/**
+ * A field's declared default, looked through a var to its schema. Only a
+ * TYPE's default counts - a var's own default is its initial value, not a
+ * licence to omit the input. The `$fnSchema` guard mirrors `asType`'s
+ * ordering: a bare `v.fn` is CALLABLE, and any callable duck-matches
+ * TypeDefination (`.name` comes with every function), which would read a
+ * phantom default off it and wrongly mark the field optional.
+ */
+type DefaultOf<F> = F extends {
+  $var: true;
+  schema?: infer S;
+} ? NonNullable<S> extends TypeDefination<any, any, infer D> ? D : never : F extends {
+  $fnSchema: unknown;
+} ? never : F extends TypeDefination<any, any, infer D> ? D : never;
+type Defaulted<I> = { [K in keyof I]: [DefaultOf<I[K]>] extends [never] ? never : K; }[keyof I];
+/** Defaulted keys are optional to send, but always present in the handler. */
+type ArgsShape<I> = Prettify<{ [K in keyof I as K extends Defaulted<I> ? never : K]: FieldIn<I[K]>; } & { [K in keyof I as K extends Defaulted<I> ? K : never]?: FieldIn<I[K]>; }>;
+/**
+ * Post-transform shape - what a handler sees. The `$var` branch must come
+ * first: a var's `name` property duck-matches TypeDefination, and falling
+ * into that branch reads the var's VALUE type instead of its schema. A
+ * TUPLE input maps position by position - the fn takes that many args.
+ */
+type InferInput<I> = I extends {
+  $var: true;
+  schema?: infer S;
+} ? InferInput<NonNullable<S>> : I extends {
+  $fnSchema: {
+    input?: infer FI;
+    output?: infer FO;
+  };
+} ? SchemaFnOut<FI, FO> & FnVarBrand<FI> : I extends readonly unknown[] ? { -readonly [K in keyof I]: InferInput<I[K]>; } : I extends TypeDefination<any, infer O, any> ? O : Prettify<{ [K in keyof I]: FieldOut<I[K]>; }>;
+/** Pre-transform shape - what a caller sends. Same branch order. */
+type InferArgs<I> = I extends {
+  $var: true;
+  schema?: infer S;
+} ? InferArgs<NonNullable<S>> : I extends {
+  $fnSchema: {
+    input?: infer FI;
+    output?: infer FO;
+  };
+} ? SchemaFnIn<FI, FO> & FnVarBrand<FI> : I extends readonly unknown[] ? { -readonly [K in keyof I]: InferArgs<I[K]>; } : I extends TypeDefination<infer T, any, any> ? T : ArgsShape<I>;
+declare const isType: (value: any) => value is TypeDefination<any, any>;
+/** A handler-less `v.fn(...)` builder doubles as a schema: the value it
+ * describes is a FN with the declared signature. The builder FN itself is
+ * branded too, so bare `v.fn` reads as "any function". */
+declare const isFnSchema: (value: any) => value is {
+  $fnSchema: {
+    input?: unknown;
+    output?: unknown;
+  };
+};
+declare const asType: (value: any) => TypeDefination<any, any>;
+declare const typeOf: (value: unknown) => "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function" | "null" | "array" | "NaN";
+declare const isVar: (value: any) => boolean;
+declare const validate: (def: TypeDefination<any, any, any>, value: unknown, path: string) => any;
+declare const vTypes: {
+  /** An `enum` narrows both sides to the literal union: `v.string({
+   * enum: ["a", "b"] })` types as `"a" | "b"`, not `string`. */
+  string: <const E extends string = string, O = E, D = never, Opt extends boolean = false>(options?: StringOptions<E, O> & WithDefault<D> & WithOptional<Opt>) => TypeDefination<E, OutOf<O, D, Opt>, DefOf<D, Opt>>;
+  number: <O = number, D = never, Opt extends boolean = false>(options?: NumberOptions<O> & WithDefault<D> & WithOptional<Opt>) => TypeDefination<number, OutOf<O, D, Opt>, DefOf<D, Opt>>;
+  boolean: <O = boolean, D = never, Opt extends boolean = false>(options?: TypeOptions<boolean, O> & WithDefault<D> & WithOptional<Opt>) => TypeDefination<boolean, OutOf<O, D, Opt>, DefOf<D, Opt>>;
+  /** A Date INSTANCE - checked with `instanceof`, never parsed. */
+  date: <O = Date, D = never, Opt extends boolean = false>(options?: TypeOptions<Date, O> & WithDefault<D> & WithOptional<Opt>) => TypeDefination<Date, OutOf<O, D, Opt>, DefOf<D, Opt>>;
+  /** Passthrough - validated as-is, never coerced or stripped. */
+  any: <T = unknown, D = never, Opt extends boolean = false>(options?: TypeOptions<T, T> & WithDefault<D> & WithOptional<Opt>) => TypeDefination<T, OutOf<T, D, Opt>, DefOf<D, Opt>>;
+  /** With a SHAPE every field validates; with NO shape (`v.object()`)
+   * any object passes, as-is. */
+  object: <S = undefined, O = { [K_1 in keyof S as K_1 extends OutOptional<S> ? never : K_1]: FieldOut<S[K_1]>; } & { [K_2 in keyof S as K_2 extends OutOptional<S> ? K_2 : never]?: FieldOut<S[K_2]> | undefined; } extends (infer T) ? { [K in keyof T]: T[K]; } : never, D = never, Opt extends boolean = false>(shape?: S, options?: TypeOptions<DefineOutput<S>, O> & WithDefault<D> & WithOptional<Opt>) => [S] extends [undefined] ? TypeDefination<Record<string, any>, Record<string, any>> : TypeDefination<ArgsShape<S>, OutOf<O, D, Opt>, DefOf<D, Opt>>;
+  /** With an ELEMENT every item validates - all failures report
+   * together, like object fields; with NO element (`v.array()`) any
+   * array passes, as-is. `min`/`max`/`length` count items. */
+  array: <E = undefined, O = FieldOut<E>[], D = never, Opt extends boolean = false>(element?: E, options?: ArrayOptions<E, O> & WithDefault<D> & WithOptional<Opt>) => [E] extends [undefined] ? TypeDefination<any[], OutOf<any[], D, Opt>, DefOf<D, Opt>> : TypeDefination<FieldIn<E>[], OutOf<O, D, Opt>, DefOf<D, Opt>>;
+};
+//#endregion
+export { DefineInput, DefineOutput, FnVarBrand, InferArgs, InferInput, InferOutput, InferType, OutputSchemaOf, Rules, TypeDefination, TypeOptions, asType, isFnSchema, isType, isVar, outputContract, typeOf, vTypes, validate };
+//# sourceMappingURL=schema.d.mts.map

package/dist/schema.mjs

@@ -0,0 +1,159 @@
+import { ValidationError } from "./error.mjs";
+//#region src/schema.ts
+/** The runtime unwrap: `def` is the documented schema (falls back to
+* `validation`), `validation` is what the exit check runs - undefined
+* means no check. A bare schema is both. */
+const outputContract = (output) => {
+	if (output === void 0) return {};
+	if (output !== null && typeof output === "object" && !Array.isArray(output) && !isType(output) && !isVar(output) && !isFnSchema(output)) {
+		const keys = Object.keys(output);
+		if (keys.length > 0 && keys.every((k) => k === "def" || k === "validation")) {
+			const { def, validation } = output;
+			return {
+				def: def ?? validation,
+				validation
+			};
+		}
+	}
+	return {
+		def: output,
+		validation: output
+	};
+};
+const isType = (value) => typeof value?.name === "string";
+/** A handler-less `v.fn(...)` builder doubles as a schema: the value it
+* describes is a FN with the declared signature. The builder FN itself is
+* branded too, so bare `v.fn` reads as "any function". */
+const isFnSchema = (value) => typeof value?.$fnSchema === "object" && value.$fnSchema !== null;
+const asType = (value) => isVar(value) ? asType(value.schema ?? {}) : isFnSchema(value) ? {
+	name: "function",
+	fnInput: value.$fnSchema.input
+} : isType(value) ? value : {
+	name: "object",
+	shape: value
+};
+const typeOf = (value) => value === null ? "null" : Array.isArray(value) ? "array" : Number.isNaN(value) ? "NaN" : typeof value;
+const isVar = (value) => value?.$var === true;
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const fail = (path, message) => {
+	throw new ValidationError(path, message);
+};
+/** Constraint checks, run after the value's type is known to be right. */
+const applyRules = (def, value, path) => {
+	if (def.enum && !def.enum.includes(value)) fail(path, `expected one of ${def.enum.join(", ")}, received ${value}`);
+	if (typeof value === "string") {
+		if (def.length !== void 0 && value.length !== def.length) fail(path, `expected length ${def.length}, received ${value.length}`);
+		if (def.min !== void 0 && value.length < def.min) fail(path, `expected at least ${def.min} characters, received ${value.length}`);
+		if (def.max !== void 0 && value.length > def.max) fail(path, `expected at most ${def.max} characters, received ${value.length}`);
+		if (def.regex && !def.regex.test(value)) fail(path, `does not match ${def.regex}`);
+		if (def.email && !EMAIL.test(value)) fail(path, "expected an email address");
+		if (def.url) try {
+			new URL(value);
+		} catch {
+			fail(path, "expected a URL");
+		}
+		if (def.startsWith !== void 0 && !value.startsWith(def.startsWith)) fail(path, `expected to start with "${def.startsWith}"`);
+		if (def.endsWith !== void 0 && !value.endsWith(def.endsWith)) fail(path, `expected to end with "${def.endsWith}"`);
+	}
+	if (Array.isArray(value)) {
+		if (def.length !== void 0 && value.length !== def.length) fail(path, `expected length ${def.length}, received ${value.length}`);
+		if (def.min !== void 0 && value.length < def.min) fail(path, `expected at least ${def.min} items, received ${value.length}`);
+		if (def.max !== void 0 && value.length > def.max) fail(path, `expected at most ${def.max} items, received ${value.length}`);
+	}
+	if (typeof value === "number") {
+		if (def.int && !Number.isInteger(value)) fail(path, `expected an integer, received ${value}`);
+		if (def.min !== void 0 && value < def.min) fail(path, `expected >= ${def.min}, received ${value}`);
+		if (def.max !== void 0 && value > def.max) fail(path, `expected <= ${def.max}, received ${value}`);
+	}
+	if (def.check) {
+		const result = def.check(value);
+		if (result !== true) fail(path, typeof result === "string" ? result : "failed check");
+	}
+};
+const validate = (def, value, path) => {
+	if (value === void 0) {
+		if (def.default !== void 0) value = def.default;
+		else if (def.optional) return void 0;
+	}
+	if (isVar(def)) {
+		if (value === void 0) return void 0;
+		const schema = def.schema;
+		return schema === void 0 ? value : validate(schema, value, path);
+	}
+	if (def.name === "any") return def.transform ? def.transform(value) : value;
+	if (def.name === "date") {
+		if (!(value instanceof Date)) throw new ValidationError(path, `expected date, received ${typeOf(value)}`);
+		return def.transform ? def.transform(value) : value;
+	}
+	if (def.name === "function") {
+		if (typeof value !== "function") throw new ValidationError(path, `expected function, received ${typeOf(value)}`);
+		const inner = def.fnInput;
+		if (inner === void 0 || value.$fn === true) return value;
+		const innerType = asType(inner);
+		return (input, parent) => value(validate(innerType, input, `${path}()`), parent);
+	}
+	if (def.name === "array") {
+		if (!Array.isArray(value)) throw new ValidationError(path, `expected array, received ${typeOf(value)}`);
+		applyRules(def, value, path);
+		if (def.shape === void 0) return def.transform ? def.transform(value) : value;
+		const elementType = asType(def.shape);
+		const items = [];
+		const problems = [];
+		for (let index = 0; index < value.length; index++) try {
+			items.push(validate(elementType, value[index], `${path}[${index}]`));
+		} catch (thrown) {
+			if (!(thrown instanceof ValidationError)) throw thrown;
+			problems.push(...thrown.issues);
+		}
+		const firstProblem = problems[0];
+		if (firstProblem) throw new ValidationError(firstProblem.path, firstProblem.message, problems);
+		return def.transform ? def.transform(items) : items;
+	}
+	if (def.name === "object") {
+		if (typeOf(value) !== "object") throw new ValidationError(path, `expected object, received ${typeOf(value)}`);
+		if (def.shape === void 0) return def.transform ? def.transform(value) : value;
+		const parsed = {};
+		const issues = [];
+		for (const [field, child] of Object.entries(def.shape)) try {
+			const parsedField = validate(asType(child), value[field], `${path}.${field}`);
+			if (parsedField !== void 0) parsed[field] = parsedField;
+		} catch (thrown) {
+			if (!(thrown instanceof ValidationError)) throw thrown;
+			issues.push(...thrown.issues);
+		}
+		const firstIssue = issues[0];
+		if (firstIssue) throw new ValidationError(firstIssue.path, firstIssue.message, issues);
+		return def.transform ? def.transform(parsed) : parsed;
+	}
+	if (typeOf(value) !== def.name) throw new ValidationError(path, `expected ${def.name}, received ${typeOf(value)}`);
+	applyRules(def, value, path);
+	return def.transform ? def.transform(value) : value;
+};
+/** Builds the runtime object; the declared return type is the contract. */
+const build = (name, options, extra) => ({
+	name,
+	...extra,
+	...options
+});
+const vTypes = {
+	/** An `enum` narrows both sides to the literal union: `v.string({
+	* enum: ["a", "b"] })` types as `"a" | "b"`, not `string`. */
+	string: (options) => build("string", options),
+	number: (options) => build("number", options),
+	boolean: (options) => build("boolean", options),
+	/** A Date INSTANCE - checked with `instanceof`, never parsed. */
+	date: (options) => build("date", options),
+	/** Passthrough - validated as-is, never coerced or stripped. */
+	any: (options) => build("any", options),
+	/** With a SHAPE every field validates; with NO shape (`v.object()`)
+	* any object passes, as-is. */
+	object: (shape, options) => build("object", options, shape === void 0 ? {} : { shape }),
+	/** With an ELEMENT every item validates - all failures report
+	* together, like object fields; with NO element (`v.array()`) any
+	* array passes, as-is. `min`/`max`/`length` count items. */
+	array: (element, options) => build("array", options, element === void 0 ? {} : { shape: element })
+};
+//#endregion
+export { asType, isFnSchema, isType, isVar, outputContract, typeOf, vTypes, validate };
+
+//# sourceMappingURL=schema.mjs.map