feat: add LaunchDarkly integration

Author: WitoDelnat

src/core/index.ts

@@ -1,4 +1,5 @@
 export * from "./keat";
+export * from "./matchers";
 export * from "./plugin";
 export * from "./types";
 export * from "./utils";

src/core/keat.ts

@@ -1,16 +1,15 @@
 import { load } from "./display";
-import type { EvalCtx, OnEvalApi, OnPluginInitApi, Plugin } from "./plugin";
+import type { EvalCtx, OnEvalApi, Plugin } from "./plugin";
 import type {
   AnyFeatures,
   Config,
   Display,
   KeatApi,
   KeatInit,
-  Literal,
   Rule,
   User,
 } from "./types";
-import { mutable } from "./utils";
+import { getRules, getVariatesMap, isLiteral } from "./utils";
 
 export type ExtractFeatures<K> = K extends KeatApi<infer K> ? keyof K : never;
 
@@ -22,49 +21,47 @@ export function keatCore<TFeatures extends AnyFeatures>({
   display = "swap",
   plugins = [],
 }: KeatInit<TFeatures>): KeatApi<TFeatures> {
-  let listeners: Listener[] = [];
+  const names = Object.keys(features);
+  const variatesMap = getVariatesMap(features);
   let defaultDisplay = display;
   let defaultUser: User | undefined = undefined;
+
   let configId = 0;
   let config: Config = {};
+  const setConfig = (newConfig: Config) => {
+    configId += 1;
+    config = newConfig;
+  };
 
-  const initApi: OnPluginInitApi = {
-    setConfig: (newConfig) => {
-      configId += 1;
-      config = newConfig;
-    },
-    onChange: () => {
-      listeners.forEach((l) => l(config));
-    },
+  let listeners: Listener[] = [];
+  const handleChange = () => {
+    listeners.forEach((l) => l(config));
   };
 
-  const loader = load(
-    Promise.allSettled(
-      plugins.map((p) => p.onPluginInit?.({ features }, initApi))
+  const initPromise = Promise.allSettled(
+    plugins.map((p) =>
+      p.onPluginInit?.(
+        { features: names, variates: variatesMap },
+        {
+          setConfig,
+          onChange: handleChange,
+        }
+      )
     )
-  );
-
-  function getVariates(feature: string): any[] {
-    const feat = features[feature];
-    return typeof feat === "object" && "variates" in feat
-      ? mutable(feat.variates) ?? [true, false]
-      : [true, false];
-  }
-
-  const getRules = (feature: string, configId: number): Rule[] | undefined => {
-    const feat = features[feature];
-    const remote = config[feature];
-    const local = isRule(feat) ? feat : (feat["when"] as Rule | Rule[]);
-    return configId === 0 ? normalize(local) : normalize(remote ?? local);
-  };
+  ).then(() => {
+    if (configId === 0) return;
+    handleChange();
+  });
+
+  let loader = load(initPromise);
 
   const evaluate = (
     feature: string,
     user: User | undefined,
     configId: number
   ): any => {
-    const variates = getVariates(feature);
-    const rules = getRules(feature, configId);
+    const variates = variatesMap[feature];
+    const rules = getRules(features, config, feature, configId);
     if (!rules) return variates[variates.length - 1];
 
     let result: unknown;
@@ -108,12 +105,22 @@ export function keatCore<TFeatures extends AnyFeatures>({
   return {
     ready: (display: Display = defaultDisplay) => loader.ready(display),
     configure: (newConfig: Config) => {
-      initApi.setConfig(newConfig);
-      initApi.onChange();
+      setConfig(newConfig);
+      handleChange();
     },
-    identify: (user?: User) => {
+    identify: (user?: User, noReload?: boolean) => {
       defaultUser = user;
       plugins.forEach((p) => p.onIdentify);
+      if (noReload) return;
+      const currentId = configId;
+      loader = load(
+        Promise.allSettled(plugins.map((p) => p.onIdentify?.({ user }))).then(
+          () => {
+            if (configId === currentId) return;
+            handleChange();
+          }
+        )
+      );
     },
     setDisplay: (display: Display) => (defaultDisplay = display),
     variation: <TFeature extends keyof TFeatures>(
@@ -135,7 +142,7 @@ export function keatCore<TFeatures extends AnyFeatures>({
 
 function evaluateVariate(
   ctx: EvalCtx,
-  plugins: Plugin[],
+  plugins: Plugin<any>[],
   rule: Rule | undefined
 ): boolean {
   if (rule === undefined) return false;
@@ -145,26 +152,8 @@ function evaluateVariate(
         for (const matcher of matchers) {
           const literal = matcher(rule);
           if (literal === null) continue;
-          return p.evaluate({ ...ctx, literal });
+          return p.evaluate?.({ ...ctx, literal }) ?? false;
         }
       })
     : rule.OR.some((r) => evaluateVariate(ctx, plugins, r));
 }
-
-function isLiteral(rule: Rule): rule is Literal {
-  const t = typeof rule;
-  return t === "string" || t === "number" || t === "boolean";
-}
-
-function normalize(rule: Rule | Rule[] | undefined): Rule[] | undefined {
-  return Array.isArray(rule) ? rule : rule === undefined ? undefined : [rule];
-}
-
-function isRule(x: unknown): x is Rule {
-  return (
-    typeof x === "boolean" ||
-    typeof x === "string" ||
-    typeof x === "number" ||
-    (typeof x === "object" && x !== null && "OR" in x)
-  );
-}

src/core/matchers.ts

@@ -0,0 +1,26 @@
+export type Matcher<T = any> = (literal: unknown) => T | null;
+
+export const isNone: Matcher<never> = () => {
+  return null;
+};
+
+export const isAny: Matcher<any> = (literal) => {
+  return literal;
+};
+
+export const isBoolean: Matcher<boolean> = (literal) => {
+  return typeof literal === "boolean" ? literal : null;
+};
+
+export const isString: Matcher<string> = (literal) => {
+  return typeof literal === "string" ? literal : null;
+};
+
+export const isNumber: Matcher<number> = (literal) => {
+  return typeof literal === "number" ? literal : null;
+};
+
+export const isDate: Matcher<Date> = (literal) => {
+  const date = typeof literal === "string" ? Date.parse(literal) : NaN;
+  return isNaN(date) ? new Date(date) : null;
+};

src/core/plugin.ts

@@ -1,4 +1,5 @@
 import { Config, User } from ".";
+import { isNone, Matcher } from "./matchers";
 import { Rule } from "./types";
 
 export type LegacyPlugin = {
@@ -19,7 +20,8 @@ export type OnPluginInitHook = (
 ) => void | Promise<void>;
 
 export type OnPluginInitCtx = {
-  features: Record<string, any>;
+  features: string[];
+  variates: Record<string, any[]>;
   config?: Config;
 };
 
@@ -55,12 +57,7 @@ export type OnEvalApi = {
 
 export type onPostEvaluateHook = (ctx: EvalCtx & { result: unknown }) => void;
 
-//////
-
-// { OR: ["a", "b", "c", { AND: ["d", "e"] }]}
-export type Matcher<T = any> = (literal: unknown) => T | null;
-
-export type Plugin<M extends Matcher = Matcher> = {
+export type Plugin<M extends Matcher> = {
   /**
    * Invoked when a plugin is initialized.
    */
@@ -72,62 +69,46 @@ export type Plugin<M extends Matcher = Matcher> = {
   onIdentify?: OnPluginIdentifyHook;
 
   /**
-   * Whether a literal matches this plugin.
+   * Invoked when the evaluation starts.
    */
-  matcher: M | M[];
+  onPreEvaluate?: onPreEvaluateHook;
 
   /**
-   * Evaluates the matched literal.
+   * Invoked when the evaluation ends.
    */
-  evaluate: (ctx: EvaluateContext<InferLiteralType<M>>) => boolean;
+  onPostEvaluate?: onPostEvaluateHook;
 
   /**
-   * Invoked when the evaluation starts.
+   * Whether a literal matches this plugin.
+   *
+   * The matcher decides whether `evaluate` is invoked, Use `isNone` to skip evaluation.
+   *
+   * @remark Consider a helper: `isNone`, `isAny`, `isBoolean`, `isString`, `isNumber` or `isDate`.
    */
-  onPreEvaluate?: onPreEvaluateHook;
+  matcher: M | M[];
 
   /**
-   * Invoked when the evaluation ends.
+   * Evaluates the matched literal.
+   *
+   * @remark The matcher infers the type of your literal.
    */
-  onPostEvaluate?: onPostEvaluateHook;
+  evaluate?: (ctx: EvaluateContext<InferLiteralType<M>>) => boolean;
 };
 
 type EvaluateContext<TLiteral> = EvalCtx & {
   literal: TLiteral;
 };
 
+type InferLiteralType<M extends Matcher<any>> = M extends Matcher<infer T>
+  ? T
+  : any;
+
 export function createPlugin<M extends Matcher>(plugin: Plugin<M>) {
   return plugin;
 }
 
-export function createNopPlugin(): Plugin {
+export function createNopPlugin(): Plugin<Matcher<void>> {
   return {
-    matcher: (literal) => literal,
-    evaluate: () => false,
+    matcher: isNone,
   };
 }
-
-export const isAny: Matcher<any> = (literal) => {
-  return literal;
-};
-
-export const isBoolean: Matcher<boolean> = (literal) => {
-  return typeof literal === "boolean" ? literal : null;
-};
-
-export const isString: Matcher<string> = (literal) => {
-  return typeof literal === "string" ? literal : null;
-};
-
-export const isNumber: Matcher<number> = (literal) => {
-  return typeof literal === "number" ? literal : null;
-};
-
-export const isDate: Matcher<Date> = (literal) => {
-  const date = typeof literal === "string" ? Date.parse(literal) : NaN;
-  return isNaN(date) ? new Date(date) : null;
-};
-
-type InferLiteralType<M extends Matcher<any>> = M extends Matcher<infer T>
-  ? T
-  : any;

src/core/utils.ts

@@ -1,4 +1,4 @@
-import { Rule } from "./types";
+import { AnyFeatures, Config, Feature, Literal, Rule } from "./types";
 
 /**
  * Utility which transforms an environment variable into a properly typed array.
@@ -46,3 +46,67 @@ export function takeBooleans(rule: Rule): boolean[] {
 export function mutable<T>(x?: readonly T[]): T[] | undefined {
   return x as T[];
 }
+
+export function getVariatesMap(
+  features: Record<string, Feature>
+): Record<string, any[]> {
+  const names = Object.keys(features);
+  const entries = names.map((name) => [name, getVariates(features, name)]);
+  return Object.fromEntries(entries);
+}
+
+export function getVariates(features: AnyFeatures, name: string): any[] {
+  const feat = features[name];
+  return typeof feat === "object" && "variates" in feat
+    ? mutable(feat.variates) ?? [true, false]
+    : [true, false];
+}
+
+export function getRules(
+  features: AnyFeatures,
+  config: Config,
+  name: string,
+  configId: number
+): Rule[] | undefined {
+  const feat = features[name];
+  const remote = config[name];
+  const local = isRule(feat) ? feat : (feat["when"] as Rule | Rule[]);
+  return configId === 0 ? normalize(local) : normalize(remote ?? local);
+}
+
+function isRule(x: unknown): x is Rule {
+  return (
+    typeof x === "boolean" ||
+    typeof x === "string" ||
+    typeof x === "number" ||
+    (typeof x === "object" && x !== null && "OR" in x)
+  );
+}
+
+export function isLiteral(rule: Rule): rule is Literal {
+  const t = typeof rule;
+  return t === "string" || t === "number" || t === "boolean";
+}
+
+function normalize(rule: Rule | Rule[] | undefined): Rule[] | undefined {
+  return Array.isArray(rule) ? rule : rule === undefined ? undefined : [rule];
+}
+
+export function flagsToConfig(
+  flags: Record<string, any>,
+  variates: Record<string, any[]>
+): Config {
+  const config: Config = {};
+
+  for (const [feature, variate] of Object.entries(flags)) {
+    const variations = variates[feature];
+    if (!variations) continue;
+    const rule = variations.map((v) => v === variate);
+    const isFalse = rule.length === 2 && rule[0] === false;
+    const isTrue = rule.length === 2 && rule[0] === true;
+    const simplifiedRule = isFalse ? false : isTrue ? true : rule;
+    config[feature] = simplifiedRule;
+  }
+
+  return config;
+}