xdbc 1.0.207 → 1.0.209

package/CONTRIBUTING.md

@@ -1,40 +1,152 @@
 # Contributing to XDBC
 
-Thank you for your interest in contributing to XDBC! We welcome contributions of all kinds, including bug reports, feature requests, code contributions, and documentation improvements.
+Thank you for your interest in contributing to XDBC. Contributions of all kinds are welcome — bug reports, feature requests, code improvements, documentation enhancements, and test coverage expansion.
+
+---
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Reporting Issues](#reporting-issues)
+- [Contributing Code](#contributing-code)
+- [Development Workflow](#development-workflow)
+- [Code Style](#code-style)
+- [Testing](#testing)
+- [Documentation](#documentation)
+- [License Agreement](#license-agreement)
+- [Code of Conduct](#code-of-conduct)
+- [Contact](#contact)
+
+---
+
+## Getting Started
+
+1. **Fork** the repository on GitHub.
+2. **Clone** your fork locally:
+   ```sh
+   git clone https://github.com/<your-username>/XDBC.git
+   cd XDBC
+   ```
+3. **Install dependencies**:
+   ```sh
+   npm install
+   ```
+4. **Run the test suite** to verify the setup:
+   ```sh
+   npm test
+   ```
+
+---
 
 ## Reporting Issues
 
-If you find a bug or have a feature request, please open an issue on GitHub. When reporting a bug, please include:
+If you encounter a bug or have a feature request, please [open an issue](https://github.com/CallariS/XDBC/issues/new) on GitHub.
 
-* Steps to reproduce the bug
-* Expected behavior
-* Actual behavior
-* Your operating system and browser (if applicable)
+When reporting a bug, include:
+
+- A clear, descriptive title
+- Steps to reproduce the issue
+- Expected behavior vs. actual behavior
+- Environment details (Node.js version, TypeScript version, OS)
+- A minimal code sample or test case, if possible
+
+For feature requests, describe the use case and how the proposed change benefits users.
+
+---
 
 ## Contributing Code
 
-1.  Fork the repository.
-2.  Create a branch for your changes: `git checkout -b my-feature-branch`.
-3.  Make your changes and commit them: `git commit -am 'Add some feature'`.
-4.  Push your changes to your fork: `git push origin my-feature-branch`.
-5.  Open a pull request on GitHub.
+### Branch Strategy
+
+- Create a feature branch from `master`:
+  ```sh
+  git checkout -b feature/my-improvement
+  ```
+- Use descriptive branch names: `feature/`, `fix/`, `docs/`, `test/`
+
+### Commit Guidelines
+
+- Write clear, concise commit messages in imperative mood:
+  - **Good**: `Add RANGE contract for numeric boundaries`
+  - **Avoid**: `Added stuff`, `WIP`, `fix`
+- Each commit should represent a single logical change
+- Reference related issues where applicable: `Fix #12 — handle null in OR.check()`
+
+### Pull Request Process
+
+1. Ensure your branch is up to date with `master`
+2. Run the full test suite and linter before submitting
+3. Open a pull request with:
+   - A description of what the change does and why
+   - Links to related issues
+   - Any breaking changes clearly noted
+4. Address review feedback promptly
+5. A maintainer will merge once the PR is approved
+
+---
+
+## Development Workflow
+
+| Command | Purpose |
+|---|---|
+| `npm test` | Run the test suite (Jest) |
+| `npm run build` | Build the project (Webpack) |
+| `npm run lint` | Lint the codebase (Biome) |
+| `npm run format` | Auto-format source files (Biome) |
+| `npm run docs` | Generate API documentation (TypeDoc) |
+
+---
 
 ## Code Style
 
-Please follow the coding style guidelines used in the project. We use Biome, so please run it before submitting a pull request.
+- **TypeScript** is the primary language. All source code resides in `src/`.
+- **Biome** is used for both linting and formatting. Run `npm run lint` and `npm run format` before submitting.
+- Follow existing patterns:
+  - Each contract class lives in its own file under `src/DBC/`
+  - Derived contracts go in subdirectories (e.g., `src/DBC/COMPARISON/`)
+  - Every contract exposes `PRE`, `POST`, and `INVARIANT` static decorator factories
+- Avoid introducing new dependencies unless absolutely necessary
+- Prefer strict types over `any` where feasible
+
+---
+
+## Testing
+
+- Tests are located in `__tests__/DBC/` and use **Jest** with `ts-jest`
+- Every new contract or behavioral change should include corresponding tests
+- Test file naming convention: `<ContractName>.test.ts`
+- Run the suite with:
+  ```sh
+  npm test
+  ```
+- Aim for tests that cover:
+  - `check()` method behavior (passing and failing cases)
+  - Decorator execution (`PRE`, `POST`, `INVARIANT`) where applicable
+  - Edge cases (null, undefined, empty arrays, wrong types)
+
+---
 
 ## Documentation
 
-We welcome improvements to the documentation. Please submit pull requests with your changes.
+- API documentation is generated with [TypeDoc](https://typedoc.org/) (`npm run docs`)
+- Use JSDoc-style comments on all public classes, methods, and parameters
+- Update the README if your change adds new contracts, features, or configuration options
+- Keep `Demo.ts` up to date with representative usage examples
 
-## License
+---
 
-By contributing to XDBC, you agree that your contributions will be licensed under the MIT license.
+## License Agreement
+
+By contributing to XDBC, you agree that your contributions will be licensed under the [MIT License](LICENSE).
+
+---
 
 ## Code of Conduct
 
-Please review and abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+All contributors must adhere to the [Code of Conduct](CODE_OF_CONDUCT.md). Respectful, professional interaction is expected in all project spaces.
+
+---
 
 ## Contact
 
-If you have any questions, please mail to [XDBC@WaXcode.net](mailto:XDBC@WaXCode.net).
+For questions about contributing, reach out at [XDBC@WaXCode.net](mailto:XDBC@WaXCode.net).

package/README.md

@@ -1,103 +1,405 @@
-# XDbC / e**X**plicit **D**esign **b**y **C**ontract™
+<p align="center">
+  <img src="https://img.shields.io/npm/v/xdbc?style=flat-square" alt="npm version" />
+  <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" />
+</p>
 
-Leverages the explicit nature of metadata to provide a **D**esign **b**y **C**ontract™ Framework in a precise and comprehensible manner.
+# XDBC — e**X**plicit **D**esign **b**y **C**ontract for TypeScript
 
-| Do...             | Instead Of                                                 |
-|-------------------|------------------------------------------------------------|
-| <pre>@DBC.ParamvalueProvider<br>public method(@AE.PRE([new REGEX(/^\.*XDBC.\*$/i)]) input : Array\<string>) {<br> ... <br>}</pre>|<pre>public method( input : Array\<string>) {<br>  input.forEach(( element, index ) => {<br>   console.assert(/^.\*XDBC.\*$/i.test(element),"inconsistent error message");<br>  });<br><br>  ...<br>}</pre>
-| <pre>@REGEX.INVARIANT(/^.\*XDBC.\*$/i)<br>public field = "XDBC";</pre>|<pre>get field() : string { return ... }<br>set field( toSet : string ) {<br> console.assert(/^.\*XDBC.\*$/i.test(element),"Inconsistent error message"); <br><br> ...<br>}</pre>
-| <pre>@REGEX.POST(/^XDBC$/i)<br>public method( input : unknown ) : string {<br> ...<br><br> return result ;<br>}</pre>|<pre>public method( input : unknown ) : string {<br> ...<br><br> if(!/^.\*XDBC.\*$/i.test(result) {<br>   throw new Error("inconsistent error message");<br> }<br><br> return result ;<br>}</pre>
-<pre>...and get consistent details about errors like: <code style = "background-color : beige ; color : red ;">[ XDBC Infringement [ From "method" in "MyClass": [ Parameter-value "+1d,+5d,-x10y" of the 1st parameter did not fulfill one of it's contracts: Violating-Arrayelement at index 2. Value has to comply to regular expression "/^(?i:(NOW)|([+-]\d+[dmy]))$/i"]]]</code></pre>
+> A decorator-based Design by Contract framework that enforces preconditions, postconditions, and invariants through TypeScript metadata — delivering precise, self-documenting, and verifiable component contracts.
 
-## What is **D**esign **b**y **C**ontract™ ?
-[**D**esign **b**y **C**ontract™ (DbC)](https://en.wikipedia.org/wiki/Design_by_contract) is a software development approach focused on defining precise and verifiable contracts between software components. These contracts specify the preconditions that must be true when calling a component (e.g., a function or method), the postconditions guaranteed after the component's execution, and the invariants that must hold true throughout the lifetime of an object or class.
+---
 
-## Benefits of Design by Contract:
+## At a Glance
 
-| Benefit               | Description                                                |
-|-----------------------|------------------------------------------------------------|
-| More Reliable         | Early error detection through contract checking            |
-| More Maintainable     | Clear responsibilities and expected behavior               |
-| Better Documentation  | Contracts as living behavior descriptions                  |
-| Easier Debugging      | Error causes traceable through contract violations         |
+| Approach | With XDBC | Without XDBC |
+|---|---|---|
+| **Parameter validation** | <pre>@DBC.ParamvalueProvider<br>method(@REGEX.PRE(/^\.*XDBC.\*$/i) input: string[]) {<br>  ...<br>}</pre> | <pre>method(input: string[]) {<br>  input.forEach((el, i) => {<br>    console.assert(/^.\*XDBC.\*$/i.test(el), "error");<br>  });<br>  ...<br>}</pre> |
+| **Field invariant** | <pre>@REGEX.INVARIANT(/^.\*XDBC.\*$/i)<br>public field = "XDBC";</pre> | <pre>get field(): string { return this._field; }<br>set field(v: string) {<br>  console.assert(/^.\*XDBC.\*$/i.test(v), "error");<br>  this._field = v;<br>}</pre> |
+| **Return validation** | <pre>@REGEX.POST(/^XDBC$/i)<br>method(input: unknown): string {<br>  ...<br>  return result;<br>}</pre> | <pre>method(input: unknown): string {<br>  ...<br>  if (!/^XDBC$/i.test(result)) {<br>    throw new Error("error");<br>  }<br>  return result;<br>}</pre> |
 
+Contract violations produce structured, actionable diagnostics:
 
-**DbC** improves software quality and maintainability by explicitly defining and verifying contract conditions.
+```
+[ XDBC Infringement [ From "method" in "MyClass": [ Parameter-value "+1d,+5d,-x10y"
+of the 1st parameter did not fulfill one of it's contracts: Violating-Arrayelement at
+index 2. Value has to comply to regular expression "/^(?i:(NOW)|([+-]\d+[dmy]))$/i"]]]
+```
+
+---
+
+## Table of Contents
+
+- [What is Design by Contract?](#what-is-design-by-contract)
+- [Why XDBC?](#why-xdbc)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Contracts Reference](#contracts-reference)
+- [Core Concepts](#core-concepts)
+- [Advanced Features](#advanced-features)
+- [Configuration](#configuration)
+- [API Documentation](#api-documentation)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## What is Design by Contract?
 
-## What is the difference between DbC and Assertions ?
+[Design by Contract (DbC)](https://en.wikipedia.org/wiki/Design_by_contract) is a software engineering methodology that defines formal, precise, and verifiable interface specifications for software components. Each component's contract comprises:
 
-| Feature          | DBC with Decorators                    | Assertions                            |
-|------------------|----------------------------------------|---------------------------------------|
-| Formality        | Formal, explicit in definition         | Informal, often within the body       |
-| Integration      | Metadata                               | Built-in keyword                      |
-| Features         | Can be more feature-rich               | Simple, primarily for error detection |
-| Readability      | Generally good, contracts are clear    | Can become cluttered                  |
-| Maintainability  | Often better, contracts are localized  | Can be harder to track and modify     |
-| Production       | Contracts can be kept or disabled      | Often disabled for performance        |
+| Element | Purpose |
+|---|---|
+| **Preconditions** | Conditions that must hold true *before* a method executes |
+| **Postconditions** | Guarantees that must hold true *after* a method returns |
+| **Invariants** | Properties that must remain true *throughout* an object's lifetime |
 
-## Demo & API Documentation
-Check out the **Demo.ts** to see some examples usages and the [API](https://callaris.github.io/XDBC/)'s documentation.
+### DbC vs. Assertions
+
+| Aspect | XDBC Decorators | Manual Assertions |
+|---|---|---|
+| Formality | Formal, declarative, co-located with signatures | Informal, scattered through method bodies |
+| Integration | TypeScript metadata and decorators | Built-in `console.assert` / `throw` |
+| Expressiveness | Composable, parameterized contract objects | Simple boolean checks |
+| Readability | Contracts are visible at the API surface | Validation logic obscures business logic |
+| Maintainability | Contracts are localized and reusable | Duplicated checks are hard to track |
+| Production control | Selectively enable/disable by contract type | Typically all-or-nothing |
+
+---
+
+## Why XDBC?
+
+- **Declarative** — contracts live as decorators alongside type signatures, not buried in method bodies
+- **Composable** — combine contracts with `AE`, `OR`, and `IF` for expressive validation
+- **Configurable** — toggle preconditions, postconditions, and invariants independently
+- **Diagnostic** — structured error messages pinpoint the exact violation, parameter, and context
+- **Extensible** — 16 built-in contracts, with support for custom contracts and Zod schema integration
+- **Zero runtime overhead** — disable contract checking in production with a single flag
+
+---
 
 ## Installation
 
 ```sh
-npm install --save xdbc
+npm install xdbc
+```
+
+**Requirements:** TypeScript 5.x with `experimentalDecorators` and `emitDecoratorMetadata` enabled in `tsconfig.json`.
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
 ```
 
-## Usage
+---
+
+## Quick Start
+
+```typescript
+import { DBC, REGEX, TYPE, EQ } from "xdbc";
+
+class UserService {
+
+  // Invariant: email must always match pattern
+  @REGEX.INVARIANT(/^[^@]+@[^@]+\.[^@]+$/)
+  public email = "user@example.com";
+
+  // Precondition: name must be a string; Postcondition: return must match pattern
+  @REGEX.POST(/^Hello, .+$/)
+  @DBC.ParamvalueProvider
+  public greet(@TYPE.PRE("string") name: string): string {
+    return `Hello, ${name}`;
+  }
+
+  // Precondition: age must be >= 0
+  @DBC.ParamvalueProvider
+  public setAge(@GREATER_OR_EQUAL.PRE(0) age: number) {
+    // ...
+  }
+}
+```
+
+---
+
+## Contracts Reference
+
+XDBC ships with **16 contracts** organized into core validators and derived specializations:
+
+### Core Contracts
 
-As by now there're 14 contracts that can be used:
+| Contract | Description | Constructor |
+|---|---|---|
+| **`REGEX`** | Value must match a regular expression | `new REGEX(expression: RegExp)` |
+| **`TYPE`** | Value must be of a specified type (supports pipe-separated: `"string\|number"`) | `new TYPE(type: string)` |
+| **`EQ`** | Value must equal (or not equal) a reference value | `new EQ(equivalent: any, invert?: boolean)` |
+| **`COMPARISON`** | Numeric comparison against a reference value | `new COMPARISON(equivalent, equalityPermitted, invert)` |
+| **`INSTANCE`** | Value must be an instance of a specified class | `new INSTANCE(reference: any \| any[])` |
+| **`AE`** | Every element in an array must satisfy a set of contracts | `new AE(conditions, index?, idxEnd?)` |
+| **`OR`** | At least one of a set of contracts must be satisfied | `new OR(conditions: DBC[])` |
+| **`IF`** | Conditional contract: if A holds, then B must also hold | `IF.PRE(condition, inCase, path?, invert?)` |
+| **`JSON_OP`** | Object must contain specific properties of specific types | `new JSON_OP(properties: {name, type}[], checkElements?)` |
+| **`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` | — |
+| **`HasAttribute`** | HTMLElement must possess a named attribute | `HasAttribute.PRE(attrName, invert?)` |
+| **`ZOD`** | Value must validate against a Zod schema | `new ZOD(schema: z.ZodType)` |
 
-- AE (*Each element of the value-array has to fulfill a certain set of contracts*)
-- EQ (*Value has to be equal to a supplied reference value*)
-- COMPARISON (*Value has to be greater, less, greater/equal, equal or less/equal than a supplied reference value*)
-- INSTANCE (*Value has to be an instance of a supplied type*)
-- JSON.OP (*Value has to contain certain properties of certain type*)
-- JSON.Parse (*String-value has to be a parsable JSON*)
-- OR (*At least one of a set of contracts has to be fulfilled*)
-- REGEX (*Value has to be validated by a supplied regular expression*)
-- TYPE (*Value has to be of a certain type*)
-- GREATER (*Derived from COMPARISON*)
-- GREATER_OR_EQUAL (*Derived from COMPARISON*)
-- LESS (*Derived from COMPARISON*)
-- LESS_OR_EQUAL (*Derived from COMPARISON*)
-- DIFFERENT (*Derived from EQ*)
+### Derived Contracts
 
-All of which expose a method **PRE**, **POST** and **INVARIANT** (*precondition, postcondition and invariant*).<br>
-Import the classes to use from **xdbc**. If parameters shall be decorated with contracts import class **DBC** also. <br><br>
+| Contract | Derives From | Semantics |
+|---|---|---|
+| **`GREATER`** | `COMPARISON` | `value > reference` |
+| **`GREATER_OR_EQUAL`** | `COMPARISON` | `value >= reference` |
+| **`LESS`** | `COMPARISON` | `value < reference` |
+| **`LESS_OR_EQUAL`** | `COMPARISON` | `value <= reference` |
+| **`DIFFERENT`** | `EQ` | `value !== reference` |
 
-The **PRE**-Method can be used to decorate method-parameter: <code>public method(@REGEX.PRE(/XDBC.\*/g) input : string)</code>.<br>Whenever the method is invoked the value will be checked. Since parameter decorators don't have access to the parameter's value, the method itself must additionally be decorated with the **ParamvalueProvider**:<br>
-<code>
-@DBC.**ParamvalueProvider**<br>
-public method(@REGEX.PRE(/XDBC.\*/g) input : string)
-</code><br><br>
-The **POST**-Method can be used to decorate a method:<br>
-<code>
-@EQ.POST(10)<br>
-public method() { return 10 ;}<br></code>
-Whenever the method returns, it's return-value will be checked.<br>
+### Built-in Regular Expressions
 
-The **INVARIANT**-Method can be used to decorate fields:<br>
-<code>
-@REGEX.INVARIANT(/^a$/)<br>
-public testProperty = "a";
-</code><br>
-Whenever the field is assigned a value and also when initialized, the new value will be checked. So there's no need to write a getter and setter just because there's is the necessity to perform checks on the value anymore.<br>
+`REGEX.stdExp` provides ready-to-use patterns:
 
-Certain contracts take other contracts as a parameter. For example the **AE** contract that applies a specified set of contracts on each element of the tagged object's value if it is an array or the object itself if it isn't: <code>@AE.PRE([new REGEX(/^(?i:(NOW)|([+-]\d+[dmy]))$/i, new GREATER(10,"length")])</code>.
+| Key | Validates |
+|---|---|
+| `htmlAttributeName` | HTML attribute names |
+| `eMail` | Email addresses |
+| `property` | Property identifiers |
+| `url` | URLs |
+| `keyPath` | Key paths |
+| `date` | Date strings |
+| `dateFormat` | Date format patterns |
+| `cssSelector` | CSS selectors |
+| `boolean` | Boolean string literals |
+| `colorCodeHEX` | Hex color codes |
+| `simpleHotkey` | Keyboard shortcuts |
+| `bcp47` | BCP 47 language tags |
 
-With **PRE**, **POST** and **INVARIANT** decorators an optional **path** parameter may be specified. This parameter is a dotted path to a nested property of the tagged object that shall be checked instead of the tagged one. Thus **@DBC.INVARIANT([new REGEX(/^.$/)])** could also be defined as: **@DBC.INVARIANT([new EQ(1)],"length")**, that way demanding that the value to be set is a string with exactly one character.
+---
 
-Multiple instances of the class **DBC** with varying settings for e.g. reporting infringements may be instantiated. Which of these instances is used to report can be defined when either using **PRE**, **POST** or **INVARIANT** by defining their **dbc** parameter: **@DBC.INVARIANT([new EQ(1)],"length","MyVendor.MyDBCInstance")**, for example. The standard path (*WaXCode.DBC*) leads to an automatically created instance, that is generated when the Framework is imported.
+## Core Concepts
 
-Many contracts got further features like the **AE**-Contract that can check specific ranges within the tagged array or the **EQ**--Contract that can be inverted turning it into **not EQual**-Contract. Check out the [API](https://callaris.github.io/XDBC/) for details.
+### Decorator Types
 
-A **DBC**'s **warningSettings** & **infringementSettings** determine what happens on warnings and errors, whereas warnings are not implemented yet.
+Every contract exposes three decorator factories:
 
-**DBC** can be turned off for **PRE**-, **POST**-Conditions and **INVARIANT**S separately by setting the proper **executionSettings** of the **DBC**-Class.
+| Decorator | Applies To | Validates |
+|---|---|---|
+| `Contract.PRE(...)` | Method parameters | Input values before method execution |
+| `Contract.POST(...)` | Methods | Return value after method execution |
+| `Contract.INVARIANT(...)` | Fields / Properties | Value on every assignment (including initialization) |
+
+### The `ParamvalueProvider` Decorator
+
+TypeScript parameter decorators do not natively receive parameter values. Any method using `PRE` parameter contracts **must** be decorated with `@DBC.ParamvalueProvider`:
+
+```typescript
+@DBC.ParamvalueProvider
+public process(
+  @TYPE.PRE("string") name: string,
+  @REGEX.PRE(/^\d{4}$/) code: string
+) { ... }
+```
+
+### Path Resolution
+
+All `PRE`, `POST`, and `INVARIANT` decorators accept an optional **`path`** parameter — a dotted path that specifies a nested property of the value to validate instead of the value itself:
+
+```typescript
+// Validate that element.tagName === "SELECT"
+@DBC.ParamvalueProvider
+public handleElement(@EQ.PRE("SELECT", false, "tagName") el: HTMLElement) { }
+
+// Validate that value.length === 1
+@EQ.INVARIANT(1, false, "length")
+public singleChar = "X";
+```
+
+Path resolution supports:
+- **Dot notation**: `"user.address.city"`
+- **Array indices**: `"items[0]"`
+- **Method calls**: `"getName()"`
+- **HTML attributes**: `"@data-id"`
+
+### Custom Hints
+
+Add context to error messages with the optional **`hint`** parameter:
+
+```typescript
+@DBC.ParamvalueProvider
+public setAge(
+  @GREATER_OR_EQUAL.PRE(0, undefined, "Age must be non-negative") age: number
+) { }
+```
+
+---
+
+## Advanced Features
+
+### Composing Contracts with `AE`
+
+Validate array elements against one or more contracts, optionally targeting a specific index range:
+
+```typescript
+// All elements must be non-empty strings matching a date pattern
+@AE.PRE([new TYPE("string"), new REGEX(/^\d{4}-\d{2}-\d{2}$/)])
+public processDates(dates: string[]) { }
+
+// Only elements at indices 1 through 3
+@AE.PRE([new REGEX(/^[A-Z]+$/)], 1, 3)
+public processRange(items: string[]) { }
+
+// Single element at index 0
+@AE.PRE([new TYPE("number")], 0)
+public processFirst(values: unknown[]) { }
+```
+
+### Logical Composition with `OR`
+
+At least one contract must pass:
+
+```typescript
+@DBC.ParamvalueProvider
+public setStatus(@OR.PRE([new EQ("active"), new EQ("inactive"), new EQ("pending")]) status: string) { }
+```
+
+### Conditional Contracts with `IF`
+
+Apply a contract only when a precondition holds:
+
+```typescript
+// If the value is a string, it must also match digits-only
+@IF.PRE(new TYPE("string"), new REGEX(/^\d+$/))
+public processInput(value: unknown) { }
+```
+
+### Zod Schema Integration
+
+Leverage Zod schemas for complex structural validation:
+
+```typescript
+import { z } from "zod";
+
+const UserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  age: z.number().int().positive()
+});
+
+@DBC.ParamvalueProvider
+public createUser( @ZOD.PRE(UserSchema) data: unknown) { }
+```
+
+### Type-Safe Static Checks
+
+Several contracts offer static `tsCheck` methods for imperative validation outside of decorators:
+
+```typescript
+// Throws if value is not a string
+const name = TYPE.tsCheck<string>(input, "string", "Expected a string");
+
+// Throws if value doesn't match regex
+const code = REGEX.tsCheck<string>(input, /^\d{4}$/, "Invalid code format");
+
+// Throws if not an instance of Date
+const date = INSTANCE.tsCheck<Date>(input, Date, "Expected a Date");
+
+// Throws if none of the conditions pass
+const result = OR.tsCheck<string>(input, [new EQ("a"), new EQ("b")]);
+```
+
+---
+
+## Configuration
+
+### DBC Instance Settings
+
+A default DBC instance is automatically registered at `WaXCode.DBC` when the module is imported. You can access and configure it:
+
+```typescript
+import { DBC } from "xdbc";
+
+// Access the default DBC instance
+const dbc = (globalThis as any).WaXCode.DBC as DBC;
+
+// Toggle contract checking
+dbc.executionSettings.checkPreconditions = true;
+dbc.executionSettings.checkPostconditions = true;
+dbc.executionSettings.checkInvariants = true;
+
+// Configure infringement handling
+dbc.infringementSettings.throwException = true;   // throw DBC.Infringement on violation
+dbc.infringementSettings.logToConsole = false;     // log to console instead
+```
+
+### Multiple DBC Instances
+
+Create isolated DBC instances with separate configurations using `DBC.register()`:
+
+```typescript
+// Register a vendor-specific instance at a custom path
+const vendorDbc = new DBC(
+  { throwException: false, logToConsole: true },
+);
+DBC.register(vendorDbc, "MyVendor.DBC");
+
+// Route a contract to the custom instance via its path
+@REGEX.INVARIANT(/^[A-Z]+$/, undefined, undefined, "MyVendor.DBC")
+public code = "ABC";
+```
+
+> **Note:** `new DBC()` does not automatically mount onto `globalThis`. Call `DBC.register(instance, path)` to make an instance available for decorator resolution.
+
+### Test Isolation
+
+Use `DBC.isolated()` to run tests with a temporary DBC instance that doesn't affect other tests:
+
+```typescript
+DBC.isolated((tempDbc) => {
+  // tempDbc is registered at "WaXCode.DBC" for the duration of this callback
+  tempDbc.executionSettings.checkPreconditions = false;
+
+  // ... run tests with contracts disabled ...
+});
+// Original DBC instance is automatically restored here
+```
+
+### Disabling Contracts in Production
+
+```typescript
+const dbc = (globalThis as any).WaXCode.DBC as DBC;
+dbc.executionSettings.checkPreconditions = false;
+dbc.executionSettings.checkPostconditions = false;
+dbc.executionSettings.checkInvariants = false;
+```
+
+---
+
+## API Documentation
+
+Full generated API documentation is available at **[callaris.github.io/XDBC](https://callaris.github.io/XDBC/)**.
+
+See [`Demo.ts`](src/Demo.ts) for annotated usage examples.
+
+---
+
+## Contributing
 
-## Contribution
 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.
 
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.
+
+---
+
+## License
+
+[MIT](LICENSE) © Callari, Salvatore
 
+---
 
+<sub>"Design by Contract" is a registered trademark of Eiffel Software. XDBC is an independent project and is not affiliated with or endorsed by Eiffel Software.</sub>