@pylonsync/functions 0.3.331 → 0.3.332

package/dist/define.d.ts

@@ -20,9 +20,9 @@
  * forgetting an auth check — when `auth: "user"` is in effect,
  * an anonymous request never reaches the handler at all.
  */
-import type { FnDefinition, QueryCtx, MutationCtx, ActionCtx, Validator } from "./types";
-interface CommonDef {
-    args?: Record<string, Validator>;
+import type { FnDefinition, QueryCtx, MutationCtx, ActionCtx, ValidatorSchema, InferArgs } from "./types";
+interface CommonDef<TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined> {
+    args?: TSchema;
     /**
      * When true, the function is callable only via `ctx.runQuery()` /
      * `ctx.runMutation()` / `ctx.runAction()` from another function
@@ -56,28 +56,28 @@ interface CommonDef {
      */
     timeout?: number;
 }
-interface QueryDefRequired<TArgs, TReturn> extends CommonDef {
+interface QueryDefRequired<TArgs, TReturn, TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined> extends CommonDef<TSchema> {
     /** Defaults to `"user"`. See [`AuthMode`] for the full surface. */
     auth?: "user" | "admin";
     handler: (ctx: QueryCtx<"required">, args: TArgs) => Promise<TReturn>;
 }
-interface QueryDefOptional<TArgs, TReturn> extends CommonDef {
+interface QueryDefOptional<TArgs, TReturn, TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined> extends CommonDef<TSchema> {
     auth: "public" | "guest";
     handler: (ctx: QueryCtx<"optional">, args: TArgs) => Promise<TReturn>;
 }
-interface MutationDefRequired<TArgs, TReturn> extends CommonDef {
+interface MutationDefRequired<TArgs, TReturn, TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined> extends CommonDef<TSchema> {
     auth?: "user" | "admin";
     handler: (ctx: MutationCtx<"required">, args: TArgs) => Promise<TReturn>;
 }
-interface MutationDefOptional<TArgs, TReturn> extends CommonDef {
+interface MutationDefOptional<TArgs, TReturn, TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined> extends CommonDef<TSchema> {
     auth: "public" | "guest";
     handler: (ctx: MutationCtx<"optional">, args: TArgs) => Promise<TReturn>;
 }
-interface ActionDefRequired<TArgs, TReturn> extends CommonDef {
+interface ActionDefRequired<TArgs, TReturn, TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined> extends CommonDef<TSchema> {
     auth?: "user" | "admin";
     handler: (ctx: ActionCtx<"required">, args: TArgs) => Promise<TReturn>;
 }
-interface ActionDefOptional<TArgs, TReturn> extends CommonDef {
+interface ActionDefOptional<TArgs, TReturn, TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined> extends CommonDef<TSchema> {
     auth: "public" | "guest";
     handler: (ctx: ActionCtx<"optional">, args: TArgs) => Promise<TReturn>;
 }
@@ -113,6 +113,14 @@ interface ActionDefOptional<TArgs, TReturn> extends CommonDef {
  * });
  * ```
  */
+export declare function query<const TSchema extends ValidatorSchema, TReturn, TAuth extends "user" | "admin" | undefined>(def: QueryDefRequired<InferArgs<TSchema>, TReturn, TSchema> & {
+    args: TSchema;
+    auth?: TAuth;
+}): FnDefinition<InferArgs<TSchema>, TReturn>;
+export declare function query<const TSchema extends ValidatorSchema, TReturn, TAuth extends "public" | "guest">(def: QueryDefOptional<InferArgs<TSchema>, TReturn, TSchema> & {
+    args: TSchema;
+    auth: TAuth;
+}): FnDefinition<InferArgs<TSchema>, TReturn>;
 export declare function query<TArgs = Record<string, unknown>, TReturn = unknown>(def: QueryDefRequired<TArgs, TReturn>): FnDefinition<TArgs, TReturn>;
 export declare function query<TArgs = Record<string, unknown>, TReturn = unknown>(def: QueryDefOptional<TArgs, TReturn>): FnDefinition<TArgs, TReturn>;
 /**
@@ -144,6 +152,14 @@ export declare function query<TArgs = Record<string, unknown>, TReturn = unknown
  * });
  * ```
  */
+export declare function mutation<const TSchema extends ValidatorSchema, TReturn, TAuth extends "user" | "admin" | undefined>(def: MutationDefRequired<InferArgs<TSchema>, TReturn, TSchema> & {
+    args: TSchema;
+    auth?: TAuth;
+}): FnDefinition<InferArgs<TSchema>, TReturn>;
+export declare function mutation<const TSchema extends ValidatorSchema, TReturn, TAuth extends "public" | "guest">(def: MutationDefOptional<InferArgs<TSchema>, TReturn, TSchema> & {
+    args: TSchema;
+    auth: TAuth;
+}): FnDefinition<InferArgs<TSchema>, TReturn>;
 export declare function mutation<TArgs = Record<string, unknown>, TReturn = unknown>(def: MutationDefRequired<TArgs, TReturn>): FnDefinition<TArgs, TReturn>;
 export declare function mutation<TArgs = Record<string, unknown>, TReturn = unknown>(def: MutationDefOptional<TArgs, TReturn>): FnDefinition<TArgs, TReturn>;
 /**
@@ -190,6 +206,14 @@ export declare function mutation<TArgs = Record<string, unknown>, TReturn = unkn
  * });
  * ```
  */
+export declare function action<const TSchema extends ValidatorSchema, TReturn, TAuth extends "user" | "admin" | undefined>(def: ActionDefRequired<InferArgs<TSchema>, TReturn, TSchema> & {
+    args: TSchema;
+    auth?: TAuth;
+}): FnDefinition<InferArgs<TSchema>, TReturn>;
+export declare function action<const TSchema extends ValidatorSchema, TReturn, TAuth extends "public" | "guest">(def: ActionDefOptional<InferArgs<TSchema>, TReturn, TSchema> & {
+    args: TSchema;
+    auth: TAuth;
+}): FnDefinition<InferArgs<TSchema>, TReturn>;
 export declare function action<TArgs = Record<string, unknown>, TReturn = unknown>(def: ActionDefRequired<TArgs, TReturn>): FnDefinition<TArgs, TReturn>;
 export declare function action<TArgs = Record<string, unknown>, TReturn = unknown>(def: ActionDefOptional<TArgs, TReturn>): FnDefinition<TArgs, TReturn>;
 export {};

package/dist/index.d.ts

@@ -22,4 +22,4 @@ export { v } from "./validators";
 export { resetDb, installTestIsolation } from "./testing";
 export { slugifyName, availableSlug } from "./slugify";
 export type { SsrResponse, SsrCookieOptions, SsrMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, } from "./ssr-runtime";
-export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, RequireMember, RequireMemberOptions, MemberRow, } from "./types";
+export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, MemberRow, } from "./types";

package/dist/types.d.ts

@@ -545,9 +545,19 @@ export interface FnDefinition<TArgs = unknown, TReturn = unknown> {
      */
     timeout?: number;
 }
-export interface Validator {
+declare const validatorType: unique symbol;
+declare const validatorOptional: unique symbol;
+/**
+ * Runtime validator carrying its validated TypeScript type.
+ *
+ * The symbol properties are type-only markers: they emit no runtime data and
+ * let the function constructors derive handler arguments from an `args` schema.
+ */
+export interface Validator<T = unknown, TOptional extends boolean = boolean> {
     type: string;
     optional?: boolean;
+    readonly [validatorType]?: T;
+    readonly [validatorOptional]?: TOptional;
     /** For v.id("tableName") */
     table?: string;
     /** For v.array(v.string()) */
@@ -559,3 +569,20 @@ export interface Validator {
     /** For v.literal("value") */
     value?: unknown;
 }
+/** Any validator accepted in an argument schema. */
+export type AnyValidator = Validator<any, boolean>;
+/** A function argument schema keyed by argument name. */
+export type ValidatorSchema = Record<string, AnyValidator>;
+/** Extract the value accepted by a validator. */
+export type InferValidator<TValidator extends AnyValidator> = TValidator extends Validator<infer TValue, boolean> ? TValue : never;
+type OptionalValidatorKeys<TSchema extends ValidatorSchema> = {
+    [TKey in keyof TSchema]-?: TSchema[TKey] extends Validator<any, true> ? TKey : never;
+}[keyof TSchema];
+type RequiredValidatorKeys<TSchema extends ValidatorSchema> = Exclude<keyof TSchema, OptionalValidatorKeys<TSchema>>;
+/** Derive a handler argument object from a validator schema. */
+export type InferArgs<TSchema extends ValidatorSchema> = {
+    [TKey in RequiredValidatorKeys<TSchema>]: InferValidator<TSchema[TKey]>;
+} & {
+    [TKey in OptionalValidatorKeys<TSchema>]?: InferValidator<TSchema[TKey]>;
+};
+export {};

package/dist/validators.d.ts

@@ -21,52 +21,52 @@
  * });
  * ```
  */
-import type { Validator } from "./types";
+import type { AnyValidator, InferArgs, InferValidator, Validator, ValidatorSchema } from "./types";
 export declare const v: {
     /** String value. */
-    string: () => Validator;
+    string: () => Validator<string, false>;
     /** Number (float64). Same as `v.float()`. */
-    number: () => Validator;
+    number: () => Validator<number, false>;
     /**
      * 64-bit float. Alias for `v.number()` so the validator API matches the
      * schema DSL (which uses `field.float()`). Prefer this in new code.
      */
-    float: () => Validator;
+    float: () => Validator<number, false>;
     /** Integer. */
-    int: () => Validator;
+    int: () => Validator<number, false>;
     /** Boolean. Same as `v.bool()`. */
-    boolean: () => Validator;
+    boolean: () => Validator<boolean, false>;
     /**
      * Boolean. Alias for `v.boolean()` so the validator API matches the
      * schema DSL (which uses `field.bool()`). Prefer this in new code.
      */
-    bool: () => Validator;
+    bool: () => Validator<boolean, false>;
     /**
      * ISO-8601 datetime string. Validates the shape of a string value; the
      * stored column type comes from the schema (`field.datetime()`).
      */
-    datetime: () => Validator;
+    datetime: () => Validator<string, false>;
     /**
      * Richtext string. Same runtime validation as `v.string()`; named
      * explicitly so server functions read as the matching schema type.
      */
-    richtext: () => Validator;
+    richtext: () => Validator<string, false>;
     /** ID reference to another entity. */
-    id: (table: string) => Validator;
+    id: (table: string) => Validator<string, false>;
     /** Null value. */
-    null: () => Validator;
+    null: () => Validator<null, false>;
     /** Array of values. */
-    array: (items: Validator) => Validator;
+    array: <TValidator extends AnyValidator>(items: TValidator) => Validator<InferValidator<TValidator>[], false>;
     /** Object with typed fields. */
-    object: (fields: Record<string, Validator>) => Validator;
+    object: <TSchema extends ValidatorSchema>(fields: TSchema) => Validator<InferArgs<TSchema>, false>;
     /** Optional value (may be omitted). */
-    optional: (inner: Validator) => Validator;
+    optional: <TValidator extends AnyValidator>(inner: TValidator) => Validator<InferValidator<TValidator>, true>;
     /** Union of multiple types. */
-    union: (...variants: Validator[]) => Validator;
+    union: <TVariants extends AnyValidator[]>(...variants: TVariants) => Validator<InferValidator<TVariants[number]>, false>;
     /** Exact literal value. */
-    literal: (value: string | number | boolean) => Validator;
+    literal: <const TValue extends string | number | boolean>(value: TValue) => Validator<TValue, false>;
     /** Any valid JSON value. */
-    any: () => Validator;
+    any: () => Validator<any, false>;
 };
 export declare function validateArgs(args: unknown, schema: Record<string, Validator>): {
     valid: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.331",
+  "version": "0.3.332",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",
@@ -32,6 +32,7 @@
     "README.md"
   ],
   "scripts": {
+    "check": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json",
     "test": "bun test",

package/src/define.ts

@@ -26,15 +26,18 @@ import type {
   QueryCtx,
   MutationCtx,
   ActionCtx,
-  Validator,
+  ValidatorSchema,
+  InferArgs,
   AuthMode,
 } from "./types";
 
 /** Default auth mode applied when a definition omits `auth`. */
 const DEFAULT_AUTH: AuthMode = "user";
 
-interface CommonDef {
-  args?: Record<string, Validator>;
+interface CommonDef<
+  TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined,
+> {
+  args?: TSchema;
   /**
    * When true, the function is callable only via `ctx.runQuery()` /
    * `ctx.runMutation()` / `ctx.runAction()` from another function
@@ -69,7 +72,11 @@ interface CommonDef {
   timeout?: number;
 }
 
-interface QueryDefRequired<TArgs, TReturn> extends CommonDef {
+interface QueryDefRequired<
+  TArgs,
+  TReturn,
+  TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined,
+> extends CommonDef<TSchema> {
   /** Defaults to `"user"`. See [`AuthMode`] for the full surface. */
   auth?: "user" | "admin";
   handler: (
@@ -78,7 +85,11 @@ interface QueryDefRequired<TArgs, TReturn> extends CommonDef {
   ) => Promise<TReturn>;
 }
 
-interface QueryDefOptional<TArgs, TReturn> extends CommonDef {
+interface QueryDefOptional<
+  TArgs,
+  TReturn,
+  TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined,
+> extends CommonDef<TSchema> {
   auth: "public" | "guest";
   handler: (
     ctx: QueryCtx<"optional">,
@@ -86,7 +97,11 @@ interface QueryDefOptional<TArgs, TReturn> extends CommonDef {
   ) => Promise<TReturn>;
 }
 
-interface MutationDefRequired<TArgs, TReturn> extends CommonDef {
+interface MutationDefRequired<
+  TArgs,
+  TReturn,
+  TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined,
+> extends CommonDef<TSchema> {
   auth?: "user" | "admin";
   handler: (
     ctx: MutationCtx<"required">,
@@ -94,7 +109,11 @@ interface MutationDefRequired<TArgs, TReturn> extends CommonDef {
   ) => Promise<TReturn>;
 }
 
-interface MutationDefOptional<TArgs, TReturn> extends CommonDef {
+interface MutationDefOptional<
+  TArgs,
+  TReturn,
+  TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined,
+> extends CommonDef<TSchema> {
   auth: "public" | "guest";
   handler: (
     ctx: MutationCtx<"optional">,
@@ -102,7 +121,11 @@ interface MutationDefOptional<TArgs, TReturn> extends CommonDef {
   ) => Promise<TReturn>;
 }
 
-interface ActionDefRequired<TArgs, TReturn> extends CommonDef {
+interface ActionDefRequired<
+  TArgs,
+  TReturn,
+  TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined,
+> extends CommonDef<TSchema> {
   auth?: "user" | "admin";
   handler: (
     ctx: ActionCtx<"required">,
@@ -110,7 +133,11 @@ interface ActionDefRequired<TArgs, TReturn> extends CommonDef {
   ) => Promise<TReturn>;
 }
 
-interface ActionDefOptional<TArgs, TReturn> extends CommonDef {
+interface ActionDefOptional<
+  TArgs,
+  TReturn,
+  TSchema extends ValidatorSchema | undefined = ValidatorSchema | undefined,
+> extends CommonDef<TSchema> {
   auth: "public" | "guest";
   handler: (
     ctx: ActionCtx<"optional">,
@@ -150,6 +177,26 @@ interface ActionDefOptional<TArgs, TReturn> extends CommonDef {
  * });
  * ```
  */
+export function query<
+  const TSchema extends ValidatorSchema,
+  TReturn,
+  TAuth extends "user" | "admin" | undefined,
+>(
+  def: QueryDefRequired<InferArgs<TSchema>, TReturn, TSchema> & {
+    args: TSchema;
+    auth?: TAuth;
+  },
+): FnDefinition<InferArgs<TSchema>, TReturn>;
+export function query<
+  const TSchema extends ValidatorSchema,
+  TReturn,
+  TAuth extends "public" | "guest",
+>(
+  def: QueryDefOptional<InferArgs<TSchema>, TReturn, TSchema> & {
+    args: TSchema;
+    auth: TAuth;
+  },
+): FnDefinition<InferArgs<TSchema>, TReturn>;
 export function query<TArgs = Record<string, unknown>, TReturn = unknown>(
   def: QueryDefRequired<TArgs, TReturn>,
 ): FnDefinition<TArgs, TReturn>;
@@ -200,6 +247,26 @@ export function query<TArgs, TReturn>(
  * });
  * ```
  */
+export function mutation<
+  const TSchema extends ValidatorSchema,
+  TReturn,
+  TAuth extends "user" | "admin" | undefined,
+>(
+  def: MutationDefRequired<InferArgs<TSchema>, TReturn, TSchema> & {
+    args: TSchema;
+    auth?: TAuth;
+  },
+): FnDefinition<InferArgs<TSchema>, TReturn>;
+export function mutation<
+  const TSchema extends ValidatorSchema,
+  TReturn,
+  TAuth extends "public" | "guest",
+>(
+  def: MutationDefOptional<InferArgs<TSchema>, TReturn, TSchema> & {
+    args: TSchema;
+    auth: TAuth;
+  },
+): FnDefinition<InferArgs<TSchema>, TReturn>;
 export function mutation<TArgs = Record<string, unknown>, TReturn = unknown>(
   def: MutationDefRequired<TArgs, TReturn>,
 ): FnDefinition<TArgs, TReturn>;
@@ -265,6 +332,26 @@ export function mutation<TArgs, TReturn>(
  * });
  * ```
  */
+export function action<
+  const TSchema extends ValidatorSchema,
+  TReturn,
+  TAuth extends "user" | "admin" | undefined,
+>(
+  def: ActionDefRequired<InferArgs<TSchema>, TReturn, TSchema> & {
+    args: TSchema;
+    auth?: TAuth;
+  },
+): FnDefinition<InferArgs<TSchema>, TReturn>;
+export function action<
+  const TSchema extends ValidatorSchema,
+  TReturn,
+  TAuth extends "public" | "guest",
+>(
+  def: ActionDefOptional<InferArgs<TSchema>, TReturn, TSchema> & {
+    args: TSchema;
+    auth: TAuth;
+  },
+): FnDefinition<InferArgs<TSchema>, TReturn>;
 export function action<TArgs = Record<string, unknown>, TReturn = unknown>(
   def: ActionDefRequired<TArgs, TReturn>,
 ): FnDefinition<TArgs, TReturn>;

package/src/define.types.test.ts

@@ -0,0 +1,109 @@
+import { expect, test } from "bun:test";
+
+import { action, mutation, query } from "./define";
+import type { FnDefinition } from "./types";
+import { v } from "./validators";
+
+type Equal<TLeft, TRight> =
+  (<T>() => T extends TLeft ? 1 : 2) extends
+  (<T>() => T extends TRight ? 1 : 2)
+    ? true
+    : false;
+type Expect<T extends true> = T;
+type ArgsOf<TDefinition> =
+  TDefinition extends FnDefinition<infer TArgs, unknown> ? TArgs : never;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+
+const inferredMutation = mutation({
+  args: {
+    required: v.string(),
+    optional: v.optional(v.number()),
+    list: v.array(v.int()),
+    nested: v.object({
+      enabled: v.boolean(),
+      label: v.optional(v.string()),
+    }),
+    union: v.union(v.literal("open"), v.literal(404), v.null()),
+    literal: v.literal("fixed"),
+    anything: v.any(),
+  },
+  async handler(_ctx, args) {
+    const required: string = args.required;
+    const optional: number | undefined = args.optional;
+    const list: number[] = args.list;
+    const nested: { enabled: boolean; label?: string } = args.nested;
+    const union: "open" | 404 | null = args.union;
+    const literal: "fixed" = args.literal;
+    const anything: any = args.anything;
+
+    return { required, optional, list, nested, union, literal, anything };
+  },
+});
+
+type InferredArgs = ArgsOf<typeof inferredMutation>;
+type _RequiredValue = Expect<Equal<InferredArgs["required"], string>>;
+type _RequiredKey = Expect<
+  Equal<{} extends Pick<InferredArgs, "required"> ? true : false, false>
+>;
+type _OptionalValue = Expect<
+  Equal<InferredArgs["optional"], number | undefined>
+>;
+type _OptionalKey = Expect<
+  Equal<{} extends Pick<InferredArgs, "optional"> ? true : false, true>
+>;
+type _Array = Expect<Equal<InferredArgs["list"], number[]>>;
+type _ObjectRequired = Expect<
+  Equal<InferredArgs["nested"]["enabled"], boolean>
+>;
+type _ObjectOptional = Expect<
+  Equal<InferredArgs["nested"]["label"], string | undefined>
+>;
+type _Union = Expect<Equal<InferredArgs["union"], "open" | 404 | null>>;
+type _Literal = Expect<Equal<InferredArgs["literal"], "fixed">>;
+type _Any = Expect<IsAny<InferredArgs["anything"]>>;
+
+const publicQuery = query({
+  auth: "public",
+  args: { id: v.id("Item") },
+  async handler(ctx, args) {
+    const userId: string | null = ctx.auth.userId;
+    const id: string = args.id;
+    return { id, userId };
+  },
+});
+
+const guestAction = action({
+  auth: "guest",
+  args: { mode: v.union(v.literal("fast"), v.literal("safe")) },
+  async handler(ctx, args) {
+    const userId: string | null = ctx.auth.userId;
+    const mode: "fast" | "safe" = args.mode;
+    return { mode, userId };
+  },
+});
+
+type ExplicitArgs = { name: string; note?: string };
+type ExplicitReturn = { ok: boolean };
+
+const explicitMutation = mutation<ExplicitArgs, ExplicitReturn>({
+  args: {
+    name: v.string(),
+    note: v.optional(v.string()),
+  },
+  async handler(_ctx, args) {
+    const explicit: ExplicitArgs = args;
+    return { ok: explicit.name.length > 0 };
+  },
+});
+
+type _ExplicitArgs = Expect<
+  Equal<ArgsOf<typeof explicitMutation>, ExplicitArgs>
+>;
+
+test("validator schemas remain available at runtime", () => {
+  expect(inferredMutation.args?.required.type).toBe("string");
+  expect(inferredMutation.args?.optional.optional).toBe(true);
+  expect(publicQuery.auth).toBe("public");
+  expect(guestAction.auth).toBe("guest");
+  expect(explicitMutation.type).toBe("mutation");
+});

package/src/index.ts

@@ -46,6 +46,11 @@ export type {
   AuthMode,
   AuthRequirement,
   FnDefinition,
+  Validator,
+  AnyValidator,
+  ValidatorSchema,
+  InferValidator,
+  InferArgs,
   RequireMember,
   RequireMemberOptions,
   MemberRow,

package/src/types.ts

@@ -658,9 +658,23 @@ export interface FnDefinition<TArgs = unknown, TReturn = unknown> {
 // Validators
 // ---------------------------------------------------------------------------
 
-export interface Validator {
+declare const validatorType: unique symbol;
+declare const validatorOptional: unique symbol;
+
+/**
+ * Runtime validator carrying its validated TypeScript type.
+ *
+ * The symbol properties are type-only markers: they emit no runtime data and
+ * let the function constructors derive handler arguments from an `args` schema.
+ */
+export interface Validator<
+  T = unknown,
+  TOptional extends boolean = boolean,
+> {
   type: string;
   optional?: boolean;
+  readonly [validatorType]?: T;
+  readonly [validatorOptional]?: TOptional;
   /** For v.id("tableName") */
   table?: string;
   /** For v.array(v.string()) */
@@ -672,3 +686,31 @@ export interface Validator {
   /** For v.literal("value") */
   value?: unknown;
 }
+
+/** Any validator accepted in an argument schema. */
+export type AnyValidator = Validator<any, boolean>;
+
+/** A function argument schema keyed by argument name. */
+export type ValidatorSchema = Record<string, AnyValidator>;
+
+/** Extract the value accepted by a validator. */
+export type InferValidator<TValidator extends AnyValidator> =
+  TValidator extends Validator<infer TValue, boolean> ? TValue : never;
+
+type OptionalValidatorKeys<TSchema extends ValidatorSchema> = {
+  [TKey in keyof TSchema]-?: TSchema[TKey] extends Validator<any, true>
+    ? TKey
+    : never;
+}[keyof TSchema];
+
+type RequiredValidatorKeys<TSchema extends ValidatorSchema> = Exclude<
+  keyof TSchema,
+  OptionalValidatorKeys<TSchema>
+>;
+
+/** Derive a handler argument object from a validator schema. */
+export type InferArgs<TSchema extends ValidatorSchema> = {
+  [TKey in RequiredValidatorKeys<TSchema>]: InferValidator<TSchema[TKey]>;
+} & {
+  [TKey in OptionalValidatorKeys<TSchema>]?: InferValidator<TSchema[TKey]>;
+};

package/src/validators.ts

@@ -22,75 +22,99 @@
  * ```
  */
 
-import type { Validator } from "./types";
-
-function validator(type: string, extra?: Partial<Validator>): Validator {
+import type {
+  AnyValidator,
+  InferArgs,
+  InferValidator,
+  Validator,
+  ValidatorSchema,
+} from "./types";
+
+function validator<T>(
+  type: string,
+  extra?: Partial<Validator<T, false>>,
+): Validator<T, false> {
   return { type, ...extra };
 }
 
 export const v = {
   /** String value. */
-  string: (): Validator => validator("string"),
+  string: (): Validator<string, false> => validator("string"),
 
   /** Number (float64). Same as `v.float()`. */
-  number: (): Validator => validator("number"),
+  number: (): Validator<number, false> => validator("number"),
 
   /**
    * 64-bit float. Alias for `v.number()` so the validator API matches the
    * schema DSL (which uses `field.float()`). Prefer this in new code.
    */
-  float: (): Validator => validator("number"),
+  float: (): Validator<number, false> => validator("number"),
 
   /** Integer. */
-  int: (): Validator => validator("int"),
+  int: (): Validator<number, false> => validator("int"),
 
   /** Boolean. Same as `v.bool()`. */
-  boolean: (): Validator => validator("boolean"),
+  boolean: (): Validator<boolean, false> => validator("boolean"),
 
   /**
    * Boolean. Alias for `v.boolean()` so the validator API matches the
    * schema DSL (which uses `field.bool()`). Prefer this in new code.
    */
-  bool: (): Validator => validator("boolean"),
+  bool: (): Validator<boolean, false> => validator("boolean"),
 
   /**
    * ISO-8601 datetime string. Validates the shape of a string value; the
    * stored column type comes from the schema (`field.datetime()`).
    */
-  datetime: (): Validator => validator("string"),
+  datetime: (): Validator<string, false> => validator("string"),
 
   /**
    * Richtext string. Same runtime validation as `v.string()`; named
    * explicitly so server functions read as the matching schema type.
    */
-  richtext: (): Validator => validator("string"),
+  richtext: (): Validator<string, false> => validator("string"),
 
   /** ID reference to another entity. */
-  id: (table: string): Validator => validator("id", { table }),
+  id: (table: string): Validator<string, false> =>
+    validator("id", { table }),
 
   /** Null value. */
-  null: (): Validator => validator("null"),
+  null: (): Validator<null, false> => validator("null"),
 
   /** Array of values. */
-  array: (items: Validator): Validator => validator("array", { items }),
+  array: <TValidator extends AnyValidator>(
+    items: TValidator,
+  ): Validator<InferValidator<TValidator>[], false> =>
+    validator("array", { items }),
 
   /** Object with typed fields. */
-  object: (fields: Record<string, Validator>): Validator =>
+  object: <TSchema extends ValidatorSchema>(
+    fields: TSchema,
+  ): Validator<InferArgs<TSchema>, false> =>
     validator("object", { fields }),
 
   /** Optional value (may be omitted). */
-  optional: (inner: Validator): Validator => ({ ...inner, optional: true }),
+  optional: <TValidator extends AnyValidator>(
+    inner: TValidator,
+  ): Validator<InferValidator<TValidator>, true> =>
+    ({
+      ...inner,
+      optional: true,
+    }) as Validator<InferValidator<TValidator>, true>,
 
   /** Union of multiple types. */
-  union: (...variants: Validator[]): Validator =>
+  union: <TVariants extends AnyValidator[]>(
+    ...variants: TVariants
+  ): Validator<InferValidator<TVariants[number]>, false> =>
     validator("union", { variants }),
 
   /** Exact literal value. */
-  literal: (value: string | number | boolean): Validator =>
-    validator("literal", { value }),
+  literal: <const TValue extends string | number | boolean>(
+    value: TValue,
+  ): Validator<TValue, false> => validator("literal", { value }),
 
   /** Any valid JSON value. */
-  any: (): Validator => validator("any"),
+  any: (): Validator<any, false> => validator("any"),
 };
 
 // ---------------------------------------------------------------------------