@bernierllc/nevar-types 0.0.1 → 0.1.0

package/.eslintrc.js

@@ -0,0 +1,29 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module'
+  },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended'
+  ],
+  plugins: ['@typescript-eslint'],
+  env: {
+    node: true,
+    jest: true
+  },
+  rules: {
+    '@typescript-eslint/explicit-function-return-type': 'warn',
+    '@typescript-eslint/no-explicit-any': 'off',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }]
+  }
+};

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2025 Bernier LLC
+
+This software is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.

package/README.md

@@ -1,45 +1,130 @@
 # @bernierllc/nevar-types
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@bernierllc/nevar-types`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+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
+
+```bash
+npm install @bernierllc/nevar-types
+```
+
+## Usage
+
+```typescript
+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.

package/__tests__/errors.test.ts

@@ -0,0 +1,189 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import {
+  NevarError,
+  NevarTriggerError,
+  NevarEvaluationError,
+  NevarActionError,
+  NevarCircuitBreakerError,
+  NevarLoopError,
+  NevarStorageError,
+  NevarValidationError,
+} from '../src/errors';
+
+describe('NevarError', () => {
+  it('should create with message only', () => {
+    const error = new NevarError('something went wrong');
+    expect(error.message).toBe('something went wrong');
+    expect(error.code).toBe('NEVAR_ERROR');
+    expect(error.name).toBe('NevarError');
+    expect(error.context).toBeUndefined();
+    expect(error.cause).toBeUndefined();
+  });
+
+  it('should create with custom code and context', () => {
+    const error = new NevarError('fail', {
+      code: 'CUSTOM_CODE',
+      context: { ruleId: 'r-1' },
+    });
+    expect(error.code).toBe('CUSTOM_CODE');
+    expect(error.context).toEqual({ ruleId: 'r-1' });
+  });
+
+  it('should chain cause using ES2022 Error.cause', () => {
+    const cause = new Error('root cause');
+    const error = new NevarError('wrapper', { cause });
+    expect(error.cause).toBe(cause);
+  });
+
+  it('should be instanceof Error', () => {
+    const error = new NevarError('test');
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(NevarError);
+  });
+});
+
+describe('NevarTriggerError', () => {
+  it('should have correct defaults', () => {
+    const error = new NevarTriggerError('trigger failed');
+    expect(error.name).toBe('NevarTriggerError');
+    expect(error.code).toBe('NEVAR_TRIGGER_ERROR');
+    expect(error.message).toBe('trigger failed');
+  });
+
+  it('should be instanceof NevarError and Error', () => {
+    const error = new NevarTriggerError('test');
+    expect(error).toBeInstanceOf(NevarError);
+    expect(error).toBeInstanceOf(Error);
+  });
+
+  it('should support cause chaining', () => {
+    const cause = new Error('underlying');
+    const error = new NevarTriggerError('trigger failed', { cause });
+    expect(error.cause).toBe(cause);
+  });
+
+  it('should support custom code override', () => {
+    const error = new NevarTriggerError('fail', { code: 'CUSTOM' });
+    expect(error.code).toBe('CUSTOM');
+  });
+
+  it('should support context', () => {
+    const error = new NevarTriggerError('fail', { context: { triggerKey: 'order.created' } });
+    expect(error.context).toEqual({ triggerKey: 'order.created' });
+  });
+});
+
+describe('NevarEvaluationError', () => {
+  it('should have correct defaults', () => {
+    const error = new NevarEvaluationError('eval failed');
+    expect(error.name).toBe('NevarEvaluationError');
+    expect(error.code).toBe('NEVAR_EVALUATION_ERROR');
+  });
+
+  it('should be instanceof NevarError', () => {
+    expect(new NevarEvaluationError('test')).toBeInstanceOf(NevarError);
+  });
+
+  it('should chain cause', () => {
+    const cause = new Error('root');
+    const error = new NevarEvaluationError('fail', { cause, context: { ruleId: 'r-1' } });
+    expect(error.cause).toBe(cause);
+    expect(error.context).toEqual({ ruleId: 'r-1' });
+  });
+});
+
+describe('NevarActionError', () => {
+  it('should have correct defaults', () => {
+    const error = new NevarActionError('action failed');
+    expect(error.name).toBe('NevarActionError');
+    expect(error.code).toBe('NEVAR_ACTION_ERROR');
+  });
+
+  it('should be instanceof NevarError', () => {
+    expect(new NevarActionError('test')).toBeInstanceOf(NevarError);
+  });
+
+  it('should support all options', () => {
+    const cause = new Error('http timeout');
+    const error = new NevarActionError('send email failed', {
+      cause,
+      code: 'ACTION_TIMEOUT',
+      context: { actionType: 'send-email' },
+    });
+    expect(error.cause).toBe(cause);
+    expect(error.code).toBe('ACTION_TIMEOUT');
+    expect(error.context).toEqual({ actionType: 'send-email' });
+  });
+});
+
+describe('NevarCircuitBreakerError', () => {
+  it('should have correct defaults', () => {
+    const error = new NevarCircuitBreakerError('circuit open');
+    expect(error.name).toBe('NevarCircuitBreakerError');
+    expect(error.code).toBe('NEVAR_CIRCUIT_BREAKER_ERROR');
+  });
+
+  it('should be instanceof NevarError', () => {
+    expect(new NevarCircuitBreakerError('test')).toBeInstanceOf(NevarError);
+  });
+});
+
+describe('NevarLoopError', () => {
+  it('should have correct defaults', () => {
+    const error = new NevarLoopError('loop detected');
+    expect(error.name).toBe('NevarLoopError');
+    expect(error.code).toBe('NEVAR_LOOP_ERROR');
+  });
+
+  it('should be instanceof NevarError', () => {
+    expect(new NevarLoopError('test')).toBeInstanceOf(NevarError);
+  });
+
+  it('should carry loop context', () => {
+    const error = new NevarLoopError('loop detected at depth 3', {
+      context: { depth: 3, triggerKey: 'order.updated', ruleIds: ['r-1', 'r-2'] },
+    });
+    expect(error.context).toEqual({ depth: 3, triggerKey: 'order.updated', ruleIds: ['r-1', 'r-2'] });
+  });
+});
+
+describe('NevarStorageError', () => {
+  it('should have correct defaults', () => {
+    const error = new NevarStorageError('db connection failed');
+    expect(error.name).toBe('NevarStorageError');
+    expect(error.code).toBe('NEVAR_STORAGE_ERROR');
+  });
+
+  it('should be instanceof NevarError', () => {
+    expect(new NevarStorageError('test')).toBeInstanceOf(NevarError);
+  });
+});
+
+describe('NevarValidationError', () => {
+  it('should have correct defaults', () => {
+    const error = new NevarValidationError('invalid rule');
+    expect(error.name).toBe('NevarValidationError');
+    expect(error.code).toBe('NEVAR_VALIDATION_ERROR');
+  });
+
+  it('should be instanceof NevarError', () => {
+    expect(new NevarValidationError('test')).toBeInstanceOf(NevarError);
+  });
+
+  it('should support all options', () => {
+    const cause = new TypeError('expected string');
+    const error = new NevarValidationError('rule name is required', {
+      cause,
+      context: { field: 'name', received: undefined },
+    });
+    expect(error.cause).toBe(cause);
+    expect(error.context).toEqual({ field: 'name', received: undefined });
+  });
+});

package/__tests__/type-guards.test.ts

@@ -0,0 +1,152 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { isConditionGroup, isCondition } from '../src/conditions';
+
+describe('isConditionGroup', () => {
+  it('should return true for a valid AND group', () => {
+    expect(isConditionGroup({
+      operator: 'AND',
+      conditions: [{ field: 'age', op: 'gt', value: 18 }],
+    })).toBe(true);
+  });
+
+  it('should return true for a valid OR group', () => {
+    expect(isConditionGroup({
+      operator: 'OR',
+      conditions: [],
+    })).toBe(true);
+  });
+
+  it('should return true for a valid NOT group', () => {
+    expect(isConditionGroup({
+      operator: 'NOT',
+      conditions: [{ field: 'status', op: 'eq', value: 'banned' }],
+    })).toBe(true);
+  });
+
+  it('should return true for nested groups', () => {
+    expect(isConditionGroup({
+      operator: 'AND',
+      conditions: [
+        { operator: 'OR', conditions: [] },
+        { field: 'x', op: 'eq', value: 1 },
+      ],
+    })).toBe(true);
+  });
+
+  it('should return false for null', () => {
+    expect(isConditionGroup(null)).toBe(false);
+  });
+
+  it('should return false for undefined', () => {
+    expect(isConditionGroup(undefined)).toBe(false);
+  });
+
+  it('should return false for a string', () => {
+    expect(isConditionGroup('AND')).toBe(false);
+  });
+
+  it('should return false for a number', () => {
+    expect(isConditionGroup(42)).toBe(false);
+  });
+
+  it('should return false when operator is missing', () => {
+    expect(isConditionGroup({ conditions: [] })).toBe(false);
+  });
+
+  it('should return false when conditions is missing', () => {
+    expect(isConditionGroup({ operator: 'AND' })).toBe(false);
+  });
+
+  it('should return false when operator is not AND/OR/NOT', () => {
+    expect(isConditionGroup({ operator: 'XOR', conditions: [] })).toBe(false);
+  });
+
+  it('should return false when conditions is not an array', () => {
+    expect(isConditionGroup({ operator: 'AND', conditions: 'not-array' })).toBe(false);
+  });
+
+  it('should return false for an empty object', () => {
+    expect(isConditionGroup({})).toBe(false);
+  });
+
+  it('should return false for a Condition (not a group)', () => {
+    expect(isConditionGroup({ field: 'age', op: 'gt', value: 18 })).toBe(false);
+  });
+});
+
+describe('isCondition', () => {
+  it('should return true for a valid condition', () => {
+    expect(isCondition({ field: 'age', op: 'gt', value: 18 })).toBe(true);
+  });
+
+  it('should return true when value is null', () => {
+    expect(isCondition({ field: 'name', op: 'is_null', value: null })).toBe(true);
+  });
+
+  it('should return true when value is undefined', () => {
+    expect(isCondition({ field: 'name', op: 'is_undefined', value: undefined })).toBe(true);
+  });
+
+  it('should return true when value is 0', () => {
+    expect(isCondition({ field: 'count', op: 'eq', value: 0 })).toBe(true);
+  });
+
+  it('should return true when value is false', () => {
+    expect(isCondition({ field: 'active', op: 'eq', value: false })).toBe(true);
+  });
+
+  it('should return true when value is empty string', () => {
+    expect(isCondition({ field: 'name', op: 'eq', value: '' })).toBe(true);
+  });
+
+  it('should return false for null', () => {
+    expect(isCondition(null)).toBe(false);
+  });
+
+  it('should return false for undefined', () => {
+    expect(isCondition(undefined)).toBe(false);
+  });
+
+  it('should return false for a string', () => {
+    expect(isCondition('field:age')).toBe(false);
+  });
+
+  it('should return false for a number', () => {
+    expect(isCondition(42)).toBe(false);
+  });
+
+  it('should return false when field is missing', () => {
+    expect(isCondition({ op: 'gt', value: 18 })).toBe(false);
+  });
+
+  it('should return false when op is missing', () => {
+    expect(isCondition({ field: 'age', value: 18 })).toBe(false);
+  });
+
+  it('should return false when value key is missing', () => {
+    expect(isCondition({ field: 'age', op: 'gt' })).toBe(false);
+  });
+
+  it('should return false when field is not a string', () => {
+    expect(isCondition({ field: 123, op: 'gt', value: 18 })).toBe(false);
+  });
+
+  it('should return false when op is not a string', () => {
+    expect(isCondition({ field: 'age', op: 123, value: 18 })).toBe(false);
+  });
+
+  it('should return false for an empty object', () => {
+    expect(isCondition({})).toBe(false);
+  });
+
+  it('should return false for a ConditionGroup', () => {
+    expect(isCondition({ operator: 'AND', conditions: [] })).toBe(false);
+  });
+});

package/dist/actions.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Configuration for retrying a failed action with exponential backoff.
+ */
+export interface ActionRetryConfig {
+    maxAttempts: number;
+    backoffMs: number;
+    backoffMultiplier: number;
+    maxBackoffMs: number;
+    retryableErrors?: string[];
+}
+/**
+ * Defines an action to execute when a rule matches.
+ */
+export interface ActionDefinition {
+    actionType: string;
+    config: Record<string, unknown>;
+    executionOrder: number;
+    retry?: ActionRetryConfig;
+}
+/**
+ * An intent represents a planned action derived from a matched rule.
+ */
+export interface ActionIntent {
+    actionType: string;
+    config: Record<string, unknown>;
+    ruleId: string;
+    ruleName: string;
+    retry?: ActionRetryConfig;
+}
+/**
+ * A trigger that should be fired as a result of an action execution.
+ */
+export interface DeferredTrigger {
+    triggerKey: string;
+    payload: Record<string, unknown>;
+}
+/**
+ * The result of executing a single action.
+ */
+export interface ActionResult {
+    intent: ActionIntent;
+    status: 'success' | 'error';
+    output: Record<string, unknown>;
+    deferredTriggers?: DeferredTrigger[];
+    durationMs: number;
+    attempts: number;
+    lastError?: string;
+}
+/**
+ * Controls how action failures are handled within a rule's action list.
+ */
+export type ActionFailureMode = 'fail-fast' | 'best-effort';
+/**
+ * Defines an action handler that can be registered with the engine.
+ * Includes the handler function, metadata for discovery, and a config schema.
+ */
+export interface ActionHandlerDefinition {
+    label: string;
+    category: string;
+    canDefer: boolean;
+    configSchema: unknown;
+    handler: (config: Record<string, unknown>, context: Record<string, unknown>, priorResults: ActionResult[]) => Promise<Record<string, unknown>>;
+}
+/**
+ * The aggregate result of executing a set of action intents.
+ */
+export interface ExecutionResult {
+    results: ActionResult[];
+    deferredTriggers: DeferredTrigger[];
+    durationMs: number;
+}

package/dist/actions.js

@@ -0,0 +1,9 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/conditions.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A group of conditions combined with a logical operator.
+ * NOT groups evaluate children as AND, then negate the result.
+ */
+export interface ConditionGroup {
+    operator: 'AND' | 'OR' | 'NOT';
+    conditions: (ConditionGroup | Condition)[];
+}
+/**
+ * A single condition that compares a field value using an operator.
+ */
+export interface Condition {
+    field: string;
+    op: string;
+    value: unknown;
+}
+/**
+ * Type guard: checks whether the given value is a ConditionGroup.
+ */
+export declare function isConditionGroup(value: unknown): value is ConditionGroup;
+/**
+ * Type guard: checks whether the given value is a Condition.
+ */
+export declare function isCondition(value: unknown): value is Condition;