better-call 0.0.0-experimental.01ff4b77

package/dist/schema.d.cts

@@ -0,0 +1,411 @@
+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;
+  /** Strings only. Trims and lowercases before the format check. */
+  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;
+};
+/** Plugin-owned field metadata. Outer key is the plugin namespace
+ * (`"http"`, `"db"`, …); core never interprets the contents. */
+type AttrBag = Record<string, Record<string, unknown>>;
+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`. A zero-arg function
+   * is called (fresh value per validate) except on `function` schemas,
+   * where the default IS the fn. */
+  default?: D | (() => D);
+  /** When true, `undefined` and `null` pass straight through unvalidated. */
+  optional?: boolean;
+  transform?: (value: any) => O;
+  /** Opaque plugin attributes - ignored by validate / Infer*. */
+  $attrs?: AttrBag;
+}
+type TypeOptions<T, O> = {
+  transform?: (value: T) => O;
+  /** Accepted on every helper; overloads refine the output when `true`. */
+  optional?: boolean;
+};
+/**
+ * `optional` widens the output with `| undefined | null`; `default` keeps
+ * it narrow because a value is always produced. Declaring both means
+ * optional to send, never absent.
+ *
+ * Helpers select among these via option-shape overloads rather than `Opt` /
+ * `D` type parameters: providing a partial type argument (e.g.
+ * `v.string<"a" | "b">`) would lock remaining params to their defaults, so
+ * `{ optional: true }` would fail to type-check.
+ */
+type OutOf<O, D, Opt> = [Opt] extends [true] ? [D] extends [never] ? O | undefined | null : O : O;
+/**
+ * Recover a type's output `O`. Plain `infer O` from
+ * `TypeDefination<any, infer O, …>` drops `| undefined` because `output?`
+ * is optional and TypeScript attributes the undefined to the property.
+ * When the third type arg is `undefined` (optional, no default), put
+ * `| undefined | null` back so handlers see the same absence validate
+ * produces at runtime.
+ */
+type OutputOf<F> = F extends TypeDefination<any, infer O, infer D> ? [D] extends [never] ? O : undefined extends D ? O | undefined | null : O : never;
+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 UnionOptions<T extends readonly unknown[], O> = TypeOptions<FieldOut<T[number]>, O> & Pick<Rules, "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, any, any> ? OutputOf<T> : 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 five 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
+ *  - anything else (e.g. `null`, `"lit"`) kept as itself - so
+ *    `v.union([user, null])` infers `User | null`, not just `User`
+ *
+ * The record case has to come after TypeDefination: 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;
+  };
+} ? FnSchemaOut<F, SchemaFnOut<FI, FO> & FnVarBrand<FI>> : F extends TypeDefination<any, any, any> ? OutputOf<F> : F extends Record<string, unknown> ? Prettify<{ [K in keyof F]: FieldOut<F[K]>; }> : F;
+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, infer D> ? undefined extends D ? T | null : T : F extends Record<string, unknown> ? ArgsShape<F> : F;
+/**
+ * `optional: true` on `v.fn.type` widens the same way a type's `optional`
+ * does: absent without a default means the value may be `undefined` or
+ * `null`.
+ */
+type FnSchemaOut<F, Fn> = F extends {
+  optional: true;
+} ? F extends {
+  default: infer _D;
+} ? Fn : Fn | undefined | null : Fn;
+/**
+ * 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. `v.fn.type`
+ * may still declare `optional` / `default` on the carrier itself.
+ */
+type DefaultOf<F> = F extends {
+  $var: true;
+  schema?: infer S;
+} ? NonNullable<S> extends TypeDefination<any, any, infer D> ? D : never : F extends {
+  $fnSchema: unknown;
+} ? F extends {
+  optional: true;
+} ? F extends {
+  default: infer D;
+} ? D : undefined : F extends {
+  default: infer D;
+} ? D : 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, any, any> ? OutputOf<I> : 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, infer D> ? undefined extends D ? T | null : 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;
+  };
+  optional?: boolean;
+  default?: unknown;
+};
+declare const asType: (value: any) => TypeDefination<any, any>;
+/**
+ * Attach plugin attributes under `namespace`, deep-merging with any
+ * already on the schema. Returns a new type def (or var) with the same
+ * value type. Core never reads these - only plugin edges do.
+ *
+ * Passed a var, attributes land on the var itself (`$attrs`) and the
+ * `$var` / `name` / `schema` identity is preserved; `customize` is rebound
+ * so attrs survive further customization.
+ */
+declare const withAttrs: <S>(schema: S, namespace: string, attrs: Record<string, unknown>) => S;
+/** Read the whole attr bag, or one plugin namespace. */
+declare function attrsOf(schema: unknown): AttrBag | undefined;
+declare function attrsOf(schema: unknown, namespace: string): Record<string, unknown> | undefined;
+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;
+/** A default may be the value itself or a factory that mints it fresh on
+ * each validate - `() => new Date()`, `() => []`, …. */
+type DefaultInput<T> = T | (() => T);
+/**
+ * Call signatures for the type helpers. Option-shape overloads replace
+ * `Opt` / `D` type parameters so a partial type argument (literal narrowing)
+ * does not lock `optional` / `default` to their defaults.
+ */
+type StringFn = {
+  <const E extends string, O = E>(options: StringOptions<E, O> & {
+    optional: true;
+    default: DefaultInput<string>;
+  }): TypeDefination<E, O, string>;
+  <const E extends string, O = E>(options: StringOptions<E, O> & {
+    optional: true;
+  }): TypeDefination<E, OutOf<O, never, true>, undefined>;
+  <const E extends string, O = E>(options: StringOptions<E, O> & {
+    default: DefaultInput<string>;
+  }): TypeDefination<E, O, string>;
+  <const E extends string, O = E>(options?: StringOptions<E, O>): TypeDefination<E, O, never>;
+};
+type NumberFn = {
+  <O = number>(options: NumberOptions<O> & {
+    optional: true;
+    default: DefaultInput<number>;
+  }): TypeDefination<number, O, number>;
+  <O = number>(options: NumberOptions<O> & {
+    optional: true;
+  }): TypeDefination<number, OutOf<O, never, true>, undefined>;
+  <O = number>(options: NumberOptions<O> & {
+    default: DefaultInput<number>;
+  }): TypeDefination<number, O, number>;
+  <O = number>(options?: NumberOptions<O>): TypeDefination<number, O, never>;
+};
+type BooleanFn = {
+  <O = boolean>(options: TypeOptions<boolean, O> & {
+    optional: true;
+    default: DefaultInput<boolean>;
+  }): TypeDefination<boolean, O, boolean>;
+  <O = boolean>(options: TypeOptions<boolean, O> & {
+    optional: true;
+  }): TypeDefination<boolean, OutOf<O, never, true>, undefined>;
+  <O = boolean>(options: TypeOptions<boolean, O> & {
+    default: DefaultInput<boolean>;
+  }): TypeDefination<boolean, O, boolean>;
+  <O = boolean>(options?: TypeOptions<boolean, O>): TypeDefination<boolean, O, never>;
+};
+type DateFn = {
+  <O = Date>(options: TypeOptions<Date, O> & {
+    optional: true;
+    default: DefaultInput<Date>;
+  }): TypeDefination<Date, O, Date>;
+  <O = Date>(options: TypeOptions<Date, O> & {
+    optional: true;
+  }): TypeDefination<Date, OutOf<O, never, true>, undefined>;
+  <O = Date>(options: TypeOptions<Date, O> & {
+    default: DefaultInput<Date>;
+  }): TypeDefination<Date, O, Date>;
+  <O = Date>(options?: TypeOptions<Date, O>): TypeDefination<Date, O, never>;
+};
+type AnyFn = {
+  <T = unknown>(options: TypeOptions<T, T> & {
+    optional: true;
+    default: DefaultInput<T>;
+  }): TypeDefination<T, T, T>;
+  <T = unknown>(options: TypeOptions<T, T> & {
+    optional: true;
+  }): TypeDefination<T, OutOf<T, never, true>, undefined>;
+  <T = unknown>(options: TypeOptions<T, T> & {
+    default: DefaultInput<T>;
+  }): TypeDefination<T, T, T>;
+  <T = unknown>(options?: TypeOptions<T, T>): TypeDefination<T, T, never>;
+};
+/**
+ * Object defaults may be partial: nested fields still run through
+ * validate (so their own defaults apply). An empty `{}` is always
+ * fine at the type level - parent `optional` / `default` must not
+ * demand that every required child be listed in the default.
+ */
+type ObjectDefault<S> = DefaultInput<Partial<ArgsShape<S>>>;
+type ObjectFn = {
+  <S, O = DefineOutput<S>>(shape: S, options: TypeOptions<DefineOutput<S>, O> & {
+    optional: true;
+    default: ObjectDefault<S>;
+  }): TypeDefination<ArgsShape<S>, O, ArgsShape<S>>;
+  <S, O = DefineOutput<S>>(shape: S, options: TypeOptions<DefineOutput<S>, O> & {
+    optional: true;
+  }): TypeDefination<ArgsShape<S>, OutOf<O, never, true>, undefined>;
+  <S, O = DefineOutput<S>>(shape: S, options: TypeOptions<DefineOutput<S>, O> & {
+    default: ObjectDefault<S>;
+  }): TypeDefination<ArgsShape<S>, O, ArgsShape<S>>;
+  <S, O = DefineOutput<S>>(shape: S, options?: TypeOptions<DefineOutput<S>, O>): TypeDefination<ArgsShape<S>, O, never>;
+  (): TypeDefination<Record<string, any>, Record<string, any>>;
+};
+type ArrayFn = {
+  <E, O = FieldOut<E>[]>(element: E, options: ArrayOptions<E, O> & {
+    optional: true;
+    default: DefaultInput<FieldIn<E>[]>;
+  }): TypeDefination<FieldIn<E>[], O, FieldIn<E>[]>;
+  <E, O = FieldOut<E>[]>(element: E, options: ArrayOptions<E, O> & {
+    optional: true;
+  }): TypeDefination<FieldIn<E>[], OutOf<O, never, true>, undefined>;
+  <E, O = FieldOut<E>[]>(element: E, options: ArrayOptions<E, O> & {
+    default: DefaultInput<FieldIn<E>[]>;
+  }): TypeDefination<FieldIn<E>[], O, FieldIn<E>[]>;
+  <E, O = FieldOut<E>[]>(element: E, options?: ArrayOptions<E, O>): TypeDefination<FieldIn<E>[], O, never>;
+  (element?: undefined, options?: ArrayOptions<undefined, any[]> & {
+    optional: true;
+    default: DefaultInput<any[]>;
+  }): TypeDefination<any[], any[], any[]>;
+  (element?: undefined, options?: ArrayOptions<undefined, any[]> & {
+    optional: true;
+  }): TypeDefination<any[], any[] | undefined | null, undefined>;
+  (element?: undefined, options?: ArrayOptions<undefined, any[]> & {
+    default: DefaultInput<any[]>;
+  }): TypeDefination<any[], any[], any[]>;
+  (element?: undefined, options?: ArrayOptions<undefined, any[]>): TypeDefination<any[], any[], never>;
+};
+type UnionFn = {
+  <const T extends readonly [unknown, ...unknown[]], O = FieldOut<T[number]>>(members: T, options: UnionOptions<T, O> & {
+    optional: true;
+    default: DefaultInput<FieldIn<T[number]>>;
+  }): TypeDefination<FieldIn<T[number]>, O, FieldIn<T[number]>>;
+  <const T extends readonly [unknown, ...unknown[]], O = FieldOut<T[number]>>(members: T, options: UnionOptions<T, O> & {
+    optional: true;
+  }): TypeDefination<FieldIn<T[number]>, OutOf<O, never, true>, undefined>;
+  <const T extends readonly [unknown, ...unknown[]], O = FieldOut<T[number]>>(members: T, options: UnionOptions<T, O> & {
+    default: DefaultInput<FieldIn<T[number]>>;
+  }): TypeDefination<FieldIn<T[number]>, O, FieldIn<T[number]>>;
+  <const T extends readonly [unknown, ...unknown[]], O = FieldOut<T[number]>>(members: T, options?: UnionOptions<T, O>): TypeDefination<FieldIn<T[number]>, O, never>;
+};
+declare const vTypes: {
+  /** An `enum` narrows both sides to the literal union: `v.string({
+   * enum: ["a", "b"] })` types as `"a" | "b"`, not `string`. */
+  string: StringFn;
+  number: NumberFn;
+  boolean: BooleanFn;
+  /** A Date INSTANCE - checked with `instanceof`, never parsed. */
+  date: DateFn;
+  /** Passthrough - validated as-is, never coerced or stripped. */
+  any: AnyFn;
+  /** With a SHAPE every field validates; with NO shape (`v.object()`)
+   * any object passes, as-is. */
+  object: ObjectFn;
+  /** 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: ArrayFn;
+  /** Try each option in order - first successful parse wins. All
+   * failing branches report together when none match. */
+  union: UnionFn;
+};
+//#endregion
+export { AttrBag, DefineInput, DefineOutput, FnVarBrand, InferArgs, InferInput, InferOutput, InferType, OutputSchemaOf, Rules, TypeDefination, TypeOptions, asType, attrsOf, isFnSchema, isType, isVar, outputContract, typeOf, vTypes, validate, withAttrs };
+//# sourceMappingURL=schema.d.cts.map