@bernierllc/nevar-types

Shared type definitions, interfaces, error classes, and type guards for the Nevar rules engine suite.

Overview

This package provides the foundational types that all Nevar packages depend on. It has zero runtime dependencies — it exports only TypeScript types, interfaces, error classes, and type guard functions.

Installation

npm install @bernierllc/nevar-types

Usage

import type {
  Rule,
  ConditionGroup,
  ActionDefinition,
  NevarConfig,
  EvaluationResult,
  NevarStorageAdapter,
} from '@bernierllc/nevar-types';

import {
  isConditionGroup,
  isCondition,
  NevarError,
  NevarEvaluationError,
} from '@bernierllc/nevar-types';

// Type guard usage
const node: ConditionGroup | Condition = getNode();
if (isConditionGroup(node)) {
  console.log(node.operator, node.conditions);
} else if (isCondition(node)) {
  console.log(node.field, node.op, node.value);
}

// Error handling with cause chain
try {
  evaluateRule(rule, context);
} catch (error) {
  if (error instanceof NevarEvaluationError) {
    console.log(error.code, error.context, error.cause);
  }
}

API

Types and Interfaces

• Rule - Complete rule definition with trigger type, condition tree, actions, and execution settings
• RuleGroup - Named collection of rules
• ConditionGroup - Tree node with operator (AND/OR/NOT) and nested conditions
• Condition - Leaf node with field, op, and value
• ActionDefinition - Action type, config, retry settings, and execution order
• ActionIntent - Resolved action ready for execution, tied to a specific rule
• ActionResult - Outcome of executing an action intent
• TriggerDefinition - Trigger type definition with payload schema
• OperatorDefinition - Operator with evaluate function, label, category, and field types
• NevarStorageAdapter - Storage interface for rules, groups, and execution logs
• NevarConfig - Full engine configuration including circuit breaker, loop, and audit settings
• EvaluationResult - Match result with evaluation trace
• LoopHandle - Runtime loop state with heartbeat tracking

Error Classes

All errors extend NevarError and support ES2022 Error.cause chaining via NevarErrorOptions:

• NevarError - Base error with code: string and context?: Record<string, unknown>
• NevarTriggerError - Trigger validation and dispatch failures
• NevarEvaluationError - Condition evaluation failures (unknown operators, provider errors)
• NevarActionError - Action execution failures
• NevarCircuitBreakerError - Circuit breaker limit violations
• NevarLoopError - Loop detection and control failures
• NevarStorageError - Storage adapter failures
• NevarValidationError - Schema and configuration validation failures

Type Guards

• isConditionGroup(value) - Returns true if value has operator and conditions fields
• isCondition(value) - Returns true if value has field, op, and value fields

Exports

Types & Interfaces

• Models: Rule, RuleGroup, LogLevel, EvaluationTrace
• Conditions: ConditionGroup, Condition
• Actions: ActionDefinition, ActionRetryConfig, ActionIntent, ActionResult, MatchedRule, DeferredTrigger, ActionFailureMode
• Triggers: TriggerDefinition
• Context: ContextProviderDefinition
• Operators: OperatorDefinition, OperatorInfo
• Storage: NevarStorageAdapter, GroupFilters, RuleFilters, LogFilters, PaginatedResult, ExecutionLogEntry
• Config: NevarConfig, CircuitBreakerConfig, LoopConfig, AuditLoggerConfig, SeedStrategy
• Results: EmitResult, PreviewResult, EvaluationResult, LoopHandle, LoopAnalysis, DetectedLoop

Error Classes

All errors extend NevarError and follow the ES2022 Error.cause pattern:

• NevarError (base)
• NevarTriggerError
• NevarEvaluationError
• NevarActionError
• NevarCircuitBreakerError
• NevarLoopError
• NevarStorageError
• NevarValidationError

Type Guards

• isConditionGroup(value) — checks for operator and conditions fields
• isCondition(value) — checks for field, op, value fields

Integration Documentation

Logger Integration

This package does not integrate with @bernierllc/logger. As a core package, logger integration is optional and not included by default. Consumers should handle logging at the service layer.

NeverHub Integration

This package does not integrate with @bernierllc/neverhub-adapter. As a core package, NeverHub integration is not applicable. NeverHub registration should be handled by service-layer packages that compose this package.

License

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