@vytches/ddd-validation 0.26.0

package/dist/rules-registry.d.ts

@@ -0,0 +1,69 @@
+import { ISpecification } from '@vytches/ddd-contracts';
+import { BusinessRuleValidator } from './business-rules/business-rule-validator';
+export interface RuleFunction<T> {
+    (validator: BusinessRuleValidator<T>): BusinessRuleValidator<T>;
+}
+export interface IRulesProvider {
+    readonly name: string;
+}
+export interface ICoreRules {
+    required: <T>(property: keyof T, message?: string) => RuleFunction<T>;
+    minLength: <T>(property: keyof T, length: number, message?: string) => RuleFunction<T>;
+    maxLength: <T>(property: keyof T, length: number, message?: string) => RuleFunction<T>;
+    /**
+     * Pattern-match a property against a RegExp.
+     *
+     * **Security warning (REL-007):** the `regex` argument is executed against
+     * input data. Do **NOT** construct the RegExp dynamically from
+     * user-controlled strings (e.g. `new RegExp(userInput)`) — this exposes
+     * your application to ReDoS (Regular Expression Denial of Service)
+     * attacks. Use only literal regex patterns in code review-able form, or
+     * pre-validate user input against a strict allow-list before constructing
+     * a RegExp.
+     *
+     * The library performs no internal validation of the regex; that is the
+     * consumer's responsibility.
+     */
+    pattern: <T>(property: keyof T, regex: RegExp, message?: string) => RuleFunction<T>;
+    range: <T>(property: keyof T, min: number, max: number, message?: string) => RuleFunction<T>;
+    email: <T>(property: keyof T, message?: string) => RuleFunction<T>;
+    satisfies: <T>(specification: ISpecification<T>, message: string) => RuleFunction<T>;
+    propertySatisfies: <T, P>(property: keyof T & string, specification: ISpecification<P>, message: string, getValue: (obj: T) => P) => RuleFunction<T>;
+    when: <T>(condition: (value: T) => boolean, thenRules: (validator: BusinessRuleValidator<T>) => void) => RuleFunction<T>;
+    whenSatisfies: <T>(specification: ISpecification<T>, thenRules: (validator: BusinessRuleValidator<T>) => void) => RuleFunction<T>;
+    otherwise: <T>(elseRules: (validator: BusinessRuleValidator<T>) => void) => RuleFunction<T>;
+}
+export declare class CoreRules implements ICoreRules, IRulesProvider {
+    readonly name = "core";
+    required: <T>(property: keyof T, message?: string) => (validator: BusinessRuleValidator<T>) => BusinessRuleValidator<T>;
+    minLength: <T>(property: keyof T, length: number, message?: string) => (validator: BusinessRuleValidator<T>) => BusinessRuleValidator<T>;
+    maxLength: <T>(property: keyof T, length: number, message?: string) => (validator: BusinessRuleValidator<T>) => BusinessRuleValidator<T>;
+    pattern: <T>(property: keyof T, regex: RegExp, message?: string) => (validator: BusinessRuleValidator<T>) => BusinessRuleValidator<T>;
+    range: <T>(property: keyof T, min: number, max: number, message?: string) => (validator: BusinessRuleValidator<T>) => BusinessRuleValidator<T>;
+    email: <T>(property: keyof T, message?: string) => (validator: BusinessRuleValidator<T>) => BusinessRuleValidator<T>;
+    satisfies: <T>(specification: ISpecification<T>, message: string) => (validator: BusinessRuleValidator<T>) => BusinessRuleValidator<T>;
+    propertySatisfies: <T, P>(property: keyof T & string, specification: ISpecification<P>, message: string, getValue: (obj: T) => P) => (validator: BusinessRuleValidator<T>) => BusinessRuleValidator<T>;
+    whenSatisfies: <T>(specification: ISpecification<T>, thenRules: (validator: BusinessRuleValidator<T>) => void) => (validator: BusinessRuleValidator<T>) => BusinessRuleValidator<T>;
+    otherwise: <T>(elseRules: (validator: BusinessRuleValidator<T>) => void) => (validator: BusinessRuleValidator<T>) => BusinessRuleValidator<T>;
+    when: <T>(condition: (value: T) => boolean, thenRules: (validator: BusinessRuleValidator<T>) => void) => (validator: BusinessRuleValidator<T>) => BusinessRuleValidator<T>;
+}
+export declare class RulesRegistry {
+    private static providers;
+    private static core;
+    /**
+     * Register a domain-specific rule provider
+     */
+    static register(provider: IRulesProvider): void;
+    /**
+     * Get a specific rule provider by name
+     */
+    static getProvider<T extends IRulesProvider>(name: string): T;
+    /**
+     * Get core rules
+     */
+    static get Rules(): ICoreRules;
+    /**
+     * Access domain-specific rules
+     */
+    static forDomain<T extends IRulesProvider>(domain: string): T;
+}

package/dist/specifications/async-composite-specification.d.ts

@@ -0,0 +1,72 @@
+import { IAsyncSpecification } from '../../../contracts/src/index.ts';
+export declare abstract class AsyncCompositeSpecification<T> implements IAsyncSpecification<T> {
+    /**
+     * Check if the candidate satisfies this specification asynchronously
+     * @param candidate The entity to evaluate
+     * @param context Optional context for evaluation (e.g., user, tenant, environment)
+     */
+    abstract isSatisfiedByAsync(candidate: T, context?: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Optional name for debugging/logging
+     */
+    readonly name?: string | undefined;
+    /**
+     * Optional description for debugging/logging
+     */
+    readonly description?: string | undefined;
+    /**
+     * Combine with another async specification using AND logic
+     */
+    and(other: IAsyncSpecification<T>): IAsyncSpecification<T>;
+    /**
+     * Combine with another async specification using OR logic
+     */
+    or(other: IAsyncSpecification<T>): IAsyncSpecification<T>;
+    /**
+     * Negate this async specification
+     */
+    not(): IAsyncSpecification<T>;
+    /**
+     * Create a specification from an async predicate function
+     */
+    static create<T>(predicate: (candidate: T, context?: Record<string, unknown>) => Promise<boolean>, name?: string, description?: string): IAsyncSpecification<T>;
+    /**
+     * Optional method to explain why specification failed
+     */
+    explainFailureAsync?(_candidate: T, _context?: Record<string, unknown>): Promise<string | null>;
+}
+/**
+ * @since 0.4.2
+ */
+export declare class AndAsyncSpecification<T> extends AsyncCompositeSpecification<T> {
+    private readonly left;
+    private readonly right;
+    readonly name: string;
+    readonly description: string;
+    constructor(left: IAsyncSpecification<T>, right: IAsyncSpecification<T>);
+    isSatisfiedByAsync(candidate: T, context?: Record<string, unknown>): Promise<boolean>;
+    explainFailureAsync(candidate: T, context?: Record<string, unknown>): Promise<string | null>;
+}
+/**
+ * @since 0.4.2
+ */
+export declare class OrAsyncSpecification<T> extends AsyncCompositeSpecification<T> {
+    private readonly left;
+    private readonly right;
+    readonly name: string;
+    readonly description: string;
+    constructor(left: IAsyncSpecification<T>, right: IAsyncSpecification<T>);
+    isSatisfiedByAsync(candidate: T, context?: Record<string, unknown>): Promise<boolean>;
+    explainFailureAsync(candidate: T, context?: Record<string, unknown>): Promise<string | null>;
+}
+/**
+ * @since 0.4.2
+ */
+export declare class NotAsyncSpecification<T> extends AsyncCompositeSpecification<T> {
+    private readonly spec;
+    readonly name: string;
+    readonly description: string;
+    constructor(spec: IAsyncSpecification<T>);
+    isSatisfiedByAsync(candidate: T, context?: Record<string, unknown>): Promise<boolean>;
+    explainFailureAsync(candidate: T, context?: Record<string, unknown>): Promise<string | null>;
+}

package/dist/specifications/composite-specification.d.ts

@@ -0,0 +1,25 @@
+import { ISpecification } from '../../../contracts/src/index.ts';
+export declare abstract class CompositeSpecification<T> implements ISpecification<T> {
+    abstract isSatisfiedBy(candidate: T): boolean;
+    and(other: ISpecification<T>): ISpecification<T>;
+    or(other: ISpecification<T>): ISpecification<T>;
+    not(): ISpecification<T>;
+    static create<T>(predicate: (candidate: T) => boolean): ISpecification<T>;
+}
+export declare class AndSpecification<T> extends CompositeSpecification<T> {
+    private readonly left;
+    private readonly right;
+    constructor(left: ISpecification<T>, right: ISpecification<T>);
+    isSatisfiedBy(candidate: T): boolean;
+}
+export declare class OrSpecification<T> extends CompositeSpecification<T> {
+    private readonly left;
+    private readonly right;
+    constructor(left: ISpecification<T>, right: ISpecification<T>);
+    isSatisfiedBy(candidate: T): boolean;
+}
+export declare class NotSpecification<T> extends CompositeSpecification<T> {
+    private readonly spec;
+    constructor(spec: ISpecification<T>);
+    isSatisfiedBy(candidate: T): boolean;
+}

package/dist/specifications/index.d.ts

@@ -0,0 +1,5 @@
+export * from './composite-specification';
+export * from './async-composite-specification';
+export * from './memoized-specification';
+export * from './specification-operators';
+export * from './specification-validator';

package/dist/specifications/memoized-specification.d.ts

@@ -0,0 +1,84 @@
+import { ISpecification } from '../../../contracts/src/index.ts';
+import { CompositeSpecification } from './composite-specification';
+/**
+ * Specification wrapper that memoizes `isSatisfiedBy` results per candidate.
+ *
+ * VP-002 (2026-05-09): cuts repeated evaluation cost when the same
+ * specification is checked multiple times against the same candidate
+ * during a single query — common in pipelines like "filter list by spec,
+ * then enrich with another spec, then sort by a third predicate that
+ * also calls the first spec." Without memoization, each `isSatisfiedBy`
+ * call walks the full predicate tree even when the answer is already
+ * known.
+ *
+ * **Memoization storage**: `WeakMap<object, boolean>` for object
+ * candidates — automatic GC when the candidate is unreachable. Primitive
+ * candidates (strings, numbers) bypass the cache entirely (WeakMap keys
+ * must be objects); for those the wrapper degrades to a pass-through.
+ *
+ * **When NOT to use this**: specs whose result depends on mutable
+ * external state (timestamps, counters, randomness, fetched data). The
+ * cache assumes "same candidate object → same answer." If your spec is
+ * pure (depends only on candidate fields), you're safe.
+ *
+ * **Lifecycle contract — NOT a singleton-safe Specification.** Per Evans
+ * (Blue Book, ch. 9), a canonical `Specification` is a *stateless predicate*:
+ * shareable, serializable, safe to cache as a singleton. `MemoizedSpecification`
+ * is intentionally stateful — its `WeakMap` cache makes results dependent
+ * on call history. Treat it as a *per-query* helper, not as something to
+ * stash in a module-level constant or DI singleton with a long lifetime.
+ * Construct fresh, use within a request, let it be collected.
+ *
+ * Composes correctly with `and`/`or`/`not` because it extends
+ * `CompositeSpecification` — but those operators wrap the *current*
+ * memoized result with new instances, so the composition itself isn't
+ * memoized. To memoize the whole tree, wrap the outer composite.
+ *
+ * @example Pure-function specification
+ * ```typescript
+ * import { MemoizedSpecification, CompositeSpecification } from '@vytches/ddd-validation';
+ *
+ * class HighValueOrder extends CompositeSpecification<Order> {
+ *   isSatisfiedBy(o: Order) { return o.total > 1000; }
+ * }
+ *
+ * const spec = new MemoizedSpecification(new HighValueOrder());
+ * spec.isSatisfiedBy(order);  // computes
+ * spec.isSatisfiedBy(order);  // cached, no recomputation
+ * spec.isSatisfiedBy(otherOrder);  // computes (different candidate)
+ *
+ * // After `order` is unreachable, its cache entry is GC'd automatically.
+ * ```
+ *
+ * @example Composing memoized + raw specs
+ * ```typescript
+ * const expensive = new MemoizedSpecification(new ComplexCustomerCheck());
+ * const cheap = new IsActiveOrder();
+ *
+ * // The composed spec re-runs `expensive` once per candidate (cache hit
+ * // on second call), and `cheap` directly each time.
+ * const both = expensive.and(cheap);
+ * ```
+ *
+ * @public
+ * @stable
+ * @since 0.25.0
+ */
+export declare class MemoizedSpecification<T extends object> extends CompositeSpecification<T> {
+    private readonly inner;
+    private readonly cache;
+    constructor(inner: ISpecification<T>);
+    isSatisfiedBy(candidate: T): boolean;
+    /**
+     * Manually evict a candidate from the cache. Use when you know the
+     * candidate's relevant fields have changed and you want fresh evaluation
+     * without discarding cache entries for other candidates.
+     */
+    invalidate(candidate: T): void;
+    /**
+     * Forwarded to the inner spec, if it implements optional `explainFailure`.
+     * Skips the cache because failure explanations are typically only computed
+     * on-demand.
+     */
+    explainFailure(candidate: T): string | null;
+}

package/dist/specifications/specification-operators.d.ts

@@ -0,0 +1,70 @@
+import { ISpecification } from '../../../contracts/src/index.ts';
+import { CompositeSpecification } from './composite-specification';
+export declare class AlwaysTrueSpecification<T> extends CompositeSpecification<T> {
+    isSatisfiedBy(_candidate: T): boolean;
+}
+export declare class AlwaysFalseSpecification<T> extends CompositeSpecification<T> {
+    isSatisfiedBy(_candidate: T): boolean;
+}
+export declare class PredicateSpecification<T> extends CompositeSpecification<T> {
+    private readonly predicate;
+    constructor(predicate: (candidate: T) => boolean);
+    isSatisfiedBy(candidate: T): boolean;
+}
+export declare class PropertyEqualsSpecification<T> extends CompositeSpecification<T> {
+    private readonly propertyName;
+    private readonly expectedValue;
+    constructor(propertyName: keyof T, expectedValue: T[keyof T]);
+    isSatisfiedBy(candidate: T): boolean;
+}
+export declare class PropertyInSpecification<T> extends CompositeSpecification<T> {
+    private readonly propertyName;
+    private readonly possibleValues;
+    constructor(propertyName: keyof T, possibleValues: T[keyof T][]);
+    isSatisfiedBy(candidate: T): boolean;
+}
+export declare class PropertyBetweenSpecification<T> extends CompositeSpecification<T> {
+    private readonly propertyName;
+    private readonly min;
+    private readonly max;
+    constructor(propertyName: keyof T, min: number, max: number);
+    isSatisfiedBy(candidate: T): boolean;
+}
+export declare const Specification: {
+    /**
+     * Tworzy specyfikację zawsze prawdziwą
+     */
+    alwaysTrue<T>(): ISpecification<T>;
+    /**
+     * Tworzy specyfikację zawsze fałszywą
+     */
+    alwaysFalse<T>(): ISpecification<T>;
+    /**
+     * Tworzy specyfikację opartą o predykat
+     */
+    create<T>(predicate: (candidate: T) => boolean): ISpecification<T>;
+    /**
+     * Tworzy specyfikację sprawdzającą równość właściwości
+     */
+    propertyEquals<T>(propertyName: keyof T, expectedValue: T[keyof T]): ISpecification<T>;
+    /**
+     * Tworzy specyfikację sprawdzającą zawieranie się właściwości w zbiorze
+     */
+    propertyIn<T>(propertyName: keyof T, possibleValues: T[keyof T][]): ISpecification<T>;
+    /**
+     * Tworzy specyfikację sprawdzającą zakres wartości
+     */
+    propertyBetween<T>(propertyName: keyof T, min: number, max: number): ISpecification<T>;
+    /**
+     * Łączy specyfikacje operatorem AND
+     */
+    and<T>(...specifications: ISpecification<T>[]): ISpecification<T>;
+    /**
+     * Łączy specyfikacje operatorem OR
+     */
+    or<T>(...specifications: ISpecification<T>[]): ISpecification<T>;
+    /**
+     * Neguje specyfikację
+     */
+    not<T>(specification: ISpecification<T>): ISpecification<T>;
+};

package/dist/specifications/specification-validator.d.ts

@@ -0,0 +1,26 @@
+import { ISpecification, IValidator } from '../../../contracts/src/index.ts';
+import { Result } from '../../../utils/src/index.ts';
+import { ValidationErrors } from '../validation-error';
+export declare class SpecificationValidator<T> implements IValidator<T> {
+    private validationRules;
+    /**
+     * Adds a validation rule based on a specification
+     */
+    addRule(specification: ISpecification<T>, message: string, property?: string, context?: Record<string, unknown>): SpecificationValidator<T>;
+    /**
+     * Adds a rule for a specific object property
+     */
+    addPropertyRule<P>(property: keyof T & string, specification: ISpecification<P>, message: string, getValue: (obj: T) => P, context?: Record<string, any>): SpecificationValidator<T>;
+    /**
+     * Performs validation based on all specifications
+     */
+    validate(value: T): Result<T, ValidationErrors>;
+    /**
+     * Creates a validator with a single rule
+     */
+    static fromSpecification<T>(specification: ISpecification<T>, message: string, property?: string, context?: Record<string, any>): SpecificationValidator<T>;
+    /**
+     * Creates an empty validator
+     */
+    static create<T>(): SpecificationValidator<T>;
+}

package/dist/validation-error.d.ts

@@ -0,0 +1,13 @@
+import { IValidationError, IValidationErrors } from '@vytches/ddd-contracts';
+export declare class ValidationError implements IValidationError {
+    readonly property: string;
+    readonly message: string;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(property: string, message: string, context?: Record<string, unknown> | undefined);
+    toString(): string;
+}
+export declare class ValidationErrors extends Error implements IValidationErrors {
+    readonly errors: IValidationError[];
+    constructor(errors: ValidationError[]);
+    get length(): number;
+}

package/dist/validation-facade.d.ts

@@ -0,0 +1,51 @@
+import { ISpecification, IValidationErrors, IValidator } from '@vytches/ddd-contracts';
+import { Result } from '@vytches/ddd-utils';
+import { BusinessRuleValidator } from './business-rules/business-rule-validator';
+import { ValidationErrors } from './validation-error';
+export declare const Validation: {
+    /**
+     * Tworzy nowy walidator reguł biznesowych
+     */
+    create<T>(): BusinessRuleValidator<T>;
+    /**
+     * Tworzy walidator oparty na specyfikacji
+     */
+    fromSpecification<T>(specification: ISpecification<T>, message: string, property?: string): IValidator<T>;
+    /**
+     * Tworzy walidator łączący wiele walidatorów
+     */
+    combine<T>(...validators: IValidator<T>[]): IValidator<T>;
+    /**
+     * Waliduje obiekt bezpośrednio za pomocą specyfikacji
+     */
+    validateWithSpecification<T>(value: T, specification: ISpecification<T>, message: string): Result<T, IValidationErrors>;
+    /**
+     * Waliduje za pomocą wielu specyfikacji z własnymi komunikatami błędów
+     */
+    validateWithRules<T>(value: T, rules: Array<{
+        specification: ISpecification<T>;
+        message: string;
+        property?: string;
+    }>): Result<T, ValidationErrors>;
+    /**
+     * Konwertuje specyfikację na walidator
+     */
+    specificationToValidator<T>(specification: ISpecification<T>, message: string, property?: string): IValidator<T>;
+    /**
+     * Konwertuje walidator na specyfikację
+     */
+    validatorToSpecification<T>(validator: IValidator<T>): ISpecification<T>;
+    /**
+     * Tworzy walidator dla głęboko zagnieżdżonej struktury obiektów
+     */
+    forNestedPath<T>(path: string[], validator: IValidator<unknown>): IValidator<T>;
+    /**
+     * Waliduje głęboko zagnieżdżoną właściwość
+     */
+    validatePath<T, P>(object: T, path: (string | number)[], valueValidator: IValidator<P>): Result<T, ValidationErrors>;
+    /**
+     * Używa zewnętrznego walidatora implementującego IValidator<T>
+     * Pozwala na integrację z bibliotekami takimi jak zod, class-validator, itp.
+     */
+    useExternal<T>(validator: IValidator<T>): IValidator<T>;
+};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@vytches/ddd-validation",
+  "version": "0.26.0",
+  "description": "Business rules and specifications for domain validation",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LLMGUIDE.md"
+  ],
+  "keywords": [
+    "ddd",
+    "domain-driven-design",
+    "typescript",
+    "validation"
+  ],
+  "author": "VytchesDDD",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vytches/ddd.git",
+    "directory": "packages/validation"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vite": "^7.3.2",
+    "vite-plugin-dts": "^4.0.0",
+    "vitest": "^2.0.0",
+    "@vytches/ddd-testing": "0.26.0"
+  },
+  "nx": {
+    "tags": [
+      "scope:validation",
+      "type:lib",
+      "layer:patterns"
+    ]
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "dependencies": {
+    "@vytches/ddd-contracts": "0.26.0",
+    "@vytches/ddd-domain-primitives": "0.26.0",
+    "@vytches/ddd-logging": "0.26.0",
+    "@vytches/ddd-utils": "0.26.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts",
+    "type-check": "tsc --noEmit"
+  }
+}