@lucas-barake/effect-form 0.1.0 → 0.2.0

package/src/Form.ts

@@ -5,19 +5,15 @@ import type * as Effect from "effect/Effect"
 import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
 
-/**
- * Unique identifier for FormBuilder instances.
- *
- * @since 1.0.0
- * @category Symbols
- */
-export const TypeId: unique symbol = Symbol.for("@lucas-barake/effect-form/Form")
-
-/**
- * @since 1.0.0
- * @category Symbols
- */
-export type TypeId = typeof TypeId
+import type {
+  AnyFieldDef,
+  ArrayFieldDef,
+  DecodedFromFields,
+  EncodedFromFields,
+  FieldDef,
+  FieldsRecord,
+} from "./Field.js"
+import { isArrayFieldDef, isFieldDef } from "./Field.js"
 
 /**
  * Unique identifier for Field references.
@@ -60,117 +56,23 @@ export const makeFieldRef = <S>(key: string): Field<S> => ({
   key,
 })
 
-/**
- * A scalar field definition containing the key and schema.
- *
- * @since 1.0.0
- * @category Models
- */
-export interface FieldDef<K extends string, S extends Schema.Schema.Any> {
-  readonly _tag: "field"
-  readonly key: K
-  readonly schema: S
-}
-
-/**
- * An array field definition containing a schema for items.
- *
- * @since 1.0.0
- * @category Models
- */
-export interface ArrayFieldDef<K extends string, S extends Schema.Schema.Any> {
-  readonly _tag: "array"
-  readonly key: K
-  readonly itemSchema: S
-}
-
-/**
- * Union of all field definition types.
- *
- * @since 1.0.0
- * @category Models
- */
-export type AnyFieldDef = FieldDef<string, Schema.Schema.Any> | ArrayFieldDef<string, Schema.Schema.Any>
-
-/**
- * Creates a scalar field definition.
- *
- * @example
- * ```ts
- * const NameField = Form.makeField("name", Schema.String)
- * const form = Form.empty.addField(NameField)
- * ```
- *
- * @since 1.0.0
- * @category Constructors
- */
-export const makeField = <K extends string, S extends Schema.Schema.Any>(
-  key: K,
-  schema: S,
-): FieldDef<K, S> => ({
-  _tag: "field",
-  key,
-  schema,
-})
-
-/**
- * Creates an array field definition.
- *
- * @example
- * ```ts
- * // Array of primitives
- * const TagsField = Form.makeArrayField("tags", Schema.String)
- *
- * // Array of objects
- * const ItemsField = Form.makeArrayField("items", Schema.Struct({
- *   name: Schema.String,
- *   quantity: Schema.Number
- * }))
- * ```
- *
- * @since 1.0.0
- * @category Constructors
- */
-export const makeArrayField = <K extends string, S extends Schema.Schema.Any>(
-  key: K,
-  itemSchema: S,
-): ArrayFieldDef<K, S> => ({
-  _tag: "array",
-  key,
-  itemSchema,
-})
-
-/**
- * A record of field definitions.
- *
- * @since 1.0.0
- * @category Models
- */
-export type FieldsRecord = Record<string, AnyFieldDef>
+// ================================
+// FormBuilder
+// ================================
 
 /**
- * Extracts the encoded (input) type from a fields record.
+ * Unique identifier for FormBuilder instances.
  *
  * @since 1.0.0
- * @category Type Helpers
+ * @category Symbols
  */
-export type EncodedFromFields<T extends FieldsRecord> = {
-  readonly [K in keyof T]: T[K] extends FieldDef<any, infer S> ? Schema.Schema.Encoded<S>
-    : T[K] extends ArrayFieldDef<any, infer S> ? ReadonlyArray<Schema.Schema.Encoded<S>>
-    : never
-}
+export const TypeId: unique symbol = Symbol.for("@lucas-barake/effect-form/Form")
 
 /**
- * Extracts the decoded (output) type from a fields record.
- *
  * @since 1.0.0
- * @category Type Helpers
+ * @category Symbols
  */
-export type DecodedFromFields<T extends FieldsRecord> = {
-  readonly [K in keyof T]: T[K] extends FieldDef<any, infer S> ? Schema.Schema.Type<S>
-    : T[K] extends ArrayFieldDef<any, infer S> ? ReadonlyArray<Schema.Schema.Type<S>>
-    : never
-}
+export type TypeId = typeof TypeId
 
 /**
  * The state of a form at runtime.
@@ -372,56 +274,6 @@ const FormBuilderProto = {
  */
 export const isFormBuilder = (u: unknown): u is FormBuilder<any, any> => Predicate.hasProperty(u, TypeId)
 
-/**
- * Checks if a field definition is an array field.
- *
- * @since 1.0.0
- * @category Guards
- */
-export const isArrayFieldDef = (def: AnyFieldDef): def is ArrayFieldDef<string, any> => def._tag === "array"
-
-/**
- * Checks if a field definition is a simple field.
- *
- * @since 1.0.0
- * @category Guards
- */
-export const isFieldDef = (def: AnyFieldDef): def is FieldDef<string, Schema.Schema.Any> => def._tag === "field"
-
-/**
- * Gets a default encoded value from a schema.
- *
- * @since 1.0.0
- * @category Helpers
- */
-export const getDefaultFromSchema = (schema: Schema.Schema.Any): unknown => {
-  const ast = schema.ast
-  switch (ast._tag) {
-    case "StringKeyword":
-    case "TemplateLiteral":
-      return ""
-    case "NumberKeyword":
-      return 0
-    case "BooleanKeyword":
-      return false
-    case "TypeLiteral": {
-      const result: Record<string, unknown> = {}
-      for (const prop of ast.propertySignatures) {
-        result[prop.name as string] = getDefaultFromSchema(Schema.make(prop.type))
-      }
-      return result
-    }
-    case "Transformation":
-      return getDefaultFromSchema(Schema.make(ast.from))
-    case "Refinement":
-      return getDefaultFromSchema(Schema.make(ast.from))
-    case "Suspend":
-      return getDefaultFromSchema(Schema.make(ast.f()))
-    default:
-      return ""
-  }
-}
-
 /**
  * An empty `FormBuilder` to start building a form.
  *
@@ -488,35 +340,3 @@ export const buildSchema = <TFields extends FieldsRecord, R>(
     R
   >
 }
-
-/**
- * Gets default encoded values for a fields record.
- *
- * @since 1.0.0
- * @category Helpers
- */
-export const getDefaultEncodedValues = (fields: FieldsRecord): Record<string, unknown> => {
-  const result: Record<string, unknown> = {}
-  for (const [key, def] of Object.entries(fields)) {
-    if (isArrayFieldDef(def)) {
-      result[key] = []
-    } else {
-      result[key] = ""
-    }
-  }
-  return result
-}
-
-/**
- * Creates a touched record with all fields set to the given value.
- *
- * @since 1.0.0
- * @category Helpers
- */
-export const createTouchedRecord = (fields: FieldsRecord, value: boolean): Record<string, boolean> => {
-  const result: Record<string, boolean> = {}
-  for (const key of Object.keys(fields)) {
-    result[key] = value
-  }
-  return result
-}

package/src/FormAtoms.ts

@@ -15,8 +15,8 @@ import * as Option from "effect/Option"
 import type * as ParseResult from "effect/ParseResult"
 import * as Schema from "effect/Schema"
 import * as Utils from "effect/Utils"
-import type * as Form from "./Form.js"
-import { buildSchema, createTouchedRecord, getDefaultFromSchema, makeFieldRef } from "./Form.js"
+import * as Field from "./Field.js"
+import * as Form from "./Form.js"
 import { recalculateDirtyFieldsForArray, recalculateDirtySubtree } from "./internal/dirty.js"
 import { getNestedValue, setNestedValue } from "./internal/path.js"
 import { createWeakRegistry, type WeakRegistry } from "./internal/weak-registry.js"
@@ -40,7 +40,7 @@ export interface FieldAtoms {
  * @since 1.0.0
  * @category Models
  */
-export interface FormAtomsConfig<TFields extends Form.FieldsRecord, R> {
+export interface FormAtomsConfig<TFields extends Field.FieldsRecord, R> {
   readonly runtime: Atom.AtomRuntime<R, any>
   readonly formBuilder: Form.FormBuilder<TFields, R>
 }
@@ -51,9 +51,9 @@ export interface FormAtomsConfig<TFields extends Form.FieldsRecord, R> {
  * @since 1.0.0
  * @category Models
  */
-export type FieldRefs<TFields extends Form.FieldsRecord> = {
-  readonly [K in keyof TFields]: TFields[K] extends Form.FieldDef<any, infer S> ? Form.Field<Schema.Schema.Encoded<S>>
-    : TFields[K] extends Form.ArrayFieldDef<any, infer S> ? Form.Field<ReadonlyArray<Schema.Schema.Encoded<S>>>
+export type FieldRefs<TFields extends Field.FieldsRecord> = {
+  readonly [K in keyof TFields]: TFields[K] extends Field.FieldDef<any, infer S> ? Form.Field<Schema.Schema.Encoded<S>>
+    : TFields[K] extends Field.ArrayFieldDef<any, infer S> ? Form.Field<ReadonlyArray<Schema.Schema.Encoded<S>>>
     : never
 }
 
@@ -63,20 +63,20 @@ export type FieldRefs<TFields extends Form.FieldsRecord> = {
  * @since 1.0.0
  * @category Models
  */
-export interface FormAtoms<TFields extends Form.FieldsRecord, R> {
+export interface FormAtoms<TFields extends Field.FieldsRecord, R> {
   readonly stateAtom: Atom.Writable<Option.Option<Form.FormState<TFields>>, Option.Option<Form.FormState<TFields>>>
   readonly crossFieldErrorsAtom: Atom.Writable<Map<string, string>, Map<string, string>>
   readonly dirtyFieldsAtom: Atom.Atom<ReadonlySet<string>>
   readonly isDirtyAtom: Atom.Atom<boolean>
   readonly submitCountAtom: Atom.Atom<number>
   readonly onSubmitAtom: Atom.Writable<
-    Atom.AtomResultFn<Form.DecodedFromFields<TFields>, unknown, unknown> | null,
-    Atom.AtomResultFn<Form.DecodedFromFields<TFields>, unknown, unknown> | null
+    Atom.AtomResultFn<Field.DecodedFromFields<TFields>, unknown, unknown> | null,
+    Atom.AtomResultFn<Field.DecodedFromFields<TFields>, unknown, unknown> | null
   >
 
-  readonly decodeAndSubmit: Atom.AtomResultFn<Form.EncodedFromFields<TFields>, unknown, unknown>
+  readonly decodeAndSubmit: Atom.AtomResultFn<Field.EncodedFromFields<TFields>, unknown, unknown>
 
-  readonly combinedSchema: Schema.Schema<Form.DecodedFromFields<TFields>, Form.EncodedFromFields<TFields>, R>
+  readonly combinedSchema: Schema.Schema<Field.DecodedFromFields<TFields>, Field.EncodedFromFields<TFields>, R>
 
   readonly fieldRefs: FieldRefs<TFields>
 
@@ -101,11 +101,11 @@ export interface FormAtoms<TFields extends Form.FieldsRecord, R> {
  * @since 1.0.0
  * @category Models
  */
-export interface FormOperations<TFields extends Form.FieldsRecord> {
+export interface FormOperations<TFields extends Field.FieldsRecord> {
   /**
    * Creates the initial form state from default values.
    */
-  readonly createInitialState: (defaultValues: Form.EncodedFromFields<TFields>) => Form.FormState<TFields>
+  readonly createInitialState: (defaultValues: Field.EncodedFromFields<TFields>) => Form.FormState<TFields>
 
   /**
    * Creates a reset state (back to initial values).
@@ -131,7 +131,7 @@ export interface FormOperations<TFields extends Form.FieldsRecord> {
    */
   readonly setFormValues: (
     state: Form.FormState<TFields>,
-    values: Form.EncodedFromFields<TFields>,
+    values: Field.EncodedFromFields<TFields>,
   ) => Form.FormState<TFields>
 
   /**
@@ -209,13 +209,13 @@ export interface FormOperations<TFields extends Form.FieldsRecord> {
  * @since 1.0.0
  * @category Constructors
  */
-export const make = <TFields extends Form.FieldsRecord, R>(
+export const make = <TFields extends Field.FieldsRecord, R>(
   config: FormAtomsConfig<TFields, R>,
 ): FormAtoms<TFields, R> => {
   const { formBuilder, runtime } = config
   const { fields } = formBuilder
 
-  const combinedSchema = buildSchema(formBuilder)
+  const combinedSchema = Form.buildSchema(formBuilder)
 
   const stateAtom = Atom.make(Option.none<Form.FormState<TFields>>()).pipe(Atom.setIdleTTL(0))
   const crossFieldErrorsAtom = Atom.make<Map<string, string>>(new Map()).pipe(Atom.setIdleTTL(0))
@@ -232,7 +232,7 @@ export const make = <TFields extends Form.FieldsRecord, R>(
     Atom.setIdleTTL(0),
   )
 
-  const onSubmitAtom = Atom.make<Atom.AtomResultFn<Form.DecodedFromFields<TFields>, unknown, unknown> | null>(
+  const onSubmitAtom = Atom.make<Atom.AtomResultFn<Field.DecodedFromFields<TFields>, unknown, unknown> | null>(
     null,
   ).pipe(Atom.setIdleTTL(0))
 
@@ -330,10 +330,10 @@ export const make = <TFields extends Form.FieldsRecord, R>(
     fieldAtomsRegistry.clear()
   }
 
-  const decodeAndSubmit = runtime.fn<Form.EncodedFromFields<TFields>>()((values, get) =>
+  const decodeAndSubmit = runtime.fn<Field.EncodedFromFields<TFields>>()((values, get) =>
     Effect.gen(function*() {
       const decoded = yield* Schema.decodeUnknown(combinedSchema)(values) as Effect.Effect<
-        Form.DecodedFromFields<TFields>,
+        Field.DecodedFromFields<TFields>,
         ParseResult.ParseError,
         R
       >
@@ -341,17 +341,17 @@ export const make = <TFields extends Form.FieldsRecord, R>(
       get.set(onSubmit, decoded)
       return yield* get.result(onSubmit, { suspendOnWaiting: true })
     })
-  ).pipe(Atom.setIdleTTL(0)) as Atom.AtomResultFn<Form.EncodedFromFields<TFields>, unknown, unknown>
+  ).pipe(Atom.setIdleTTL(0)) as Atom.AtomResultFn<Field.EncodedFromFields<TFields>, unknown, unknown>
 
   const fieldRefs = Object.fromEntries(
-    Object.keys(fields).map((key) => [key, makeFieldRef(key)]),
+    Object.keys(fields).map((key) => [key, Form.makeFieldRef(key)]),
   ) as FieldRefs<TFields>
 
   const operations: FormOperations<TFields> = {
     createInitialState: (defaultValues) => ({
       values: defaultValues,
       initialValues: defaultValues,
-      touched: createTouchedRecord(fields, false) as { readonly [K in keyof TFields]: boolean },
+      touched: Field.createTouchedRecord(fields, false) as { readonly [K in keyof TFields]: boolean },
       submitCount: 0,
       dirtyFields: new Set(),
     }),
@@ -359,14 +359,14 @@ export const make = <TFields extends Form.FieldsRecord, R>(
     createResetState: (state) => ({
       values: state.initialValues,
       initialValues: state.initialValues,
-      touched: createTouchedRecord(fields, false) as { readonly [K in keyof TFields]: boolean },
+      touched: Field.createTouchedRecord(fields, false) as { readonly [K in keyof TFields]: boolean },
       submitCount: 0,
       dirtyFields: new Set(),
     }),
 
     createSubmitState: (state) => ({
       ...state,
-      touched: createTouchedRecord(fields, true) as { readonly [K in keyof TFields]: boolean },
+      touched: Field.createTouchedRecord(fields, true) as { readonly [K in keyof TFields]: boolean },
       submitCount: state.submitCount + 1,
     }),
 
@@ -380,7 +380,7 @@ export const make = <TFields extends Form.FieldsRecord, R>(
       )
       return {
         ...state,
-        values: newValues as Form.EncodedFromFields<TFields>,
+        values: newValues as Field.EncodedFromFields<TFields>,
         dirtyFields: newDirtyFields,
       }
     },
@@ -405,12 +405,12 @@ export const make = <TFields extends Form.FieldsRecord, R>(
     }),
 
     appendArrayItem: (state, arrayPath, itemSchema, value) => {
-      const newItem = value ?? getDefaultFromSchema(itemSchema)
+      const newItem = value ?? Field.getDefaultFromSchema(itemSchema)
       const currentItems = (getNestedValue(state.values, arrayPath) ?? []) as ReadonlyArray<unknown>
       const newItems = [...currentItems, newItem]
       return {
         ...state,
-        values: setNestedValue(state.values, arrayPath, newItems) as Form.EncodedFromFields<TFields>,
+        values: setNestedValue(state.values, arrayPath, newItems) as Field.EncodedFromFields<TFields>,
         dirtyFields: recalculateDirtyFieldsForArray(state.dirtyFields, state.initialValues, arrayPath, newItems),
       }
     },
@@ -420,7 +420,7 @@ export const make = <TFields extends Form.FieldsRecord, R>(
       const newItems = currentItems.filter((_, i) => i !== index)
       return {
         ...state,
-        values: setNestedValue(state.values, arrayPath, newItems) as Form.EncodedFromFields<TFields>,
+        values: setNestedValue(state.values, arrayPath, newItems) as Field.EncodedFromFields<TFields>,
         dirtyFields: recalculateDirtyFieldsForArray(state.dirtyFields, state.initialValues, arrayPath, newItems),
       }
     },
@@ -440,7 +440,7 @@ export const make = <TFields extends Form.FieldsRecord, R>(
       newItems[indexB] = temp
       return {
         ...state,
-        values: setNestedValue(state.values, arrayPath, newItems) as Form.EncodedFromFields<TFields>,
+        values: setNestedValue(state.values, arrayPath, newItems) as Field.EncodedFromFields<TFields>,
         dirtyFields: recalculateDirtyFieldsForArray(state.dirtyFields, state.initialValues, arrayPath, newItems),
       }
     },
@@ -459,7 +459,7 @@ export const make = <TFields extends Form.FieldsRecord, R>(
       newItems.splice(toIndex, 0, item)
       return {
         ...state,
-        values: setNestedValue(state.values, arrayPath, newItems) as Form.EncodedFromFields<TFields>,
+        values: setNestedValue(state.values, arrayPath, newItems) as Field.EncodedFromFields<TFields>,
         dirtyFields: recalculateDirtyFieldsForArray(state.dirtyFields, state.initialValues, arrayPath, newItems),
       }
     },

package/src/index.ts

@@ -1,3 +1,10 @@
+/**
+ * Field definitions for type-safe forms.
+ *
+ * @since 1.0.0
+ */
+export * as Field from "./Field.js"
+
 /**
  * @since 1.0.0
  */