Skip to content
forms

Schema adapters

A schema plugin for any Standard Schema library.

definePlugin from @lunarhue/forms-core/plugins makes a schema plugin for any Standard Schema library when you give it a name and a schema adapter. Validation and types already go through Standard Schema, so the adapter only says which schemas it accepts and what values they start from. It has:

  • vendor: the library’s name, matched against schema["~standard"].vendor.
  • defaultValue(schema): the value a form starts from when defaultValues leaves it out.
  • itemValue(schema, path): the value push or insert gives a new item of the array at path when it gets none.
import type { SchemaAdapter } from "@lunarhue/forms-core";
import { definePlugin } from "@lunarhue/forms-core/plugins";
import { defaultOf, itemDefaultOf, type ArkSchema } from "./ark-defaults";

const adapter: SchemaAdapter<ArkSchema> = {
  vendor: "arktype",
  defaultValue: (schema) => defaultOf(schema),
  itemValue: (schema, path) => itemDefaultOf(schema, path),
};

export const ark = () => definePlugin({ name: "ark", schema: adapter });

With ark() in a form’s plugins, defaultValues becomes optional for an ArkSchema. Without it, defaultValues is required and complete. zod() and valibot() are schema plugins of the same shape.

TS2353 from define in a function generic over the schema

A helper that takes any schema and returns a definition fails to compile when its type parameter is the schema type:

const forms = createFormsCore({ plugins: [zod()] });

export function makeForm<S extends z.ZodObject>(schema: S) {
  return forms.define({ schema });
}
error TS2353: Object literal may only specify known properties, and 'schema' does not exist in type
'(options: void) => WithPlugins<Definition<never, S, readonly [Plugin<undefined, "zod", never, never, ZodSchema>], FormError, undefined, unknown>, [], NoInfer<DefinedValue<...>>>'.

define uses conditional types to ask two things about the schema: is there one at all, and does an installed schema plugin accept it? While S is a type parameter, TypeScript can’t answer either, so the config matches no case. A bound of S extends StandardSchemaV1, explicit type arguments such as define<never, S>, and the function form define(() => ({ schema })) fail the same way. The adapters’ define takes the same config, so React and Solid show the same error.

Make the helper generic over the schema’s values instead. Then the schema type is concrete and TypeScript can tell the zod plugin accepts it. The form gets the same types an ordinary define gives it. These two compile:

import { createFormsCore, type StandardSchemaV1 } from "@lunarhue/forms-core";
import { zod } from "@lunarhue/forms-schema/zod";
import { z } from "zod";

const forms = createFormsCore({ plugins: [zod()] });

// I is the schema's input and O its output.
export function makeForm<I extends object, O>(schema: z.ZodType<O, I>, onSubmit: (value: O) => void) {
  return forms.define({ schema, onSubmit });
}

// Any Standard Schema. No schema plugin accepts this type, so it needs defaultValues.
export function makeStandard<V extends object>(schema: StandardSchemaV1<V>, defaultValues: V) {
  return forms.define({ schema, defaultValues });
}

Last updated