@tanstack-isomorphic-form/core

Core primitives for @tanstack-isomorphic-form. Framework integrations can use these utilities to read submitted form data, validate it with a Standard Schema, run an action, and represent the resulting form state.

Installation

pnpm add @tanstack-isomorphic-form/core

Exports

JSON Schema

jsonSchemaFromStandardSchema(schema, options?)

Generates and validates the input JSON Schema for a StandardJSONSchemaV1 schema. By default it requests the draft-2020-12 target. Pass the result to createFormDataExtractor.

const jsonSchema = jsonSchemaFromStandardSchema(schema);
const extractFormData = createFormDataExtractor(jsonSchema);

jsonSchemaIncludesBinaryFile(jsonSchema)

Returns true when a JSON Schema contains a field with format: "binary", including fields nested in objects, arrays, and unions. Framework integrations can use this to select multipart/form-data for native submissions.

Form-data extraction

createFormDataExtractor(jsonSchema, options?)

Creates a function that converts FormData into the input shape represented by the JSON Schema. Object and array fields are reconstructed from field names; unsupported or absent fields are omitted.

The optional FormDataToObjectOptions customizes the separators used in field names. The default syntax is address.street for object properties and items[0] for array items.

FormDataExtractor<TSchema>

The function type returned by createFormDataExtractor. It accepts FormData and returns InferFormDataSchemaExtract<TSchema>.

FormDataToObjectOptions

Configuration for the field-name separators used while converting FormData into nested objects and arrays:

• propertyStartDelimiter
• propertyEndDelimiter
• indexStartDelimiter
• indexEndDelimiter

FormDataSchema<Input, Output>

The form schema constraint. A form schema implements both StandardSchemaV1 for validation and StandardJSONSchemaV1 for generating its input JSON Schema.

InferFormDataSchemaExtract<TSchema>

The extracted, pre-validation value shape for a form schema. Leaf values are represented as form values such as strings, File objects, or null-like values; nested objects and arrays retain their structure.

Actions

runFormAction(options)

Extracts and optionally sanitizes form values, validates them with the supplied schema, and runs actionFn when validation succeeds. It returns the resulting state and an optional redirect destination without performing navigation itself.

redirectAfterAction(options)

Builds a successful or failed action result that also redirects. It preserves an optional ok, result, or error value while moving the router options into redirect.

return redirectAfterAction({ to: "/todos" });

FormActionPanicError

An Error subclass used to represent an unexpected exception raised while running the form action or loader flow.

FormAction<TSchema, TResult, TError, TRedirect>

The action function type. It receives validated schema output as { data } and resolves to a success result, failure result, or either result with a redirect.

InferFormActionResult<TActionFn>

Infers the result type returned by a successful form action.

InferFormActionError<TActionFn>

Infers the error type returned by a failed form action.

RedirectAfterActionReturn<T>

The type returned by redirectAfterAction, including the redirect options and the inferred ok, result, and error fields.

ValueSanitizer<TSchema>

The type of a function that normalizes extracted values before they are stored in form state. The original form values are still what the schema validates.

Loaders

createFormLoader(options)

Creates a route loader. The loader reads submitted form data, runs the form action for POST requests, and otherwise returns idle state with optional defaults. Its options include the schema, action, extractor, optional defaults and sanitizer, and a submittedFormDataReader adapter.

createSubmittedFormDataReader(getRequest)

Creates the server/client submittedFormDataReader adapter required by createFormLoader. The server reader returns request.formData() for POST requests; the client reader returns undefined.

FormLoader<TSchema, TActionFn>

The loader function type created by createFormLoader. It accepts a route loader context containing location.publicHref and optional per-load default values.

FormLoaderReturn<TSchema, TActionFn, TActionUrl>

The promise returned by a form loader. It contains the action URL and the current FormState.

Form state

FormState<TSchema, TResult, TError>

The discriminated union used to represent a form lifecycle state: idle, pending, success, or error. All states include extracted values; success states include result, and error states contain either schema validation issues or a form-level error.

FormActionState<TSchema, TActionFn>

The FormState specialized for a particular form action. Its result and error types are inferred from TActionFn, and unexpected errors are represented by FormActionPanicError.

Repository

• Source: https://github.com/cahnory/tanstack-isomorphic-form/tree/main/libs/core
• Issues: https://github.com/cahnory/tanstack-isomorphic-form/issues

License

MIT