@formadapter/core 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ludicrous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# `@formadapter/core`
+
+Framework-free schema compilation, value preparation, validation helpers, and
+submission state for FormAdapter.
+
+```sh
+bun add @formadapter/core zod
+```
+
+## Schema contract
+
+A schema must expose both Standard Schema V1 validation and Standard JSON
+Schema V1 input conversion. Zod 4 and ArkType 2 provide those interfaces
+natively, so this package has no runtime dependency on either library.
+
+```ts
+import { compileForm, getDefaultValues, validate } from "@formadapter/core";
+import { z } from "zod";
+
+const schema = z.object({
+  email: z.email(),
+  seats: z.number().int().min(1),
+});
+
+const model = compileForm(schema);
+const defaults = getDefaultValues(model);
+const result = await validate(schema, { email: "ada@example.com", seats: 2 });
+```
+
+FormAdapter reads only the schema's input-side JSON Schema for rendering, then
+delegates validation and transformation back to the original schema. Input and
+output types may therefore differ without losing type safety.
+
+`compileForm(schema, config)` normalizes objects, scalar/object arrays,
+constraints, formats, options, defaults, references, `allOf`, nullable values,
+and discriminated object unions into a renderer-neutral model. Configuration
+can add presentation rules, dynamic options, async field validators, array
+labels, and custom control names without changing the schema.
+
+## Prepared values and presentation rules
+
+`prepareFormValues(model, values)` applies browser-to-schema absence semantics:
+optional blanks become absent, nullable blanks become `null`, empty optional
+objects disappear, and fields hidden by presentation predicates are pruned.
+`validatePresentationRules` enforces `requiredWhenVisible` independently of the
+schema. Use both at a server trust boundary when presentation rules matter.
+
+## Submission state
+
+`SubmissionState<Data>` is the serializable contract shared by the React,
+server, Next.js, TanStack Start, oRPC, and HTTP packages. Use
+`submissionSuccess`, `submissionFailure`, `initialSubmissionState`, and
+`isSubmissionState` when writing a custom transport.
+
+The package also exports typed path helpers, option serialization, issue/error
+normalization, schema input/output inference, default construction, and the
+canonical `isReservedFormPathSegment` guard for custom transports.
+
+## Boundaries
+
+Tuples, dynamic record keys, general structural unions, circular references,
+and discriminated object unions inside arrays compile to explicit unsupported
+nodes. Renderers can show those nodes through their own diagnostic slot instead
+of silently dropping schema structure. Multiple file selection must use an
+array-of-files schema; `multiple: true` is rejected on a scalar file field.
+
+Property names must also be losslessly encodable as form paths. Empty,
+numeric-like, transport-reserved, `root`, or prototype-reserved names and names that
+contain `.`, `[`, `]`, `'`, or `"` compile to an unsupported node instead of
+binding to the wrong value.

package/dist/index.d.ts

@@ -0,0 +1,328 @@
+//#region src/path-segment.d.ts
+declare const STANDARD_OBJECT_PROTOTYPE_SEGMENTS: readonly ["__defineGetter__", "__defineSetter__", "__lookupGetter__", "__lookupSetter__", "__proto__", "constructor", "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable", "toLocaleString", "toString", "valueOf"];
+type ReservedFormPathSegment = (typeof STANDARD_OBJECT_PROTOTYPE_SEGMENTS)[number] | "prototype" | "root";
+/** Names that collide with JavaScript object lookup or form-runtime state. */
+declare const RESERVED_FORM_PATH_SEGMENTS: ReadonlySet<string>;
+/** True when a schema property cannot be represented losslessly as one path segment. */
+declare function isReservedFormPathSegment(segment: string): boolean;
+//#endregion
+//#region src/path.d.ts
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+type FileLike = {
+  readonly name: string;
+  readonly size: number;
+  readonly type: string;
+  readonly lastModified: number;
+};
+type Atomic = Primitive | Date | RegExp | Error | Function | Promise<unknown> | Map<unknown, unknown> | Set<unknown> | ArrayBuffer | DataView | FileLike;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type IsTraversable<T> = IsAny<T> extends true ? false : NonNullable<T> extends Atomic ? false : NonNullable<T> extends object ? true : false;
+type NextDepth<Depth extends readonly unknown[]> = [...Depth, 0];
+type AtMaxDepth<Depth extends readonly unknown[]> = Depth["length"] extends 8 ? true : false;
+type Join<Prefix extends string, Key extends string> = Prefix extends "" ? Key : `${Prefix}.${Key}`;
+type PathWhitespace = " " | "\f" | "\n" | "\r" | "	" | "\v";
+type TrimPathWhitespace<Key extends string> = Key extends `${PathWhitespace}${infer Rest}` ? TrimPathWhitespace<Rest> : Key extends `${infer Rest}${PathWhitespace}` ? TrimPathWhitespace<Rest> : Key;
+type NumericLikePathKey<Key extends string> = TrimPathWhitespace<Key> extends "" ? true : TrimPathWhitespace<Key> extends `${number}` | "+Infinity" | "-Infinity" | "Infinity" ? true : false;
+type SafePathKey<Key extends string> = Key extends "" | ReservedFormPathSegment ? never : NumericLikePathKey<Key> extends true ? never : Key extends `$ACTION_${string}` | `__formadapter_${string}` | `${string}.${string}` | `${string}[${string}` | `${string}]${string}` | `${string}'${string}` | `${string}"${string}` ? never : Key;
+type PathsForValue<Value, Prefix extends string, Depth extends readonly unknown[]> = Prefix | (AtMaxDepth<Depth> extends true ? never : NonNullable<Value> extends readonly (infer Item)[] ? `${Prefix}[]` | (IsTraversable<Item> extends true ? PathsForValue<NonNullable<Item>, `${Prefix}[]`, NextDepth<Depth>> : never) : IsTraversable<Value> extends true ? ObjectPaths<NonNullable<Value>, Prefix, NextDepth<Depth>> : never);
+type ObjectPaths<Value, Prefix extends string, Depth extends readonly unknown[]> = Value extends unknown ? Value extends object ? { [Key in Extract<keyof Value, string>]-?: PathsForValue<Value[Key], Join<Prefix, SafePathKey<Key>>, Depth> }[Extract<keyof Value, string>] : never : never;
+/** Canonical schema field paths. Array items use `[]`, for example `users[].email`. */
+type FieldPath<Value> = IsTraversable<Value> extends true ? Extract<ObjectPaths<NonNullable<Value>, "", []>, string> : never;
+type SegmentValue<Value, Segment extends string> = Value extends unknown ? Segment extends `${infer Prefix}[]` ? SegmentValue<Value, Prefix> extends readonly (infer Item)[] ? Item : never : Segment extends keyof NonNullable<Value> ? NonNullable<Value>[Segment] : never : never;
+type PathValueInternal<Value, Path extends string> = Path extends `${infer Head}.${infer Tail}` ? PathValueInternal<SegmentValue<Value, Head>, Tail> : SegmentValue<Value, Path>;
+type PathValue<Value, Path extends FieldPath<Value>> = PathValueInternal<Value, Path>;
+type DeepPartial<Value> = IsAny<Value> extends true ? Value : Value extends Atomic ? Value : Value extends readonly (infer Item)[] ? Array<DeepPartial<Item>> : Value extends object ? { [Key in keyof Value]?: DeepPartial<Value[Key]> } : Value;
+declare function pathToName(path: ReadonlyArray<string | number>): string;
+declare function pathToConfigPath(path: ReadonlyArray<string | number>): string;
+//#endregion
+//#region src/types.d.ts
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | readonly JsonValue[] | {
+  readonly [key: string]: JsonValue;
+};
+type JsonSchema = boolean | JsonSchemaObject;
+interface JsonSchemaObject {
+  readonly $ref?: string;
+  readonly $defs?: Readonly<Record<string, JsonSchema>>;
+  readonly definitions?: Readonly<Record<string, JsonSchema>>;
+  readonly type?: string | readonly string[];
+  readonly title?: string;
+  readonly description?: string;
+  readonly default?: unknown;
+  readonly readOnly?: boolean;
+  readonly properties?: Readonly<Record<string, JsonSchema>>;
+  readonly additionalProperties?: JsonSchema;
+  readonly patternProperties?: Readonly<Record<string, JsonSchema>>;
+  readonly propertyNames?: JsonSchema;
+  readonly required?: readonly string[];
+  readonly items?: JsonSchema | readonly JsonSchema[];
+  readonly prefixItems?: readonly JsonSchema[];
+  readonly enum?: readonly unknown[];
+  readonly const?: unknown;
+  readonly anyOf?: readonly JsonSchema[];
+  readonly oneOf?: readonly JsonSchema[];
+  readonly allOf?: readonly JsonSchema[];
+  readonly format?: string;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly pattern?: string;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly exclusiveMinimum?: number;
+  readonly exclusiveMaximum?: number;
+  readonly multipleOf?: number;
+  readonly minItems?: number;
+  readonly maxItems?: number;
+  readonly uniqueItems?: boolean;
+  readonly contentEncoding?: string;
+  readonly contentMediaType?: string;
+  readonly [keyword: string]: unknown;
+}
+type BuiltInControl = "text" | "email" | "url" | "tel" | "password" | "search" | "date" | "datetime-local" | "time" | "textarea" | "number" | "range" | "checkbox" | "select" | "radio" | "file" | "hidden";
+type NativeInputType = Exclude<BuiltInControl, "textarea" | "select" | "radio">;
+type FieldDataType = "string" | "number" | "integer" | "boolean" | "file" | "unknown";
+type FieldPredicate<Values> = (values: Readonly<DeepPartial<Values>>) => boolean;
+type FieldState<Values> = boolean | FieldPredicate<Values>;
+type MaybePromise<Value> = Promise<Value> | Value;
+/** The portable subset of AbortSignal exposed to field validators. */
+interface AsyncFieldValidationSignal {
+  readonly aborted: boolean;
+  readonly reason: unknown;
+  addEventListener(type: "abort", listener: () => void, options?: {
+    readonly once?: boolean;
+  }): void;
+  removeEventListener(type: "abort", listener: () => void): void;
+  throwIfAborted(): void;
+}
+interface AsyncFieldValidationContext {
+  /** Aborted when a newer validation for the same runtime field starts. */
+  readonly signal: AsyncFieldValidationSignal;
+}
+type AsyncFieldValidator<Value, Values> = (value: Value, values: Readonly<DeepPartial<Values>>, context: AsyncFieldValidationContext) => MaybePromise<readonly string[] | string | undefined>;
+interface FormOption<Value extends JsonPrimitive = JsonPrimitive> {
+  readonly label: string;
+  readonly value: Value;
+}
+type FieldOptionValue<Value> = unknown extends Value ? JsonPrimitive : Extract<Value, JsonPrimitive>;
+type FieldOptions<Values, Value = unknown> = readonly FormOption<FieldOptionValue<Value>>[] | ((values: Readonly<DeepPartial<Values>>) => readonly FormOption<FieldOptionValue<Value>>[]);
+interface ArrayConfig<Values = unknown> {
+  readonly addLabel?: string;
+  readonly removeLabel?: string;
+  readonly moveUpLabel?: string;
+  readonly moveDownLabel?: string;
+  readonly itemLabel?: string | ((index: number, item: unknown, values: Readonly<DeepPartial<Values>>) => string);
+}
+interface FieldConfig<Control extends string = never, Values = unknown, Value = unknown> {
+  readonly label?: string;
+  readonly description?: string;
+  readonly placeholder?: string;
+  readonly control?: BuiltInControl | Control;
+  readonly hidden?: FieldState<Values>;
+  readonly disabled?: FieldState<Values>;
+  readonly readOnly?: FieldState<Values>;
+  readonly order?: number;
+  readonly className?: string;
+  readonly controlProps?: Readonly<Record<string, unknown>>;
+  readonly defaultValue?: Value;
+  /** A static list or a synchronous projection of query-backed application state. */
+  readonly options?: FieldOptions<Values, Value>;
+  readonly multiple?: boolean;
+  /** Makes an optional schema field required only while it is rendered. */
+  readonly requiredWhenVisible?: FieldState<Values>;
+  readonly requiredMessage?: string;
+  /** Runs after authoritative schema validation succeeds for this field. */
+  readonly asyncValidate?: AsyncFieldValidator<Value, Values>;
+  /** Debounces async validation. Defaults to 250ms. */
+  readonly asyncValidationDebounceMs?: number;
+  readonly array?: ArrayConfig<Values>;
+}
+interface FormConfig<Input, Control extends string = never> {
+  readonly fields?: { readonly [Path in FieldPath<Input>]?: FieldConfig<Control, Input, PathValue<Input, Path>> | undefined };
+  readonly jsonSchema?: {
+    readonly libraryOptions?: Readonly<Record<string, unknown>>;
+    readonly opaqueRefinements?: "base" | "error";
+  };
+}
+interface ResolvedFieldConfig<Control extends string = never, Values = unknown, Value = unknown> {
+  readonly control?: BuiltInControl | Control;
+  readonly placeholder?: string;
+  readonly hidden: FieldState<Values>;
+  readonly disabled: FieldState<Values>;
+  readonly readOnly: FieldState<Values>;
+  readonly order?: number;
+  readonly className?: string;
+  readonly controlProps?: Readonly<Record<string, unknown>>;
+  readonly multiple: boolean;
+  readonly options?: FieldOptions<Values, Value>;
+  readonly requiredWhenVisible: FieldState<Values>;
+  readonly requiredMessage?: string;
+  readonly asyncValidate?: AsyncFieldValidator<Value, Values>;
+  readonly asyncValidationDebounceMs: number;
+  readonly array?: ArrayConfig<Values>;
+  readonly extensions: Readonly<Record<string, unknown>>;
+}
+interface ScalarConstraints {
+  readonly format?: string;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly pattern?: string;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly exclusiveMinimum?: number;
+  readonly exclusiveMaximum?: number;
+  readonly multipleOf?: number;
+  readonly accept?: string;
+  readonly multiple: boolean;
+  readonly contentEncoding?: string;
+  readonly contentMediaType?: string;
+}
+interface BaseField<Kind extends FormNode["kind"], Control extends string, Values> {
+  readonly kind: Kind;
+  readonly key: string;
+  readonly path: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly required: boolean;
+  readonly nullable: boolean;
+  readonly defaultValue?: unknown;
+  readonly config: ResolvedFieldConfig<Control, Values>;
+  readonly source: JsonSchema;
+}
+interface ScalarField<Control extends string = never, Values = unknown> extends BaseField<"scalar", Control, Values> {
+  readonly dataType: FieldDataType;
+  readonly control: BuiltInControl | Control;
+  readonly inputType?: NativeInputType;
+  readonly constraints: ScalarConstraints;
+  readonly options?: readonly FormOption[];
+}
+interface ObjectField<Control extends string = never, Values = unknown> extends BaseField<"object", Control, Values> {
+  readonly children: readonly FormNode<Control, Values>[];
+}
+interface ArrayField<Control extends string = never, Values = unknown> extends BaseField<"array", Control, Values> {
+  readonly item: FormNode<Control, Values>;
+  readonly minItems?: number;
+  readonly maxItems?: number;
+  readonly uniqueItems: boolean;
+}
+interface UnsupportedField<Control extends string = never, Values = unknown> extends BaseField<"unsupported", Control, Values> {
+  readonly reason: string;
+}
+type FormNode<Control extends string = never, Values = unknown> = ScalarField<Control, Values> | ObjectField<Control, Values> | ArrayField<Control, Values> | UnsupportedField<Control, Values>;
+interface FormModel<Input = unknown, Control extends string = never> {
+  readonly root: FormNode<Control, Input>;
+  readonly fields: readonly FormNode<Control, Input>[];
+  readonly fieldMap: Readonly<Record<string, FormNode<Control, Input>>>;
+}
+//#endregion
+//#region src/standard.d.ts
+/** A Standard Schema issue. Kept structural so schema libraries remain optional. */
+interface StandardIssue {
+  readonly message: string;
+  readonly path?: ReadonlyArray<PropertyKey | {
+    readonly key: PropertyKey;
+  }> | undefined;
+}
+interface StandardSuccess<Output> {
+  readonly value: Output;
+  readonly issues?: undefined;
+}
+interface StandardFailure {
+  readonly issues: ReadonlyArray<StandardIssue>;
+}
+type StandardResult<Output> = StandardSuccess<Output> | StandardFailure;
+interface StandardTypes<Input = unknown, Output = Input> {
+  readonly input: Input;
+  readonly output: Output;
+}
+interface StandardJSONSchemaOptions {
+  readonly target: "draft-2020-12" | "draft-07" | "openapi-3.0" | (string & {});
+  readonly libraryOptions?: Readonly<Record<string, unknown>> | undefined;
+}
+interface FormSchema<Input = unknown, Output = Input> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly types?: StandardTypes<Input, Output> | undefined;
+    readonly validate: (value: unknown, options?: {
+      readonly libraryOptions?: Readonly<Record<string, unknown>> | undefined;
+    }) => StandardResult<Output> | Promise<StandardResult<Output>>;
+    readonly jsonSchema: {
+      readonly input: (options: StandardJSONSchemaOptions) => Record<string, unknown>;
+      readonly output: (options: StandardJSONSchemaOptions) => Record<string, unknown>;
+    };
+  };
+}
+type InferInput<Schema extends FormSchema> = NonNullable<Schema["~standard"]["types"]>["input"];
+type InferOutput<Schema extends FormSchema> = NonNullable<Schema["~standard"]["types"]>["output"];
+//#endregion
+//#region src/compile.d.ts
+declare class SchemaConversionError extends Error {
+  override readonly name = "SchemaConversionError";
+  constructor(message: string, options?: ErrorOptions);
+}
+declare function toInputJsonSchema<Schema extends FormSchema>(schema: Schema, config?: FormConfig<InferInput<Schema>, string>): JsonSchemaObject;
+declare function compileForm<Schema extends FormSchema, Control extends string = never>(schema: Schema, config?: FormConfig<InferInput<Schema>, Control>): FormModel<InferInput<Schema>, Control>;
+//#endregion
+//#region src/defaults.d.ts
+declare function defaultValueForNode(node: FormNode<string, unknown>): unknown;
+declare function getDefaultValues<Input, Control extends string>(model: FormModel<Input, Control>): DeepPartial<Input>;
+//#endregion
+//#region src/prepare.d.ts
+/**
+* Converts browser form values to schema input: optional blanks become absent,
+* nullable blanks become null, and presentation-hidden branches are pruned.
+*/
+declare function prepareFormValues<Input, Control extends string>(model: FormModel<Input, Control>, values: unknown): unknown;
+//#endregion
+//#region src/options.d.ts
+/** Stable DOM serialization for non-string option values. */
+declare function serializeOptionValue(value: JsonPrimitive): string;
+declare function optionForSerializedValue(options: readonly FormOption[], serialized: string): FormOption | undefined;
+//#endregion
+//#region src/submission.d.ts
+type SubmissionErrorKind = "business" | "transport" | "validation";
+interface IdleSubmission {
+  readonly status: "idle";
+}
+interface SuccessfulSubmission<Data = unknown> {
+  readonly status: "success";
+  readonly data?: Data;
+  readonly message?: string;
+}
+interface FailedSubmission {
+  readonly status: "error";
+  readonly errorKind: SubmissionErrorKind;
+  readonly fieldErrors: Readonly<Record<string, readonly string[]>>;
+  readonly formErrors: readonly string[];
+}
+type SubmissionState<Data = unknown> = FailedSubmission | IdleSubmission | SuccessfulSubmission<Data>;
+type SubmissionAction<Payload, Data = unknown> = (previousState: SubmissionState<Data>, payload: Payload) => Promise<SubmissionState<Data>>;
+declare const initialSubmissionState: IdleSubmission;
+declare function submissionFailure(options?: {
+  readonly errorKind?: SubmissionErrorKind;
+  readonly fieldErrors?: Readonly<Record<string, readonly string[]>>;
+  readonly formErrors?: readonly string[];
+}): FailedSubmission;
+declare function submissionSuccess<Data = undefined>(data?: Data, message?: string): SuccessfulSubmission<Data>;
+declare function isSubmissionState(value: unknown): value is SubmissionState;
+//#endregion
+//#region src/rules.d.ts
+declare function resolveFieldState<Values>(state: FieldState<Values> | undefined, values: Readonly<DeepPartial<Values>>, fallback?: boolean): boolean;
+declare function isEmptyFieldValue(value: unknown): boolean;
+/** Validates portable presentation rules that are intentionally outside the schema. */
+declare function validatePresentationRules<Input, Control extends string>(model: FormModel<Input, Control>, values: Readonly<DeepPartial<Input>>): readonly StandardIssue[];
+//#endregion
+//#region src/validation.d.ts
+type ValidationResult<Output> = {
+  readonly success: true;
+  readonly data: Output;
+} | {
+  readonly success: false;
+  readonly issues: readonly StandardIssue[];
+};
+declare function issuePath(issue: StandardIssue): readonly PropertyKey[];
+declare function issuesToFieldErrors(issues: readonly StandardIssue[]): Readonly<Record<string, readonly string[]>>;
+declare function validate<Schema extends FormSchema>(schema: Schema, value: unknown): Promise<ValidationResult<InferOutput<Schema>>>;
+//#endregion
+export { type ArrayConfig, type ArrayField, type AsyncFieldValidationContext, type AsyncFieldValidationSignal, type AsyncFieldValidator, type BuiltInControl, type DeepPartial, type FailedSubmission, type FieldConfig, type FieldDataType, type FieldOptions, type FieldPath, type FieldPredicate, type FieldState, type FormConfig, type FormModel, type FormNode, type FormOption, type FormSchema, type IdleSubmission, type InferInput, type InferOutput, type JsonPrimitive, type JsonSchema, type JsonSchemaObject, type JsonValue, type MaybePromise, type NativeInputType, type ObjectField, type PathValue, RESERVED_FORM_PATH_SEGMENTS, type ReservedFormPathSegment, type ResolvedFieldConfig, type ScalarConstraints, type ScalarField, SchemaConversionError, type StandardFailure, type StandardIssue, type StandardJSONSchemaOptions, type StandardResult, type StandardSuccess, type StandardTypes, type SubmissionAction, type SubmissionErrorKind, type SubmissionState, type SuccessfulSubmission, type UnsupportedField, type ValidationResult, compileForm, defaultValueForNode, getDefaultValues, initialSubmissionState, isEmptyFieldValue, isReservedFormPathSegment, isSubmissionState, issuePath, issuesToFieldErrors, optionForSerializedValue, pathToConfigPath, pathToName, prepareFormValues, resolveFieldState, serializeOptionValue, submissionFailure, submissionSuccess, toInputJsonSchema, validate, validatePresentationRules };
+//# sourceMappingURL=index.d.ts.map