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

package/src/builder/conditions.ts

@@ -0,0 +1,321 @@
+import type { Condition, ConditionGroup } from "@f-o-t/condition-evaluator";
+
+export type ConditionBuilderState = {
+   readonly conditions: (Condition | ConditionGroup)[];
+};
+
+export type ConditionBuilder = {
+   readonly number: (
+      field: string,
+      operator: "gt" | "gte" | "lt" | "lte" | "eq" | "neq",
+      value: number,
+   ) => ConditionBuilder;
+
+   readonly string: (
+      field: string,
+      operator:
+         | "eq"
+         | "neq"
+         | "contains"
+         | "not_contains"
+         | "starts_with"
+         | "ends_with"
+         | "in"
+         | "not_in"
+         | "like"
+         | "not_like"
+         | "ilike"
+         | "not_ilike"
+         | "regex"
+         | "not_regex",
+      value: string | string[],
+   ) => ConditionBuilder;
+
+   readonly boolean: (
+      field: string,
+      operator: "eq" | "neq",
+      value: boolean,
+   ) => ConditionBuilder;
+
+   readonly date: (
+      field: string,
+      operator: "gt" | "gte" | "lt" | "lte" | "eq" | "neq" | "between",
+      value: string | Date | [string | Date, string | Date],
+   ) => ConditionBuilder;
+
+   readonly array: (
+      field: string,
+      operator:
+         | "contains"
+         | "not_contains"
+         | "contains_all"
+         | "contains_any"
+         | "is_empty"
+         | "is_not_empty"
+         | "length_eq"
+         | "length_gt"
+         | "length_lt",
+      value: unknown,
+   ) => ConditionBuilder;
+
+   readonly ref: (
+      field: string,
+      operator: string,
+      valueRef: string,
+   ) => ConditionBuilder;
+
+   readonly and: (
+      builder: (cb: ConditionBuilder) => ConditionBuilder,
+   ) => ConditionBuilder;
+
+   readonly or: (
+      builder: (cb: ConditionBuilder) => ConditionBuilder,
+   ) => ConditionBuilder;
+
+   readonly raw: (condition: Condition | ConditionGroup) => ConditionBuilder;
+
+   readonly build: () => ConditionGroup;
+
+   readonly getConditions: () => ReadonlyArray<Condition | ConditionGroup>;
+};
+
+let conditionIdCounter = 0;
+let groupIdCounter = 0;
+
+const generateConditionId = (): string => `cond-${++conditionIdCounter}`;
+const generateGroupId = (): string => `group-${++groupIdCounter}`;
+
+export const resetBuilderIds = (): void => {
+   conditionIdCounter = 0;
+   groupIdCounter = 0;
+};
+
+const createConditionBuilder = (
+   state: ConditionBuilderState = { conditions: [] },
+   operator: "AND" | "OR" = "AND",
+): ConditionBuilder => {
+   const addCondition = (
+      condition: Condition | ConditionGroup,
+   ): ConditionBuilder => {
+      return createConditionBuilder(
+         { conditions: [...state.conditions, condition] },
+         operator,
+      );
+   };
+
+   return {
+      number: (field, op, value) =>
+         addCondition({
+            id: generateConditionId(),
+            type: "number",
+            field,
+            operator: op,
+            value,
+         }),
+
+      string: (field, op, value) =>
+         addCondition({
+            id: generateConditionId(),
+            type: "string",
+            field,
+            operator: op,
+            value: value as string,
+         } as Condition),
+
+      boolean: (field, op, value) =>
+         addCondition({
+            id: generateConditionId(),
+            type: "boolean",
+            field,
+            operator: op,
+            value,
+         }),
+
+      date: (field, op, value) => {
+         const normalizedValue =
+            value instanceof Date
+               ? value.toISOString()
+               : Array.isArray(value)
+                 ? value.map((v) => (v instanceof Date ? v.toISOString() : v))
+                 : value;
+
+         return addCondition({
+            id: generateConditionId(),
+            type: "date",
+            field,
+            operator: op,
+            value: normalizedValue as string,
+         } as Condition);
+      },
+
+      array: (field, op, value) =>
+         addCondition({
+            id: generateConditionId(),
+            type: "array",
+            field,
+            operator: op,
+            value,
+         } as Condition),
+
+      ref: (field, op, valueRef) =>
+         addCondition({
+            id: generateConditionId(),
+            type: "number",
+            field,
+            operator: op,
+            valueRef,
+         } as Condition),
+
+      and: (builderFn) => {
+         const nestedBuilder = createConditionBuilder(
+            { conditions: [] },
+            "AND",
+         );
+         const result = builderFn(nestedBuilder);
+         return addCondition(result.build());
+      },
+
+      or: (builderFn) => {
+         const nestedBuilder = createConditionBuilder({ conditions: [] }, "OR");
+         const result = builderFn(nestedBuilder);
+         return addCondition(result.build());
+      },
+
+      raw: (condition) => addCondition(condition),
+
+      build: (): ConditionGroup => ({
+         id: generateGroupId(),
+         operator,
+         conditions: state.conditions,
+      }),
+
+      getConditions: () => state.conditions,
+   };
+};
+
+export const conditions = (): ConditionBuilder =>
+   createConditionBuilder({ conditions: [] }, "AND");
+
+export const and = (
+   builderFn: (cb: ConditionBuilder) => ConditionBuilder,
+): ConditionGroup => {
+   const builder = createConditionBuilder({ conditions: [] }, "AND");
+   return builderFn(builder).build();
+};
+
+export const or = (
+   builderFn: (cb: ConditionBuilder) => ConditionBuilder,
+): ConditionGroup => {
+   const builder = createConditionBuilder({ conditions: [] }, "OR");
+   return builderFn(builder).build();
+};
+
+export const all = (
+   ...items: (Condition | ConditionGroup)[]
+): ConditionGroup => ({
+   id: generateGroupId(),
+   operator: "AND",
+   conditions: items,
+});
+
+export const any = (
+   ...items: (Condition | ConditionGroup)[]
+): ConditionGroup => ({
+   id: generateGroupId(),
+   operator: "OR",
+   conditions: items,
+});
+
+export const num = (
+   field: string,
+   operator: "gt" | "gte" | "lt" | "lte" | "eq" | "neq",
+   value: number,
+): Condition => ({
+   id: generateConditionId(),
+   type: "number",
+   field,
+   operator,
+   value,
+});
+
+export const str = (
+   field: string,
+   operator:
+      | "eq"
+      | "neq"
+      | "contains"
+      | "not_contains"
+      | "starts_with"
+      | "ends_with"
+      | "in"
+      | "not_in"
+      | "like"
+      | "not_like"
+      | "ilike"
+      | "not_ilike"
+      | "regex"
+      | "not_regex",
+   value: string | string[],
+): Condition =>
+   ({
+      id: generateConditionId(),
+      type: "string",
+      field,
+      operator,
+      value,
+   }) as Condition;
+
+export const bool = (
+   field: string,
+   operator: "eq" | "neq",
+   value: boolean,
+): Condition => ({
+   id: generateConditionId(),
+   type: "boolean",
+   field,
+   operator,
+   value,
+});
+
+export const date = (
+   field: string,
+   operator: "gt" | "gte" | "lt" | "lte" | "eq" | "neq" | "between",
+   value: string | Date | [string | Date, string | Date],
+): Condition => {
+   const normalizedValue =
+      value instanceof Date
+         ? value.toISOString()
+         : Array.isArray(value)
+           ? value.map((v) => (v instanceof Date ? v.toISOString() : v))
+           : value;
+
+   return {
+      id: generateConditionId(),
+      type: "date",
+      field,
+      operator,
+      value: normalizedValue as string,
+   } as Condition;
+};
+
+export const arr = (
+   field: string,
+   operator:
+      | "contains"
+      | "not_contains"
+      | "contains_all"
+      | "contains_any"
+      | "is_empty"
+      | "is_not_empty"
+      | "length_eq"
+      | "length_gt"
+      | "length_lt",
+   value?: unknown,
+): Condition =>
+   ({
+      id: generateConditionId(),
+      type: "array",
+      field,
+      operator,
+      value,
+   }) as Condition;

package/src/builder/rule.ts

@@ -0,0 +1,192 @@
+import type { ConditionGroup } from "@f-o-t/condition-evaluator";
+import type { z } from "zod";
+import type {
+   ConsequenceDefinitions,
+   DefaultConsequences,
+} from "../types/consequence";
+import type { RuleInput } from "../types/rule";
+import {
+   type ConditionBuilder,
+   conditions as createConditions,
+} from "./conditions";
+
+export type RuleBuilderState<
+   _TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly id?: string;
+   readonly name?: string;
+   readonly description?: string;
+   readonly conditions?: ConditionGroup;
+   readonly consequences: Array<{
+      type: keyof TConsequences;
+      payload: z.infer<TConsequences[keyof TConsequences]>;
+   }>;
+   readonly priority: number;
+   readonly enabled: boolean;
+   readonly stopOnMatch: boolean;
+   readonly tags: string[];
+   readonly category?: string;
+   readonly metadata?: Record<string, unknown>;
+};
+
+export type RuleBuilder<
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+> = {
+   readonly id: (id: string) => RuleBuilder<TContext, TConsequences>;
+
+   readonly named: (name: string) => RuleBuilder<TContext, TConsequences>;
+
+   readonly describedAs: (
+      description: string,
+   ) => RuleBuilder<TContext, TConsequences>;
+
+   readonly when: (
+      conditions: ConditionGroup | ((cb: ConditionBuilder) => ConditionBuilder),
+   ) => RuleBuilder<TContext, TConsequences>;
+
+   readonly then: <K extends keyof TConsequences>(
+      type: K,
+      payload: z.infer<TConsequences[K]>,
+   ) => RuleBuilder<TContext, TConsequences>;
+
+   readonly withPriority: (
+      priority: number,
+   ) => RuleBuilder<TContext, TConsequences>;
+
+   readonly enabled: (
+      enabled?: boolean,
+   ) => RuleBuilder<TContext, TConsequences>;
+
+   readonly disabled: () => RuleBuilder<TContext, TConsequences>;
+
+   readonly stopOnMatch: (
+      stop?: boolean,
+   ) => RuleBuilder<TContext, TConsequences>;
+
+   readonly tagged: (...tags: string[]) => RuleBuilder<TContext, TConsequences>;
+
+   readonly inCategory: (
+      category: string,
+   ) => RuleBuilder<TContext, TConsequences>;
+
+   readonly withMetadata: (
+      metadata: Record<string, unknown>,
+   ) => RuleBuilder<TContext, TConsequences>;
+
+   readonly build: () => RuleInput<TContext, TConsequences>;
+
+   readonly getState: () => RuleBuilderState<TContext, TConsequences>;
+};
+
+const createRuleBuilder = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   state: RuleBuilderState<TContext, TConsequences> = {
+      consequences: [],
+      priority: 0,
+      enabled: true,
+      stopOnMatch: false,
+      tags: [],
+   },
+): RuleBuilder<TContext, TConsequences> => {
+   const update = (
+      updates: Partial<RuleBuilderState<TContext, TConsequences>>,
+   ): RuleBuilder<TContext, TConsequences> => {
+      return createRuleBuilder({ ...state, ...updates });
+   };
+
+   return {
+      id: (id) => update({ id }),
+
+      named: (name) => update({ name }),
+
+      describedAs: (description) => update({ description }),
+
+      when: (conditionsOrBuilder) => {
+         if (typeof conditionsOrBuilder === "function") {
+            const builder = createConditions();
+            const result = conditionsOrBuilder(builder);
+            return update({ conditions: result.build() });
+         }
+         return update({ conditions: conditionsOrBuilder });
+      },
+
+      // biome-ignore lint/suspicious/noThenProperty: Intentional fluent API method for rule builder (when().then())
+      then: (type, payload) => {
+         return update({
+            consequences: [
+               ...state.consequences,
+               { type, payload } as {
+                  type: keyof TConsequences;
+                  payload: z.infer<TConsequences[keyof TConsequences]>;
+               },
+            ],
+         });
+      },
+
+      withPriority: (priority) => update({ priority }),
+
+      enabled: (enabled = true) => update({ enabled }),
+
+      disabled: () => update({ enabled: false }),
+
+      stopOnMatch: (stop = true) => update({ stopOnMatch: stop }),
+
+      tagged: (...tags) => update({ tags: [...state.tags, ...tags] }),
+
+      inCategory: (category) => update({ category }),
+
+      withMetadata: (metadata) =>
+         update({ metadata: { ...state.metadata, ...metadata } }),
+
+      build: (): RuleInput<TContext, TConsequences> => {
+         if (!state.name) {
+            throw new Error("Rule must have a name");
+         }
+         if (!state.conditions) {
+            throw new Error("Rule must have conditions");
+         }
+         if (state.consequences.length === 0) {
+            throw new Error("Rule must have at least one consequence");
+         }
+
+         return {
+            id: state.id,
+            name: state.name,
+            description: state.description,
+            conditions: state.conditions,
+            consequences: state.consequences,
+            priority: state.priority,
+            enabled: state.enabled,
+            stopOnMatch: state.stopOnMatch,
+            tags: state.tags,
+            category: state.category,
+            metadata: state.metadata,
+         };
+      },
+
+      getState: () => state,
+   };
+};
+
+export const rule = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(): RuleBuilder<TContext, TConsequences> => {
+   return createRuleBuilder<TContext, TConsequences>();
+};
+
+export const createRule = <
+   TContext = unknown,
+   TConsequences extends ConsequenceDefinitions = DefaultConsequences,
+>(
+   builderFn: (
+      rb: RuleBuilder<TContext, TConsequences>,
+   ) => RuleBuilder<TContext, TConsequences>,
+): RuleInput<TContext, TConsequences> => {
+   const builder = createRuleBuilder<TContext, TConsequences>();
+   return builderFn(builder).build();
+};

package/src/cache/cache.ts

@@ -0,0 +1,135 @@
+import type { CacheStats } from "../types/state";
+
+export type CacheEntry<T> = {
+   value: T;
+   expiresAt: number;
+   createdAt: number;
+};
+
+export type Cache<T> = {
+   readonly get: (key: string) => T | undefined;
+   readonly set: (key: string, value: T) => void;
+   readonly has: (key: string) => boolean;
+   readonly delete: (key: string) => boolean;
+   readonly clear: () => void;
+   readonly getStats: () => CacheStats;
+};
+
+export type CacheOptions = {
+   readonly ttl: number;
+   readonly maxSize: number;
+   readonly onEvict?: (key: string, value: unknown) => void;
+};
+
+export const createCache = <T>(options: CacheOptions): Cache<T> => {
+   const entries = new Map<string, CacheEntry<T>>();
+   let hits = 0;
+   let misses = 0;
+   let evictions = 0;
+
+   const isExpired = (entry: CacheEntry<T>): boolean => {
+      return Date.now() > entry.expiresAt;
+   };
+
+   const evictExpired = (): void => {
+      const now = Date.now();
+      for (const [key, entry] of entries) {
+         if (now > entry.expiresAt) {
+            entries.delete(key);
+            evictions++;
+            options.onEvict?.(key, entry.value);
+         }
+      }
+   };
+
+   const evictOldest = (): void => {
+      if (entries.size === 0) return;
+
+      // ES6 Maps maintain insertion order - first key is oldest (O(1) lookup)
+      const oldestKey = entries.keys().next().value;
+      if (oldestKey !== undefined) {
+         const entry = entries.get(oldestKey);
+         entries.delete(oldestKey);
+         evictions++;
+         if (entry) {
+            options.onEvict?.(oldestKey, entry.value);
+         }
+      }
+   };
+
+   const get = (key: string): T | undefined => {
+      const entry = entries.get(key);
+
+      if (!entry) {
+         misses++;
+         return undefined;
+      }
+
+      if (isExpired(entry)) {
+         entries.delete(key);
+         evictions++;
+         options.onEvict?.(key, entry.value);
+         misses++;
+         return undefined;
+      }
+
+      hits++;
+      return entry.value;
+   };
+
+   const set = (key: string, value: T): void => {
+      evictExpired();
+
+      while (entries.size >= options.maxSize) {
+         evictOldest();
+      }
+
+      const now = Date.now();
+      entries.set(key, {
+         value,
+         expiresAt: now + options.ttl,
+         createdAt: now,
+      });
+   };
+
+   const has = (key: string): boolean => {
+      const entry = entries.get(key);
+      if (!entry) return false;
+      if (isExpired(entry)) {
+         entries.delete(key);
+         evictions++;
+         options.onEvict?.(key, entry.value);
+         return false;
+      }
+      return true;
+   };
+
+   const deleteEntry = (key: string): boolean => {
+      return entries.delete(key);
+   };
+
+   const clear = (): void => {
+      entries.clear();
+   };
+
+   const getStats = (): CacheStats => {
+      const totalRequests = hits + misses;
+      return {
+         size: entries.size,
+         maxSize: options.maxSize,
+         hits,
+         misses,
+         hitRate: totalRequests > 0 ? hits / totalRequests : 0,
+         evictions,
+      };
+   };
+
+   return {
+      get,
+      set,
+      has,
+      delete: deleteEntry,
+      clear,
+      getStats,
+   };
+};

package/src/cache/noop.ts

@@ -0,0 +1,20 @@
+import type { CacheStats } from "../types/state";
+import type { Cache } from "./cache";
+
+export const createNoopCache = <T>(): Cache<T> => {
+   return {
+      get: () => undefined,
+      set: () => {},
+      has: () => false,
+      delete: () => false,
+      clear: () => {},
+      getStats: (): CacheStats => ({
+         size: 0,
+         maxSize: 0,
+         hits: 0,
+         misses: 0,
+         hitRate: 0,
+         evictions: 0,
+      }),
+   };
+};