@bernierllc/validators-runner

Validation orchestration engine that provides a flexible framework for running validation rules against targets with advanced configuration, reporting, and error handling capabilities.

Installation

npm install @bernierllc/validators-runner

Usage

Basic Example

import { ValidationRunner, RunnerBuilder } from '@bernierllc/validators-runner';

// Create a validation rule
const textRule = {
  meta: { id: 'text-check', name: 'Text Check' },
  async execute(target) {
    if (target.data.includes('error')) {
      return [{ 
        level: 'error', 
        message: 'Found error in text',
        location: { line: 1, column: 0 }
      }];
    }
    return [];
  }
};

// Build and configure runner
const runner = new RunnerBuilder()
  .withRule(textRule)
  .withConcurrency(5)
  .build();

// Define targets to validate
const targets = [
  { id: 'doc1', type: 'text', data: 'This is clean content' },
  { id: 'doc2', type: 'text', data: 'This has error content' }
];

// Run validation
const result = await runner.validate(targets);

console.log(`Found ${result.problems.length} problems`);
console.log(`Processed ${result.stats.targets} targets in ${result.stats.durationMs}ms`);

Advanced Configuration

import { ConfigLoader } from '@bernierllc/validators-runner';

// Load configuration from file
const config = await ConfigLoader.fromFile('./validation.config.json');

const runner = new RunnerBuilder()
  .withConfig(config)
  .withRule(textRule)
  .withReporter(consoleReporter)
  .build();

// Configure filtering and rule options
const configuredRunner = new ValidationRunner({
  rules: [textRule],
  config: {
    include: ['**/*.ts', '**/*.js'],
    exclude: ['**/node_modules/**'],
    primitives: {
      'text-check': ['error', { maxLength: 100 }]
    }
  },
  concurrency: 10,
  timeout: 5000
});

Configuration File Example

{
  "include": ["**/*.ts", "**/*.js"],
  "exclude": ["**/dist/**", "**/node_modules/**"],
  "primitives": {
    "text-check": "error",
    "length-check": ["warn", { "max": 1000 }]
  },
  "timeout": 10000
}

API Reference

ValidationRunner

Main orchestration class for running validations.

Constructor

new ValidationRunner(options: RunnerOptions)

Options:

• rules: Rule[] - Validation rules to apply
• config?: RunnerConfig - Configuration options
• concurrency?: number - Max concurrent validations (default: 5)
• timeout?: number - Timeout per validation in ms (default: 30000)

Methods

validate(targets: RunnerTarget[]): Promise<RunnerResult>

Validates all targets and returns comprehensive results.

Parameters:

• targets - Array of targets to validate

Returns:

• RunnerResult - Validation results with problems, stats, and metadata

RunnerBuilder

Fluent API for constructing ValidationRunner instances.

Methods

withRule(rule: Rule): RunnerBuilder
withReporter(reporter: Reporter): RunnerBuilder  
withConfig(config: RunnerConfig): RunnerBuilder
withConcurrency(concurrency: number): RunnerBuilder
withTimeout(timeout: number): RunnerBuilder
build(): ValidationRunner

ConfigLoader

Utility for loading configuration from various sources.

Static Methods

ConfigLoader.fromFile(path: string): Promise<RunnerConfig>
ConfigLoader.fromObject(obj: any): Promise<RunnerConfig>
ConfigLoader.fromEnv(prefix?: string): Promise<RunnerConfig>

Types

RunnerTarget

interface RunnerTarget {
  id: string;
  type: string;
  data: any;
}

RunnerResult

interface RunnerResult {
  problems: Problem[];
  stats: {
    targets: number;
    durationMs: number;
    rulesApplied: string[];
  };
  targetResults: Map<string, ValidationResult>;
  executionMeta: ExecutionMetadata;
}

RunnerConfig

interface RunnerConfig {
  include?: string[];
  exclude?: string[];
  primitives?: Record<string, any>;
  timeout?: number;
}

Integration Status

Logger Integration

• Status: not-applicable
• Reason: Core validation infrastructure focuses on orchestration without introducing logging dependencies. Consumer applications should handle logging of validation results as appropriate for their context.

Docs-Suite Integration

• Status: ready
• Format: markdown
• Description: Package includes comprehensive markdown documentation with TypeScript examples and API references suitable for docs-suite integration.

NeverHub Integration

• Status: not-applicable
• Reason: Validation runner is a foundational utility that operates synchronously on provided data. Event-driven service discovery is not applicable to this validation orchestration pattern.

Error Handling

The package follows structured error handling patterns:

// All operations return structured results
const result = await runner.validate(targets);

if (result.problems.length > 0) {
  console.log('Validation issues found:');
  result.problems.forEach(problem => {
    console.log(`${problem.level}: ${problem.message}`);
  });
}

// Execution metadata includes error details
if (result.executionMeta.errors.length > 0) {
  console.log('Execution errors:', result.executionMeta.errors);
}

Contributing

This package follows the BernierLLC package standards:

• TypeScript strict mode
• 90%+ test coverage for core packages
• Zero linting errors
• Comprehensive documentation

License

Copyright (c) 2025 Bernier LLC. All rights reserved.