xdbc 1.0.216 → 1.0.218

package/.gitattributes

@@ -1,3 +1,11 @@
+# Enforce LF line endings for all text files
+* text=auto eol=lf
+
+# Explicitly binary files
+*.png binary
+*.jpg binary
+*.ico binary
+
 # Exclude generated site output from GitHub language statistics.
 docs/** linguist-generated=true
 coverage/** linguist-generated=true

package/.vscode/settings.json

@@ -1,3 +1,3 @@
-{
-	"cSpell.words": ["alia", "esign", "ontract", "Paramvalue", "Postconditions"]
-}
+{
+	"cSpell.words": ["alia", "esign", "ontract", "Paramvalue", "Postconditions"]
+}

package/.vscode/tasks.json

@@ -1,23 +1,23 @@
-{
-	"version": "2.0.0",
-	"tasks": [
-		{
-			"label": "Build and Publish to NPM",
-			"type": "shell",
-			"command": "npm version patch --no-git-tag-version; npm run build; npm publish",
-			"problemMatcher": [],
-			"group": "build"
-		},
-		{
-			"label": "Serve Test.html",
-			"type": "shell",
-			"command": "Copy-Item Test.html dist\\index.html; npm start",
-			"problemMatcher": [],
-			"isBackground": true,
-			"presentation": {
-				"reveal": "always",
-				"panel": "new"
-			}
-		}
-	]
-}
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"label": "Build and Publish to NPM",
+			"type": "shell",
+			"command": "npm version patch --no-git-tag-version; npm run build; npm publish",
+			"problemMatcher": [],
+			"group": "build"
+		},
+		{
+			"label": "Serve Test.html",
+			"type": "shell",
+			"command": "Copy-Item Test.html dist\\index.html; npm start",
+			"problemMatcher": [],
+			"isBackground": true,
+			"presentation": {
+				"reveal": "always",
+				"panel": "new"
+			}
+		}
+	]
+}

package/ASSESSMENT.md

@@ -0,0 +1,249 @@
+# XDBC — Code Quality Assessment
+
+**Date:** May 9, 2026
+**Version:** 1.0.217
+**Scope:** 24 TypeScript source files (4,425 LOC), 19 test suites (1,539 LOC, 218 tests), build configuration, and project structure.
+
+---
+
+## Executive Summary
+
+XDBC is a production-ready TypeScript Design by Contract framework built on the decorator pattern. It provides 17 contract types — from basic type and equality checks through Zod schema validation, conditional logic, and declarative HTML input binding — all surfaced as ergonomic `@PRE`, `@POST`, and `@INVARIANT` decorators. The codebase is clean, fully documented, zero-warning, and comprehensively tested. Architecture is mature: factory helpers centralize decorator wiring, caching is bounded, DBC instances are decoupled from global state, and the DOM binding layer extends the framework declaratively to HTML without any JavaScript wiring.
+
+| Dimension | Score | Notes |
+|---|---|---|
+| Architecture | 9 / 10 | Clean hierarchy, factory pattern, decoupled instances, composable contracts |
+| Code Quality | 9 / 10 | 0 TypeScript errors, JSDoc on all public APIs, justified `any` usage |
+| Test Coverage | 9 / 10 | 218 tests across 19 suites; all contracts, decorators, DOM binding, and callbacks covered |
+| Security | 9.5 / 10 | Prototype pollution blocked, ReDoS-safe, HTML-sanitized errors, 0 audit vulnerabilities |
+| Performance | 8 / 10 | Lazy regex compilation, bounded FIFO caches, zero-cost disabling |
+| Maintainability | 9 / 10 | Consistent patterns, factory helpers, extensible DOM registry, 0 TODO/FIXME debt |
+| **Overall** | **9 / 10** | Production-ready with excellent correctness, security, test coverage, and extensibility |
+
+---
+
+## 1. Architecture
+
+XDBC follows a single-inheritance hierarchy: `DBC` is the base class providing the entire decorator infrastructure, and 17 contract classes extend it. Each contract class exposes three static decorator factories (`PRE`, `POST`, `INVARIANT`), a static `checkAlgorithm()` for composable use, and an instance `check()` method for dynamic scenarios.
+
+**Strengths:**
+
+- **Factory helpers** (`createPRE`, `createPOST`, `createINVARIANT`) centralize decorator wiring in the base class, eliminating hundreds of lines of duplicated boilerplate across contracts
+- **Decoupled instances** — `DBC.register()` separates construction from global mounting; `DBC.isolated()` enables test isolation without global state pollution; `DBC.getRegistered()` provides a typed public accessor
+- **Composability** — `AE` (Array Element) accepts any `{ check(toCheck) }` object, enabling contract chaining (e.g., AE + REGEX to validate every element of an array matches a pattern)
+- **Path resolution** — Dot notation, array indices, method calls, and `::` multi-path syntax for deep property access in nested structures
+- **Lazy initialization** — `REGEX.stdExp` patterns compiled on first access, not at import time
+- **DOM binding layer** — `scanDOM()` + `registerDOMContract()` extend the framework to HTML inputs declaratively, with a full registry of all attribute-expressible contracts and an OR fragment combinator
+
+**Contract library:**
+
+| Category | Contracts |
+|---|---|
+| Equality | EQ, DIFFERENT |
+| Type | TYPE, INSTANCE, DEFINED, UNDEFINED |
+| Comparison | GREATER, LESS, GREATER_OR_EQUAL, LESS_OR_EQUAL |
+| Pattern | REGEX (+ 13 built-in standard patterns), ZOD |
+| Structure | JSON_OP, JSON_Parse, HasAttribute, ARRAY, PLAIN_OBJECT |
+| Logic | OR, AE (Array Element), IF (conditional) |
+
+---
+
+## 2. Code Quality
+
+### Compiler Status
+
+**0 TypeScript errors.** Strict mode enabled with `experimentalDecorators`, `emitDecoratorMetadata`, target ES6, `moduleResolution: "bundler"`, and explicit `rootDir: "./src"`.
+
+### Type Safety
+
+`any` annotations are confined to reflection and decorator boundaries where TypeScript cannot express the runtime types. Each is documented with a `biome-ignore lint/suspicious/noExplicitAny` comment explaining the necessity. No gratuitous `any` usage exists outside those boundaries.
+
+### Documentation
+
+100% JSDoc coverage on all public methods with `@param`, `@returns`, and `@throws` tags. Region markers (`#region`/`#endregion`) structure each file into logical sections. TypeDoc configuration generates browsable HTML documentation (`npm run docs`).
+
+### Code Organization
+
+| File | LOC | Responsibility |
+|---|---|---|
+| DBC.ts | ~800 | Core infrastructure: decorators, caching, path resolution, reporting, `onInfringement` callback |
+| Demo.ts | ~500 | Full-coverage usage examples — all 17 contracts demonstrated |
+| AE.ts | ~271 | Array element contract (most complex) |
+| REGEX.ts | ~179 | Pattern matching + 13 lazy standard expressions |
+| OR.ts | ~175 | Logical OR composition |
+| DOM.ts | ~120 | Declarative HTML input binding via `data-xdbc-*` attributes |
+| Remaining 17 | 30–150 each | Individual contracts, well-scoped |
+
+No dead code, no unused imports, no TODO/FIXME comments.
+
+---
+
+## 3. Test Coverage
+
+**218 tests across 19 suites — all passing.**
+
+| Test Suite | Tests | Focus |
+|---|---|---|
+| ARRAY | ~8 | Array type enforcement, null/undefined passthrough |
+| PLAIN_OBJECT | ~8 | Plain object enforcement, array/null rejection |
+| DEFINED | ~6 | Null and undefined rejection |
+| UNDEFINED | ~6 | Non-undefined rejection |
+| REGEX | ~15 | Pattern matching, standard expressions, invert mode |
+| TYPE | ~10 | Type checking, multi-type strings |
+| EQ | ~10 | Strict equality, path resolution, inversion |
+| GREATER / LESS / comparisons | ~16 | All four comparison directions, boundary values |
+| AE | ~14 | Array element checking, index and range modes |
+| INSTANCE | ~8 | Constructor instance checks |
+| OR | ~10 | Multi-condition OR logic |
+| IF | ~8 | Conditional contract (condition + inCase) |
+| HasAttribute | ~8 | HTMLElement attribute presence |
+| JSON_OP | ~8 | Object property + type checking |
+| JSON_Parse | ~6 | JSON string parseability |
+| ZOD | ~12 | Zod schema validation (string, number, object) |
+| Decorators | ~25 | PRE, POST, INVARIANT, ParamvalueProvider, static methods |
+| onInfringement | ~19 | Callback signature, type/value context, decorator integration |
+| DOM | ~38 | All 10 attribute contracts, OR fragments, IME, registerDOMContract, onInfringement integration |
+
+**Notable test characteristics:**
+
+- Happy path and negative cases for every contract
+- Edge cases: null, undefined, empty string, zero, false, boundary values
+- Invert mode tested where applicable (EQ→DIFFERENT, HasAttribute, IF)
+- HTMLElement contracts tested natively via jsdom environment
+- DOM tests verify input reversion, event cleanup, and IME composition handling
+- `onInfringement` tests verify all three context types (`precondition`, `postcondition`, `invariant`) and the `value` field
+
+---
+
+## 4. Security
+
+| Protection | Implementation | Status |
+|---|---|---|
+| Prototype pollution | `resolve()` blocks `__proto__`, `constructor`, `prototype` tokens | ✅ |
+| ReDoS | `REGEX.stdExp.url` uses non-backtracking pattern | ✅ |
+| Error message injection | `DBC.sanitize()` HTML-entity-encodes all interpolated values | ✅ |
+| No dangerous patterns | No `eval()`, `Function()`, or dynamic code execution | ✅ |
+| DOM input reversion | Invalid input reverted before the DOM sees it; throws swallowed inside event handler | ✅ |
+| Minimal dependencies | `reflect-metadata` + `zod` at runtime only | ✅ |
+| 0 npm audit vulnerabilities | Clean dependency tree (overrides applied for transitive vulnerabilities) | ✅ |
+
+---
+
+## 5. Performance
+
+| Optimization | Detail |
+|---|---|
+| **Lazy regex** | `REGEX.stdExp` compiles 13 patterns on first access, not at import |
+| **Cached DBC lookups** | Decorator factories resolve the DBC instance once and reuse on subsequent calls |
+| **Path token cache** | Parsed path tokens cached (FIFO, max 1000 entries) |
+| **DBC instance cache** | Resolved namespace paths cached (FIFO, max 1000 entries) |
+| **Zero-cost disable** | `executionSettings.check*` flags short-circuit before any validation logic |
+| **IME-aware DOM binding** | Validation suspended during composition; fired once on `compositionend` |
+
+**Inherent characteristics** (not defects):
+
+- Closures per decorated method — required by the decorator pattern
+- `paramValueRequests` nested Map — O(1) key lookup, iteration only over contracted parameters per method (typically 1–5)
+- `scanDOM()` queries the subtree once at call time; listeners are attached per element with a cleanup function returned
+
+---
+
+## 6. Notable Features
+
+### `onInfringement` Callback
+
+Infringement handling is configurable per DBC instance via `infringementSettings`:
+
+```ts
+dbc.infringementSettings.throwException = true;
+dbc.infringementSettings.logToConsole = false;
+dbc.infringementSettings.onInfringement = (infringement, context) => {
+    // infringement — DBC.Infringement (extends Error, has .message and .stack)
+    // context.type — "precondition" | "postcondition" | "invariant"
+    // context.value — the raw value that violated the contract
+    Sentry.captureException(infringement, { extra: context });
+};
+```
+
+The callback fires before `throwException`, so it always runs even when an exception is thrown. All three settings are independent and combinable.
+
+### DOM / HTML Input Binding
+
+```ts
+import { scanDOM } from "xdbc/DBC/DOM";
+const cleanup = scanDOM(); // returns a removeEventListeners function
+```
+
+```html
+<input data-xdbc data-xdbc-regex="^\d*$" />
+<input data-xdbc data-xdbc-or="regex:^\d+$;;eq:N/A" />
+```
+
+All 10 attribute-expressible contracts are registered out of the box. Custom contracts can be added via `registerDOMContract(key, checkFn)` before calling `scanDOM()`.
+
+### `DBC.getRegistered(path?)`
+
+Public static that returns a registered DBC instance by namespace path, enabling programmatic access to any registered instance without holding a direct reference.
+
+---
+
+## 7. Build & Tooling
+
+| Tool | Version | Configuration |
+|---|---|---|
+| TypeScript | 5.8 | Strict, decorators, ES6 target, `moduleResolution: "bundler"` |
+| Webpack | 5.99 | `ts-loader`, inline source maps, entry `./src/Demo.ts` |
+| Jest + ts-jest | 29.7 | jsdom environment, 19 test suites |
+| Biome | 1.9.4 | Tabs, recommended lint rules, import organization |
+| TypeDoc | configured | `npm run docs` generates full HTML API documentation |
+| GitHub Actions | CI workflow | Lint → Test (with coverage) → Build on every push |
+
+**Runtime dependencies:** `reflect-metadata`, `zod` — minimal and appropriate.
+
+---
+
+## 8. Strengths
+
+- **Comprehensive contract library** — 17 contracts covering types, equality, comparison, regex, JSON, arrays, instances, conditionals, and schema validation
+- **Ergonomic API** — Non-invasive decorators that preserve clean method signatures
+- **Rich error context** — Infringement messages include class name, method name, parameter index, path, and violation details; `onInfringement` callback provides the full `DBC.Infringement` instance and context type
+- **Flexible execution** — Enable/disable preconditions, postconditions, and invariants independently; log, callback, or throw on violations
+- **Deep property validation** — Dot notation paths, array indices, method calls, multi-path `::` syntax
+- **Type-safe imperative checks** — `tsCheck()` static methods on REGEX, TYPE, INSTANCE, OR, EQ, ZOD for use outside decorators
+- **Standard pattern library** — 13 ready-to-use RegExp patterns (email, URL, BCP47, date, CSS selectors, etc.) lazily compiled
+- **Declarative DOM binding** — `scanDOM()` + `data-xdbc-*` attributes enforce contracts on HTML inputs without per-element JavaScript
+- **Extensible** — `registerDOMContract()` lets consumers plug in custom contracts; `DBC.register()` decouples instance lifecycle
+- **Zero technical debt** — No TODO/FIXME, no dead code, no unused imports, 0 TS errors, 0 lint violations, 0 audit vulnerabilities
+
+---
+
+## 9. Recommendations
+
+| # | Recommendation | Priority | Effort |
+|---|---|---|---|
+| 1 | Add Jest coverage thresholds to `jest.config.js` to protect coverage over time | Low | 15m |
+| 2 | Add pre-commit hooks (husky + lint-staged) to enforce format/lint before commit | Low | 1h |
+| 3 | Publish `DOM.ts` as a separate npm entry point (`"exports"` field in `package.json`) for consumers who do not need DOM binding | Low | 30m |
+
+---
+
+## Appendix: Null/Undefined Behavior Matrix
+
+| Contract | `null` | `undefined` | Rationale |
+|---|---|---|---|
+| DEFINED | Error | Error | Exists to catch null/undefined |
+| UNDEFINED | Error | Pass | Exists to require undefined |
+| TYPE | Pass | Pass | Optional parameters — no value means no violation |
+| REGEX | Pass | Pass | Optional parameters — no value means no violation |
+| INSTANCE | Pass | Pass | Optional parameters — no value means no violation |
+| ARRAY | Pass | Pass | Optional parameters — no value means no violation |
+| PLAIN_OBJECT | Pass | Pass | Optional parameters — no value means no violation |
+| EQ | `=== null` | `=== undefined` | Strict equality — works correctly |
+| COMPARISON | Crashes | Crashes | Correct — comparing null numerically is a programming error |
+| AE | Delegates | Delegates | Passes through to sub-contract behavior |
+| OR | Delegates | Delegates | Passes through to sub-contract behavior |
+| IF | Delegates | Delegates | Depends on condition/inCase contracts |
+| JSON_OP | Error | Error | Invalid input |
+| JSON_Parse | Throws | Throws | Not a parseable string |
+| HasAttribute | Error | Error | Not an HTMLElement |
+| ZOD | Delegates | Delegates | Depends on Zod schema definition |

package/README.md

@@ -3,7 +3,7 @@
   <img src="https://img.shields.io/npm/l/xdbc?style=flat-square" alt="license" />
   <img src="https://img.shields.io/npm/dt/xdbc?style=flat-square" alt="downloads" />
   <img src="https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript" alt="TypeScript" />
-  <img src="https://img.shields.io/badge/decorators-stage%203-green?style=flat-square" alt="decorators" />
+  <img src="https://img.shields.io/badge/decorators-experimentalDecorators-blue?style=flat-square" alt="decorators" />
   <img src="https://img.shields.io/badge/optimized%20for-VS%20Code-007acc?style=flat-square&logo=visualstudiocode" alt="VS Code" />
 </p>
 
@@ -36,12 +36,15 @@ index 2. Value has to comply to regular expression "/^(?i:(NOW)|([+-]\d+[dmy]))$
 - [What is Design by Contract?](#what-is-design-by-contract)
 - [Why XDBC?](#why-xdbc)
 - [Installation](#installation)
+- [Decorator API](#decorator-api)
 - [Quick Start](#quick-start)
 - [Contracts Reference](#contracts-reference)
 - [Core Concepts](#core-concepts)
 - [Advanced Features](#advanced-features)
+- [DOM / HTML Input Binding](#dom--html-input-binding)
 - [Configuration](#configuration)
 - [API Documentation](#api-documentation)
+- [Built With XDBC](#built-with-xdbc)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -101,6 +104,20 @@ npm install xdbc
 
 ---
 
+## Decorator API
+
+XDBC is built on TypeScript's **legacy (`experimentalDecorators`) decorator API** — not the TC39 Stage 3 decorator API.
+
+**Why?** Stage 3 decorators deliberately excluded parameter decorators from their scope. Parameter decorators are the foundation of XDBC's contract syntax: `@DEFINED.PRE()`, `@GREATER.PRE(0)`, and every other `PRE` contract applied per-parameter depends on them. There is no equivalent in Stage 3, and no workaround that preserves the same ergonomics.
+
+**Is this unusual?** No. Some of the most widely adopted TypeScript frameworks in the industry require `experimentalDecorators` for exactly the same reason and have no near-term plans to migrate: on the backend, NestJS (used at thousands of companies, tens of millions of weekly downloads), TypeORM, class-validator, and class-transformer; on the frontend, `vue-class-component` (Vue's official class-based API) and MobX (the dominant React state management library for class-based stores). `experimentalDecorators: true` is compatible with Angular, Vue, and React — it is a TypeScript compiler flag, not a framework-level constraint, and does not conflict with any framework's runtime behavior. Any project already using these libraries has `experimentalDecorators: true` in its tsconfig and can adopt XDBC with zero additional configuration. For projects that don't, enabling it requires adding two lines to `tsconfig.json` — see [Installation](#installation).
+
+**Is it risky?** No. TypeScript explicitly supports both APIs simultaneously and has made no announcement about removing `experimentalDecorators`. Any project already using the frameworks above already has `experimentalDecorators: true` in its tsconfig, meaning XDBC requires zero additional configuration in those environments.
+
+**What about the future?** TC39 has an active Stage 1 proposal — [Class Method Parameter Decorators](https://github.com/tc39/proposals/blob/main/stage-1-proposals.md) (Ron Buckton, 2023) — that would close this gap. When parameter decorators reach a stable stage, XDBC will migrate to Stage 3. Because all decorator wiring is contained in `DBC.ts` and the 17 contract classes are completely insulated from it, that migration will be localized and non-breaking at the API level.
+
+---
+
 ## Quick Start
 
 ```typescript
@@ -149,6 +166,7 @@ XDBC ships with **16 contracts** organized into core validators and derived spec
 | **`JSON_Parse`** | String must be valid JSON; optionally forwards parsed result | `new JSON_Parse(receptor?: (json) => void)` |
 | **`DEFINED`** | Value must not be `null` or `undefined` | — |
 | **`UNDEFINED`** | Value must be `undefined` | — |
+| **`ARRAY`** | Value must be an array | — |
 | **`HasAttribute`** | HTMLElement must possess a named attribute | `HasAttribute.PRE(attrName, invert?)` |
 | **`ZOD`** | Value must validate against a Zod schema | `new ZOD(schema: z.ZodType)` |
 
@@ -161,6 +179,7 @@ XDBC ships with **16 contracts** organized into core validators and derived spec
 | **`LESS`** | `COMPARISON` | `value < reference` |
 | **`LESS_OR_EQUAL`** | `COMPARISON` | `value <= reference` |
 | **`DIFFERENT`** | `EQ` | `value !== reference` |
+| **`PLAIN_OBJECT`** | `ARRAY` | Value must be a non-null, non-array object |
 
 ### Built-in Regular Expressions
 
@@ -316,6 +335,95 @@ const result = OR.tsCheck<string>(input, [new EQ("a"), new EQ("b")]);
 
 ---
 
+## DOM / HTML Input Binding
+
+XDBC can enforce contracts directly on `<input>` and `<textarea>` elements using HTML data attributes — no JavaScript wiring required per element.
+
+### Setup
+
+```ts
+import { scanDOM } from "xdbc/DBC/DOM";
+
+// Call once after the DOM is ready. Returns a cleanup function.
+const cleanup = scanDOM();
+
+// Optionally scope to a subtree:
+const cleanup = scanDOM(document.getElementById("my-form"));
+
+// Remove all listeners (e.g. on component unmount):
+cleanup();
+```
+
+### Marking an element
+
+Add `data-xdbc` to opt an element in. The optional value sets the DBC instance path (default: `"WaXCode.DBC"`):
+
+```html
+<input data-xdbc />
+<input data-xdbc="MyApp.DBC" />
+```
+
+### Built-in contract attributes
+
+| Attribute | Example value | Contract |
+|---|---|---|
+| `data-xdbc-regex` | `^\d*$` | `REGEX` |
+| `data-xdbc-type` | `string\|number` | `TYPE` |
+| `data-xdbc-eq` | `hello` | `EQ` |
+| `data-xdbc-different` | `forbidden` | `EQ` (inverted) |
+| `data-xdbc-defined` | *(no value needed)* | `DEFINED` |
+| `data-xdbc-undefined` | *(no value needed)* | `UNDEFINED` |
+| `data-xdbc-greater` | `5` | `COMPARISON` |
+| `data-xdbc-greater-or-equal` | `5` | `COMPARISON` |
+| `data-xdbc-less` | `100` | `COMPARISON` |
+| `data-xdbc-less-or-equal` | `100` | `COMPARISON` |
+| `data-xdbc-or` | `regex:^\d+$;;eq:N/A` | OR combinator (see below) |
+
+Multiple attributes on one element are all enforced — the first failure blocks and reports.
+
+### OR fragment syntax
+
+Use `data-xdbc-or` to express that the value must satisfy **at least one** of several contracts. Fragments are separated by `;;`; each fragment is `<contract-key>:<value>`, where the split is on the **first** `:` only (so colons inside regex patterns are safe):
+
+```html
+<!-- digits, OR exactly the string "N/A" -->
+<input data-xdbc data-xdbc-or="regex:^\d+$;;eq:N/A" />
+
+<!-- http or https URL, OR the literal "N/A" -->
+<input data-xdbc data-xdbc-or="regex:^https?://;;eq:N/A" />
+```
+
+### Behaviour on infringement
+
+1. The element's value is **reverted** to the last accepted state, blocking the invalid input.
+2. The DBC instance's `onInfringement`, `logToConsole`, and `throwException` settings are all honoured. Any throw is swallowed inside the event handler so it cannot propagate unhandled.
+
+### IME / composition awareness
+
+Validation is suspended during IME composition (e.g. CJK on-screen keyboards) and runs once on `compositionend`, so partially composed characters are never incorrectly rejected.
+
+### Registering custom contracts
+
+Use `registerDOMContract` to add any contract — including future ones — without modifying the library:
+
+```ts
+import { registerDOMContract } from "xdbc/DBC/DOM";
+import { MY_CONTRACT } from "./MY_CONTRACT";
+
+// Register once, before scanDOM():
+registerDOMContract("my-contract", (value, attrValue) =>
+    MY_CONTRACT.checkAlgorithm(value, attrValue),
+);
+```
+
+```html
+<input data-xdbc data-xdbc-my-contract="someConfig" />
+```
+
+The `attrValue` string is whatever appears in the attribute — parse it however your contract needs.
+
+---
+
 ## Configuration
 
 ### DBC Instance Settings
@@ -336,8 +444,18 @@ dbc.executionSettings.checkInvariants = true;
 // Configure infringement handling
 dbc.infringementSettings.throwException = true;   // throw DBC.Infringement on violation
 dbc.infringementSettings.logToConsole = false;     // log to console instead
+
+# React to infringements programmatically
+dbc.infringementSettings.onInfringement = (infringement, context) => {
+    // infringement — DBC.Infringement instance (extends Error, has .message and .stack)
+    // context.type — "precondition" | "postcondition" | "invariant"
+    // context.value — the raw value that violated the contract
+    Sentry.captureException(infringement, { extra: context });
+};
 ```
 
+The callback fires **before** `throwException`, so it always runs even when an exception is thrown. All three settings are independent and can be combined freely.
+
 ### Multiple DBC Instances
 
 Create isolated DBC instances with separate configurations using `DBC.register()`:
@@ -389,6 +507,20 @@ See [`Demo.ts`](src/Demo.ts) for annotated usage examples.
 
 ---
 
+## Built With XDBC
+
+XDBC is actively used in production across the following projects:
+
+| Project | Context |
+|---|---|
+| [CodBi](https://github.com/XIMA-formcycle-Entwicklerkreis/CodBi) | Low-code engine plugin for [XIMA Formcycle](https://www.xima.de/formcycle) |
+| [tinymce-multicloud-plugin](https://github.com/CallariS/tinymce-multicloud-plugin) | multiCloud plugin for [TinyMCE](https://www.tiny.cloud) |
+| *(internal)* | Comprehensive Active Directory management suite for schools, deployed at a German public administration |
+
+*XDBC is used in the Angular frontends of the above projects.*
+
+---
+
 ## Contributing
 
 Participation is highly valued and warmly welcomed. The ultimate goal is to create a tool that proves genuinely useful and empowers a wide range of developers to build more robust and reliable applications.

package/__tests__/DBC/AE.test.ts

@@ -1,62 +1,62 @@
-import { AE } from "../../src/DBC/AE";
-import { EQ } from "../../src/DBC/EQ";
-import { REGEX } from "../../src/DBC/REGEX";
-
-describe("AE", () => {
-	const ae = new AE([new REGEX(/^a$/), new EQ("a")]);
-
-	test("Should report no infringement with 'a' to check", () => {
-		expect(ae.check("a" as unknown as object)).toBe(true);
-	});
-
-	test("Should report no infringement with ['a','a','a'] to check", () => {
-		expect(ae.check(["a", "a", "a"] as unknown as object)).toBe(true);
-	});
-
-	test("Should report infringement with ['a','b','a'] to check", () => {
-		expect(typeof ae.check(["a", "b", "a"] as unknown as object)).toBe(
-			"string",
-		);
-		1;
-	});
-
-	test("Should not report infringement with ['b','a','b'] to check when checking only index 1", () => {
-		expect(
-			new AE([new REGEX(/^a$/), new EQ("a")], 1).check([
-				"b",
-				"a",
-				"b",
-			] as unknown as object),
-		).toBe(true);
-	});
-
-	test("Should report infringement with ['b','a','b'] to check when checking from index 1 on", () => {
-		expect(
-			typeof new AE([new REGEX(/^a$/), new EQ("a")], 1, -1).check([
-				"b",
-				"a",
-				"b",
-			] as unknown as object),
-		).toBe("string");
-	});
-
-	test("Should not report infringement with ['a','a','b'] to check when checking from index 0 to 1", () => {
-		expect(
-			new AE([new REGEX(/^a$/), new EQ("a")], 0, 1).check([
-				"a",
-				"a",
-				"b",
-			] as unknown as object),
-		).toBe(true);
-	});
-
-	test("Should report infringement with ['a','a','b'] to check when checking from index 0 to 1 case of EQ-Condition", () => {
-		expect(
-			typeof new AE([new REGEX(/^a$/), new EQ("b")], 0, 1).check([
-				"a",
-				"a",
-				"b",
-			] as unknown as object),
-		).toBe("string");
-	});
-});
+import { AE } from "../../src/DBC/AE";
+import { EQ } from "../../src/DBC/EQ";
+import { REGEX } from "../../src/DBC/REGEX";
+
+describe("AE", () => {
+	const ae = new AE([new REGEX(/^a$/), new EQ("a")]);
+
+	test("Should report no infringement with 'a' to check", () => {
+		expect(ae.check("a" as unknown as object)).toBe(true);
+	});
+
+	test("Should report no infringement with ['a','a','a'] to check", () => {
+		expect(ae.check(["a", "a", "a"] as unknown as object)).toBe(true);
+	});
+
+	test("Should report infringement with ['a','b','a'] to check", () => {
+		expect(typeof ae.check(["a", "b", "a"] as unknown as object)).toBe(
+			"string",
+		);
+		1;
+	});
+
+	test("Should not report infringement with ['b','a','b'] to check when checking only index 1", () => {
+		expect(
+			new AE([new REGEX(/^a$/), new EQ("a")], 1).check([
+				"b",
+				"a",
+				"b",
+			] as unknown as object),
+		).toBe(true);
+	});
+
+	test("Should report infringement with ['b','a','b'] to check when checking from index 1 on", () => {
+		expect(
+			typeof new AE([new REGEX(/^a$/), new EQ("a")], 1, -1).check([
+				"b",
+				"a",
+				"b",
+			] as unknown as object),
+		).toBe("string");
+	});
+
+	test("Should not report infringement with ['a','a','b'] to check when checking from index 0 to 1", () => {
+		expect(
+			new AE([new REGEX(/^a$/), new EQ("a")], 0, 1).check([
+				"a",
+				"a",
+				"b",
+			] as unknown as object),
+		).toBe(true);
+	});
+
+	test("Should report infringement with ['a','a','b'] to check when checking from index 0 to 1 case of EQ-Condition", () => {
+		expect(
+			typeof new AE([new REGEX(/^a$/), new EQ("b")], 0, 1).check([
+				"a",
+				"a",
+				"b",
+			] as unknown as object),
+		).toBe("string");
+	});
+});