@bernierllc/nevar-types 0.0.1 → 0.1.0

package/dist/conditions.js

@@ -0,0 +1,35 @@
+"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 });
+exports.isConditionGroup = isConditionGroup;
+exports.isCondition = isCondition;
+/**
+ * Type guard: checks whether the given value is a ConditionGroup.
+ */
+function isConditionGroup(value) {
+    if (value === null || value === undefined || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    return (typeof obj.operator === 'string' &&
+        (obj.operator === 'AND' || obj.operator === 'OR' || obj.operator === 'NOT') &&
+        Array.isArray(obj.conditions));
+}
+/**
+ * Type guard: checks whether the given value is a Condition.
+ */
+function isCondition(value) {
+    if (value === null || value === undefined || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    return (typeof obj.field === 'string' &&
+        typeof obj.op === 'string' &&
+        'value' in obj);
+}

package/dist/config.d.ts

@@ -0,0 +1,64 @@
+import { LogLevel } from './models';
+import { ActionFailureMode } from './actions';
+import { NevarStorageAdapter } from './storage';
+/**
+ * Configuration for the circuit breaker that prevents cascading failures.
+ */
+export interface CircuitBreakerConfig {
+    enabled?: boolean;
+    maxFailures?: number;
+    resetTimeMs?: number;
+    halfOpenMaxAttempts?: number;
+    maxCascadeDepth?: number;
+    maxActionsPerChain?: number;
+    maxChainDurationMs?: number;
+    maxConcurrentChains?: number;
+}
+/**
+ * Configuration for loop detection and prevention.
+ */
+export interface LoopConfig {
+    maxDepth?: number;
+    maxExecutionsPerTrigger?: number;
+    windowMs?: number;
+    allowInfiniteLoops?: boolean;
+    maxConcurrentLoops?: number;
+    heartbeatIntervalMs?: number;
+    maxMissedHeartbeats?: number;
+}
+/**
+ * Configuration for the audit logger.
+ */
+/**
+ * Override structure for per-rule, per-trigger, and per-action log levels.
+ */
+export interface AuditLoggerOverrides {
+    byRule?: Record<string, LogLevel>;
+    byTrigger?: Record<string, LogLevel>;
+    byAction?: Record<string, LogLevel>;
+}
+export interface AuditLoggerConfig {
+    enabled?: boolean;
+    logLevel?: LogLevel;
+    retentionDays?: number;
+    defaultLevel?: LogLevel;
+    overrides?: AuditLoggerOverrides;
+}
+/**
+ * Strategy for seeding initial rules into storage.
+ */
+export type SeedStrategy = 'skip-existing' | 'overwrite' | 'error-on-conflict' | 'skip_existing' | 'update_existing' | 'replace_all';
+/**
+ * Top-level configuration for the Nevar engine.
+ */
+export interface NevarConfig {
+    storage: NevarStorageAdapter;
+    defaultGroupId?: string;
+    logLevel?: LogLevel;
+    failureMode?: ActionFailureMode;
+    actionFailureMode?: ActionFailureMode;
+    circuitBreaker?: CircuitBreakerConfig;
+    loop?: LoopConfig;
+    auditLogger?: AuditLoggerConfig;
+    seedStrategy?: SeedStrategy;
+}

package/dist/config.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/context.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Defines a context provider that enriches trigger payloads with additional data.
+ */
+export interface ContextProviderDefinition {
+    key: string;
+    description?: string;
+    resolve: (payload: Record<string, unknown>) => Promise<Record<string, unknown>>;
+}

package/dist/context.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/errors.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Options for constructing a NevarError.
+ */
+export interface NevarErrorOptions {
+    cause?: Error;
+    code?: string;
+    context?: Record<string, unknown>;
+}
+/**
+ * Base error class for all Nevar errors.
+ * Follows ES2022 Error.cause pattern for error chain propagation.
+ */
+export declare class NevarError extends Error {
+    readonly code: string;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, options?: NevarErrorOptions);
+}
+/**
+ * Thrown when a trigger fails to fire or is invalid.
+ */
+export declare class NevarTriggerError extends NevarError {
+    constructor(message: string, options?: NevarErrorOptions);
+}
+/**
+ * Thrown when condition evaluation fails.
+ */
+export declare class NevarEvaluationError extends NevarError {
+    constructor(message: string, options?: NevarErrorOptions);
+}
+/**
+ * Thrown when an action fails to execute.
+ */
+export declare class NevarActionError extends NevarError {
+    constructor(message: string, options?: NevarErrorOptions);
+}
+/**
+ * Thrown when the circuit breaker trips due to too many failures.
+ */
+export declare class NevarCircuitBreakerError extends NevarError {
+    constructor(message: string, options?: NevarErrorOptions);
+}
+/**
+ * Thrown when a loop is detected in the evaluation chain.
+ */
+export declare class NevarLoopError extends NevarError {
+    constructor(message: string, options?: NevarErrorOptions);
+}
+/**
+ * Thrown when a storage operation fails.
+ */
+export declare class NevarStorageError extends NevarError {
+    constructor(message: string, options?: NevarErrorOptions);
+}
+/**
+ * Thrown when input validation fails.
+ */
+export declare class NevarValidationError extends NevarError {
+    constructor(message: string, options?: NevarErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,95 @@
+"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 });
+exports.NevarValidationError = exports.NevarStorageError = exports.NevarLoopError = exports.NevarCircuitBreakerError = exports.NevarActionError = exports.NevarEvaluationError = exports.NevarTriggerError = exports.NevarError = void 0;
+/**
+ * Base error class for all Nevar errors.
+ * Follows ES2022 Error.cause pattern for error chain propagation.
+ */
+class NevarError extends Error {
+    code;
+    context;
+    constructor(message, options) {
+        super(message, { cause: options?.cause });
+        this.name = 'NevarError';
+        this.code = options?.code ?? 'NEVAR_ERROR';
+        this.context = options?.context;
+    }
+}
+exports.NevarError = NevarError;
+/**
+ * Thrown when a trigger fails to fire or is invalid.
+ */
+class NevarTriggerError extends NevarError {
+    constructor(message, options) {
+        super(message, { ...options, code: options?.code ?? 'NEVAR_TRIGGER_ERROR' });
+        this.name = 'NevarTriggerError';
+    }
+}
+exports.NevarTriggerError = NevarTriggerError;
+/**
+ * Thrown when condition evaluation fails.
+ */
+class NevarEvaluationError extends NevarError {
+    constructor(message, options) {
+        super(message, { ...options, code: options?.code ?? 'NEVAR_EVALUATION_ERROR' });
+        this.name = 'NevarEvaluationError';
+    }
+}
+exports.NevarEvaluationError = NevarEvaluationError;
+/**
+ * Thrown when an action fails to execute.
+ */
+class NevarActionError extends NevarError {
+    constructor(message, options) {
+        super(message, { ...options, code: options?.code ?? 'NEVAR_ACTION_ERROR' });
+        this.name = 'NevarActionError';
+    }
+}
+exports.NevarActionError = NevarActionError;
+/**
+ * Thrown when the circuit breaker trips due to too many failures.
+ */
+class NevarCircuitBreakerError extends NevarError {
+    constructor(message, options) {
+        super(message, { ...options, code: options?.code ?? 'NEVAR_CIRCUIT_BREAKER_ERROR' });
+        this.name = 'NevarCircuitBreakerError';
+    }
+}
+exports.NevarCircuitBreakerError = NevarCircuitBreakerError;
+/**
+ * Thrown when a loop is detected in the evaluation chain.
+ */
+class NevarLoopError extends NevarError {
+    constructor(message, options) {
+        super(message, { ...options, code: options?.code ?? 'NEVAR_LOOP_ERROR' });
+        this.name = 'NevarLoopError';
+    }
+}
+exports.NevarLoopError = NevarLoopError;
+/**
+ * Thrown when a storage operation fails.
+ */
+class NevarStorageError extends NevarError {
+    constructor(message, options) {
+        super(message, { ...options, code: options?.code ?? 'NEVAR_STORAGE_ERROR' });
+        this.name = 'NevarStorageError';
+    }
+}
+exports.NevarStorageError = NevarStorageError;
+/**
+ * Thrown when input validation fails.
+ */
+class NevarValidationError extends NevarError {
+    constructor(message, options) {
+        super(message, { ...options, code: options?.code ?? 'NEVAR_VALIDATION_ERROR' });
+        this.name = 'NevarValidationError';
+    }
+}
+exports.NevarValidationError = NevarValidationError;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export type { LogLevel, RuleGroup, Rule, EvaluationTrace } from './models';
+export type { ConditionGroup, Condition } from './conditions';
+export { isConditionGroup, isCondition } from './conditions';
+export type { ActionRetryConfig, ActionDefinition, ActionIntent, DeferredTrigger, ActionResult, ActionFailureMode, ActionHandlerDefinition, ExecutionResult, } from './actions';
+export type { TriggerDefinition } from './triggers';
+export type { ContextProviderDefinition } from './context';
+export type { OperatorDefinition, OperatorInfo } from './operators';
+export type { GroupFilters, RuleFilters, LogFilters, PaginatedResult, ExecutionLogEntry, NevarStorageAdapter, } from './storage';
+export type { CircuitBreakerConfig, LoopConfig, AuditLoggerConfig, AuditLoggerOverrides, SeedStrategy, NevarConfig, } from './config';
+export type { EvaluationResult, EmitResult, PreviewResult, MatchedRule, LoopHandle, LoopAnalysis, DetectedLoop, } from './results';
+export { NevarError, NevarTriggerError, NevarEvaluationError, NevarActionError, NevarCircuitBreakerError, NevarLoopError, NevarStorageError, NevarValidationError, } from './errors';
+export type { NevarErrorOptions } from './errors';

package/dist/index.js

@@ -0,0 +1,23 @@
+"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 });
+exports.NevarValidationError = exports.NevarStorageError = exports.NevarLoopError = exports.NevarCircuitBreakerError = exports.NevarActionError = exports.NevarEvaluationError = exports.NevarTriggerError = exports.NevarError = exports.isCondition = exports.isConditionGroup = void 0;
+var conditions_1 = require("./conditions");
+Object.defineProperty(exports, "isConditionGroup", { enumerable: true, get: function () { return conditions_1.isConditionGroup; } });
+Object.defineProperty(exports, "isCondition", { enumerable: true, get: function () { return conditions_1.isCondition; } });
+// Errors
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "NevarError", { enumerable: true, get: function () { return errors_1.NevarError; } });
+Object.defineProperty(exports, "NevarTriggerError", { enumerable: true, get: function () { return errors_1.NevarTriggerError; } });
+Object.defineProperty(exports, "NevarEvaluationError", { enumerable: true, get: function () { return errors_1.NevarEvaluationError; } });
+Object.defineProperty(exports, "NevarActionError", { enumerable: true, get: function () { return errors_1.NevarActionError; } });
+Object.defineProperty(exports, "NevarCircuitBreakerError", { enumerable: true, get: function () { return errors_1.NevarCircuitBreakerError; } });
+Object.defineProperty(exports, "NevarLoopError", { enumerable: true, get: function () { return errors_1.NevarLoopError; } });
+Object.defineProperty(exports, "NevarStorageError", { enumerable: true, get: function () { return errors_1.NevarStorageError; } });
+Object.defineProperty(exports, "NevarValidationError", { enumerable: true, get: function () { return errors_1.NevarValidationError; } });

package/dist/models.d.ts

@@ -0,0 +1,56 @@
+import { ConditionGroup } from './conditions';
+import { ActionDefinition } from './actions';
+/**
+ * Log level for rule evaluation and execution tracing.
+ */
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'all' | 'none' | 'matches_only' | 'errors_only';
+/**
+ * A rule group organizes rules under a shared context (e.g., tenant, environment).
+ */
+export interface RuleGroup {
+    id: string;
+    name: string;
+    slug: string;
+    isActive?: boolean;
+    isDefault: boolean;
+    rules?: Rule[];
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * A rule defines conditions that, when matched against a trigger, produce actions.
+ */
+export interface Rule {
+    id: string;
+    groupId: string;
+    name: string;
+    slug: string;
+    triggerType: string;
+    conditions: ConditionGroup;
+    actions: ActionDefinition[];
+    executionOrder: number;
+    isActive: boolean;
+    stopOnMatch: boolean;
+    allowLoop: boolean;
+    logLevel: LogLevel;
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * A single step in the evaluation trace, recording what was evaluated and the outcome.
+ */
+export interface EvaluationTrace {
+    type?: 'group' | 'condition';
+    operator?: 'AND' | 'OR' | 'NOT';
+    field?: string;
+    op?: string;
+    value?: unknown;
+    expected?: unknown;
+    actual?: unknown;
+    result?: boolean;
+    matched?: boolean;
+    children?: EvaluationTrace[];
+    durationMs?: number;
+}

package/dist/models.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/operators.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Full operator definition including the evaluate function.
+ * Used internally by the engine to evaluate conditions.
+ */
+export interface OperatorDefinition {
+    name?: string;
+    description?: string;
+    label?: string;
+    category?: string;
+    fieldTypes?: string[];
+    schema?: unknown;
+    evaluate: (fieldValue: unknown, conditionValue: unknown) => boolean;
+}
+/**
+ * Discovery subset of an operator — excludes the evaluate function.
+ * Used for listing available operators to consumers.
+ */
+export interface OperatorInfo {
+    name: string;
+    description?: string;
+    label?: string;
+    category?: string;
+    fieldTypes?: string[];
+}

package/dist/operators.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/results.d.ts

@@ -0,0 +1,79 @@
+import { Rule, EvaluationTrace } from './models';
+import { ActionResult, ActionIntent } from './actions';
+import { ExecutionLogEntry } from './storage';
+/**
+ * The result of evaluating a single rule's conditions against a payload.
+ */
+export interface EvaluationResult {
+    matched: boolean;
+    trace: EvaluationTrace[];
+    durationMs?: number;
+}
+/**
+ * The result of emitting a trigger and executing matched rules.
+ */
+export interface EmitResult {
+    status: 'executed' | 'no_match' | 'loop_blocked' | 'circuit_tripped';
+    triggerKey: string;
+    groupId: string | null;
+    rulesEvaluated: number;
+    rulesMatched: number;
+    actionsExecuted: number;
+    actionResults: ActionResult[];
+    durationMs: number;
+    logs: ExecutionLogEntry[];
+}
+/**
+ * The result of previewing a trigger without executing actions.
+ */
+export interface PreviewResult {
+    status: 'previewed' | 'no_match';
+    triggerKey: string;
+    groupId: string | null;
+    rulesEvaluated: number;
+    rulesMatched: number;
+    intents: ActionIntent[];
+    evaluationTraces: Array<{
+        rule: Rule;
+        trace: EvaluationTrace[];
+    }>;
+    durationMs: number;
+}
+/**
+ * A rule that matched during evaluation, along with its evaluation result.
+ */
+export interface MatchedRule {
+    rule: Rule;
+    evaluationResult: EvaluationResult;
+}
+/**
+ * A handle to a running evaluation loop (e.g., polling or streaming).
+ */
+export interface LoopHandle {
+    id: string;
+    stop?: () => void;
+    isRunning?: () => boolean;
+    triggerKey?: string;
+    status?: 'running' | 'paused' | 'killed' | 'completed' | string;
+    iterations?: number;
+    startedAt?: Date;
+    lastHeartbeat?: Date;
+}
+/**
+ * Analysis of a detected evaluation loop.
+ */
+export interface LoopAnalysis {
+    detected?: boolean;
+    hasLoops?: boolean;
+    loops: DetectedLoop[];
+}
+/**
+ * A single detected loop in the evaluation chain.
+ */
+export interface DetectedLoop {
+    triggerKey?: string;
+    ruleIds: string[];
+    depth?: number;
+    chain?: string[];
+    allOptedIn?: boolean;
+}

package/dist/results.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/storage.d.ts

@@ -0,0 +1,100 @@
+import { Rule, RuleGroup, LogLevel } from './models';
+/**
+ * Filters for querying rule groups.
+ */
+export interface GroupFilters {
+    name?: string;
+    isActive?: boolean;
+    isDefault?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Filters for querying rules.
+ */
+export interface RuleFilters {
+    groupId?: string;
+    triggerType?: string;
+    isActive?: boolean;
+    name?: string;
+    slug?: string;
+}
+/**
+ * Filters for querying execution logs.
+ */
+export interface LogFilters {
+    triggerKey?: string;
+    groupId?: string;
+    ruleId?: string;
+    status?: string;
+    fromDate?: Date;
+    toDate?: Date;
+    from?: Date;
+    to?: Date;
+    page?: number;
+    pageSize?: number;
+}
+/**
+ * A paginated result set.
+ */
+export interface PaginatedResult<T> {
+    items?: T[];
+    data?: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages?: number;
+}
+/**
+ * A log entry recording the execution of a trigger.
+ */
+export interface ExecutionLogEntry {
+    id: string;
+    triggerKey: string;
+    triggerPayload?: Record<string, unknown>;
+    groupId: string | null;
+    ruleId: string | null;
+    ruleName?: string;
+    status: string;
+    logLevel?: LogLevel;
+    message?: string;
+    data?: Record<string, unknown>;
+    conditionsEvaluated?: Array<{
+        field?: string;
+        op?: string;
+        expected?: unknown;
+        actual?: unknown;
+        matched?: boolean;
+    }>;
+    actionsExecuted?: import('./actions').ActionResult[];
+    errorMessage?: string;
+    durationMs: number;
+    timestamp: Date;
+}
+/**
+ * The storage adapter interface that all persistence backends must implement.
+ */
+export interface NevarStorageAdapter {
+    createGroup(group: Omit<RuleGroup, 'id'>): Promise<RuleGroup>;
+    updateGroup(id: string, patch: Partial<RuleGroup>): Promise<RuleGroup>;
+    deleteGroup(id: string): Promise<void>;
+    findGroup(id: string): Promise<RuleGroup | null>;
+    findDefaultGroup(): Promise<RuleGroup | null>;
+    findGroupForContext(metadata: Record<string, unknown>): Promise<RuleGroup | null>;
+    listGroups(filters?: GroupFilters): Promise<RuleGroup[]>;
+    createRule(rule: Omit<Rule, 'id'>): Promise<Rule>;
+    updateRule(id: string, patch: Partial<Rule>): Promise<Rule>;
+    deleteRule(id: string): Promise<void>;
+    findRule(id: string): Promise<Rule | null>;
+    findActiveRules(groupId: string, triggerKey: string): Promise<Rule[]>;
+    listRules(filters?: RuleFilters): Promise<Rule[]>;
+    writeLog(entry: ExecutionLogEntry): Promise<void>;
+    queryLogs(filters: LogFilters): Promise<PaginatedResult<ExecutionLogEntry>>;
+    purgeLogs(olderThan: Date): Promise<number>;
+    transformRules(filter: RuleFilters, transform: (rule: Rule) => Rule): Promise<{
+        updated: number;
+        failed: Array<{
+            ruleId: string;
+            error: string;
+        }>;
+    }>;
+}

package/dist/storage.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/triggers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Defines a trigger type that the engine listens for.
+ */
+export interface TriggerDefinition {
+    key: string;
+    description?: string;
+    category?: string;
+    payloadSchema?: unknown;
+    schema?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}

package/dist/triggers.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 });