@f-o-t/rules-engine 2.0.2 → 3.0.0

package/src/validation/schema.ts

@@ -0,0 +1,386 @@
+import {
+   type Condition,
+   type ConditionGroup,
+   isConditionGroup,
+} from "@f-o-t/condition-evaluator";
+import { z } from "zod";
+import type {
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "../types/consequence";
+import { type Rule, RuleSchema, RuleSetSchema } from "../types/rule";
+
+// ============================================================================
+// Zod Schemas - Define schemas first, then infer types
+// ============================================================================
+
+export const ValidationErrorSchema = z.object({
+   path: z.string(),
+   message: z.string(),
+   code: z.string(),
+});
+export type ValidationError = z.infer<typeof ValidationErrorSchema>;
+
+export const ValidationResultSchema = z.object({
+   valid: z.boolean(),
+   errors: z.array(ValidationErrorSchema),
+});
+export type ValidationResult = z.infer<typeof ValidationResultSchema>;
+
+export const ValidationOptionsSchema = z.object({
+   validateConditions: z.boolean().optional(),
+   validateConsequences: z.boolean().optional(),
+   strictMode: z.boolean().optional(),
+});
+export type ValidationOptions = z.infer<typeof ValidationOptionsSchema>;
+
+// Resolved options with defaults applied
+export type ResolvedValidationOptions = {
+   validateConditions: boolean;
+   validateConsequences: boolean;
+   strictMode: boolean;
+};
+
+// ============================================================================
+// Default options (derived from schema)
+// ============================================================================
+
+const DEFAULT_OPTIONS: ValidationOptions = ValidationOptionsSchema.parse({});
+
+const createError = (
+   path: string,
+   message: string,
+   code: string,
+): ValidationError => ({
+   path,
+   message,
+   code,
+});
+
+const validResult = (): ValidationResult => ({
+   valid: true,
+   errors: [],
+});
+
+const invalidResult = (
+   errors: ReadonlyArray<ValidationError>,
+): ValidationResult => ({
+   valid: false,
+   errors: [...errors],
+});
+
+const validateConditionStructure = (
+   condition: Condition | ConditionGroup,
+   path: string,
+): ReadonlyArray<ValidationError> => {
+   const errors: ValidationError[] = [];
+
+   if (isConditionGroup(condition)) {
+      if (!condition.id || typeof condition.id !== "string") {
+         errors.push(
+            createError(
+               `${path}.id`,
+               "Condition group must have a string id",
+               "MISSING_GROUP_ID",
+            ),
+         );
+      }
+
+      if (!["AND", "OR"].includes(condition.operator)) {
+         errors.push(
+            createError(
+               `${path}.operator`,
+               `Invalid operator: ${condition.operator}. Must be "AND" or "OR"`,
+               "INVALID_GROUP_OPERATOR",
+            ),
+         );
+      }
+
+      if (!Array.isArray(condition.conditions)) {
+         errors.push(
+            createError(
+               `${path}.conditions`,
+               "Condition group must have a conditions array",
+               "MISSING_CONDITIONS_ARRAY",
+            ),
+         );
+      } else if (condition.conditions.length === 0) {
+         errors.push(
+            createError(
+               `${path}.conditions`,
+               "Condition group must have at least one condition",
+               "EMPTY_CONDITIONS_ARRAY",
+            ),
+         );
+      } else {
+         for (let i = 0; i < condition.conditions.length; i++) {
+            const nestedErrors = validateConditionStructure(
+               condition.conditions[i] as Condition | ConditionGroup,
+               `${path}.conditions[${i}]`,
+            );
+            errors.push(...nestedErrors);
+         }
+      }
+   } else {
+      if (!condition.id || typeof condition.id !== "string") {
+         errors.push(
+            createError(
+               `${path}.id`,
+               "Condition must have a string id",
+               "MISSING_CONDITION_ID",
+            ),
+         );
+      }
+
+      if (!condition.type || typeof condition.type !== "string") {
+         errors.push(
+            createError(
+               `${path}.type`,
+               "Condition must have a type",
+               "MISSING_CONDITION_TYPE",
+            ),
+         );
+      }
+
+      if (!condition.field || typeof condition.field !== "string") {
+         errors.push(
+            createError(
+               `${path}.field`,
+               "Condition must have a field",
+               "MISSING_CONDITION_FIELD",
+            ),
+         );
+      }
+
+      if (!condition.operator || typeof condition.operator !== "string") {
+         errors.push(
+            createError(
+               `${path}.operator`,
+               "Condition must have an operator",
+               "MISSING_CONDITION_OPERATOR",
+            ),
+         );
+      }
+   }
+
+   return errors;
+};
+
+const validateConsequenceStructure = <
+   TConsequences extends ConsequenceDefinitions,
+>(
+   consequences: ReadonlyArray<{ type: unknown; payload: unknown }>,
+   consequenceSchemas?: TConsequences,
+   strictMode = false,
+): ReadonlyArray<ValidationError> => {
+   const errors: ValidationError[] = [];
+
+   for (let i = 0; i < consequences.length; i++) {
+      const consequence = consequences[i];
+      if (!consequence) continue;
+      const path = `consequences[${i}]`;
+
+      if (!consequence.type || typeof consequence.type !== "string") {
+         errors.push(
+            createError(
+               `${path}.type`,
+               "Consequence must have a type",
+               "MISSING_CONSEQUENCE_TYPE",
+            ),
+         );
+         continue;
+      }
+
+      if (strictMode && consequenceSchemas) {
+         const schema = consequenceSchemas[consequence.type as string];
+         if (!schema) {
+            errors.push(
+               createError(
+                  `${path}.type`,
+                  `Unknown consequence type: ${consequence.type}`,
+                  "UNKNOWN_CONSEQUENCE_TYPE",
+               ),
+            );
+         } else {
+            const result = schema.safeParse(consequence.payload);
+            if (!result.success) {
+               for (const issue of result.error.issues) {
+                  errors.push(
+                     createError(
+                        `${path}.payload.${issue.path.join(".")}`,
+                        issue.message,
+                        "INVALID_CONSEQUENCE_PAYLOAD",
+                     ),
+                  );
+               }
+            }
+         }
+      }
+   }
+
+   return errors;
+};
+
+export const validateRule = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rule: unknown,
+   options: ValidationOptions & { consequenceSchemas?: TConsequences } = {},
+): ValidationResult => {
+   const opts = { ...DEFAULT_OPTIONS, ...options };
+   const errors: ValidationError[] = [];
+
+   const schemaResult = RuleSchema.safeParse(rule);
+   if (!schemaResult.success) {
+      for (const issue of schemaResult.error.issues) {
+         errors.push(
+            createError(
+               issue.path.join("."),
+               issue.message,
+               "SCHEMA_VALIDATION_FAILED",
+            ),
+         );
+      }
+      return invalidResult(errors);
+   }
+
+   const validRule = schemaResult.data as Rule<TContext, TConsequences>;
+
+   if (opts.validateConditions) {
+      const conditionErrors = validateConditionStructure(
+         validRule.conditions,
+         "conditions",
+      );
+      errors.push(...conditionErrors);
+   }
+
+   if (opts.validateConsequences || opts.strictMode) {
+      const consequenceErrors = validateConsequenceStructure(
+         validRule.consequences as ReadonlyArray<{
+            type: unknown;
+            payload: unknown;
+         }>,
+         opts.consequenceSchemas,
+         opts.strictMode ?? false,
+      );
+      errors.push(...consequenceErrors);
+   }
+
+   return errors.length > 0 ? invalidResult(errors) : validResult();
+};
+
+export const validateRules = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rules: ReadonlyArray<unknown>,
+   options: ValidationOptions & { consequenceSchemas?: TConsequences } = {},
+): ValidationResult => {
+   const errors: ValidationError[] = [];
+
+   for (let i = 0; i < rules.length; i++) {
+      const result = validateRule<TContext, TConsequences>(rules[i], options);
+      if (!result.valid) {
+         for (const error of result.errors) {
+            errors.push(
+               createError(
+                  `rules[${i}].${error.path}`,
+                  error.message,
+                  error.code,
+               ),
+            );
+         }
+      }
+   }
+
+   return errors.length > 0 ? invalidResult(errors) : validResult();
+};
+
+export const validateRuleSet = (ruleSet: unknown): ValidationResult => {
+   const errors: ValidationError[] = [];
+
+   const schemaResult = RuleSetSchema.safeParse(ruleSet);
+   if (!schemaResult.success) {
+      for (const issue of schemaResult.error.issues) {
+         errors.push(
+            createError(
+               issue.path.join("."),
+               issue.message,
+               "SCHEMA_VALIDATION_FAILED",
+            ),
+         );
+      }
+      return invalidResult(errors);
+   }
+
+   return validResult();
+};
+
+export const validateConditions = (
+   conditions: ConditionGroup,
+): ValidationResult => {
+   const errors = validateConditionStructure(conditions, "conditions");
+   return errors.length > 0 ? invalidResult(errors) : validResult();
+};
+
+export const parseRule = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rule: unknown,
+   options: ValidationOptions & { consequenceSchemas?: TConsequences } = {},
+): Rule<TContext, TConsequences> => {
+   const result = validateRule<TContext, TConsequences>(rule, options);
+   if (!result.valid) {
+      throw new Error(
+         `Invalid rule: ${result.errors.map((e) => e.message).join(", ")}`,
+      );
+   }
+   return rule as Rule<TContext, TConsequences>;
+};
+
+export const safeParseRule = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   rule: unknown,
+   options: ValidationOptions & { consequenceSchemas?: TConsequences } = {},
+):
+   | { success: true; data: Rule<TContext, TConsequences> }
+   | { success: false; errors: ReadonlyArray<ValidationError> } => {
+   const result = validateRule<TContext, TConsequences>(rule, options);
+   if (!result.valid) {
+      return { success: false, errors: result.errors };
+   }
+   return { success: true, data: rule as Rule<TContext, TConsequences> };
+};
+
+export const createRuleValidator = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   consequenceSchemas: TConsequences,
+   defaultOptions: ValidationOptions = {},
+) => {
+   return {
+      validate: (rule: unknown, options: ValidationOptions = {}) =>
+         validateRule<TContext, TConsequences>(rule, {
+            ...defaultOptions,
+            ...options,
+            consequenceSchemas,
+         }),
+      parse: (rule: unknown, options: ValidationOptions = {}) =>
+         parseRule<TContext, TConsequences>(rule, {
+            ...defaultOptions,
+            ...options,
+            consequenceSchemas,
+         }),
+      safeParse: (rule: unknown, options: ValidationOptions = {}) =>
+         safeParseRule<TContext, TConsequences>(rule, {
+            ...defaultOptions,
+            ...options,
+            consequenceSchemas,
+         }),
+   };
+};

package/src/versioning/version-store.ts

@@ -0,0 +1,337 @@
+import type {
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "../types/consequence";
+import type { Rule } from "../types/rule";
+import { generateId } from "../utils/id";
+
+export type RuleVersion<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly versionId: string;
+   readonly ruleId: string;
+   readonly version: number;
+   readonly rule: Rule<TContext, TConsequences>;
+   readonly createdAt: Date;
+   readonly createdBy?: string;
+   readonly comment?: string;
+   readonly changeType: "create" | "update" | "delete" | "enable" | "disable";
+};
+
+export type VersionHistory<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly ruleId: string;
+   readonly currentVersion: number;
+   readonly versions: ReadonlyArray<RuleVersion<TContext, TConsequences>>;
+};
+
+export type VersionStore<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly histories: ReadonlyMap<
+      string,
+      VersionHistory<TContext, TConsequences>
+   >;
+};
+
+export const createVersionStore = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(): VersionStore<TContext, TConsequences> => ({
+   histories: new Map(),
+});
+
+export const addVersion = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   store: VersionStore<TContext, TConsequences>,
+   rule: Rule<TContext, TConsequences>,
+   changeType: RuleVersion<TContext, TConsequences>["changeType"],
+   options: { createdBy?: string; comment?: string } = {},
+): VersionStore<TContext, TConsequences> => {
+   const histories = new Map(store.histories);
+   const existingHistory = histories.get(rule.id);
+
+   const currentVersion = existingHistory
+      ? existingHistory.currentVersion + 1
+      : 1;
+
+   const version: RuleVersion<TContext, TConsequences> = {
+      versionId: generateId(),
+      ruleId: rule.id,
+      version: currentVersion,
+      rule: { ...rule },
+      createdAt: new Date(),
+      createdBy: options.createdBy,
+      comment: options.comment,
+      changeType,
+   };
+
+   const newHistory: VersionHistory<TContext, TConsequences> = {
+      ruleId: rule.id,
+      currentVersion,
+      versions: existingHistory
+         ? [...existingHistory.versions, version]
+         : [version],
+   };
+
+   histories.set(rule.id, newHistory);
+
+   return { histories };
+};
+
+export const getHistory = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   store: VersionStore<TContext, TConsequences>,
+   ruleId: string,
+): VersionHistory<TContext, TConsequences> | undefined => {
+   return store.histories.get(ruleId);
+};
+
+export const getVersion = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   store: VersionStore<TContext, TConsequences>,
+   ruleId: string,
+   version: number,
+): RuleVersion<TContext, TConsequences> | undefined => {
+   const history = store.histories.get(ruleId);
+   if (!history) return undefined;
+   return history.versions.find((v) => v.version === version);
+};
+
+export const getLatestVersion = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   store: VersionStore<TContext, TConsequences>,
+   ruleId: string,
+): RuleVersion<TContext, TConsequences> | undefined => {
+   const history = store.histories.get(ruleId);
+   if (!history || history.versions.length === 0) return undefined;
+   return history.versions[history.versions.length - 1];
+};
+
+export const getAllVersions = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   store: VersionStore<TContext, TConsequences>,
+   ruleId: string,
+): ReadonlyArray<RuleVersion<TContext, TConsequences>> => {
+   const history = store.histories.get(ruleId);
+   return history?.versions ?? [];
+};
+
+export const rollbackToVersion = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   store: VersionStore<TContext, TConsequences>,
+   ruleId: string,
+   targetVersion: number,
+   options: { createdBy?: string; comment?: string } = {},
+): {
+   store: VersionStore<TContext, TConsequences>;
+   rule: Rule<TContext, TConsequences> | undefined;
+} => {
+   const targetVersionRecord = getVersion(store, ruleId, targetVersion);
+   if (!targetVersionRecord) {
+      return { store, rule: undefined };
+   }
+
+   const rolledBackRule: Rule<TContext, TConsequences> = {
+      ...targetVersionRecord.rule,
+      updatedAt: new Date(),
+   };
+
+   const newStore = addVersion(store, rolledBackRule, "update", {
+      createdBy: options.createdBy,
+      comment: options.comment ?? `Rollback to version ${targetVersion}`,
+   });
+
+   return { store: newStore, rule: rolledBackRule };
+};
+
+export const compareVersions = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   store: VersionStore<TContext, TConsequences>,
+   ruleId: string,
+   version1: number,
+   version2: number,
+): {
+   version1: RuleVersion<TContext, TConsequences> | undefined;
+   version2: RuleVersion<TContext, TConsequences> | undefined;
+   differences: ReadonlyArray<{
+      field: string;
+      oldValue: unknown;
+      newValue: unknown;
+   }>;
+} | null => {
+   const v1 = getVersion(store, ruleId, version1);
+   const v2 = getVersion(store, ruleId, version2);
+
+   if (!v1 || !v2) {
+      return null;
+   }
+
+   const differences: Array<{
+      field: string;
+      oldValue: unknown;
+      newValue: unknown;
+   }> = [];
+
+   const compareFields = [
+      "name",
+      "description",
+      "priority",
+      "enabled",
+      "stopOnMatch",
+      "category",
+   ] as const;
+
+   for (const field of compareFields) {
+      const oldValue = v1.rule[field];
+      const newValue = v2.rule[field];
+      if (JSON.stringify(oldValue) !== JSON.stringify(newValue)) {
+         differences.push({ field, oldValue, newValue });
+      }
+   }
+
+   if (
+      JSON.stringify(v1.rule.conditions) !== JSON.stringify(v2.rule.conditions)
+   ) {
+      differences.push({
+         field: "conditions",
+         oldValue: v1.rule.conditions,
+         newValue: v2.rule.conditions,
+      });
+   }
+
+   if (
+      JSON.stringify(v1.rule.consequences) !==
+      JSON.stringify(v2.rule.consequences)
+   ) {
+      differences.push({
+         field: "consequences",
+         oldValue: v1.rule.consequences,
+         newValue: v2.rule.consequences,
+      });
+   }
+
+   if (JSON.stringify(v1.rule.tags) !== JSON.stringify(v2.rule.tags)) {
+      differences.push({
+         field: "tags",
+         oldValue: v1.rule.tags,
+         newValue: v2.rule.tags,
+      });
+   }
+
+   return { version1: v1, version2: v2, differences };
+};
+
+export const getVersionsByDateRange = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   store: VersionStore<TContext, TConsequences>,
+   startDate: Date,
+   endDate: Date,
+): ReadonlyArray<RuleVersion<TContext, TConsequences>> => {
+   const versions: RuleVersion<TContext, TConsequences>[] = [];
+
+   for (const history of store.histories.values()) {
+      for (const version of history.versions) {
+         if (version.createdAt >= startDate && version.createdAt <= endDate) {
+            versions.push(version);
+         }
+      }
+   }
+
+   return versions.sort(
+      (a, b) => a.createdAt.getTime() - b.createdAt.getTime(),
+   );
+};
+
+export const getVersionsByChangeType = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   store: VersionStore<TContext, TConsequences>,
+   changeType: RuleVersion<TContext, TConsequences>["changeType"],
+): ReadonlyArray<RuleVersion<TContext, TConsequences>> => {
+   const versions: RuleVersion<TContext, TConsequences>[] = [];
+
+   for (const history of store.histories.values()) {
+      for (const version of history.versions) {
+         if (version.changeType === changeType) {
+            versions.push(version);
+         }
+      }
+   }
+
+   return versions;
+};
+
+export const pruneOldVersions = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   store: VersionStore<TContext, TConsequences>,
+   keepCount: number,
+): VersionStore<TContext, TConsequences> => {
+   const histories = new Map<string, VersionHistory<TContext, TConsequences>>();
+
+   for (const [ruleId, history] of store.histories) {
+      const prunedVersions =
+         history.versions.length > keepCount
+            ? history.versions.slice(-keepCount)
+            : history.versions;
+
+      histories.set(ruleId, {
+         ruleId,
+         currentVersion: history.currentVersion,
+         versions: prunedVersions,
+      });
+   }
+
+   return { histories };
+};
+
+export const formatVersionHistory = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   history: VersionHistory<TContext, TConsequences>,
+): string => {
+   const lines: string[] = [
+      `=== Version History for Rule: ${history.ruleId} ===`,
+      `Current Version: ${history.currentVersion}`,
+      `Total Versions: ${history.versions.length}`,
+      "",
+   ];
+
+   for (const version of history.versions) {
+      lines.push(
+         `v${version.version} - ${version.changeType} (${version.createdAt.toISOString()})`,
+      );
+      if (version.createdBy) {
+         lines.push(`  By: ${version.createdBy}`);
+      }
+      if (version.comment) {
+         lines.push(`  Comment: ${version.comment}`);
+      }
+   }
+
+   return lines.join("\n");
+};