@lucas-barake/effect-form 0.13.0 → 0.15.0

package/src/FormBuilder.ts

@@ -14,72 +14,31 @@ import type {
 } from "./Field.js"
 import { isArrayFieldDef, isFieldDef, makeField } from "./Field.js"
 
-/**
- * @category Models
- */
 export interface SubmittedValues<TFields extends FieldsRecord> {
   readonly encoded: EncodedFromFields<TFields>
   readonly decoded: DecodedFromFields<TFields>
 }
 
-/**
- * Unique identifier for Field references.
- *
- * @category Symbols
- * @internal
- */
 export const FieldTypeId: unique symbol = Symbol.for("@lucas-barake/effect-form/Field")
 
-/**
- * @category Symbols
- * @internal
- */
 export type FieldTypeId = typeof FieldTypeId
 
-/**
- * A field reference carrying type and path info for type-safe setValue operations.
- *
- * @category Models
- */
 export interface FieldRef<S> {
   readonly [FieldTypeId]: FieldTypeId
   readonly _S: S
   readonly key: string
 }
 
-/**
- * Creates a field reference for type-safe setValue operations.
- *
- * @category Constructors
- * @internal
- */
 export const makeFieldRef = <S>(key: string): FieldRef<S> => ({
   [FieldTypeId]: FieldTypeId,
   _S: undefined as any,
   key,
 })
 
-// ================================
-// FormBuilder
-// ================================
-
-/**
- * Unique identifier for FormBuilder instances.
- *
- * @category Symbols
- */
 export const TypeId: unique symbol = Symbol.for("@lucas-barake/effect-form/Form")
 
-/**
- * @category Symbols
- */
 export type TypeId = typeof TypeId
 
-/**
- * The state of a form at runtime.
- *
- * @category Models
- */
 export interface FormState<TFields extends FieldsRecord> {
   readonly values: EncodedFromFields<TFields>
   readonly initialValues: EncodedFromFields<TFields>
@@ -101,123 +60,38 @@ interface AsyncRefinement {
 
 type Refinement = SyncRefinement | AsyncRefinement
 
-/**
- * A builder for constructing type-safe forms with Effect Schema validation.
- *
- * **Details**
- *
- * FormBuilder uses a fluent API pattern to define form fields. Each field
- * includes a Schema for validation. The builder accumulates field definitions
- * and context requirements (`R`) from schemas that use Effect services.
- *
- * @category Models
- */
 export interface FormBuilder<TFields extends FieldsRecord, R> {
   readonly [TypeId]: TypeId
   readonly fields: TFields
   readonly refinements: ReadonlyArray<Refinement>
   readonly _R?: R
 
-  /**
-   * Adds a scalar field to the form builder.
-   *
-   * @example
-   * ```ts
-   * const NameField = Field.makeField("name", Schema.String)
-   * const form = FormBuilder.empty.addField(NameField)
-   * ```
-   */
   addField<K extends string, S extends Schema.Schema.Any>(
     this: FormBuilder<TFields, R>,
     field: FieldDef<K, S>,
   ): FormBuilder<TFields & { readonly [key in K]: FieldDef<K, S> }, R | Schema.Schema.Context<S>>
 
-  /**
-   * Adds an array field to the form builder.
-   *
-   * @example
-   * ```ts
-   * const ItemsField = Field.makeArrayField("items", Schema.Struct({ name: Schema.String }))
-   * const form = FormBuilder.empty.addField(ItemsField)
-   * ```
-   */
   addField<K extends string, S extends Schema.Schema.Any>(
     this: FormBuilder<TFields, R>,
     field: ArrayFieldDef<K, S>,
   ): FormBuilder<TFields & { readonly [key in K]: ArrayFieldDef<K, S> }, R | Schema.Schema.Context<S>>
 
-  /**
-   * Adds a scalar field using inline key and schema.
-   * Shorthand for `Field.makeField(key, schema)` when field reuse is not needed.
-   *
-   * @example
-   * ```ts
-   * const form = FormBuilder.empty
-   *   .addField("email", Schema.String)
-   *   .addField("age", Schema.Number)
-   * ```
-   */
   addField<K extends string, S extends Schema.Schema.Any>(
     this: FormBuilder<TFields, R>,
     key: K,
     schema: S,
   ): FormBuilder<TFields & { readonly [key in K]: FieldDef<K, S> }, R | Schema.Schema.Context<S>>
 
-  /**
-   * Merges another FormBuilder's fields into this one.
-   * Useful for composing reusable field groups.
-   *
-   * @example
-   * ```ts
-   * const addressFields = FormBuilder.empty
-   *   .addField("street", Schema.String)
-   *   .addField("city", Schema.String)
-   *
-   * const userForm = FormBuilder.empty
-   *   .addField("name", Schema.String)
-   *   .merge(addressFields)
-   * ```
-   */
   merge<TFields2 extends FieldsRecord, R2>(
     this: FormBuilder<TFields, R>,
     other: FormBuilder<TFields2, R2>,
   ): FormBuilder<TFields & TFields2, R | R2>
 
-  /**
-   * Adds a synchronous cross-field validation refinement to the form.
-   *
-   * @example
-   * ```ts
-   * const form = FormBuilder.empty
-   *   .addField("password", Schema.String)
-   *   .addField("confirmPassword", Schema.String)
-   *   .refine((values) => {
-   *     if (values.password !== values.confirmPassword) {
-   *       return { path: ["confirmPassword"], message: "Passwords must match" }
-   *     }
-   *   })
-   * ```
-   */
   refine(
     this: FormBuilder<TFields, R>,
     predicate: (values: DecodedFromFields<TFields>) => Schema.FilterOutput,
   ): FormBuilder<TFields, R>
 
-  /**
-   * Adds an asynchronous cross-field validation refinement to the form.
-   *
-   * @example
-   * ```ts
-   * const form = FormBuilder.empty
-   *   .addField("username", Schema.String)
-   *   .refineEffect((values) =>
-   *     Effect.gen(function* () {
-   *       const taken = yield* checkUsername(values.username)
-   *       if (taken) return { path: ["username"], message: "Already taken" }
-   *     })
-   *   )
-   * ```
-   */
   refineEffect<RD>(
     this: FormBuilder<TFields, R>,
     predicate: (values: DecodedFromFields<TFields>) => Effect.Effect<Schema.FilterOutput, never, RD>,
@@ -274,49 +148,8 @@ const FormBuilderProto = {
   },
 }
 
-/**
- * Checks if a value is a `FormBuilder`.
- *
- * @example
- * ```ts
- * import { FormBuilder } from "@lucas-barake/effect-form"
- *
- * const builder = FormBuilder.empty
- *
- * console.log(FormBuilder.isFormBuilder(builder))
- * // Output: true
- *
- * console.log(FormBuilder.isFormBuilder({}))
- * // Output: false
- * ```
- *
- * @category Guards
- */
 export const isFormBuilder = (u: unknown): u is FormBuilder<any, any> => Predicate.hasProperty(u, TypeId)
 
-/**
- * An empty `FormBuilder` to start building a form.
- *
- * **Details**
- *
- * This is the entry point for building a form. Use method chaining to add
- * fields and then build the form with a React adapter.
- *
- * @example
- * ```ts
- * import { Field, FormBuilder } from "@lucas-barake/effect-form"
- * import * as Schema from "effect/Schema"
- *
- * const EmailField = Field.makeField("email", Schema.String)
- * const PasswordField = Field.makeField("password", Schema.String)
- *
- * const loginForm = FormBuilder.empty
- *   .addField(EmailField)
- *   .addField(PasswordField)
- * ```
- *
- * @category Constructors
- */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export const empty: FormBuilder<{}, never> = (() => {
   const self = Object.create(FormBuilderProto)
@@ -325,11 +158,6 @@ export const empty: FormBuilder<{}, never> = (() => {
   return self
 })()
 
-/**
- * Builds a combined Schema from a FormBuilder's field definitions.
- *
- * @category Schema
- */
 export const buildSchema = <TFields extends FieldsRecord, R>(
   self: FormBuilder<TFields, R>,
 ): Schema.Schema<DecodedFromFields<TFields>, EncodedFromFields<TFields>, R> => {

package/src/Mode.ts

@@ -1,22 +1,5 @@
-/**
- * Form validation mode configuration.
- */
 import * as Duration from "effect/Duration"
 
-/**
- * Controls when field validation is triggered and whether form auto-submits.
- *
- * Simple modes (string):
- * - `"onSubmit"`: Validation only runs when the form is submitted (default)
- * - `"onBlur"`: Validation runs when a field loses focus
- * - `"onChange"`: Validation runs on every value change (sync)
- *
- * Object modes (with options):
- * - `{ onChange: { debounce, autoSubmit? } }`: Debounced validation, optional auto-submit
- * - `{ onBlur: { autoSubmit: true } }`: Validate on blur, auto-submit when valid
- *
- * @category Models
- */
 export type FormMode =
   | "onSubmit"
   | "onBlur"
@@ -25,34 +8,18 @@ export type FormMode =
   | { readonly onBlur: { readonly autoSubmit: true } }
   | { readonly onChange: { readonly debounce: Duration.DurationInput; readonly autoSubmit: true } }
 
-/**
- * Form mode without auto-submit options.
- * Used when SubmitArgs is not void, since auto-submit cannot provide custom arguments.
- *
- * @category Models
- */
 export type FormModeWithoutAutoSubmit =
   | "onSubmit"
   | "onBlur"
   | "onChange"
   | { readonly onChange: { readonly debounce: Duration.DurationInput; readonly autoSubmit?: false } }
 
-/**
- * Parsed form mode with resolved values.
- *
- * @category Models
- */
 export interface ParsedMode {
   readonly validation: "onSubmit" | "onBlur" | "onChange"
   readonly debounce: number | null
   readonly autoSubmit: boolean
 }
 
-/**
- * Parses a FormMode into a normalized ParsedMode.
- *
- * @category Parsing
- */
 export const parse = (mode: FormMode = "onSubmit"): ParsedMode => {
   if (typeof mode === "string") {
     return { validation: mode, debounce: null, autoSubmit: false }

package/src/Path.ts

@@ -1,15 +1,5 @@
-/**
- * Path utilities for form field operations.
- */
-
 const BRACKET_NOTATION_REGEX = /\[(\d+)\]/g
 
-/**
- * Converts a schema path array to a dot/bracket notation string.
- *
- * @example
- * schemaPathToFieldPath(["items", 0, "name"]) // "items[0].name"
- */
 export const schemaPathToFieldPath = (path: ReadonlyArray<PropertyKey>): string => {
   if (path.length === 0) return ""
 
@@ -25,21 +15,9 @@ export const schemaPathToFieldPath = (path: ReadonlyArray<PropertyKey>): string
   return result
 }
 
-/**
- * Checks if a path matches a root path or is a descendant of it.
- * Handles both dot notation (root.child) and bracket notation (root[0]).
- *
- * @example
- * isPathUnderRoot("items[0].name", "items[0]") // true
- * isPathUnderRoot("items[0].name", "items") // true
- * isPathUnderRoot("other", "items") // false
- */
 export const isPathUnderRoot = (path: string, rootPath: string): boolean =>
   path === rootPath || path.startsWith(rootPath + ".") || path.startsWith(rootPath + "[")
 
-/**
- * Checks if a field path or any of its parent paths are in the dirty set.
- */
 export const isPathOrParentDirty = (dirtyFields: ReadonlySet<string>, path: string): boolean => {
   if (dirtyFields.has(path)) return true
 
@@ -58,12 +36,6 @@ export const isPathOrParentDirty = (dirtyFields: ReadonlySet<string>, path: stri
   return false
 }
 
-/**
- * Gets a nested value from an object using dot/bracket notation path.
- *
- * @example
- * getNestedValue({ items: [{ name: "A" }] }, "items[0].name") // "A"
- */
 export const getNestedValue = (obj: unknown, path: string): unknown => {
   if (path === "") return obj
   const parts = path.replace(BRACKET_NOTATION_REGEX, ".$1").split(".")
@@ -75,13 +47,6 @@ export const getNestedValue = (obj: unknown, path: string): unknown => {
   return current
 }
 
-/**
- * Sets a nested value in an object immutably using dot/bracket notation path.
- *
- * @example
- * setNestedValue({ items: [{ name: "A" }] }, "items[0].name", "B")
- * // { items: [{ name: "B" }] }
- */
 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(".")

package/src/Validation.ts

@@ -1,25 +1,10 @@
-/**
- * Validation utilities for form error handling.
- */
 import * as Option from "effect/Option"
 import * as ParseResult from "effect/ParseResult"
 import type * as AST from "effect/SchemaAST"
 import { schemaPathToFieldPath } from "./Path.js"
 
-/**
- * Source of a validation error.
- * - 'field': Error from field schema validation (e.g., minLength, pattern)
- * - 'refinement': Error from cross-field refinement (e.g., password !== confirm)
- *
- * @category Models
- */
 export type ErrorSource = "field" | "refinement"
 
-/**
- * A validation error entry with its source.
- *
- * @category Models
- */
 export interface ErrorEntry {
   readonly message: string
   readonly source: ErrorSource
@@ -35,10 +20,6 @@ const getBaseAST = (ast: AST.AST): AST.AST => {
   }
 }
 
-/**
- * Returns true if the AST represents a composite type where refinements indicate cross-field validation.
- * Covers: Schema.Struct, Class, Tuple, Union, Suspend.
- */
 const isCompositeType = (ast: AST.AST): boolean => {
   const base = getBaseAST(ast)
   switch (base._tag) {
@@ -53,11 +34,6 @@ const isCompositeType = (ast: AST.AST): boolean => {
   }
 }
 
-/**
- * Extracts the first error message from a ParseError.
- *
- * @category Error Handling
- */
 export const extractFirstError = (error: ParseResult.ParseError): Option.Option<string> => {
   const issues = ParseResult.ArrayFormatter.formatErrorSync(error)
   if (issues.length === 0) {
@@ -66,12 +42,6 @@ export const extractFirstError = (error: ParseResult.ParseError): Option.Option<
   return Option.some(issues[0].message)
 }
 
-/**
- * Routes validation errors from a ParseError to a map of field paths to error messages.
- * Used for cross-field validation where schema errors need to be displayed on specific fields.
- *
- * @category Error Handling
- */
 export const routeErrors = (error: ParseResult.ParseError): Map<string, string> => {
   const result = new Map<string, string>()
   const issues = ParseResult.ArrayFormatter.formatErrorSync(error)
@@ -140,17 +110,6 @@ const determineErrorSources = (error: ParseResult.ParseError): Map<string, Error
   return sources
 }
 
-/**
- * Routes validation errors with source tracking.
- *
- * Source determination:
- * - `kind: "Predicate"` on composite types → "refinement" (cross-field validation)
- * - All other errors → "field" (per-field schema validation)
- *
- * Empty string key ("") stores root-level errors (refinements without specific paths).
- *
- * @category Error Handling
- */
 export const routeErrorsWithSource = (error: ParseResult.ParseError): Map<string, ErrorEntry> => {
   const result = new Map<string, ErrorEntry>()
   const formattedIssues = ParseResult.ArrayFormatter.formatErrorSync(error)

package/src/index.ts

@@ -1,31 +1,34 @@
-/**
- * Field definitions for type-safe forms.
- */
+
 export * as Field from "./Field.js"
 
 /**
- * Atoms for a single field.
- *
- * @category Models
- */
+   * Root anchor atom for the form's dependency graph.
+   * Mount this atom to keep all form state alive even when field components unmount.
+   *
+   * Useful for:
+   * - Multi-step wizards where steps unmount but state should persist
+   * - Conditional fields (toggles) where state should survive visibility changes
+   *
+   * @example
+   * ```tsx
+   * // Keep form state alive at wizard root level
+   * function Wizard() {
+   *   useAtomMount(step1Form.mount)
+   *   useAtomMount(step2Form.mount)
+   *   return currentStep === 1 ? <Step1 /> : <Step2 />
+   * }
+   * ```
+   */
 export * as FormAtoms from "./FormAtoms.js"
 
-/**
- * @category Models
- */
+
 export * as FormBuilder from "./FormBuilder.js"
 
-/**
- * Form validation mode configuration.
- */
+
 export * as Mode from "./Mode.js"
 
-/**
- * Path utilities for form field operations.
- */
+
 export * as Path from "./Path.js"
 
-/**
- * Validation utilities for form error handling.
- */
+
 export * as Validation from "./Validation.js"

package/src/internal/dirty.ts

@@ -1,16 +1,7 @@
-/**
- * Internal dirty tracking algorithms.
- *
- * @internal
- */
 import * as Equal from "effect/Equal"
 import * as Utils from "effect/Utils"
 import { getNestedValue, isPathUnderRoot } from "../Path.js"
 
-/**
- * Recalculates dirty fields for an array after mutation.
- * Clears all paths under the array and re-evaluates each item.
- */
 export const recalculateDirtyFieldsForArray = (
   dirtyFields: ReadonlySet<string>,
   initialValues: unknown,
@@ -50,12 +41,6 @@ export const recalculateDirtyFieldsForArray = (
   return nextDirty
 }
 
-/**
- * Recalculates dirty fields for a subtree after value change.
- * Clears the rootPath and all children, then re-evaluates recursively.
- *
- * @param rootPath - Empty string for full form, or a specific path for targeted update
- */
 export const recalculateDirtySubtree = (
   currentDirty: ReadonlySet<string>,
   allInitial: unknown,

package/src/internal/weak-registry.ts

@@ -1,14 +1,3 @@
-/**
- * Internal WeakRef-based registry for caching atoms.
- *
- * @internal
- */
-
-/**
- * A registry that uses WeakRef to allow garbage collection of cached values.
- *
- * @internal
- */
 export interface WeakRegistry<V extends object> {
   readonly get: (key: string) => V | undefined
   readonly set: (key: string, value: V) => void
@@ -17,12 +6,6 @@ export interface WeakRegistry<V extends object> {
   readonly values: () => IterableIterator<V>
 }
 
-/**
- * Creates a WeakRef-based registry with automatic cleanup via FinalizationRegistry.
- * Falls back to a regular Map in environments without WeakRef support.
- *
- * @internal
- */
 export const createWeakRegistry = <V extends object>(): WeakRegistry<V> => {
   if (typeof WeakRef === "undefined" || typeof FinalizationRegistry === "undefined") {
     const map = new Map<string, V>()