@voila.dev/effect-form 0.27.0

package/src/FormBuilder.ts

@@ -0,0 +1,235 @@
+import type * as Effect from "effect/Effect";
+import type * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import * as SchemaGetter from "effect/SchemaGetter";
+import type * as AtomRegistry from "effect/unstable/reactivity/AtomRegistry";
+
+import type {
+	AnyFieldDef,
+	ArrayFieldDef,
+	DecodedFromFields,
+	EncodedFromFields,
+	FieldDef,
+	FieldsRecord,
+} from "./Field.ts";
+import { isArrayFieldDef, isFieldDef, makeField } from "./Field.ts";
+
+/**
+ * Flattens an intersection of field records into a single object type so that
+ * hover types and error messages display as `{ email: ...; password: ... }`
+ * instead of `{ email: ... } & { password: ... } & ...`.
+ *
+ * Note: `Types.Simplify` from effect is not used here because its
+ * `extends infer B ? B : never` indirection erases the `FieldsRecord`
+ * constraint in generic positions.
+ */
+type Simplify<T> = { readonly [K in keyof T]: T[K] } & {};
+
+export interface SubmittedValues<TFields extends FieldsRecord> {
+	readonly encoded: EncodedFromFields<TFields>;
+	readonly decoded: DecodedFromFields<TFields>;
+}
+
+export const FieldTypeId: unique symbol = Symbol.for(
+	"@voila.dev/effect-form/Field",
+);
+
+export type FieldTypeId = typeof FieldTypeId;
+
+export interface FieldRef<S> {
+	readonly [FieldTypeId]: FieldTypeId;
+	readonly _S: S;
+	readonly key: string;
+}
+
+export const makeFieldRef = <S>(key: string): FieldRef<S> => ({
+	[FieldTypeId]: FieldTypeId,
+	_S: undefined as any,
+	key,
+});
+
+export const TypeId: unique symbol = Symbol.for("@voila.dev/effect-form/Form");
+
+export type TypeId = typeof TypeId;
+
+export interface FormState<TFields extends FieldsRecord> {
+	readonly values: EncodedFromFields<TFields>;
+	readonly initialValues: EncodedFromFields<TFields>;
+	readonly lastSubmittedValues: Option.Option<SubmittedValues<TFields>>;
+	readonly touched: { readonly [K in keyof TFields]: boolean };
+	readonly submitCount: number;
+	readonly validationCount: number;
+	readonly dirtyFields: ReadonlySet<string>;
+}
+
+interface SyncRefinement {
+	readonly _tag: "sync";
+	readonly fn: (values: unknown) => Schema.FilterOutput;
+}
+
+interface AsyncRefinement {
+	readonly _tag: "async";
+	readonly fn: (
+		values: unknown,
+	) => Effect.Effect<undefined | boolean | Schema.FilterIssue, never, unknown>;
+}
+
+type Refinement = SyncRefinement | AsyncRefinement;
+
+export interface FormBuilder<TFields extends FieldsRecord, R> {
+	readonly [TypeId]: TypeId;
+	readonly fields: TFields;
+	readonly refinements: ReadonlyArray<Refinement>;
+	readonly _R?: R;
+
+	addField<K extends string, S extends Schema.Top>(
+		this: FormBuilder<TFields, R>,
+		field: FieldDef<K, S>,
+	): FormBuilder<
+		Simplify<TFields & { readonly [key in K]: FieldDef<K, S> }>,
+		R | Schema.Codec.DecodingServices<S>
+	>;
+
+	addField<K extends string, S extends Schema.Top>(
+		this: FormBuilder<TFields, R>,
+		field: ArrayFieldDef<K, S>,
+	): FormBuilder<
+		Simplify<TFields & { readonly [key in K]: ArrayFieldDef<K, S> }>,
+		R | Schema.Codec.DecodingServices<S>
+	>;
+
+	addField<K extends string, S extends Schema.Top>(
+		this: FormBuilder<TFields, R>,
+		key: K,
+		schema: S,
+	): FormBuilder<
+		Simplify<TFields & { readonly [key in K]: FieldDef<K, S> }>,
+		R | Schema.Codec.DecodingServices<S>
+	>;
+
+	merge<TFields2 extends FieldsRecord, R2>(
+		this: FormBuilder<TFields, R>,
+		other: FormBuilder<TFields2, R2>,
+	): FormBuilder<Simplify<TFields & TFields2>, R | R2>;
+
+	refine(
+		this: FormBuilder<TFields, R>,
+		predicate: (values: DecodedFromFields<TFields>) => Schema.FilterOutput,
+	): FormBuilder<TFields, R>;
+
+	refineEffect<RD>(
+		this: FormBuilder<TFields, R>,
+		predicate: (
+			values: DecodedFromFields<TFields>,
+		) => Effect.Effect<Schema.FilterOutput, never, RD>,
+	): FormBuilder<TFields, R | Exclude<RD, AtomRegistry.AtomRegistry>>;
+}
+
+const FormBuilderProto = {
+	[TypeId]: TypeId,
+	addField<TFields extends FieldsRecord, R>(
+		this: FormBuilder<TFields, R>,
+		keyOrField: string | AnyFieldDef,
+		schema?: Schema.Top,
+	): FormBuilder<any, any> {
+		const field =
+			typeof keyOrField === "string"
+				? makeField(keyOrField, schema!)
+				: keyOrField;
+		const newSelf = Object.create(FormBuilderProto);
+		newSelf.fields = { ...this.fields, [field.key]: field };
+		newSelf.refinements = this.refinements;
+		return newSelf;
+	},
+	merge<TFields extends FieldsRecord, R, TFields2 extends FieldsRecord, R2>(
+		this: FormBuilder<TFields, R>,
+		other: FormBuilder<TFields2, R2>,
+	): FormBuilder<TFields & TFields2, R | R2> {
+		const newSelf = Object.create(FormBuilderProto);
+		newSelf.fields = { ...this.fields, ...other.fields };
+		newSelf.refinements = [...this.refinements, ...other.refinements];
+		return newSelf;
+	},
+	refine<TFields extends FieldsRecord, R>(
+		this: FormBuilder<TFields, R>,
+		predicate: (values: DecodedFromFields<TFields>) => Schema.FilterOutput,
+	): FormBuilder<TFields, R> {
+		const newSelf = Object.create(FormBuilderProto);
+		newSelf.fields = this.fields;
+		newSelf.refinements = [
+			...this.refinements,
+			{
+				_tag: "sync" as const,
+				fn: (values: unknown) =>
+					predicate(values as DecodedFromFields<TFields>),
+			},
+		];
+		return newSelf;
+	},
+	refineEffect<TFields extends FieldsRecord, R, RD>(
+		this: FormBuilder<TFields, R>,
+		predicate: (
+			values: DecodedFromFields<TFields>,
+		) => Effect.Effect<Schema.FilterOutput, never, RD>,
+	): FormBuilder<TFields, R | Exclude<RD, AtomRegistry.AtomRegistry>> {
+		const newSelf = Object.create(FormBuilderProto);
+		newSelf.fields = this.fields;
+		newSelf.refinements = [
+			...this.refinements,
+			{
+				_tag: "async" as const,
+				fn: (values: unknown) =>
+					predicate(values as DecodedFromFields<TFields>),
+			},
+		];
+		return newSelf;
+	},
+};
+
+export const isFormBuilder = (u: unknown): u is FormBuilder<any, any> =>
+	Predicate.hasProperty(u, TypeId);
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export const empty: FormBuilder<{}, never> = (() => {
+	const self = Object.create(FormBuilderProto);
+	self.fields = {};
+	self.refinements = [];
+	return self;
+})();
+
+export const buildSchema = <TFields extends FieldsRecord, R>(
+	self: FormBuilder<TFields, R>,
+): Schema.Codec<DecodedFromFields<TFields>, EncodedFromFields<TFields>, R> => {
+	const schemaFields: Record<string, Schema.Top> = {};
+	for (const [key, def] of Object.entries(self.fields)) {
+		if (isArrayFieldDef(def)) {
+			schemaFields[key] = Schema.Array(def.itemSchema);
+		} else if (isFieldDef(def)) {
+			schemaFields[key] = def.schema;
+		}
+	}
+
+	let schema: Schema.Codec<any, any, any, any> = Schema.Struct(schemaFields);
+
+	for (const refinement of self.refinements) {
+		if (refinement._tag === "sync") {
+			schema = schema.pipe(
+				Schema.check(Schema.makeFilter((input) => refinement.fn(input))),
+			);
+		} else {
+			schema = schema.pipe(
+				Schema.decode({
+					decode: SchemaGetter.checkEffect((input) => refinement.fn(input)),
+					encode: SchemaGetter.passthrough(),
+				}),
+			);
+		}
+	}
+
+	return schema as Schema.Codec<
+		DecodedFromFields<TFields>,
+		EncodedFromFields<TFields>,
+		R
+	>;
+};

package/src/Mode.ts

@@ -0,0 +1,63 @@
+import type * as Duration from "effect/Duration";
+
+export type FormMode =
+	| {
+			readonly validation?: "onSubmit";
+			readonly autoSubmit?: false;
+			readonly debounce?: never;
+	  }
+	| {
+			readonly validation: "onBlur";
+			readonly autoSubmit?: boolean;
+			readonly debounce?: never;
+	  }
+	| {
+			readonly validation: "onChange";
+			readonly debounce?: Duration.Input;
+			readonly autoSubmit?: boolean;
+	  };
+
+export type FormModeWithoutAutoSubmit =
+	| {
+			readonly validation?: "onSubmit";
+			readonly autoSubmit?: false;
+			readonly debounce?: never;
+	  }
+	| {
+			readonly validation: "onBlur";
+			readonly autoSubmit?: false;
+			readonly debounce?: never;
+	  }
+	| {
+			readonly validation: "onChange";
+			readonly debounce?: Duration.Input;
+			readonly autoSubmit?: false;
+	  };
+
+export interface ParsedMode {
+	readonly validation: "onSubmit" | "onBlur" | "onChange";
+	readonly debounce: Duration.Input | null;
+	readonly autoSubmit: boolean;
+}
+
+export const parse = (mode?: FormMode): ParsedMode => {
+	const validation = mode?.validation ?? "onSubmit";
+
+	if (validation === "onBlur") {
+		return {
+			validation: "onBlur",
+			debounce: null,
+			autoSubmit: mode?.autoSubmit === true,
+		};
+	}
+
+	if (validation === "onChange") {
+		return {
+			validation: "onChange",
+			debounce: mode?.debounce ?? null,
+			autoSubmit: mode?.autoSubmit === true,
+		};
+	}
+
+	return { validation: "onSubmit", debounce: null, autoSubmit: false };
+};

package/src/Path.ts

@@ -0,0 +1,76 @@
+const BRACKET_NOTATION_REGEX = /\[(\d+)\]/g;
+
+export const schemaPathToFieldPath = (
+	path: ReadonlyArray<PropertyKey>,
+): string => {
+	if (path.length === 0) return "";
+
+	let result = String(path[0]);
+	for (let i = 1; i < path.length; i++) {
+		const segment = path[i];
+		if (typeof segment === "number") {
+			result += `[${segment}]`;
+		} else {
+			result += `.${String(segment)}`;
+		}
+	}
+	return result;
+};
+
+export const isPathUnderRoot = (path: string, rootPath: string): boolean =>
+	path === rootPath ||
+	path.startsWith(rootPath + ".") ||
+	path.startsWith(rootPath + "[");
+
+export const isPathOrParentDirty = (
+	dirtyFields: ReadonlySet<string>,
+	path: string,
+): boolean => {
+	if (dirtyFields.has(path)) return true;
+
+	let parent = path;
+	while (true) {
+		const lastDot = parent.lastIndexOf(".");
+		const lastBracket = parent.lastIndexOf("[");
+		const splitIndex = Math.max(lastDot, lastBracket);
+
+		if (splitIndex === -1) break;
+
+		parent = parent.substring(0, splitIndex);
+		if (dirtyFields.has(parent)) return true;
+	}
+
+	return false;
+};
+
+export const getNestedValue = (obj: unknown, path: string): unknown => {
+	if (path === "") return obj;
+	const parts = path.replace(BRACKET_NOTATION_REGEX, ".$1").split(".");
+	let current: unknown = obj;
+	for (const part of parts) {
+		if (current == null || typeof current !== "object") return undefined;
+		current = (current as Record<string, unknown>)[part];
+	}
+	return current;
+};
+
+export const setNestedValue = <T>(obj: T, path: string, value: unknown): T => {
+	if (path === "") return value as T;
+	const parts = path.replace(BRACKET_NOTATION_REGEX, ".$1").split(".");
+	const result = { ...obj } as Record<string, unknown>;
+	const lastPart = parts[parts.length - 1];
+	if (lastPart === undefined) return result as T;
+
+	let current = result;
+	for (const part of parts.slice(0, -1)) {
+		if (Array.isArray(current[part])) {
+			current[part] = [...(current[part] as Array<unknown>)];
+		} else {
+			current[part] = { ...(current[part] as Record<string, unknown>) };
+		}
+		current = current[part] as Record<string, unknown>;
+	}
+
+	current[lastPart] = value;
+	return result as T;
+};

package/src/Validation.ts

@@ -0,0 +1,167 @@
+import * as Option from "effect/Option";
+import type * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import { schemaPathToFieldPath } from "./Path.ts";
+
+export type ErrorSource = "field" | "refinement";
+
+export interface ErrorEntry {
+	readonly message: string;
+	readonly source: ErrorSource;
+}
+
+interface IssueSourceEntry {
+	readonly path: ReadonlyArray<PropertyKey>;
+	readonly source: ErrorSource;
+	readonly issue: SchemaIssue.Issue;
+}
+
+const standardFormatter = SchemaIssue.makeFormatterStandardSchemaV1();
+
+const collectIssueSources = (
+	error: Schema.SchemaError,
+): ReadonlyArray<IssueSourceEntry> => {
+	const entries: Array<IssueSourceEntry> = [];
+
+	const walk = (
+		issue: SchemaIssue.Issue,
+		path: ReadonlyArray<PropertyKey>,
+		source: ErrorSource,
+	): void => {
+		switch (issue._tag) {
+			case "Filter":
+				if (path.length === 0) {
+					walk(issue.issue, path, "refinement");
+				} else {
+					walk(issue.issue, path, source);
+				}
+				break;
+			case "Encoding":
+				if (path.length === 0) {
+					walk(issue.issue, path, "refinement");
+				} else {
+					walk(issue.issue, path, source);
+				}
+				break;
+			case "Pointer":
+				walk(issue.issue, [...path, ...issue.path], source);
+				break;
+			case "Composite":
+				for (const sub of issue.issues) {
+					walk(sub, path, source);
+				}
+				break;
+			case "AnyOf":
+				for (const sub of issue.issues) {
+					walk(sub, path, source);
+				}
+				break;
+			case "InvalidType":
+			case "InvalidValue":
+			case "MissingKey":
+			case "UnexpectedKey":
+			case "Forbidden":
+			case "OneOf":
+				entries.push({ path, source, issue });
+				break;
+		}
+	};
+
+	walk(error.issue, [], "field");
+	return entries;
+};
+
+const getIssueMessage = (issue: SchemaIssue.Issue): string | undefined => {
+	const formatted = standardFormatter(issue);
+	return formatted.issues[0]?.message;
+};
+
+export const extractFirstError = (
+	error: Schema.SchemaError,
+): Option.Option<string> => {
+	const formatted = standardFormatter(error.issue);
+	if (formatted.issues.length === 0) {
+		return Option.none();
+	}
+	const issue = formatted.issues[0];
+	return issue === undefined ? Option.none() : Option.some(issue.message);
+};
+
+const normalizePath = (
+	path: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }> | undefined,
+): ReadonlyArray<PropertyKey> => {
+	if (!path) return [];
+	return path.map((segment) =>
+		typeof segment === "object" && segment !== null && "key" in segment
+			? segment.key
+			: (segment as PropertyKey),
+	);
+};
+
+export const routeErrors = (error: Schema.SchemaError): Map<string, string> => {
+	const result = new Map<string, string>();
+	const formatted = standardFormatter(error.issue);
+
+	for (const issue of formatted.issues) {
+		const fieldPath = schemaPathToFieldPath(normalizePath(issue.path));
+		if (fieldPath && !result.has(fieldPath)) {
+			result.set(fieldPath, issue.message);
+		}
+	}
+
+	return result;
+};
+
+export const routeErrorsWithSource = (
+	error: Schema.SchemaError,
+): Map<string, ErrorEntry> => {
+	const result = new Map<string, ErrorEntry>();
+	const formattedIssues = standardFormatter(error.issue).issues;
+	const issueSources = collectIssueSources(error);
+	const messageSources = new Map<string, ErrorSource>();
+	const refinementPaths = new Set<string>();
+
+	for (const entry of issueSources) {
+		const fieldPath = schemaPathToFieldPath(entry.path) ?? "";
+		const message = getIssueMessage(entry.issue);
+		if (message !== undefined) {
+			const messageKey = `${fieldPath}::${message}`;
+			const existing = messageSources.get(messageKey);
+			if (
+				!existing ||
+				(existing === "field" && entry.source === "refinement")
+			) {
+				messageSources.set(messageKey, entry.source);
+			}
+		}
+		if (entry.source === "refinement") {
+			refinementPaths.add(fieldPath);
+		}
+	}
+
+	for (const issue of formattedIssues) {
+		const fieldPath = schemaPathToFieldPath(normalizePath(issue.path)) ?? "";
+		if (result.has(fieldPath)) continue;
+		const preferredSource: ErrorSource = refinementPaths.has(fieldPath)
+			? "refinement"
+			: "field";
+		const messageKey = `${fieldPath}::${issue.message}`;
+		const issueSource = messageSources.get(messageKey) ?? "field";
+		if (preferredSource === "refinement" && issueSource !== "refinement") {
+			continue;
+		}
+		result.set(fieldPath, { message: issue.message, source: issueSource });
+	}
+
+	if (result.size < formattedIssues.length) {
+		for (const issue of formattedIssues) {
+			const fieldPath = schemaPathToFieldPath(normalizePath(issue.path)) ?? "";
+			if (result.has(fieldPath)) continue;
+			const messageKey = `${fieldPath}::${issue.message}`;
+			const issueSource = messageSources.get(messageKey) ?? "field";
+			result.set(fieldPath, { message: issue.message, source: issueSource });
+		}
+	}
+
+	return result;
+};

package/src/index.ts

@@ -0,0 +1,13 @@
+export * as Field from "./Field.ts";
+
+export * as FieldState from "./FieldState.ts";
+
+export * as FormAtoms from "./FormAtoms.ts";
+
+export * as FormBuilder from "./FormBuilder.ts";
+
+export * as Mode from "./Mode.ts";
+
+export * as Path from "./Path.ts";
+
+export * as Validation from "./Validation.ts";

package/src/internal/dirty.ts

@@ -0,0 +1,113 @@
+import * as Equal from "effect/Equal";
+import { getNestedValue, isPathUnderRoot } from "../Path.ts";
+
+export const recalculateDirtyFieldsForArray = (
+	dirtyFields: ReadonlySet<string>,
+	initialValues: unknown,
+	arrayPath: string,
+	newItems: ReadonlyArray<unknown>,
+): ReadonlySet<string> => {
+	const initialItems = (getNestedValue(initialValues, arrayPath) ??
+		[]) as ReadonlyArray<unknown>;
+
+	if (newItems === initialItems) {
+		return dirtyFields;
+	}
+
+	const nextDirty = new Set(
+		Array.from(dirtyFields).filter((path) => !isPathUnderRoot(path, arrayPath)),
+	);
+
+	const loopLength = Math.max(newItems.length, initialItems.length);
+	for (let i = 0; i < loopLength; i++) {
+		const itemPath = `${arrayPath}[${i}]`;
+		const newItem = newItems[i];
+		const initialItem = initialItems[i];
+
+		if (newItem === initialItem) continue;
+
+		if (!Equal.equals(newItem, initialItem)) {
+			nextDirty.add(itemPath);
+		}
+	}
+
+	if (newItems.length !== initialItems.length) {
+		nextDirty.add(arrayPath);
+	} else {
+		nextDirty.delete(arrayPath);
+	}
+
+	return nextDirty;
+};
+
+export const recalculateDirtySubtree = (
+	currentDirty: ReadonlySet<string>,
+	allInitial: unknown,
+	allValues: unknown,
+	rootPath: string = "",
+): ReadonlySet<string> => {
+	const targetValue = rootPath
+		? getNestedValue(allValues, rootPath)
+		: allValues;
+	const targetInitial = rootPath
+		? getNestedValue(allInitial, rootPath)
+		: allInitial;
+
+	if (targetValue === targetInitial) {
+		if (rootPath === "") {
+			return new Set();
+		}
+
+		let changed = false;
+		const nextDirty = new Set(currentDirty);
+		for (const path of currentDirty) {
+			if (isPathUnderRoot(path, rootPath)) {
+				nextDirty.delete(path);
+				changed = true;
+			}
+		}
+		return changed ? nextDirty : currentDirty;
+	}
+
+	const nextDirty = new Set(currentDirty);
+
+	if (rootPath === "") {
+		nextDirty.clear();
+	} else {
+		for (const path of nextDirty) {
+			if (isPathUnderRoot(path, rootPath)) {
+				nextDirty.delete(path);
+			}
+		}
+	}
+
+	const recurse = (current: unknown, initial: unknown, path: string): void => {
+		if (current === initial) return;
+
+		if (Array.isArray(current)) {
+			const initialArr = (initial ?? []) as ReadonlyArray<unknown>;
+			for (let i = 0; i < Math.max(current.length, initialArr.length); i++) {
+				recurse(current[i], initialArr[i], path ? `${path}[${i}]` : `[${i}]`);
+			}
+		} else if (current !== null && typeof current === "object") {
+			const initialObj = (initial ?? {}) as Record<string, unknown>;
+			for (const key in current as object) {
+				recurse(
+					(current as Record<string, unknown>)[key],
+					initialObj[key],
+					path ? `${path}.${key}` : key,
+				);
+			}
+			for (const key in initialObj) {
+				if (!(key in (current as object))) {
+					recurse(undefined, initialObj[key], path ? `${path}.${key}` : key);
+				}
+			}
+		} else {
+			if (!Equal.equals(current, initial) && path) nextDirty.add(path);
+		}
+	};
+
+	recurse(targetValue, targetInitial, rootPath);
+	return nextDirty;
+};