@n0n3br/ngx-form-dependency-engine

@n0n3br/ngx-form-dependency-engine

Reactive dependency engine for Angular FormGroup: declare when → effect rules between controls — "when these conditions hold against the form's value, apply these effects to a target control."

No visual builder, no schema framework. One engine class, pure functions, real Angular signals.

Features

• 15 condition operators (equals, in, contains, matches, greaterThan, isEmpty, custom predicates…)
• AND / OR groups with arbitrary nesting
• Effects: show · hide · enable · disable · setRequired · unsetRequired · addValidators / removeValidators (namespaced) · setValue · setOptions
• Per-dependency and per-key validator namespacing — strictly additive over baseline validators
• Chained rules propagate inside one pass; genuine cycles are capped (maxIterations) and warned, never hang
• Emit-free internal writes (emitEvent: false) — no re-entrancy surprises
• hiddenFields / fieldOptions exposed as real signals; zoneless-ready

Requires Angular ≥ 22 with Reactive Forms.

Install

npm install @n0n3br/ngx-form-dependency-engine

Quick start

import { Component, DestroyRef, inject } from '@angular/core';
import { FormControl, FormGroup, Validators } from '@angular/forms';
import {
  FormDependencyEngine,
  dep,
  f,
  allOf,
  show,
  hide,
  setRequired,
} from '@n0n3br/ngx-form-dependency-engine';

@Component({/* ... */})
export class QuoteComponent {
  readonly form = new FormGroup({
    kind: new FormControl<'PF' | 'PJ'>('PF'),
    companyDoc: new FormControl(''),
    personDoc: new FormControl(''),
    income: new FormControl(0),
  });

  readonly engine = new FormDependencyEngine(this.form, [
    dep('doc-type', 'companyDoc')
      .when(f('kind').equals('PJ'))
      .then(show(), setRequired())
      .otherwise(hide())
      .build(),
    dep('premium', 'bonus')
      .when(allOf(f('kind').equals('PF'), f('income').greaterThan(5000)))
      .then(show())
      .build(),
  ]);

  constructor() {
    inject(DestroyRef).onDestroy(() => this.engine.destroy());
    this.engine.activate(); // runs an initial pass, then follows form.valueChanges
  }
}

@if (!engine.isHidden('companyDoc')) {
<input [formControl]="form.controls.companyDoc" />
}

Directive usage

Prefer configuring rules straight from the template? Attach fdeDependencies to the <form> element. The directive owns the engine lifecycle (build, activate, rebuild on input change, destroy) and is exported as fde so templates read state directly.

import { Component } from '@angular/core';
import { FormControl, FormGroup } from '@angular/forms';
import {
  Dependency,
  dep,
  f,
  hide,
  setOptions,
  setRequired,
  show,
  unsetRequired,
} from '@n0n3br/ngx-form-dependency-engine';

@Component({/* ... */})
export class SignupComponent {
  readonly form = new FormGroup({
    accountType: new FormControl('personal'),
    companyName: new FormControl(''),
    plan: new FormControl('Starter'),
  });

  readonly deps: Dependency[] = [
    dep('business-company', 'companyName')
      .when(f('accountType').equals('business'))
      .then(show(), setRequired())
      .otherwise(hide(), unsetRequired())
      .build(),
    dep('plan-options', 'plan')
      .when(f('accountType').equals('business'))
      .then(setOptions(['Team', 'Enterprise']))
      .build(),
  ];
}

<form [formGroup]="form" [fdeDependencies]="deps" #fde="fde">
  @if (!fde.isHidden('companyName')) {
  <input formControlName="companyName" />
  }

  <select formControlName="plan">
    @for (plan of fde.optionsFor('plan') ?? []; track plan) {
    <option [value]="plan">{{ plan }}</option>
    }
  </select>
</form>

Directive API:

Member	Description
fdeDependencies	Dependency[] input; pass null to run with no rules. Swapping the array at runtime rebuilds the engine.
fdeConfig	Optional FormDependencyEngineConfig (e.g. maxIterations).
engine	Readonly signal with the live FormDependencyEngine instance (or null before init).
isHidden(path)	Null-safe visibility read for templates.
optionsFor(path)	Null-safe option list read.
reevaluate()	Force an evaluation pass.

Works with [formGroup] (reactive) and template-driven forms — it resolves whatever ControlContainer hosts the element. Reactive forms are recommended since the engine maps controls at construction time.

Core API

new FormDependencyEngine(form, dependencies, config?)

Member	Description
activate(): Subscription	Runs the first evaluation pass, then re-evaluates on every form.valueChanges.
destroy(): void	Unsubscribes.
reevaluate(): void	Forces a manual evaluation pass.
isHidden(field): boolean	Reads the hiddenFields signal set.
optionsFor(field): unknown[] | undefined	Reads the fieldOptions signal map.
hiddenFields: Signal<ReadonlySet<string>>	Fields currently hidden by hide effects.
fieldOptions: Signal<ReadonlyMap<string, unknown[]>>	Option lists written by setOptions.
settled: Signal<number>	Bumps after every evaluation pass — use it in computed()s to track emit-free writes.

config: { maxIterations?: number } — how many internal passes a single evaluation may take while still changing state (default 5). Hitting the cap logs a circular-dependency warning.

Conditions

interface Condition {
  field: string; // dot-path into the form value, e.g. "endereco.cidade"
  operator: ConditionOperator;
  value?: unknown;
  custom?: (formValue: any) => boolean; // wins over operator entirely
}

Operators: equals · notEquals · in · notIn · contains · notContains · greaterThan · greaterOrEqual · lessThan · lessOrEqual · isEmpty · isNotEmpty · truthy · falsy · matches.

Groups combine with { logic: 'AND' | 'OR', conditions: [...] }; empty AND is vacuously true.

Effects

Every effect accepts an optional target override (defaults to the owning dependency's target).

Effect	Extra payload	Behavior
show / hide	—	Toggles membership in hiddenFields. Never clears values.
enable / disable	—	Native control enable/disable; guarded no-op if already in that state.
setRequired / unsetRequired	—	Namespaced by the dependency id — two dependencies can require the same field independently.
addValidators / removeValidators	key, validators?	Arbitrary validator sets under your own stable key.
setValue	value literal or (formValue) => value	Writes with emitEvent: false.
setOptions	options literal or (formValue) => options	Writes into the fieldOptions signal only.

Validator management is strictly additive: validators present on a control before the engine ever touched it are preserved through every attach/detach cycle.

Evaluation loop

Because internal writes do not emit events, the engine loops internally: evaluate all dependencies → apply effects → compare state by content (never by reference) → repeat until nothing changes or maxIterations is reached. A chain A→B→C fully propagates within a single pass series; a true cycle caps out and warns.

Fluent rule builder

The builder layer produces plain, frozen contract objects — identical to hand-written literals.

import { allOf, anyOf, dep, f, not } from '@n0n3br/ngx-form-dependency-engine';
import { Validators } from '@angular/forms';

const dependency = dep('show-guarantee', 'guarantee')
  .when(
    allOf(f('amount').greaterThan(50000), anyOf(f('profile').equals('gold'), f('vip').truthy())),
  )
  .then(show(), setRequired(), addValidators('min-len', [Validators.minLength(3)]))
  .otherwise(hide(), unsetRequired())
  .build();

• f(path) — every operator is a method: .equals(), .in([...]), .isEmpty(), .matches(/re/)…
• .and() / .or() — chain groups: f('a').equals(1).and(f('b').equals(2)).or(f('c').equals(3))
• allOf(...) / anyOf(...) / not(condition) — combinators
• Effect factories: show(target?), hide(), enable(), disable(), setRequired(), unsetRequired(), addValidators(key, validators, target?), removeValidators(key, target?), setValue(valueOrFn, target?), setOptions(optionsOrFn, target?)
• dep(id, target).when(...).then(...).otherwise(...).build() — throws without when, freezes its output

Demo application

This repository ships an interactive showcase covering every feature:

git clone https://github.com/rogeriolaa/ngx-form-dependency-engine
cd ngx-form-dependency-engine
npm install
npm start          # serves the demo at http://localhost:4200

Sections: Playground · Cascade · Validators Lab · Chains & Cycles · State Inspector · Builder Playground.

Development

Command	Description
npm run build:lib	Build the publishable library to dist/.
npm test	Run the library unit tests (Vitest).
npm run test:coverage	Unit tests with a V8 coverage report (kept at ~99% statements).
ng test demo	Run demo tests.
npm run lint	ESLint across workspace.
npm run build:demo	Production build of the demo (Pages base href).

License

MIT rogeriolaa