@bernierllc/nevar-types 0.0.1 → 0.1.0

package/src/results.ts

@@ -0,0 +1,91 @@
+/*
+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 { 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/src/storage.ts

@@ -0,0 +1,118 @@
+/*
+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 { 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 {
+  // Group operations
+  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[]>;
+
+  // Rule operations
+  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[]>;
+
+  // Log operations
+  writeLog(entry: ExecutionLogEntry): Promise<void>;
+  queryLogs(filters: LogFilters): Promise<PaginatedResult<ExecutionLogEntry>>;
+  purgeLogs(olderThan: Date): Promise<number>;
+
+  // Bulk operations
+  transformRules(
+    filter: RuleFilters,
+    transform: (rule: Rule) => Rule
+  ): Promise<{ updated: number; failed: Array<{ ruleId: string; error: string }> }>;
+}

package/src/triggers.ts

@@ -0,0 +1,19 @@
+/*
+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.
+*/
+
+/**
+ * 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/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "__tests__"]
+}