Feat: Type-safety using a FactTypeMapping

export interface EngineOptions {
  allowUndefinedFacts?: boolean;
  allowUndefinedConditions?: boolean;
  pathResolver?: PathResolver;
}

export interface EngineResult<FactTypeDictionary> {
  events: Event[];
  failureEvents: Event[];
  almanac: Almanac<FactTypeDictionary>;
  results: RuleResult[];
  failureResults: RuleResult[];
}

export default function engineFactory<
  FactTypeDictionary extends Record<string, any> = {}
>(
  rules: Array<RuleProperties<FactTypeDictionary>>,
  options?: EngineOptions
): Engine<FactTypeDictionary>;

// This helper gives us optionality. If the key is in the dictionary, then we return the type,
// otherwise we return the default type which is unknown (unless the user specifies it on the call itself)
type FactReturn<
  Dictionary,
  Key,
  Default = unknown
> = Key extends keyof Dictionary ? Dictionary[Key] : Default;

export class Engine<FactTypeDictionary extends Record<string, any> = {}> {
  constructor(
    rules?: Array<RuleProperties<FactTypeDictionary>>,
    options?: EngineOptions
  );

  addRule(rule: RuleProperties<FactTypeDictionary>): this;
  removeRule(ruleOrName: Rule | string): boolean;
  updateRule(rule: Rule): void;

  setCondition(name: string, conditions: TopLevelCondition): this;
  removeCondition(name: string): boolean;

  addOperator(operator: Operator): Map<string, Operator>;
  addOperator<A, B>(
    operatorName: string,
    callback: OperatorEvaluator<A, B>
  ): Map<string, Operator>;
  removeOperator(operator: Operator | string): boolean;

  addFact<T>(fact: Fact<T>): this;
  addFact<DefaultValueType, Key extends string>(
    id: Key,
    valueCallback:
      | DynamicFactCallback<
          FactReturn<FactTypeDictionary, Key, DefaultValueType>,
          FactTypeDictionary
        >
      | FactReturn<FactTypeDictionary, Key, DefaultValueType>,
    options?: FactOptions
  ): this;
  removeFact(factOrId: string | Fact<any>): boolean;
  getFact<Key extends string>(
    factId: Key
  ): Fact<FactReturn<FactTypeDictionary, Key>, FactTypeDictionary>;

  on(eventName: "success", handler: EventHandler<FactTypeDictionary>): this;
  on(eventName: "failure", handler: EventHandler<FactTypeDictionary>): this;
  on(eventName: string, handler: EventHandler<FactTypeDictionary>): this;

  // TODO: This run keyset should optionally reference the types from FactTypeDictionary
  run(facts?: Record<string, any>): Promise<EngineResult<FactTypeDictionary>>;
  stop(): this;
}

export interface OperatorEvaluator<A, B> {
  (factValue: A, compareToValue: B): boolean;
}

export class Operator<A = unknown, B = unknown> {
  public name: string;
  constructor(
    name: string,
    evaluator: OperatorEvaluator<A, B>,
    validator?: (factValue: A) => boolean
  );
}

export class Almanac<FactTypeDictionary> {
  // If a path is passed, then we don't have a good way to know the type anymore so we return unknown
  factValue<Key extends string, Path>(
    factId: Key,
    params?: Record<string, any>,
    path?: Path
  ): Promise<
    Path extends string ? unknown : FactReturn<FactTypeDictionary, Key>
  >;
  addRuntimeFact<Key extends string>(
    factId: Key,
    value: FactReturn<FactTypeDictionary, Key, any>
  ): void;
}

export type FactOptions = {
  cache?: boolean;
  priority?: number;
};

export type DynamicFactCallback<T, FactTypeDictionary> = (
  params: Record<string, any>,
  almanac: Almanac<FactTypeDictionary>
) => T;

export class Fact<T = unknown, FactTypeDictionary = {}> {
  id: string;
  priority: number;
  options: FactOptions;
  value?: T;
  calculationMethod?: DynamicFactCallback<T, FactTypeDictionary>;

  constructor(
    id: string,
    value: T | DynamicFactCallback<T, FactTypeDictionary>,
    options?: FactOptions
  );
}

export interface Event {
  type: string;
  params?: Record<string, any>;
}

export type PathResolver = (value: object, path: string) => any;

export type EventHandler<FactTypeDictionary> = (
  event: Event,
  almanac: Almanac<FactTypeDictionary>,
  ruleResult: RuleResult
) => void;

export interface RuleProperties<FactTypeDictionary = {}> {
  conditions: TopLevelCondition;
  event: Event;
  name?: string;
  priority?: number;
  onSuccess?: EventHandler<FactTypeDictionary>;
  onFailure?: EventHandler<FactTypeDictionary>;
}
export type RuleSerializable = Pick<
  Required<RuleProperties<any>>,
  "conditions" | "event" | "name" | "priority"
>;

export interface RuleResult {
  name: string;
  conditions: TopLevelCondition;
  event?: Event;
  priority?: number;
  result: any;
}

// Something like a rule could be constructed outside of the context of an engine.
// For simplicity, we just default it to an empty dictionary since often the types won't come up in the rule definition
// (basically only if you were to attach an event, AND reference factValue from the almanac)
export class Rule<FactTypeDictionary extends Record<string, any> = {}>
  implements RuleProperties<FactTypeDictionary>
{
  constructor(ruleProps: RuleProperties<FactTypeDictionary> | string);
  name: string;
  conditions: TopLevelCondition;
  event: Event;
  priority: number;
  setConditions(conditions: TopLevelCondition): this;
  setEvent(event: Event): this;
  setPriority(priority: number): this;
  toJSON(): string;
  toJSON<T extends boolean>(
    stringify: T
  ): T extends true ? string : RuleSerializable;
}

interface ConditionProperties {
  fact: string;
  operator: string;
  value: { fact: string } | any;
  path?: string;
  priority?: number;
  params?: Record<string, any>;
  name?: string;
}

type NestedCondition = ConditionProperties | TopLevelCondition;
type AllConditions = {
  all: NestedCondition[];
  name?: string;
  priority?: number;
};
type AnyConditions = {
  any: NestedCondition[];
  name?: string;
  priority?: number;
};
type NotConditions = { not: NestedCondition; name?: string; priority?: number };
type ConditionReference = {
  condition: string;
  name?: string;
  priority?: number;
};
export type TopLevelCondition =
  | AllConditions
  | AnyConditions
  | NotConditions
  | ConditionReference;