@jayoncode/form-intelligence API

---

@jayoncode/form-intelligence API

Classes

FormModuleHost

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Constructors

Constructor

new FormModuleHost<TValues>(
   form: FormInstance<TValues>, 
   config: ResolvedFormConfig<TValues>, 
   events: FormEventBus, 
pluginRegistry: PluginRegistry<TValues>): FormModuleHost<TValues>;

Parameters

Parameter	Type
form	FormInstance<TValues>
config	ResolvedFormConfig<TValues>
events	FormEventBus
pluginRegistry	PluginRegistry<TValues>

Returns

FormModuleHost<TValues>

Methods

register()

register(module: FormModule<TValues>): void;

Parameters

Parameter	Type
module	FormModule<TValues>

Returns

void

registerPlugin()

registerPlugin(plugin: FormPlugin<TValues>, order?: number): void;

Parameters

Parameter	Type
plugin	FormPlugin<TValues>
order	number

Returns

void

has()

has(id: string): boolean;

Parameters

Parameter	Type
id	string

Returns

boolean

start()

start(): void;

Returns

void

destroy()

destroy(): void;

Returns

void

---

FormModuleRegistry

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Constructors

Constructor

new FormModuleRegistry<TValues>(): FormModuleRegistry<TValues>;

Returns

FormModuleRegistry<TValues>

Methods

register()

register(module: FormModule<TValues>): void;

Parameters

Parameter	Type
module	FormModule<TValues>

Returns

void

unregister()

unregister(id: string): boolean;

Parameters

Parameter	Type
id	string

Returns

boolean

has()

has(id: string): boolean;

Parameters

Parameter	Type
id	string

Returns

boolean

size()

size(): number;

Returns

number

list()

list(): readonly FormModule<TValues>[];

Returns

readonly FormModule<TValues>[]

initializeAll()

initializeAll(context: FormModuleContext<TValues>): void;

Parameters

Parameter	Type
context	FormModuleContext<TValues>

Returns

void

startAll()

startAll(context: FormModuleContext<TValues>): void;

Parameters

Parameter	Type
context	FormModuleContext<TValues>

Returns

void

stopAll()

stopAll(context: FormModuleContext<TValues>): void;

Parameters

Parameter	Type
context	FormModuleContext<TValues>

Returns

void

destroyAll()

destroyAll(context: FormModuleContext<TValues>): void;

Parameters

Parameter	Type
context	FormModuleContext<TValues>

Returns

void

---

DependencyEngine

Structural dependency graph façade (Phase 6 / ADR-007).

Constructors

Constructor

new DependencyEngine(options?: DependencyEngineOptions): DependencyEngine;

Parameters

Parameter	Type
options	DependencyEngineOptions

Returns

DependencyEngine

Methods

registerMap()

registerMap(map: DependencyMap, options?: {
  actions?: readonly DependencyAction[];
  actionsByChild?: Partial<Record<string, readonly DependencyAction[]>>;
  inferred?: boolean;
}): void;

Parameters

Parameter	Type
map	DependencyMap
options?	{ actions?: readonly DependencyAction[]; actionsByChild?: Partial<Record<string, readonly DependencyAction[]>>; inferred?: boolean; }
options.actions?	readonly DependencyAction[]
options.actionsByChild?	Partial<Record<string, readonly DependencyAction[]>>
options.inferred?	boolean

Returns

void

addEdge()

addEdge(
   child: string, 
   parents: readonly string[], 
   actions?: readonly DependencyAction[], 
   options?: {
  clearValue?: unknown;
  inferred?: boolean;
}): void;

Parameters

Parameter	Type	Default value
child	string	undefined
parents	readonly string[]	undefined
actions	readonly DependencyAction[]	DEFAULT_DEPENDENCY_ACTIONS
options?	{ clearValue?: unknown; inferred?: boolean; }	undefined
options.clearValue?	unknown	undefined
options.inferred?	boolean	undefined

Returns

void

addEdgeConfig()

addEdgeConfig(config: DependencyEdgeConfig & {
  to: string;
}): void;

Parameters

Parameter	Type
config	DependencyEdgeConfig & { to: string; }

Returns

void

syncInferredFromFields()

syncInferredFromFields<TValues>(fields: ReadonlyMap<string, FieldOptions<TValues>>): void;

Sync inferred edges from FieldOptions.dependsOn (revalidate-only).

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Parameters

Parameter	Type
fields	ReadonlyMap<string, FieldOptions<TValues>>

Returns

void

getDependents()

getDependents(path: string): readonly string[];

Parameters

Parameter	Type
path	string

Returns

readonly string[]

getParents()

getParents(path: string): readonly string[];

Parameters

Parameter	Type
path	string

Returns

readonly string[]

detectCycles()

detectCycles(): readonly readonly string[][];

Returns

readonly readonly string[][]

topologicalOrder()

topologicalOrder(seeds?: readonly string[]): readonly string[];

Parameters

Parameter	Type
seeds?	readonly string[]

Returns

readonly string[]

inspect()

inspect(): DependencyGraph;

Returns

DependencyGraph

onParentChange()

onParentChange(path: string): CascadeResult;

Propagate a parent change: clear / revalidate / recompute / reloadOptions for dependents in topological order.

Parameters

Parameter	Type
path	string

Returns

CascadeResult

---

FormIntelligentError

Extends

• Error

Extended by

• ConfigurationError
• DraftStorageError
• OfflineQueueError
• PluginError
• SubmitError
• ValidationError
• WorkflowError

Constructors

Constructor

new FormIntelligentError(
   message: string, 
   code: FormErrorCode, 
   options?: FormErrorOptions): FormIntelligentError;

Parameters

Parameter	Type
message	string
code	FormErrorCode
options	FormErrorOptions

Returns

FormIntelligentError

Overrides

Error.constructor

Properties

Property	Modifier	Type
code	readonly	FormErrorCode
details	readonly	Readonly<PlainObject> | undefined

---

ValidationError

Extends

• FormIntelligentError

Constructors

Constructor

new ValidationError(message: string, options?: FormErrorOptions): ValidationError;

Parameters

Parameter	Type
message	string
options	FormErrorOptions

Returns

ValidationError

Overrides

FormIntelligentError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	FormErrorCode	FormIntelligentError.code
details	readonly	Readonly<PlainObject> | undefined	FormIntelligentError.details

---

SubmitError

Extends

• FormIntelligentError

Constructors

Constructor

new SubmitError(message: string, options?: FormErrorOptions): SubmitError;

Parameters

Parameter	Type
message	string
options	FormErrorOptions

Returns

SubmitError

Overrides

FormIntelligentError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	FormErrorCode	FormIntelligentError.code
details	readonly	Readonly<PlainObject> | undefined	FormIntelligentError.details

---

WorkflowError

Extends

• FormIntelligentError

Constructors

Constructor

new WorkflowError(message: string, options?: FormErrorOptions): WorkflowError;

Parameters

Parameter	Type
message	string
options	FormErrorOptions

Returns

WorkflowError

Overrides

FormIntelligentError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	FormErrorCode	FormIntelligentError.code
details	readonly	Readonly<PlainObject> | undefined	FormIntelligentError.details

---

ConfigurationError

Extends

• FormIntelligentError

Constructors

Constructor

new ConfigurationError(message: string, options?: FormErrorOptions): ConfigurationError;

Parameters

Parameter	Type
message	string
options	FormErrorOptions

Returns

ConfigurationError

Overrides

FormIntelligentError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	FormErrorCode	FormIntelligentError.code
details	readonly	Readonly<PlainObject> | undefined	FormIntelligentError.details

---

DraftStorageError

Recoverable draft persistence failures (quota, corrupt payload).

Extends

• FormIntelligentError

Constructors

Constructor

new DraftStorageError(message: string, options?: FormErrorOptions): DraftStorageError;

Parameters

Parameter	Type
message	string
options	FormErrorOptions

Returns

DraftStorageError

Overrides

FormIntelligentError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	FormErrorCode	FormIntelligentError.code
details	readonly	Readonly<PlainObject> | undefined	FormIntelligentError.details

---

OfflineQueueError

Offline queue failures (quota, overflow reject).

Extends

• FormIntelligentError

Constructors

Constructor

new OfflineQueueError(message: string, options?: FormErrorOptions): OfflineQueueError;

Parameters

Parameter	Type
message	string
options	FormErrorOptions

Returns

OfflineQueueError

Overrides

FormIntelligentError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	FormErrorCode	FormIntelligentError.code
details	readonly	Readonly<PlainObject> | undefined	FormIntelligentError.details

---

PluginError

Isolated plugin/middleware failures (setup or hook throw).

Extends

• FormIntelligentError

Constructors

Constructor

new PluginError(message: string, options?: FormErrorOptions): PluginError;

Parameters

Parameter	Type
message	string
options	FormErrorOptions

Returns

PluginError

Overrides

FormIntelligentError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	FormErrorCode	FormIntelligentError.code
details	readonly	Readonly<PlainObject> | undefined	FormIntelligentError.details

---

MiddlewarePipeline

Onion middleware registry. Lower order runs earlier (outer). Same order → registration order.

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Constructors

Constructor

new MiddlewarePipeline<TValues>(): MiddlewarePipeline<TValues>;

Returns

MiddlewarePipeline<TValues>

Methods

use()

use(middleware: MiddlewareInput<TValues>): () => void;

Parameters

Parameter	Type
middleware	MiddlewareInput<TValues>

Returns

() => void

run()

run(input: {
  form: FormInstance<TValues>;
  phase: MiddlewarePhase;
  signal: AbortSignal;
  meta?: Readonly<Record<string, unknown>>;
}): Promise<MiddlewareRunResult>;

Parameters

Parameter	Type
input	{ form: FormInstance<TValues>; phase: MiddlewarePhase; signal: AbortSignal; meta?: Readonly<Record<string, unknown>>; }
input.form	FormInstance<TValues>
input.phase	MiddlewarePhase
input.signal	AbortSignal
input.meta?	Readonly<Record<string, unknown>>

Returns

Promise<MiddlewareRunResult>

clear()

clear(): void;

Returns

void

Interfaces

FormController

Thin façade over FormInstance for adapters and design systems.

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Properties

Property	Modifier	Type
state	readonly	FormState<TValues>

Methods

subscribe()

subscribe(listener: () => void): () => void;

Parameters

Parameter	Type
listener	() => void

Returns

() => void

getSnapshot()

getSnapshot(): FormState<TValues>;

Returns

FormState<TValues>

submit()

submit(options?: SubmitOptions): Promise<boolean>;

Parameters

Parameter	Type
options?	SubmitOptions

Returns

Promise<boolean>

reset()

reset(options?: ResetOptions<TValues>): void;

Parameters

Parameter	Type
options?	ResetOptions<TValues>

Returns

void

field()

field(path: string): FieldController<TValues>;

Parameters

Parameter	Type
path	string

Returns

FieldController<TValues>

firstInvalidPath()

firstInvalidPath(): string | undefined;

First path with a non-empty error message.

Returns

string | undefined

focusFirstInvalid()

focusFirstInvalid(): string | undefined;

Focuses the first invalid control when a DOM document is available. Returns the path (or undefined if none). Safe no-op under SSR.

Returns

string | undefined

destroy()

destroy(): void;

Returns

void

---

FrameworkAdapter

Contract for framework UI adapters (React, Vue, Angular, Svelte, …). Implementations ship in separate packages — never required by core.

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Properties

Property	Modifier	Type
name	readonly	string

Methods

connect()

connect(form: FormInstance<TValues>): void | (() => void);

Bind framework lifecycle / reactivity to a form instance. Return a cleanup that disconnects subscriptions and effects.

Parameters

Parameter	Type
form	FormInstance<TValues>

Returns

void | (() => void)

---

PersistenceAdapter

Persist form values for drafts and autosave. Implementations may be sync (localStorage) or async (IndexedDB, remote).

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Properties

Property	Modifier	Type
name?	readonly	string

Methods

load()

load(key: string): TValues | Promise<TValues | null> | null;

Parameters

Parameter	Type
key	string

Returns

TValues | Promise<TValues | null> | null

save()

save(key: string, values: TValues): void | Promise<void>;

Parameters

Parameter	Type
key	string
values	TValues

Returns

void | Promise<void>

clear()

clear(key: string): void | Promise<void>;

Parameters

Parameter	Type
key	string

Returns

void | Promise<void>

---

SyncPersistenceAdapter

Sync persistence surface used by draft workflow today. Compatible with PersistenceAdapter when methods are synchronous.

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Properties

Property	Modifier	Type
name?	readonly	string

Methods

load()

load(key: string): TValues | null;

Parameters

Parameter	Type
key	string

Returns

TValues | null

save()

save(key: string, values: TValues): void;

Parameters

Parameter	Type
key	string
values	TValues

Returns

void

clear()

clear(key: string): void;

Parameters

Parameter	Type
key	string

Returns

void

---

SchemaAdapter

Bridge any validation library into Form Intelligence. Schema adapters are optional — core never depends on Zod/Yup/etc. Error keys are field paths (dot notation).

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Properties

Property	Modifier	Type
name?	readonly	string

Methods

validate()

validate(values: TValues): 
  | Readonly<Record<string, string>>
| Promise<Readonly<Record<string, string>>>;

Parameters

Parameter	Type
values	TValues

Returns

| Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>

---

SubmitTransportAdapter

Transport layer for form submission (fetch, GraphQL, custom API clients). Keep UI frameworks out of this interface — values + meta only.

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>
TResult	unknown

Properties

Property	Modifier	Type
name?	readonly	string

Methods

submit()

submit(values: TValues, meta?: SubmitMeta): TResult | Promise<TResult>;

Parameters

Parameter	Type
values	TValues
meta?	SubmitMeta

Returns

TResult | Promise<TResult>

---

FormModuleContext

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Properties

Property	Modifier	Type
form	readonly	FormInstance<TValues>
config	readonly	ResolvedFormConfig<TValues>
events	readonly	FormEventBus

Methods

registerCleanup()

registerCleanup(cleanup: () => void): void;

Parameters

Parameter	Type
cleanup	() => void

Returns

void

---

FormModule

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Properties

Property	Modifier	Type
id	readonly	string
order?	readonly	number

Methods

initialize()?

optional initialize(context: FormModuleContext<TValues>): void;

Parameters

Parameter	Type
context	FormModuleContext<TValues>

Returns

void

start()?

optional start(context: FormModuleContext<TValues>): void;

Parameters

Parameter	Type
context	FormModuleContext<TValues>

Returns

void

stop()?

optional stop(context: FormModuleContext<TValues>): void;

Parameters

Parameter	Type
context	FormModuleContext<TValues>

Returns

void

destroy()?

optional destroy(context: FormModuleContext<TValues>): void;

Parameters

Parameter	Type
context	FormModuleContext<TValues>

Returns

void

---

FieldAriaIds

Properties

Property	Modifier	Type
errorId?	readonly	string
descriptionId?	readonly	string

---

FieldAria

CamelCase ARIA snapshot for adapters and FieldController.

Properties

Property	Modifier	Type
ariaInvalid	readonly	boolean
ariaRequired	readonly	boolean
ariaDescribedBy	readonly	string | undefined

---

FieldAriaAttributes

Spread-friendly DOM attributes ({...field.aria.attributes}).

Properties

Property	Modifier	Type
aria-invalid	readonly	boolean
aria-required	readonly	boolean | undefined
aria-describedby	readonly	string | undefined

---

ComputeFieldAriaInput

Properties

Property	Modifier	Type	Description
error?	readonly	string	-
required?	readonly	boolean	True when presentation/UI marks the field required.
ids?	readonly	FieldAriaIds	-

---

FieldAriaResult

Properties

Property	Modifier	Type
aria	readonly	FieldAria
attributes	readonly	FieldAriaAttributes

---

CalculationBuilder

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Methods

from()

from(...deps: string[]): CalculationBuilder<TValues>;

Parameters

Parameter	Type
...deps	string[]

Returns

CalculationBuilder<TValues>

lazy()

lazy(enabled?: boolean): CalculationBuilder<TValues>;

Parameters

Parameter	Type
enabled?	boolean

Returns

CalculationBuilder<TValues>

memoized()

memoized(enabled?: boolean): CalculationBuilder<TValues>;

Parameters

Parameter	Type
enabled?	boolean

Returns

CalculationBuilder<TValues>

markDirty()

markDirty(enabled?: boolean): CalculationBuilder<TValues>;

Parameters

Parameter	Type
enabled?	boolean

Returns

CalculationBuilder<TValues>

compute()

compute(fn: (ctx: CalculationComputeContext<TValues>) => unknown): void;

Parameters

Parameter	Type
fn	(ctx: CalculationComputeContext<TValues>) => unknown

Returns

void

---

CalculationDefinition

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Properties

Property	Modifier	Type	Description
path	readonly	string	-
compute	readonly	(context: CalculationComputeContext<TValues>) => unknown	-
deps?	readonly	readonly string[]	-
markDirty?	readonly	boolean	When true, writing the derived value marks the field dirty. Default false.
lazy?	readonly	boolean	Skip initial compute on register; still runs when deps change.
memoized?	readonly	boolean	Skip compute when dependency fingerprint is unchanged.

---

CalculateOptions

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Properties

Property	Modifier	Type
deps?	readonly	readonly string[]
markDirty?	readonly	boolean
lazy?	readonly	boolean
memoized?	readonly	boolean
compute	readonly	(context: { values: TValues; }) => unknown

---

DependencyRegistrar()

Type Parameters

Type Parameter	Default type
_TValues extends Record<string, unknown>	Record<string, unknown>

DependencyRegistrar(map: DependencyMap): DependencyRegistrar<_TValues>;

Parameters

Parameter	Type
map	DependencyMap

Returns

DependencyRegistrar<_TValues>

Methods

link()

link(parent: string): {
  to: {
     effect: DependencyRegistrar<_TValues>;
  };
};

Parameters

Parameter	Type
parent	string

Returns

{
  to: {
     effect: DependencyRegistrar<_TValues>;
  };
}

Name	Type
to()	(child: string) => { effect: DependencyRegistrar<_TValues>; }

edge()

edge(config: DependencyEdgeConfig & {
  to: string;
}): DependencyRegistrar<_TValues>;

Parameters

Parameter	Type
config	DependencyEdgeConfig & { to: string; }

Returns

DependencyRegistrar<_TValues>

inspect()

inspect(): DependencyGraph;

Returns

DependencyGraph

---

DependencyEdgeConfig

Properties

Property	Modifier	Type
from	readonly	string | readonly string[]
actions?	readonly	readonly DependencyAction[]
clearValue?	readonly	unknown

---

DependencyEdge

Properties

Property	Modifier	Type	Description
from	readonly	string	-
to	readonly	string	-
actions	readonly	readonly DependencyAction[]	-
clearValue?	readonly	unknown	-
inferred?	readonly	boolean	Inferred from FieldOptions.dependsOn — cycles warn; explicit edges throw.

---

DependencyNode

Properties

Property	Modifier	Type
path	readonly	string
parents	readonly	readonly string[]
children	readonly	readonly string[]

---

DependencyGraph

Properties

Property	Modifier	Type
nodes	readonly	ReadonlyMap<string, DependencyNode>
edges	readonly	readonly DependencyEdge[]

Methods

dependentsOf()

dependentsOf(path: string): readonly string[];

Parameters

Parameter	Type
path	string

Returns

readonly string[]

parentsOf()

parentsOf(path: string): readonly string[];

Parameters

Parameter	Type
path	string

Returns

readonly string[]

topoOrder()

topoOrder(seeds?: readonly string[]): readonly string[];

Parameters

Parameter	Type
seeds?	readonly string[]

Returns

readonly string[]

---

CascadeResult

Properties

Property	Modifier	Type
clears	readonly	readonly { path: string; clearValue: unknown; }[]
revalidate	readonly	readonly string[]
recompute	readonly	readonly string[]
reloadOptions	readonly	readonly string[]

---

PresentationState

Properties

Property	Modifier	Type
field	readonly	FieldUiState
options	readonly	readonly FieldOption[] | undefined
form	readonly	FormUiState

---

PresentationSnapshot

Properties

Property	Modifier	Type
fieldUi	readonly	FieldUiMap
formUi	readonly	FormUiState
fieldOptions	readonly	Readonly<Record<FieldPath, readonly FieldOption[]>>

---

TransformContext

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Properties

Property	Modifier	Type
path	readonly	string
values	readonly	TValues
signal?	readonly	AbortSignal

---

SanitizeOptions

Properties

Property	Modifier	Type	Description
stripHtml?	readonly	boolean	Strip simple HTML tags. Default true when sanitize: true.
stripControlChars?	readonly	boolean	Strip C0 control chars except tab/newline. Default true when sanitize: true.

---

TransformPipelineOptions

Properties

Property	Modifier	Type
trim?	readonly	boolean | "start" | "end" | "both"
normalize?	readonly	boolean | "nfc" | "nfd"
sanitize?	readonly	boolean | SanitizeOptions
parse?	readonly	Parser
stages?	readonly	readonly TransformFn<Record<string, unknown>>[]

---

TransformPipelineHandle

Methods

pipe()

pipe(...stages: TransformFn<Record<string, unknown>>[]): TransformPipelineHandle;

Parameters

Parameter	Type
...stages	TransformFn<Record<string, unknown>>[]

Returns

TransformPipelineHandle

clear()

clear(): void;

Returns

void

---

FieldUiState

Properties

Property	Type	Description
visible	boolean	-
disabled	boolean	-
required	boolean | undefined	-
readOnly?	boolean	Additive — when true, controls should be non-editable but still focusable.
busy?	boolean	Additive — e.g. async option load / validating.
hasError?	boolean	Derived UI projection (validation state): raw error present. Distinct from showError (whether to display).
errorMessage?	string	Derived UI projection: error string when present.
showError?	boolean	Derived UI projection (UI state): whether the error should be displayed under the active errorDisplay policy.
status?	"validating" | "error" | "success" | "idle"	Derived UI projection: exactly one of validating

---

FormUiState

Properties

Property	Modifier	Type
submitDisabled	readonly	boolean

---

FieldOption

Properties

Property	Modifier	Type
label	readonly	string
value	readonly	string

---

RuleContext

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Properties

Property	Modifier	Type
values	readonly	TValues

Methods

show()

show(...paths: readonly string[]): void;

Parameters

Parameter	Type
...paths	readonly string[]

Returns

void

hide()

hide(...paths: readonly string[]): void;

Parameters

Parameter	Type
...paths	readonly string[]

Returns

void

require()

require(...paths: readonly string[]): void;

Parameters

Parameter	Type
...paths	readonly string[]

Returns

void

optional()

optional(...paths: readonly string[]): void;

Parameters

Parameter	Type
...paths	readonly string[]

Returns

void

enable()

enable(...paths: readonly string[]): void;

Parameters

Parameter	Type
...paths	readonly string[]

Returns

void

disable()

disable(...paths: readonly string[]): void;

Parameters

Parameter	Type
...paths	readonly string[]

Returns

void

disableSubmit()

disableSubmit(): void;

Returns

void

enableSubmit()

enableSubmit(): void;

Returns

void

setValue()

setValue(path: string, value: unknown): void;

Parameters

Parameter	Type
path	string
value	unknown

Returns

void

---

FormRuleDefinition

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Properties

Property	Modifier	Type
watch	readonly	string
equals?	readonly	unknown
notEquals?	readonly	unknown
greaterThan?	readonly	number
lessThan?	readonly	number
show?	readonly	readonly string[]
hide?	readonly	readonly string[]
require?	readonly	readonly string[]
optional?	readonly	readonly string[]
enable?	readonly	readonly string[]
disable?	readonly	readonly string[]
disableSubmit?	readonly	boolean
changes?	readonly	(value: unknown, values: TValues) => | readonly FieldOption[] | Promise<readonly FieldOption[]>
populate?	readonly	string
then?	readonly	(context: RuleContext<TValues>) => void

---

WizardStep

Properties

Property	Modifier	Type	Description
id?	readonly	string	-
fields?	readonly	readonly string[]	-
validate?	readonly	boolean	-
when?	readonly	(values: Record<string, unknown>) => boolean	Skip this step when predicate returns false (conditional steps MVP).
next?	readonly	| string | ((values: Record<string, unknown>) => string | undefined)	Explicit next step id, or resolver from values.
canLeave?	readonly	(ctx: WizardGuardContext) => boolean | Promise<boolean>	-
canEnter?	readonly	(ctx: WizardGuardContext) => boolean | Promise<boolean>	-

---

WizardGuardContext

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Properties

Property	Modifier	Type
values	readonly	TValues
fromStepId	readonly	string | undefined
toStepId	readonly	string
signal	readonly	AbortSignal

---

WizardConfig

Properties

Property	Modifier	Type	Description
steps	readonly	readonly WizardStep[]	-
initialStep?	readonly	number	-
goToValidation?	readonly	WizardNavigateValidation	Default validation for goTo. - all — validate entire form (SHIPPED default) - step — validate current step fields only - none — skip validation
persistStepInDraft?	readonly	boolean	When true, draft save/restore includes currentStep.

---

WizardStepGraphNode

Properties

Property	Modifier	Type
id	readonly	string
index	readonly	number
nextIds	readonly	readonly string[]

---

WizardStepGraph

Properties

Property	Modifier	Type
nodes	readonly	readonly WizardStepGraphNode[]

---

JsonFormPayload

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Properties

Property	Modifier	Type
kind	readonly	"json"
values	readonly	TValues

---

MultipartFormPayload

Properties

Property	Modifier	Type
kind	readonly	"multipart"
formData	readonly	FormData

---

ToFormDataOptions

Properties

Property	Modifier	Type	Description
omitEmpty?	readonly	boolean	Skip empty strings, empty file arrays, null, and undefined. Default true.

---

PluginErrorReport

Properties

Property	Modifier	Type
plugin?	readonly	string
hook?	readonly	string
phase?	readonly	string
error	readonly	unknown

---

MiddlewareContext

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Properties

Property	Modifier	Type
form	readonly	FormInstance<TValues>
phase	readonly	MiddlewarePhase
signal	readonly	AbortSignal
meta	readonly	Readonly<Record<string, unknown>>

Methods

halt()

halt(reason?: string): void;

Parameters

Parameter	Type
reason?	string

Returns

void

---

MiddlewareRegistration

Properties

Property	Modifier	Type
name	readonly	string
order?	readonly	number
phases?	readonly	readonly MiddlewarePhase[]

---

MiddlewareRunResult

Properties

Property	Modifier	Type
halted	readonly	boolean
reason?	readonly	string

---

AsyncRetryPolicy

Properties

Property	Modifier	Type	Description
maxAttempts	readonly	number	Total attempts including the first; minimum 1.
delayMs?	readonly	number | ((attempt: number) => number)	Attempt is 1-based after a failure.
shouldRetry?	readonly	(error: unknown, attempt: number) => boolean	-

---

AsyncCachePolicy

Properties

Property	Modifier	Type	Description
ttl	readonly	TtlInput	-
storage?	readonly	"memory" | "session"	Default "memory". "session" is accepted for API compatibility but is memory-only — async validation outcomes are never written to sessionStorage (cleartext sensitive-data policy).
maxEntries?	readonly	number	Default 256.

---

AsyncValidatorOptions

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Properties

Property	Modifier	Type
validate	readonly	(value: unknown, context: ValidationContext<TValues> & { signal: AbortSignal; }) => | ValidatorResult | Promise<ValidatorResult>
debounce?	readonly	number
retry?	readonly	number | AsyncRetryPolicy
timeout?	readonly	number
cache?	readonly	false | TtlInput | AsyncCachePolicy
abortPrevious?	readonly	boolean
preventDuplicates?	readonly	boolean
cacheKey?	readonly	(value: unknown, context: ValidationContext<TValues>) => string
sharedCache?	readonly	string | boolean
offline?	readonly	"skip" | "fail" | "queue"

---

AsyncJob

Properties

Property	Modifier	Type
id	readonly	string
path	readonly	string
generation	readonly	number
cacheKey	readonly	string
signal	readonly	AbortSignal
startedAt	readonly	number
status	readonly	"scheduled" | "running" | "settled" | "aborted" | "timeout" | "queued"

---

FieldMetaState

Properties

Property	Modifier	Type
isValidating	readonly	boolean
label?	readonly	string
description?	readonly	string
hidden?	readonly	boolean

---

ValidationFormAccessor

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Methods

get()

get(path: string): unknown;

Parameters

Parameter	Type
path	string

Returns

unknown

values()

values(): TValues;

Returns

TValues

---

ValidationContext

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Properties

Property	Modifier	Type	Description
values	readonly	TValues	-
path	readonly	string	-
form	readonly	ValidationFormAccessor<TValues>	-
signal?	readonly	AbortSignal	Present when validation is tied to an in-flight async job (Phase 4A).

---

CustomFieldValidatorContext

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Properties

Property	Modifier	Type
value	readonly	unknown
path	readonly	string
form	readonly	ValidationFormAccessor<TValues>

---

FieldSchemaConfig

Properties

Property	Modifier	Type
type?	readonly	BuiltInFieldType
required?	readonly	boolean
email?	readonly	boolean
password?	readonly	boolean
url?	readonly	boolean
minLength?	readonly	number
validate?	readonly	FieldValidateRules
validators?	readonly	readonly CustomFieldValidator<Record<string, unknown>>[]
format?	readonly	| Formatter | "phone" | "currency" | "slug" | "philippine-phone" | "credit-card"

---

FieldOptions

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Properties

Property	Modifier	Type	Description
defaultValue?	readonly	unknown	-
validators?	readonly	readonly Validator<TValues>[]	-
validateOn?	readonly	ValidationMode	-
dependsOn?	readonly	readonly string[]	-
format?	readonly	Formatter	-
parse?	readonly	Parser	-
formatOnDisplay?	readonly	boolean	-
parseOnInput?	readonly	boolean	-
transform?	readonly	| TransformPipelineOptions | readonly TransformFn<TValues>[]	Canonical inbound transforms (trim/normalize/sanitize/parse/stages). Distinct from display format/parse — see /transform and TRANSFORM_INBOUND_ORDER.
label?	readonly	string	-
description?	readonly	string	-
hidden?	readonly	boolean	-
metadata?	readonly	Readonly<Record<string, unknown>>	-

---

FieldHandle

Type Parameters

Type Parameter
_TValues extends Record<string, unknown>

Properties

Property	Modifier	Type	Description
path	readonly	string	-
value	readonly	unknown	-
error	readonly	string | undefined	-
touched	readonly	boolean	-
dirty	readonly	boolean	-
visited	readonly	boolean	-
ui	readonly	FieldUiView	Full presentation maps (same sources as state.fieldUi / formUi / fieldOptions).
meta	readonly	FieldState & FieldMetaState	Field state + meta (controller surface).
aria	readonly	FieldAriaResult	Accessibility snapshot + spread attributes. Register element ids via setAriaIds so aria-describedby can link errors/help.

Methods

setValue()

setValue(value: unknown): void;

Parameters

Parameter	Type
value	unknown

Returns

void

setTouched()

setTouched(touched?: boolean): void;

Parameters

Parameter	Type
touched?	boolean

Returns

void

setVisited()

setVisited(visited?: boolean): void;

Parameters

Parameter	Type
visited?	boolean

Returns

void

setAriaIds()

setAriaIds(ids: FieldAriaIds): void;

Register error/description element ids for aria-describedby.

Parameters

Parameter	Type
ids	FieldAriaIds

Returns

void

onBlur()

onBlur(): void;

Returns

void

onFocus()

onFocus(): void;

Returns

void

validate()

validate(): Promise<boolean>;

Returns

Promise<boolean>

bind()

bind(): FieldBinding;

Returns

FieldBinding

---

ValueFieldBinding

Properties

Property	Modifier	Type
kind?	readonly	"value"
name	readonly	string
value	readonly	unknown
onChange	readonly	(value: unknown) => void
onBlur	readonly	() => void
onFocus	readonly	() => void

---

FileFieldBinding

Properties

Property	Modifier	Type	Description
kind	readonly	"file"	-
name	readonly	string	-
files	readonly	File[]	Canonical file selection (File[]).
onChange	readonly	(files: File[] | FileList | null | undefined) => void	-
onBlur	readonly	() => void	-
onFocus	readonly	() => void	-

---

AutosaveConfig

Properties

Property	Modifier	Type
enabled?	readonly	boolean
debounceMs?	readonly	number
onSave	readonly	(values: Record<string, unknown>) => void | Promise<void>

---

DraftConfig

Properties

Property	Modifier	Type	Description
enabled?	readonly	boolean	-
storageKey?	readonly	string	-
storage?	readonly	DraftStorageKind	-
adapter?	readonly	DraftStorageAdapter	-
onRestore?	readonly	(values: Record<string, unknown>) => void	-
promptOnRestore?	readonly	boolean	-
onRestorePrompt?	readonly	(values: Record<string, unknown>) => RestorePromptResult	-
onRestoreDecline?	readonly	DraftRestoreDeclinePolicy	What to do when onRestorePrompt returns false. Default "keep"
versioning?	readonly	boolean	Persist versioned envelopes (DraftEnvelopeV1) instead of raw values.
schemaVersion?	readonly	string	App schema id compared / migrated when envelopes are enabled.
migrateDraft?	readonly	(envelope: DraftEnvelopeV1) => DraftEnvelopeV1	Migrate an envelope before restore; throw to reject restore.

---

RestoreDraftOptions

Properties

Property	Modifier	Type	Description
force?	readonly	boolean	Default false — if the form is dirty, no-op unless force (D-RESTORE-RACE).
prompt?	readonly	boolean	Default false — if true, call DraftConfig.onRestorePrompt when set.
merge?	readonly	"overlay" | "replace"	Default overlay — { ...defaults, ...draft }. replace uses draft keys only.

---

AnalyticsConfig

Properties

Property	Modifier	Type	Description
enabled?	readonly	boolean	-
includePaths?	readonly	readonly string[]	When set, only these paths appear in path-keyed metrics (deny-by-default for others). Values are never captured — paths only.
excludePaths?	readonly	readonly string[]	Paths omitted from path-keyed metrics.
onSnapshot?	readonly	(snapshot: FormAnalyticsSnapshot) => void	Invoked whenever a snapshot is produced via getAnalytics().

---

FormAnalyticsSnapshot

Properties

Property	Modifier	Type
startedAt	readonly	number
completedAt	readonly	number | null
errorCount	readonly	number
errorsByField	readonly	Readonly<Record<FieldPath, number>>
abandonedAt	readonly	number | null
currentStep	readonly	number
fieldViews	readonly	Readonly<Record<FieldPath, number>>
dropOffField	readonly	string | null
timeToCompleteMs	readonly	number | null
timeToFirstErrorMs	readonly	number | null

---

OfflineQueueConfig

Properties

Property	Modifier	Type	Description
enabled?	readonly	boolean	-
storageKey?	readonly	string	-
maxItems?	readonly	number	Soft cap on queued items.
overflow?	readonly	OfflineOverflowPolicy	Behavior when maxItems is exceeded. Default: drop-oldest.
idempotencyKey?	readonly	(values: Record<string, unknown>) => string	Deduplicate pending items with the same key (skip enqueue).
onConflict?	readonly	(local: QueuedSubmission<Record<string, unknown>>, error: unknown) => | void | OfflineConflictAction | Promise<void | OfflineConflictAction>	Called when a queued item fails during flush. - keep (default) — leave at head, stop flush - drop — discard and continue - retry — keep at head and continue attempting
onOverflow?	readonly	(dropped: QueuedSubmission<Record<string, unknown>>, policy: OfflineOverflowPolicy) => void	-

---

KeyboardShortcutConfig

Properties

Property	Modifier	Type
combo	readonly	string
action	readonly	"submit" | "saveDraft" | "undo" | "redo"

---

WorkflowConfig

Properties

Property	Modifier	Type
autosave?	readonly	AutosaveConfig
draft?	readonly	DraftConfig
wizard?	readonly	WizardConfig
analytics?	readonly	AnalyticsConfig
offlineQueue?	readonly	OfflineQueueConfig
keyboard?	readonly	readonly KeyboardShortcutConfig[]

---

SubmissionQueueState

Properties

Property	Modifier	Type
pending	readonly	number
flushing	readonly	boolean

---

SetValueOptions

Properties

Property	Modifier	Type
recordHistory?	readonly	boolean
markDirty?	readonly	boolean

---

SubmitOptions

Properties

Property	Modifier	Type
preventDoubleSubmit?	readonly	boolean
includeDiff?	readonly	boolean
retry?	readonly	number | RetryPolicy

---

FormChangeRecord

Properties

Property	Modifier	Type	Description
path	readonly	string	-
type	readonly	FormChangeType	-
previous?	readonly	unknown	-
current?	readonly	unknown	-
from?	readonly	string	Present when type is moved (source path).

---

FormDiffMetadata

Properties

Property	Modifier	Type
durationMs	readonly	number
changeCount	readonly	number
addedCount	readonly	number
removedCount	readonly	number
changedCount	readonly	number
unchangedCount	readonly	number
movedCount	readonly	number

---

FormDiffResult

Properties

Property	Modifier	Type
changes	readonly	readonly FormChangeRecord[]
hasChanges	readonly	boolean
metadata	readonly	FormDiffMetadata

---

FormDiffOptions

Properties

Property	Modifier	Type
maxDepth?	readonly	number
includeUnchanged?	readonly	boolean
treatUndefinedAsMissing?	readonly	boolean

---

SubmitSecurityCaptcha

CAPTCHA token under the submission security namespace (ADR-CAP-001).

Properties

Property	Modifier	Type
provider	readonly	string
token	readonly	string
expiresAt?	readonly	number

---

SubmitSecurityMeta

Security namespace on submit meta. Stable path: meta.security.captcha (future: CSRF, OTP, …).

Properties

Property	Modifier	Type
captcha?	readonly	SubmitSecurityCaptcha

---

SubmitMeta

Properties

Property	Modifier	Type	Description
changedFields?	readonly	readonly string[]	-
diff?	readonly	FormDiffResult	-
signal?	readonly	AbortSignal	-
security?	readonly	SubmitSecurityMeta	Populated by the Security Stage (e.g. CAPTCHA plugin).
upload?	readonly	SubmitUploadMeta	Populated after a successful upload-transport submit.

---

ValidateOptions

Properties

Property	Modifier	Type
paths?	readonly	readonly string[]
mode?	readonly	ValidationMode

---

ResetOptions

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Properties

Property	Modifier	Type
values?	readonly	Partial<TValues>
keepDirty?	readonly	boolean

---

FormConfig

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Properties

Property	Modifier	Type	Description
initialValues?	readonly	TValues	-
target?	readonly	string | HTMLElement	-
form?	readonly	string | HTMLElement	-
schema?	readonly	| SchemaAdapter<Record<string, unknown>> | Partial<Record<string, FieldSchemaDefinition>>	-
onSubmit?	readonly	(values: TValues, meta?: SubmitMeta) => void | Promise<void>	-
onSubmitError?	readonly	(error: unknown) => void	-
onPluginError?	readonly	PluginErrorHandler	Receives isolated plugin/hook failures (setup, hooks, destroy). Does not rethrow — form continues per Phase 15 isolation policy.
validateOn?	readonly	ValidationMode	-
validators?	readonly	Partial<Record<string, | Validator<TValues> | readonly Validator<TValues>[]>>	-
crossFieldValidators?	readonly	readonly CrossFieldRule<TValues>[]	-
formValidators?	readonly	readonly CrossFieldValidator<TValues>[]	-
workflow?	readonly	WorkflowConfig	-
autoSave?	readonly	AutosaveConfig & { every?: string; }	-
wizard?	readonly	boolean | WizardConfig	-
rules?	readonly	readonly FormRuleInput<TValues>[]	-
plugins?	readonly	readonly FormPlugin<TValues>[]	Plugins registered at create time (same as calling form.use(plugin) for each entry, in order). Prefer this for declarative setup; use form.use() later for conditional or late registration.
subscribe?	readonly	| FormSubscribeListener<TValues> | readonly FormSubscribeListener<TValues>[]	State listeners registered at create time (same store as form.subscribe()). Pass one listener or an array. Each receives the form instance, is invoked once after create (so UI can sync immediately), then on every state notify. Lives until form.destroy(). Prefer framework adapters for React/Vue; use this for vanilla / host UI.
dependencies?	readonly	Readonly<Record<string, string | readonly string[]>>	Explicit dependency map: child → parent(s). Cycles throw ConfigurationError at registration (ADR-007).
dependencyActions?	readonly	Partial<Record<string, readonly DependencyAction[]>>	Per-child action overrides for dependencies (default ["clear","revalidate"]).

---

FieldState

Properties

Property	Modifier	Type
touched	readonly	boolean
dirty	readonly	boolean
visited	readonly	boolean
changed	readonly	boolean

---

FormState

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Properties

Property	Modifier	Type	Description
values	readonly	TValues	-
errors	readonly	Readonly<Record<FieldPath, string>>	-
touched	readonly	Readonly<Record<FieldPath, boolean>>	-
dirty	readonly	Readonly<Record<FieldPath, boolean>>	-
visited	readonly	Readonly<Record<FieldPath, boolean>>	-
changed	readonly	Readonly<Record<FieldPath, boolean>>	-
isSubmitting	readonly	boolean	-
isValidating	readonly	boolean	-
isValid	readonly	boolean	-
isDirty	readonly	boolean	-
isChanged	readonly	boolean	-
submitCount	readonly	number	-
submitPhase	readonly	SubmitPhase	Last / current submit lifecycle phase.
workflow	readonly	WorkflowState	-
fieldUi	readonly	FieldUiMap	-
formUi	readonly	FormUiState	-
fieldMeta	readonly	Readonly<Record<FieldPath, FieldMetaState>>	-
fieldOptions	readonly	Readonly<Record<FieldPath, readonly FieldOption[]>>	-
submissionQueue	readonly	SubmissionQueueState	-

---

WorkflowState

Properties

Property	Modifier	Type
currentStep	readonly	number
totalSteps	readonly	number
canGoNext	readonly	boolean
canGoPrev	readonly	boolean
progress	readonly	number
isAutosaving	readonly	boolean
lastAutosaveAt	readonly	number | null

---

FormCheckpoint

Durable form checkpoint — distinct from getSnapshot() (external-store identity).

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Properties

Property	Modifier	Type
version	readonly	1
kind	readonly	"checkpoint"
capturedAt	readonly	number
values	readonly	TValues
errors?	readonly	Readonly<Record<string, string>>
touched?	readonly	Readonly<Record<string, boolean>>
dirty?	readonly	Readonly<Record<string, boolean>>
visited?	readonly	Readonly<Record<string, boolean>>
fieldUi?	readonly	Readonly<Record<string, FieldUiState>>
workflow?	readonly	{ currentStep: number; }
workflow.currentStep	readonly	number

---

CreateCheckpointOptions

Properties

Property	Modifier	Type
include?	readonly	readonly ( | "values" | "workflow" | "touched" | "errors" | "dirty" | "visited" | "fieldUi")[]

---

RestoreCheckpointOptions

Properties

Property	Modifier	Type
recordHistory?	readonly	boolean
restoreMeta?	readonly	boolean

---

FormInstance

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Properties

Property	Modifier	Type	Description
id	readonly	string	-
ref	readonly	FormRef	-
ui	readonly	FormUiProjection<TValues>	Derived UI projection (@jayoncode/form-intelligence/ui). Uses registered policies from ui() plugin, or package defaults.
state	readonly	FormState<TValues>	Current form snapshot — same as getFormState().
workflow	public	{ next: Promise<boolean>; prev: void; goTo: Promise<boolean>; getStepGraph: WizardStepGraph; visibleSteps: readonly string[]; }	-
workflow.next	public	Promise<boolean>	-
workflow.prev	public	void	-
workflow.goTo	public	Promise<boolean>	-
workflow.getStepGraph	public	WizardStepGraph	-
workflow.visibleSteps	public	readonly string[]	-

Methods

field()

field(path: string, options?: FieldOptions<TValues>): FieldHandle<TValues>;

Parameters

Parameter	Type
path	string
options?	FieldOptions<TValues>

Returns

FieldHandle<TValues>

firstInvalidPath()

firstInvalidPath(): string | undefined;

First path with a non-empty error (stable key order).

Returns

string | undefined

focusFirstInvalid()

focusFirstInvalid(): string | undefined;

Focus first invalid control when document exists; SSR-safe no-op. Returns the focused path or undefined.

Returns

string | undefined

registeredFieldPaths()

registeredFieldPaths(): readonly string[];

Paths registered via field() in registration order.

Returns

readonly string[]

pushField()

pushField(arrayPath: string, item?: unknown): string;

Parameters

Parameter	Type
arrayPath	string
item?	unknown

Returns

string

removeField()

removeField(arrayPath: string, index: number): void;

Parameters

Parameter	Type
arrayPath	string
index	number

Returns

void

insertField()

insertField(
   arrayPath: string, 
   index: number, 
   item?: unknown): string;

Parameters

Parameter	Type
arrayPath	string
index	number
item?	unknown

Returns

string

submit()

submit(options?: SubmitOptions): Promise<boolean>;

Parameters

Parameter	Type
options?	SubmitOptions

Returns

Promise<boolean>

cancelSubmit()

cancelSubmit(): void;

Returns

void

useMiddleware()

useMiddleware(middleware: MiddlewareInput<TValues>): () => void;

Register onion middleware for submit/validate phases. Same stack as plugin hooks — see MIDDLEWARE_HOOK_MAP.

Parameters

Parameter	Type
middleware	MiddlewareInput<TValues>

Returns

() => void

reset()

reset(options?: ResetOptions<TValues>): void;

Parameters

Parameter	Type
options?	ResetOptions<TValues>

Returns

void

validate()

validate(options?: ValidateOptions): Promise<boolean>;

Parameters

Parameter	Type
options?	ValidateOptions

Returns

Promise<boolean>

values()

Call Signature

values(): TValues;

Returns

TValues

Call Signature

values(path: string): unknown;

Parameters

Parameter	Type
path	string

Returns

unknown

get()

get(path: string): unknown;

Parameters

Parameter	Type
path	string

Returns

unknown

errors()

errors(path?: string): string | Readonly<Record<string, string>> | undefined;

Parameters

Parameter	Type
path?	string

Returns

string | Readonly<Record<string, string>> | undefined

setValue()

setValue(
   path: string, 
   value: unknown, 
   options?: SetValueOptions): void;

Parameters

Parameter	Type
path	string
value	unknown
options?	SetValueOptions

Returns

void

markNonPersistent()

markNonPersistent(path: string): void;

Mark a path as browser-owned ephemeral (non-persistent). File fields are registered automatically from DOM type="file" or file-shaped values. Drafts, autosave, offline queue, and history omit these paths (ADR-FILE-001).

Parameters

Parameter	Type
path	string

Returns

void

toFormData()

toFormData(options?: ToFormDataOptions): FormData;

Build FormData from current values (files as binary parts). Applications remain responsible for the network transport (ADR-FILE-001).

Parameters

Parameter	Type
options?	ToFormDataOptions

Returns

FormData

payload()

payload(options?: ToFormDataOptions): FormPayload<TValues>;

JSON when no files are present; multipart FormData when any file selection is non-empty.

Parameters

Parameter	Type
options?	ToFormDataOptions

Returns

FormPayload<TValues>

setError()

setError(path: string, message: string): void;

Parameters

Parameter	Type
path	string
message	string

Returns

void

clearErrors()

clearErrors(path?: string): void;

Parameters

Parameter	Type
path?	string

Returns

void

getFieldState()

getFieldState(path: string): FieldState;

Parameters

Parameter	Type
path	string

Returns

FieldState

getFieldMeta()

getFieldMeta(path: string): FieldMetaState;

Parameters

Parameter	Type
path	string

Returns

FieldMetaState

getFormState()

getFormState(): FormState<TValues>;

Returns

FormState<TValues>

getSnapshot()

getSnapshot(): FormState<TValues>;

For useSyncExternalStore(form.subscribe, form.getSnapshot). Not a durable checkpoint.

Returns

FormState<TValues>

getPresentation()

Call Signature

getPresentation(path: string): PresentationState;

Per-path presentation (field UI + options + form UI).

Parameters

Parameter	Type
path	string

Returns

PresentationState

Call Signature

getPresentation(): PresentationSnapshot;

Full presentation maps (same sources as state.fieldUi / formUi / fieldOptions).

Returns

PresentationSnapshot

createCheckpoint()

createCheckpoint(options?: CreateCheckpointOptions): FormCheckpoint<TValues>;

Durable checkpoint for undo/restore flows — see restoreCheckpoint.

Parameters

Parameter	Type
options?	CreateCheckpointOptions

Returns

FormCheckpoint<TValues>

restoreCheckpoint()

restoreCheckpoint(checkpoint: FormCheckpoint<TValues>, options?: RestoreCheckpointOptions): void;

Parameters

Parameter	Type
checkpoint	FormCheckpoint<TValues>
options?	RestoreCheckpointOptions

Returns

void

getValues()

getValues(): TValues;

Returns

TValues

getErrors()

getErrors(): Readonly<Record<FieldPath, string>>;

Returns

Readonly<Record<FieldPath, string>>

isValid()

isValid(): boolean;

Returns

boolean

isSubmitting()

isSubmitting(): boolean;

Returns

boolean

submissionGuard()

submissionGuard(options?: Pick<SubmitOptions, "preventDoubleSubmit">): SubmissionGuardResult;

Hard submission eligibility (enforced by submit()). Distinct from form.ui.canSubmit (UX projection + disableSubmitWhen).

Parameters

Parameter	Type
options?	Pick<SubmitOptions, "preventDoubleSubmit">

Returns

SubmissionGuardResult

isDirty()

isDirty(): boolean;

Returns

boolean

changedFields()

changedFields(): readonly string[];

Returns

readonly string[]

changedSinceSubmitFields()

changedSinceSubmitFields(): readonly string[];

Returns

readonly string[]

diffFromDefaults()

diffFromDefaults(options?: FormDiffOptions): Promise<FormDiffResult>;

Parameters

Parameter	Type
options?	FormDiffOptions

Returns

Promise<FormDiffResult>

diffFrom()

diffFrom(baseline: Record<string, unknown>, options?: FormDiffOptions): Promise<FormDiffResult>;

Parameters

Parameter	Type
baseline	Record<string, unknown>
options?	FormDiffOptions

Returns

Promise<FormDiffResult>

when()

when(field: string): WhenRuleBuilder<TValues>;

Parameters

Parameter	Type
field	string

Returns

WhenRuleBuilder<TValues>

dependencies()

Call Signature

dependencies(map: Readonly<Record<string, string | readonly string[]>>): void;

Register explicit dependency map (fail-fast on cycles).

Parameters

Parameter	Type
map	Readonly<Record<string, string | readonly string[]>>

Returns

void

Call Signature

dependencies(): DependencyRegistrar<TValues>;

Fluent dependency registrar + inspect().

Returns

DependencyRegistrar<TValues>

calculate()

Call Signature

calculate(path: string): CalculationBuilder<TValues>;

Fluent derived field: form.calculate("total").from("price","qty").compute(...).

Parameters

Parameter	Type
path	string

Returns

CalculationBuilder<TValues>

Call Signature

calculate(path: string, options: 
  | CalculateOptions<TValues>
  | ((context: {
  values: TValues;
}) => unknown)): void;

Parameters

Parameter	Type
path	string
options	| CalculateOptions<TValues> | ((context: { values: TValues; }) => unknown)

Returns

void

transform()

Call Signature

transform(path: string): TransformPipelineHandle;

Register inbound transform stages for a path.

Parameters

Parameter	Type
path	string

Returns

TransformPipelineHandle

Call Signature

transform(path: string, stages: readonly TransformFn<TValues>[]): void;

Parameters

Parameter	Type
path	string
stages	readonly TransformFn<TValues>[]

Returns

void

saveDraft()

saveDraft(): void;

Returns

void

restoreDraft()

restoreDraft(options?: RestoreDraftOptions): Promise<boolean>;

Restore persisted draft into the live form (after mount). Returns true when values were applied; false when skipped (disabled / empty / declined / dirty without force / corrupt).

Parameters

Parameter	Type
options?	RestoreDraftOptions

Returns

Promise<boolean>

undo()

undo(): boolean;

Returns

boolean

redo()

redo(): boolean;

Returns

boolean

getAnalytics()

getAnalytics(): FormAnalyticsSnapshot;

Returns

FormAnalyticsSnapshot

flushOfflineQueue()

flushOfflineQueue(): Promise<{
  flushed: number;
  failed: number;
}>;

Returns

Promise<{ flushed: number; failed: number; }>

use()

Call Signature

use(plugin: FormPlugin<TValues>): void;

Parameters

Parameter	Type
plugin	FormPlugin<TValues>

Returns

void

Call Signature

use<TSelected>(selector: FormSelector<TValues, TSelected>): TSelected;

Type Parameters

Type Parameter
TSelected

Parameters

Parameter	Type
selector	FormSelector<TValues, TSelected>

Returns

TSelected

listPlugins()

listPlugins(): readonly {
  name: string;
  order: number;
  version?: string;
}[];

Registered plugins (name / order / version) for DevTools introspection.

Returns

readonly { name: string; order: number; version?: string; }[]

subscribe()

subscribe(listener: () => void): () => void;

Advanced: reactive UI updates. Framework adapters call this internally. For declarative create-time listeners, prefer createForm({ subscribe }).

Parameters

Parameter	Type
listener	() => void

Returns

() => void

on()

on(event: FormEvent, listener: (payload?: unknown) => void): () => void;

Parameters

Parameter	Type
event	FormEvent
listener	(payload?: unknown) => void

Returns

() => void

emit()

emit(event: FormEvent, payload?: unknown): void;

Emit a form lifecycle event (plugins may use for upload:*).

Parameters

Parameter	Type
event	FormEvent
payload?	unknown

Returns

void

destroy()

destroy(): void;

Returns

void

registerPlugin()

registerPlugin(plugin: FormPlugin<TValues>): void;

Parameters

Parameter	Type
plugin	FormPlugin<TValues>

Returns

void

---

FormPluginSetupResult

Properties

Property	Modifier	Type
onDestroy?	readonly	() => void

---

FormPlugin

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Properties

Property	Modifier	Type	Description
name	readonly	string	-
version?	readonly	string	Plugin package/semver label (metadata only).
engines?	readonly	string	Semver range against @jayoncode/form-intelligence (>=3.1.0, ^3.1.0, or exact). Checked at register/use.
order?	readonly	number	-

Methods

setup()

setup(form: FormInstance<TValues>, api: FormPluginApi<TValues>): void | FormPluginSetupResult | (() => void);

Parameters

Parameter	Type
form	FormInstance<TValues>
api	FormPluginApi<TValues>

Returns

void | FormPluginSetupResult | (() => void)

Type Aliases

FieldController

type FieldController<TValues> = FieldHandle<TValues>;

Preferred UI binding surface over reaching into form internals (Phase 16). Alias of the enhanced FieldHandle (includes aria / setAriaIds).

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

---

DependencyAction

type DependencyAction = "clear" | "reloadOptions" | "revalidate" | "recompute" | "preserve";

---

DependencyMap

type DependencyMap = Readonly<Record<FieldPath, FieldPath | readonly FieldPath[]>>;

Map sugar: child path → parent path(s).

---

TransformFn

type TransformFn<TValues> = (value: unknown, ctx: TransformContext<TValues>) => unknown;

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Parameters

Parameter	Type
value	unknown
ctx	TransformContext<TValues>

Returns

unknown

---

FieldUiMap

type FieldUiMap = Readonly<Record<string, FieldUiState>>;

---

WizardNavigateValidation

type WizardNavigateValidation = "step" | "all" | "none";

Validation scope for workflow.goTo. Default "all" preserves SHIPPED behavior.

---

CanonicalFileValue

type CanonicalFileValue = File[];

Canonical in-memory representation for file fields (ADR-FILE-001 Phase A).

---

FormPayloadKind

type FormPayloadKind = "json" | "multipart";

---

FormPayload

type FormPayload<TValues> = 
  | JsonFormPayload<TValues>
  | MultipartFormPayload;

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

---

FormatPreset

type FormatPreset = "philippine-phone" | "credit-card" | "phone" | "currency" | "slug";

---

Formatter

type Formatter = (value: unknown) => unknown;

Parameters

Parameter	Type
value	unknown

Returns

unknown

---

Parser

type Parser = (value: unknown) => unknown;

Parameters

Parameter	Type
value	unknown

Returns

unknown

---

PluginPipelineStage

type PluginPipelineStage = typeof PLUGIN_PIPELINE_STAGES[number];

---

PluginErrorHandler

type PluginErrorHandler = (report: PluginErrorReport) => void;

Parameters

Parameter	Type
report	PluginErrorReport

Returns

void

---

MiddlewarePhase

type MiddlewarePhase = 
  | "beforeValidate"
  | "afterValidate"
  | "beforeSubmit"
  | "afterSubmit"
  | "submitError"
  | "beforeSetValue"
  | "afterSetValue";

Phases that onion middleware and plugin hooks can observe.

---

MiddlewareNext

type MiddlewareNext = () => Promise<void>;

Returns

Promise<void>

---

FormMiddleware

type FormMiddleware<TValues> = (ctx: MiddlewareContext<TValues>, next: MiddlewareNext) => void | Promise<void>;

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Parameters

Parameter	Type
ctx	MiddlewareContext<TValues>
next	MiddlewareNext

Returns

void | Promise<void>

---

MiddlewareInput

type MiddlewareInput<TValues> = 
  | FormMiddleware<TValues> & Partial<MiddlewareRegistration>
  | MiddlewareRegistration & {
  run: FormMiddleware<TValues>;
};

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

---

TtlInput

type TtlInput = 
  | number
  | `${number}ms`
  | `${number}s`
  | `${number}m`
  | `${number}h`;

---

FieldPath

type FieldPath = string;

---

FormRuleInput

type FormRuleInput<TValues> = 
  | FormRuleDefinition<TValues>
  | WhenRuleBuilder<TValues>
  | WhenRuleBuilder;

Plain rule object or a when() builder (createForm calls .build() for builders).

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

---

ValidationMode

type ValidationMode = "onChange" | "onBlur" | "onSubmit" | "onTouched" | "all";

---

FormEvent

type FormEvent = 
  | "change"
  | "blur"
  | "focus"
  | "reset"
  | "submit"
  | "validate"
  | "validated"
  | "autosave"
  | "draft"
  | "upload:progress"
  | "upload:complete"
  | "upload:error";

---

ValidatorResult

type ValidatorResult = true | false | string | undefined;

---

BuiltInFieldType

type BuiltInFieldType = "text" | "email" | "password" | "url" | "file";

---

CustomFieldValidator

type CustomFieldValidator<TValues> = (context: CustomFieldValidatorContext<TValues>) => 
  | ValidatorResult
| Promise<ValidatorResult>;

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Parameters

Parameter	Type
context	CustomFieldValidatorContext<TValues>

Returns

| ValidatorResult | Promise<ValidatorResult>

---

FormRef

type FormRef = (element: HTMLFormElement | null) => void;

Parameters

Parameter	Type
element	HTMLFormElement | null

Returns

void

---

FieldSchemaDefinition

type FieldSchemaDefinition = 
  | BuiltInFieldType
  | FieldSchemaConfig;

---

Validator

type Validator<TValues> = (value: unknown, context: ValidationContext<TValues>) => 
  | ValidatorResult
| Promise<ValidatorResult>;

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Parameters

Parameter	Type
value	unknown
context	ValidationContext<TValues>

Returns

| ValidatorResult | Promise<ValidatorResult>

---

FieldBinding

type FieldBinding = 
  | ValueFieldBinding
  | FileFieldBinding;

Headless binding — file fields omit controlled value (ADR-FILE-001).

---

DraftRestoreDeclinePolicy

type DraftRestoreDeclinePolicy = "keep" | "clear" | "remember";

Policy when onRestorePrompt returns false (user declined).

• keep — leave the draft; the next prompt can ask again (default)
• clear — delete the draft so it will not prompt again
• remember — keep the draft; suppress prompts for the same draft content until it changes

---

RestorePromptResult

type RestorePromptResult = boolean | "defer";

Result of onRestorePrompt.

• true — restore
• false — decline and apply onRestoreDecline
• "defer" — skip this attempt without applying decline policy (e.g. wait until after mount)

---

SubmitPhase

type SubmitPhase = "idle" | "validating" | "submitting" | "success" | "error";

Submit lifecycle phase (Phase 10). isSubmitting remains the boolean loading flag.

---

FormSubscribeListener

type FormSubscribeListener<TValues> = (form: FormInstance<TValues>) => void;

State listener for createForm({ subscribe }). Receives the form instance. Lives until form.destroy() — use form.subscribe() when you need unsubscribe.

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Parameters

Parameter	Type
form	FormInstance<TValues>

Returns

void

---

FormSelector

type FormSelector<TValues, TSelected> = (state: FormState<TValues>) => TSelected;

Type Parameters

Type Parameter
TValues extends Record<string, unknown>
TSelected

Parameters

Parameter	Type
state	FormState<TValues>

Returns

TSelected

---

AsyncValidator

type AsyncValidator<TValues> = Validator<TValues> & {
  __async: true;
};

Type Declaration

Name	Type
__async	true

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

---

AsyncValidatorWithOptions

type AsyncValidatorWithOptions<TValues> = AsyncValidator<TValues> & {
  __asyncOptions: AsyncValidatorOptions<TValues>;
};

Type Declaration

Name	Type
__asyncOptions	AsyncValidatorOptions<TValues>

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

---

FileSizeInput

type FileSizeInput = number | string;

Variables

DEFAULT_FIELD_UI

const DEFAULT_FIELD_UI: FieldUiState;

Defaults when a path is missing from fieldUi (API freeze §5).

---

PRESENTATION_OWNERSHIP

const PRESENTATION_OWNERSHIP: {
  producers: readonly ["workflow.rules", "dependency.populate", "schema.requiredBaseline"];
  consumers: readonly ["dom.enhancer", "framework.adapters", "a11y"];
  nonWriters: readonly ["validation", "transform", "format"];
};

Ownership note (Phase 9 / ADR-018): Workflow rules and schema/static required baseline produce UI intents; Presentation exposes them. Validation must not write visible/hidden/required on validate ticks. DOM enhancer and adapters consume getPresentation / field.ui only.

Type Declaration

Name	Type
producers	readonly ["workflow.rules", "dependency.populate", "schema.requiredBaseline"]
consumers	readonly ["dom.enhancer", "framework.adapters", "a11y"]
nonWriters	readonly ["validation", "transform", "format"]

---

TRANSFORM_INBOUND_ORDER

const TRANSFORM_INBOUND_ORDER: readonly ["trim", "normalize", "sanitize", "custom", "parse"];

Fixed inbound stage order (Alg 8 / 13_TRANSFORM_ENGINE). Format/display is outbound-only and is not part of this list.

---

PLUGIN_PIPELINE_STAGES

const PLUGIN_PIPELINE_STAGES: readonly ["beforeValidate", "validate", "afterValidate", "beforeSubmit", "submit", "afterSubmit", "submitError"];

Documented interceptor stages (Phase 15). Onion useMiddleware + plugin hooks share this map (D-MW-VS-PLUGIN).

---

MIDDLEWARE_HOOK_MAP

const MIDDLEWARE_HOOK_MAP: {
  beforeValidate: "beforeValidate";
  afterValidate: "afterValidate";
  beforeSubmit: "beforeSubmit";
  afterSubmit: "afterSubmit";
};

Maps plugin hook names → middleware phases (Phase 10 / D-MW-VS-PLUGIN). Plugin api.on(hook) and form.useMiddleware share one interceptor stack per phase. Documented pipeline stages: see PLUGIN_PIPELINE_STAGES.

Type Declaration

Name	Type	Default value
beforeValidate	"beforeValidate"	"beforeValidate"
afterValidate	"afterValidate"	"afterValidate"
beforeSubmit	"beforeSubmit"	"beforeSubmit"
afterSubmit	"afterSubmit"	"afterSubmit"

---

MIDDLEWARE_ONLY_PHASES

const MIDDLEWARE_ONLY_PHASES: readonly ["submitError", "beforeSetValue", "afterSetValue"];

Phases that exist only on the middleware onion (no plugin hook synonym yet).

---

ASYNC_VALIDATOR_OPTION_DEFAULTS

const ASYNC_VALIDATOR_OPTION_DEFAULTS: {
  debounce: 300;
  retry: 0;
  timeout: undefined;
  cache: false;
  abortPrevious: true;
  preventDuplicates: true;
  sharedCache: false;
  offline: "skip";
};

Defaults when the options-object overload is used (API_SIGNATURE_FREEZE §1).

Type Declaration

Name	Type	Default value
debounce	300	300
retry	0	0
timeout	undefined	undefined
cache	false	false
abortPrevious	true	true
preventDuplicates	true	true
sharedCache	false	false
offline	"skip"	"skip"

---

email

const email: Validator;

---

required

const required: Validator;

---

url

const url: Validator;

---

FORM_INTELLIGENT_VERSION

const FORM_INTELLIGENT_VERSION: "3.1.0" = "3.1.0";

Package version used for plugin engines compatibility checks.

Functions

createFormController()

function createFormController<TValues>(form: FormInstance<TValues>): FormController<TValues>;

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Parameters

Parameter	Type
form	FormInstance<TValues>

Returns

FormController<TValues>

---

isFrameworkAdapter()

function isFrameworkAdapter(value: unknown): value is FrameworkAdapter<Record<string, unknown>>;

Parameters

Parameter	Type
value	unknown

Returns

value is FrameworkAdapter<Record<string, unknown>>

---

isPersistenceAdapter()

function isPersistenceAdapter(value: unknown): value is PersistenceAdapter<Record<string, unknown>>;

Parameters

Parameter	Type
value	unknown

Returns

value is PersistenceAdapter<Record<string, unknown>>

---

isSchemaAdapter()

function isSchemaAdapter(value: unknown): value is SchemaAdapter<Record<string, unknown>>;

Parameters

Parameter	Type
value	unknown

Returns

value is SchemaAdapter<Record<string, unknown>>

---

isSubmitTransportAdapter()

function isSubmitTransportAdapter(value: unknown): value is SubmitTransportAdapter<Record<string, unknown>, unknown>;

Parameters

Parameter	Type
value	unknown

Returns

value is SubmitTransportAdapter<Record<string, unknown>, unknown>

---

createForm()

function createForm<TValues>(config: FormConfig<TValues>): FormInstance<TValues>;

Create a form workflow instance. Pass target / form.ref for DOM-backed forms (HTML constraints imported on attach), or initialValues for headless usage.

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Parameters

Parameter	Type
config	FormConfig<TValues>

Returns

FormInstance<TValues>

---

pluginAsModule()

function pluginAsModule<TValues>(
   plugin: FormPlugin<TValues>, 
   order?: number, 
api?: FormPluginApi<TValues>): FormModule<TValues>;

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Parameters

Parameter	Type
plugin	FormPlugin<TValues>
order	number
api?	FormPluginApi<TValues>

Returns

FormModule<TValues>

---

computeFieldAria()

function computeFieldAria(input: ComputeFieldAriaInput): FieldAriaResult;

Pure ARIA computation from field state — no DOM queries (Phase 16 / Spec 27).

Parameters

Parameter	Type
input	ComputeFieldAriaInput

Returns

FieldAriaResult

---

calculate()

function calculate<TValues>(path: string): CalculationBuilder<TValues>;

Root helper — returns an unbound builder. Prefer form.calculate(path).

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Parameters

Parameter	Type
path	string

Returns

CalculationBuilder<TValues>

---

dependencies()

function dependencies(map: DependencyMap): DependencyMap;

Standalone helper — returns a normalized dependency map for config merge.

Parameters

Parameter	Type
map	DependencyMap

Returns

DependencyMap

---

resolveFieldUi()

function resolveFieldUi(
   path: string, 
   fieldUi: FieldUiMap, 
   extras?: {
  busy?: boolean;
}): FieldUiState;

Resolve presentation flags for a path with freeze defaults.

Parameters

Parameter	Type
path	string
fieldUi	FieldUiMap
extras?	{ busy?: boolean; }
extras.busy?	boolean

Returns

FieldUiState

---

createTransformPipeline()

function createTransformPipeline(options?: TransformPipelineOptions, outbound?: Formatter): TransformPipeline;

Compile a reusable inbound transform pipeline. Stage order is fixed: trim → normalize → sanitize → custom → parse.

Parameters

Parameter	Type
options	TransformPipelineOptions
outbound?	Formatter

Returns

TransformPipeline

---

runTransformInbound()

function runTransformInbound<TValues>(
   raw: unknown, 
   options: 
  | TransformPipelineOptions
  | readonly TransformFn<TValues>[]
  | undefined, 
   ctx: TransformContext<TValues>): unknown;

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Parameters

Parameter	Type
raw	unknown
options	| TransformPipelineOptions | readonly TransformFn<TValues>[] | undefined
ctx	TransformContext<TValues>

Returns

unknown

---

when()

function when<TValues>(field: string): WhenRuleBuilder<TValues>;

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Parameters

Parameter	Type
field	string

Returns

WhenRuleBuilder<TValues>

---

satisfiesEnginesRange()

function satisfiesEnginesRange(range: string, version?: string): boolean;

Minimal semver range check for plugin engines metadata. Supports: >=x.y.z, ^x.y.z, exact x.y.z.

Parameters

Parameter	Type	Default value
range	string	undefined
version	string	FORM_INTELLIGENT_VERSION

Returns

boolean

---

composeMiddleware()

function composeMiddleware<TContext>(middlewares: readonly PluginMiddleware<TContext>[]): (context: TContext) => Promise<void>;

Type Parameters

Type Parameter
TContext

Parameters

Parameter	Type
middlewares	readonly PluginMiddleware<TContext>[]

Returns

(context: TContext) => Promise<void>

---

runMiddlewareChain()

function runMiddlewareChain<TContext>(middlewares: readonly PluginMiddleware<TContext>[], context: TContext): Promise<void>;

Type Parameters

Type Parameter
TContext

Parameters

Parameter	Type
middlewares	readonly PluginMiddleware<TContext>[]
context	TContext

Returns

Promise<void>

---

clearSharedValidationCaches()

function clearSharedValidationCaches(): void;

Test helper — clears shared namespaces.

Returns

void

---

parseTtl()

function parseTtl(input: TtlInput): number;

Parse TTL input to milliseconds. Plain numbers are treated as milliseconds.

Parameters

Parameter	Type
input	TtlInput

Returns

number

---

matchesField()

function matchesField<TValues>(targetPath: string, message?: string): Validator<TValues>;

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Parameters

Parameter	Type	Default value
targetPath	string	undefined
message	string	"Values must match."

Returns

Validator<TValues>

---

requiredWhen()

function requiredWhen<TValues>(
   sourcePath: string, 
   predicate: (value: unknown, context: ValidationContext<TValues>) => boolean, 
message?: string): Validator<TValues>;

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Parameters

Parameter	Type	Default value
sourcePath	string	undefined
predicate	(value: unknown, context: ValidationContext<TValues>) => boolean	undefined
message	string	"This field is required."

Returns

Validator<TValues>

---

runValidationPipeline()

function runValidationPipeline<TValues>(input: ValidationPipelineInput<TValues>): Promise<Record<string, string>>;

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Parameters

Parameter	Type
input	ValidationPipelineInput<TValues>

Returns

Promise<Record<string, string>>

---

currency()

function currency(options?: CurrencyValidatorOptions): Validator;

Parameters

Parameter	Type
options	CurrencyValidatorOptions

Returns

Validator

---

custom()

function custom<TValues>(fn: CustomFieldValidator<TValues>): Validator<TValues>;

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Parameters

Parameter	Type
fn	CustomFieldValidator<TValues>

Returns

Validator<TValues>

---

asyncValidator()

Call Signature

function asyncValidator<TValues>(validate: Validator<TValues>): AsyncValidator<TValues>;

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Parameters

Parameter	Type
validate	Validator<TValues>

Returns

AsyncValidator<TValues>

Call Signature

function asyncValidator<TValues>(options: AsyncValidatorOptions<TValues>): AsyncValidatorWithOptions<TValues>;

Type Parameters

Type Parameter	Default type
TValues extends Record<string, unknown>	Record<string, unknown>

Parameters

Parameter	Type
options	AsyncValidatorOptions<TValues>

Returns

AsyncValidatorWithOptions<TValues>

---

isAsyncValidator()

function isAsyncValidator<TValues>(validator: Validator<TValues>): validator is AsyncValidator<TValues>;

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Parameters

Parameter	Type
validator	Validator<TValues>

Returns

validator is AsyncValidator<TValues>

---

getAsyncValidatorOptions()

function getAsyncValidatorOptions<TValues>(validator: Validator<TValues>): 
  | AsyncValidatorOptions<TValues>
  | undefined;

Type Parameters

Type Parameter
TValues extends Record<string, unknown>

Parameters

Parameter	Type
validator	Validator<TValues>

Returns

| AsyncValidatorOptions<TValues> | undefined

---

date()

function date(options?: DateValidatorOptions): Validator;

Parameters

Parameter	Type
options	DateValidatorOptions

Returns

Validator

---

parseByteSize()

function parseByteSize(input: string | number): number;

Parse a byte size as a number or human string ("5MB", "500kb", "1 GiB").

Parameters

Parameter	Type
input	string | number

Returns

number

---

accept()

function accept(pattern: string | readonly string[]): Validator;

Require every selected file to match HTML-like accept tokens (extensions .png, MIME image/png, or wildcards image/*).

Parameters

Parameter	Type
pattern	string | readonly string[]

Returns

Validator

---

maxSize()

function maxSize(limit: FileSizeInput): Validator;

Maximum size per file (bytes or "5MB").

Parameters

Parameter	Type
limit	FileSizeInput

Returns

Validator

---

minSize()

function minSize(limit: FileSizeInput): Validator;

Minimum size per file (bytes or "1KB"). Empty selection passes.

Parameters

Parameter	Type
limit	FileSizeInput

Returns

Validator

---

maxFiles()

function maxFiles(limit: number): Validator;

Maximum number of selected files.

Parameters

Parameter	Type
limit	number

Returns

Validator

---

minFiles()

function minFiles(limit: number): Validator;

Minimum number of selected files. Empty still fails when limit > 0.

Parameters

Parameter	Type
limit	number

Returns

Validator

---

maxLength()

function maxLength(max: number): Validator;

Parameters

Parameter	Type
max	number

Returns

Validator

---

minLength()

function minLength(min: number): Validator;

Parameters

Parameter	Type
min	number

Returns

Validator

---

number()

function number(options?: NumberValidatorOptions): Validator;

Parameters

Parameter	Type
options	NumberValidatorOptions

Returns

Validator

---

min()

function min(minimum: number): Validator;

Parameters

Parameter	Type
minimum	number

Returns

Validator

---

max()

function max(maximum: number): Validator;

Parameters

Parameter	Type
maximum	number

Returns

Validator

---

password()

function password(options?: PasswordValidatorOptions): Validator;

Parameters

Parameter	Type
options	PasswordValidatorOptions

Returns

Validator

---

phone()

function phone(message?: string): Validator;

Parameters

Parameter	Type	Default value
message	string	"Enter a valid phone number."

Returns

Validator

---

regex()

function regex(pattern: RegExp, message?: string): Validator;

Parameters

Parameter	Type	Default value
pattern	RegExp	undefined
message	string	"Invalid format."

Returns

Validator