feat: Initial version of the flagd js core (#620)

Signed-off-by: Kavindu Dodanduwa <[email protected]>
Signed-off-by: Kavindu Dodanduwa <[email protected]>
Co-authored-by: Todd Baert <[email protected]>

Author: Kavindu-Dodan

.gitmodules

@@ -10,3 +10,6 @@
 [submodule "libs/providers/flagd-web/spec"]
 	path = libs/providers/flagd-web/spec
 	url = https://github.com/open-feature/spec.git
+[submodule "libs/shared/flagd-core/flagd-schemas"]
+	path = libs/shared/flagd-core/flagd-schemas
+	url = [email protected]:open-feature/flagd-schemas.git

libs/shared/flagd-core/.eslintrc.json

@@ -0,0 +1,25 @@
+{
+  "extends": ["../../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/dependency-checks": "error"
+      }
+    }
+  ]
+}

libs/shared/flagd-core/README.md

@@ -0,0 +1,21 @@
+# flagd-core
+
+flagd-core contain the core logic of flagd [in-process evaluation](https://flagd.dev/architecture/#in-process-evaluation) provider.
+This package is intended to be used by concrete implementations of flagd in-process providers.
+
+## Usage
+
+flagd-core wraps a simple flagd feature flag storage and flag evaluation logic.
+
+To use this implementation, instantiate a `FlagdCore` and provide valid flagd flag configurations.
+
+```typescript
+const core = new FlagdCore();
+core.setConfigurations(FLAG_CONFIGURATION_STRING);
+```
+
+Once initialization is complete, use matching flag resolving call.
+
+```typescript
+const resolution = core.resolveBooleanEvaluation('myBoolFlag', false, {});
+```

libs/shared/flagd-core/flagd-schemas

@@ -0,0 +1,11 @@
+/* eslint-disable */
+export default {
+  displayName: 'flagd-core',
+  preset: '../../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../../coverage/libs/shared/flagd-core',
+};

libs/shared/flagd-core/jest.config.ts

@@ -0,0 +1,13 @@
+{
+  "name": "@openfeature/flagd-core",
+  "version": "0.0.1-alpha",
+  "scripts": {
+    "publish-if-not-exists": "cp $NPM_CONFIG_USERCONFIG .npmrc && if [ \"$(npm show $npm_package_name@$npm_package_version version)\" = \"$(npm run current-version -s)\" ]; then echo 'already published, skipping'; else npm publish --access public; fi",
+    "current-version": "echo $npm_package_version"
+  },
+  "dependencies": {
+    "@openfeature/server-sdk": ">=1.6.0",
+    "ajv": "^8.12.0",
+    "tslib": "^2.3.0"
+  }
+}

libs/shared/flagd-core/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "flagd-core",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/shared/flagd-core/src",
+  "projectType": "library",
+  "targets": {
+    "publish": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "npm run publish-if-not-exists",
+        "cwd": "dist/libs/shared/flagd-core"
+      },
+      "dependsOn": [
+        "build"
+      ]
+    },
+    "lint": {
+      "executor": "@nx/linter:eslint",
+      "outputs": [
+        "{options.outputFile}"
+      ],
+      "options": {
+        "lintFilePatterns": [
+          "libs/shared/flagd-core/**/*.ts"
+        ]
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": [
+        "{workspaceRoot}/coverage/{projectRoot}"
+      ],
+      "options": {
+        "jestConfig": "libs/shared/flagd-core/jest.config.ts",
+        "passWithNoTests": true
+      },
+      "configurations": {
+        "ci": {
+          "ci": true,
+          "codeCoverage": true
+        }
+      }
+    },
+    "package": {
+      "executor": "@nx/rollup:rollup",
+      "outputs": [
+        "{options.outputPath}"
+      ],
+      "options": {
+        "project": "libs/shared/flagd-core/package.json",
+        "outputPath": "dist/libs/shared/flagd-core",
+        "entryFile": "libs/shared/flagd-core/src/index.ts",
+        "tsConfig": "libs/shared/flagd-core/tsconfig.lib.json",
+        "compiler": "tsc",
+        "generateExportsField": true,
+        "buildableProjectDepsInPackageJsonType": "dependencies",
+        "umdName": "flagd-core",
+        "external": "all",
+        "format": [
+          "cjs",
+          "esm"
+        ],
+        "assets": [
+          {
+            "glob": "package.json",
+            "input": "./assets",
+            "output": "./src/"
+          },
+          {
+            "glob": "LICENSE",
+            "input": "./",
+            "output": "./"
+          },
+          {
+            "glob": "README.md",
+            "input": "./libs/shared/flagd-core",
+            "output": "./"
+          }
+        ],
+        "updateBuildableProjectDepsInPackageJson": true
+      }
+    }
+  },
+  "tags": []
+}

libs/shared/flagd-core/project.json

@@ -0,0 +1,3 @@
+export * from './lib/flagd-core';
+export * from './lib/feature-flag';
+export * from './lib/storage';

libs/shared/flagd-core/src/index.ts

@@ -0,0 +1,72 @@
+import {FeatureFlag, Flag} from './feature-flag';
+
+describe('Flagd flag structure', () => {
+  it('should be constructed with valid input - boolean', () => {
+    const input: Flag = {
+      state: 'ENABLED',
+      defaultVariant: 'off',
+      variants: {
+        on: true,
+        off: false,
+      },
+      targeting: '',
+    };
+
+    const ff = new FeatureFlag(input);
+
+    expect(ff).toBeTruthy();
+    expect(ff.state).toBe('ENABLED');
+    expect(ff.defaultVariant).toBe('off');
+    expect(ff.targetingString).toBe('""');
+    expect(ff.variants.get('on')).toBeTruthy();
+    expect(ff.variants.get('off')).toBeFalsy();
+  });
+
+  it('should be constructed with valid input - number', () => {
+    const input = {
+      state: 'ENABLED',
+      defaultVariant: 'one',
+      variants: {
+        one: 1.0,
+        two: 2.0,
+      },
+      targeting: '',
+    };
+
+    const ff = new FeatureFlag(input);
+
+    expect(ff).toBeTruthy();
+    expect(ff.state).toBe('ENABLED');
+    expect(ff.defaultVariant).toBe('one');
+    expect(ff.targetingString).toBe('""');
+    expect(ff.variants.get('one')).toBe(1.0);
+    expect(ff.variants.get('two')).toBe(2.0);
+  });
+
+  it('should be constructed with valid input - object', () => {
+    const input = {
+      state: 'ENABLED',
+      defaultVariant: 'pi2',
+      variants: {
+        pi2: {
+          value: 3.14,
+          accuracy: 2,
+        },
+        pi5: {
+          value: 3.14159,
+          accuracy: 5,
+        },
+      },
+      targeting: '',
+    };
+
+    const ff = new FeatureFlag(input);
+
+    expect(ff).toBeTruthy();
+    expect(ff.state).toBe('ENABLED');
+    expect(ff.defaultVariant).toBe('pi2');
+    expect(ff.targetingString).toBe('""');
+    expect(ff.variants.get('pi2')).toStrictEqual({ value: 3.14, accuracy: 2 });
+    expect(ff.variants.get('pi5')).toStrictEqual({ value: 3.14159, accuracy: 5 });
+  });
+});

libs/shared/flagd-core/src/lib/feature-flag.spec.ts

@@ -0,0 +1,44 @@
+import {FlagValue} from '@openfeature/server-sdk';
+
+/**
+ * Flagd flag configuration structure mapping to schema definition.
+ */
+export interface Flag {
+  state: string,
+  defaultVariant: string,
+  variants: {[key: string]: FlagValue},
+  targeting: string
+}
+
+/**
+ * Flagd flag configuration structure for internal reference.
+ */
+export class FeatureFlag {
+  private readonly _state: string;
+  private readonly _defaultVariant: string;
+  private readonly _variants: Map<string, FlagValue>;
+  private readonly _targetingString: string;
+
+  constructor(flag: Flag) {
+    this._state = flag['state'];
+    this._defaultVariant = flag['defaultVariant'];
+    this._variants = new Map<string, FlagValue>(Object.entries(flag['variants']));
+    this._targetingString = JSON.stringify(flag['targeting']);
+  }
+
+  get state(): string {
+    return this._state;
+  }
+
+  get defaultVariant(): string {
+    return this._defaultVariant;
+  }
+
+  get targetingString(): string {
+    return this._targetingString;
+  }
+
+  get variants(): Map<string, FlagValue> {
+    return this._variants
+  }
+}

libs/shared/flagd-core/src/lib/feature-flag.ts

@@ -0,0 +1,77 @@
+import {FlagdCore} from './flagd-core';
+import {StandardResolutionReasons, TypeMismatchError} from '@openfeature/server-sdk';
+
+const flagCfg = `{"flags":{"myBoolFlag":{"state":"ENABLED","variants":{"on":true,"off":false},"defaultVariant":"on"},"myStringFlag":{"state":"ENABLED","variants":{"key1":"val1","key2":"val2"},"defaultVariant":"key1"},"myFloatFlag":{"state":"ENABLED","variants":{"one":1.23,"two":2.34},"defaultVariant":"one"},"myIntFlag":{"state":"ENABLED","variants":{"one":1,"two":2},"defaultVariant":"one"},"myObjectFlag":{"state":"ENABLED","variants":{"object1":{"key":"val"},"object2":{"key":true}},"defaultVariant":"object1"},"fibAlgo":{"variants":{"recursive":"recursive","memo":"memo","loop":"loop","binet":"binet"},"defaultVariant":"recursive","state":"ENABLED","targeting":{"if":[{"$ref":"emailWithFaas"},"binet",null]}},"targetedFlag":{"variants":{"first":"AAA","second":"BBB","third":"CCC"},"defaultVariant":"first","state":"ENABLED","targeting":{"if":[{"in":["@openfeature.dev",{"var":"email"}]},"second",{"in":["Chrome",{"var":"userAgent"}]},"third",null]}}},"$evaluators":{"emailWithFaas":{"in":["@faas.com",{"var":["email"]}]}}}`;
+
+describe('flagdJsCore resolving', () => {
+  let core: FlagdCore;
+
+  beforeAll(() => {
+    core = new FlagdCore();
+    core.setConfigurations(flagCfg);
+  });
+
+  it('should resolve boolean flag', () => {
+    const resolved = core.resolveBooleanEvaluation('myBoolFlag', false, {});
+    expect(resolved.value).toBeTruthy();
+    expect(resolved.reason).toBe(StandardResolutionReasons.STATIC);
+    expect(resolved.variant).toBe("on")
+  });
+
+  it('should resolve string flag', () => {
+    const resolved = core.resolveStringEvaluation('myStringFlag', 'key2', {});
+    expect(resolved.value).toBe('val1');
+    expect(resolved.reason).toBe(StandardResolutionReasons.STATIC);
+    expect(resolved.variant).toBe("key1")
+  });
+
+  it('should resolve number flag', () => {
+    const resolved = core.resolveNumberEvaluation('myFloatFlag', 2.34, {});
+    expect(resolved.value).toBe(1.23);
+    expect(resolved.reason).toBe(StandardResolutionReasons.STATIC);
+    expect(resolved.variant).toBe("one")
+  });
+
+  it('should resolve object flag', () => {
+    const resolved = core.resolveObjectEvaluation('myObjectFlag', {key: true}, {});
+    expect(resolved.value).toStrictEqual({key: 'val'});
+    expect(resolved.reason).toBe(StandardResolutionReasons.STATIC);
+    expect(resolved.variant).toBe("object1")
+  });
+
+});
+
+describe('flagdJsCore validations', () => {
+  // flags of disabled, invalid variants and missing variant
+  const mixFlags =
+    '{"flags":{"myBoolFlag":{"state":"DISABLED","variants":{"on":true,"off":false},"defaultVariant":"on"},"myStringFlag":{"state":"ENABLED","variants":{"on":true,"off":false},"defaultVariant":"on"},"myIntFlag":{"state":"ENABLED","variants":{"two":2},"defaultVariant":"one"}}}';
+  let core: FlagdCore;
+
+  beforeAll(() => {
+    core = new FlagdCore();
+    core.setConfigurations(mixFlags);
+  });
+
+  it('should validate flag type - eval int as boolean', () => {
+    expect(() => core.resolveBooleanEvaluation('myIntFlag', true, {}))
+      .toThrow(TypeMismatchError)
+  });
+
+  it('should validate flag status', () => {
+    const evaluation = core.resolveBooleanEvaluation('myBoolFlag', false, {});
+
+    expect(evaluation).toBeTruthy()
+    expect(evaluation.value).toBe(false)
+    expect(evaluation.reason).toBe(StandardResolutionReasons.DISABLED)
+  });
+
+  it('should validate variant', () => {
+    expect(() => core.resolveStringEvaluation('myStringFlag', 'hello', {}))
+      .toThrow(TypeMismatchError)
+  });
+
+  it('should validate variant existence', () => {
+    expect(() => core.resolveNumberEvaluation('myIntFlag', 100, {}))
+      .toThrow(TypeMismatchError)
+  });
+});