@statsig/js-client 0.0.1-beta.10

package/.eslintrc.json

@@ -0,0 +1,34 @@
+{
+  "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",
+          {
+            "ignoredDependencies": [
+              "jest-fetch-mock",
+              "@nx/webpack",
+              "statsig-test-helpers"
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}

package/README.md

@@ -0,0 +1,12 @@
+# Statsig - Precomputed Evaluations
+
+> [!IMPORTANT]
+> This version of the SDK is still in beta. The non-beta version can be found [here](https://github.com/statsig-io/js-client).
+
+The JavaScript SDK for single user client environments. If you need a SDK for another language or server environment, check out our [other SDKs](https://docs.statsig.com/#sdks).
+
+Statsig helps you move faster with feature gates (feature flags), and/or dynamic configs. It also allows you to run A/B/n tests to validate your new features and understand their impact on your KPIs. If you're new to Statsig, check out our product and create an account at [statsig.com](https://www.statsig.com).
+
+## Getting Started
+
+Check out our [SDK docs](https://docs.statsig.com/client/javascript-sdk) to get started.

package/jest.config.ts

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

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@statsig/js-client",
+  "version": "0.0.1-beta.10",
+  "dependencies": {
+    "@statsig/client-core": "0.0.1-beta.10"
+  },
+  "jsdelivr": "./build/js-client.min.js",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "typings": "./src/index.d.ts"
+}

package/project.json

@@ -0,0 +1,52 @@
+{
+  "name": "js-client",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/js-client/src",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "command": ":",
+      "dependsOn": ["^build", "build-webpack"]
+    },
+    "publish": {
+      "command": "ts-node ./tools/scripts/publish.ts js-client",
+      "dependsOn": ["build", "^build-webpack"]
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "outputs": ["{options.outputFile}"]
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "jestConfig": "packages/js-client/jest.config.ts"
+      }
+    },
+    "build-ts": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/packages/js-client",
+        "main": "packages/js-client/src/index.ts",
+        "tsConfig": "packages/js-client/tsconfig.lib.json",
+        "assets": ["packages/js-client/*.md"]
+      }
+    },
+    "build-webpack": {
+      "executor": "@nx/webpack:webpack",
+      "outputs": ["{options.outputPath}"],
+      "defaultConfiguration": "production",
+      "options": {
+        "statsJson": true,
+        "verbose": true,
+        "outputPath": "overridden in webpack config",
+        "main": "overridden in webpack config",
+        "tsConfig": "packages/js-client/tsconfig.lib.json",
+        "webpackConfig": "packages/js-client/webpack.config.js"
+      },
+      "dependsOn": ["build-ts"]
+    }
+  },
+  "tags": []
+}

package/src/EvaluationData.ts

@@ -0,0 +1,19 @@
+import {
+  DynamicConfigEvaluation,
+  GateEvaluation,
+  LayerEvaluation,
+} from '@statsig/client-core';
+
+export type EvaluationResponseWithUpdates = {
+  feature_gates: Record<string, GateEvaluation>;
+  dynamic_configs: Record<string, DynamicConfigEvaluation>;
+  layer_configs: Record<string, LayerEvaluation>;
+  time: number;
+  has_updates: true;
+  hash_used: 'none' | 'sha256' | 'djb2';
+  derived_fields?: Record<string, unknown>;
+};
+
+export type EvaluationResponse =
+  | EvaluationResponseWithUpdates
+  | { has_updates: false };

package/src/EvaluationResponseDeltas.ts

@@ -0,0 +1,108 @@
+import { DJB2Object, typedJsonParse } from '@statsig/client-core';
+
+import { EvaluationResponseWithUpdates } from './EvaluationData';
+
+type DeltasEvaluationResponse = EvaluationResponseWithUpdates & {
+  deleted_configs?: string[];
+  deleted_gates?: string[];
+  deleted_layers?: string[];
+  is_delta: true;
+  has_updates: true;
+  checksum: string;
+  deltas_full_response?: Record<string, unknown>;
+};
+
+export type DeltasFailureInfo = {
+  hadBadDeltaChecksum: boolean;
+  badChecksum?: string;
+  badMergedConfigs?: Record<string, unknown>;
+  badFullResponse?: Record<string, unknown>;
+};
+
+type DeltasResult = string | DeltasFailureInfo | null;
+
+export function resolveDeltasResponse(
+  cache: EvaluationResponseWithUpdates,
+  deltasString: string,
+): DeltasResult {
+  const deltas = typedJsonParse<DeltasEvaluationResponse>(
+    deltasString,
+    'checksum',
+    'Failed to parse DeltasEvaluationResponse',
+  );
+
+  if (!deltas) {
+    return {
+      hadBadDeltaChecksum: true,
+    };
+  }
+
+  const merged = _mergeDeltasIntoCache(cache, deltas);
+  const resolved = _handleDeletedEntries(merged);
+
+  const actualChecksum = DJB2Object({
+    feature_gates: resolved.feature_gates,
+    dynamic_configs: resolved.dynamic_configs,
+    layer_configs: resolved.layer_configs,
+  });
+
+  const isMatch = actualChecksum === deltas.checksum;
+  if (!isMatch) {
+    return {
+      hadBadDeltaChecksum: true,
+      badChecksum: actualChecksum,
+      badMergedConfigs: resolved,
+      badFullResponse: deltas.deltas_full_response,
+    };
+  }
+
+  return JSON.stringify(resolved);
+}
+
+function _mergeDeltasIntoCache(
+  cache: EvaluationResponseWithUpdates,
+  deltas: DeltasEvaluationResponse,
+): DeltasEvaluationResponse {
+  return {
+    ...cache,
+    ...deltas,
+    feature_gates: {
+      ...cache.feature_gates,
+      ...deltas.feature_gates,
+    },
+    layer_configs: {
+      ...cache.layer_configs,
+      ...deltas.layer_configs,
+    },
+    dynamic_configs: {
+      ...cache.dynamic_configs,
+      ...deltas.dynamic_configs,
+    },
+  };
+}
+
+function _handleDeletedEntries(
+  deltas: DeltasEvaluationResponse,
+): EvaluationResponseWithUpdates {
+  const result = deltas;
+
+  _deleteEntriesInRecord(deltas.deleted_gates, result.feature_gates);
+  delete result.deleted_gates;
+
+  _deleteEntriesInRecord(deltas.deleted_configs, result.dynamic_configs);
+  delete result.deleted_configs;
+
+  _deleteEntriesInRecord(deltas.deleted_layers, result.layer_configs);
+  delete result.deleted_layers;
+
+  return result;
+}
+
+function _deleteEntriesInRecord(
+  keys: string[] | undefined,
+  values: Record<string, unknown>,
+) {
+  keys?.forEach((key) => {
+    delete values[key];
+  });
+}

package/src/EvaluationStore.ts

@@ -0,0 +1,99 @@
+import {
+  AnyEvaluation,
+  DataAdapterResult,
+  DataSource,
+  DetailedEvaluation,
+  DynamicConfigEvaluation,
+  EvaluationDetails,
+  GateEvaluation,
+  LayerEvaluation,
+  typedJsonParse,
+} from '@statsig/client-core';
+
+import { EvaluationResponse } from './EvaluationData';
+
+type EvaluationStoreValues = EvaluationResponse & { has_updates: true };
+
+export default class EvaluationStore {
+  private _values: EvaluationStoreValues | null = null;
+  private _source: DataSource = 'Uninitialized';
+  private _lcut = 0;
+  private _receivedAt = 0;
+
+  constructor(private _sdkKey: string) {}
+
+  reset(): void {
+    this._values = null;
+    this._source = 'Loading';
+    this._lcut = 0;
+    this._receivedAt = 0;
+  }
+
+  finalize(): void {
+    if (this._values) {
+      return;
+    }
+
+    this._source = 'NoValues';
+  }
+
+  setValuesFromDataAdapter(result: DataAdapterResult | null): void {
+    if (!result) {
+      return;
+    }
+
+    const values = typedJsonParse<EvaluationResponse>(
+      result.data,
+      'has_updates',
+      'Failed to parse EvaluationResponse',
+    );
+
+    if (values?.has_updates !== true) {
+      return;
+    }
+
+    this._lcut = values.time;
+    this._receivedAt = result.receivedAt;
+    this._source = result.source;
+    this._values = values;
+  }
+
+  getGate(name: string): DetailedEvaluation<GateEvaluation> {
+    const evaluation = this._values?.feature_gates[name] ?? null;
+    return this._makeDetailedEvaluation(evaluation);
+  }
+
+  getConfig(name: string): DetailedEvaluation<DynamicConfigEvaluation> {
+    const evaluation = this._values?.dynamic_configs[name] ?? null;
+    return this._makeDetailedEvaluation(evaluation);
+  }
+
+  getLayer(name: string): DetailedEvaluation<LayerEvaluation> {
+    const evaluation = this._values?.layer_configs[name] ?? null;
+    return this._makeDetailedEvaluation(evaluation);
+  }
+
+  private _makeDetailedEvaluation<T extends AnyEvaluation>(
+    evaluation: T | null,
+  ): DetailedEvaluation<T> {
+    return {
+      evaluation,
+      details: this._getDetails(evaluation == null),
+    };
+  }
+
+  private _getDetails(isUnrecognized: boolean): EvaluationDetails {
+    if (this._source === 'Uninitialized' || this._source === 'NoValues') {
+      return { reason: this._source };
+    }
+
+    const subreason = isUnrecognized ? 'Unrecognized' : 'Recognized';
+    const reason = `${this._source}:${subreason}`;
+
+    return {
+      reason,
+      lcut: this._lcut,
+      receivedAt: this._receivedAt,
+    };
+  }
+}

package/src/Network.ts

@@ -0,0 +1,112 @@
+import {
+  NetworkCore,
+  StatsigClientEmitEventFunc,
+  StatsigUser,
+  _getOverridableUrl,
+  typedJsonParse,
+} from '@statsig/client-core';
+
+import { EvaluationResponse } from './EvaluationData';
+import { resolveDeltasResponse } from './EvaluationResponseDeltas';
+import { StatsigOptions } from './StatsigOptions';
+
+const DEFAULT_API = 'https://api.statsig.com/v1';
+const DEFAULT_ENDPOINT = '/initialize';
+
+type EvaluationsFetchArgs = {
+  hash: 'djb2' | 'sha256' | 'none';
+  deltasResponseRequested: boolean;
+  user?: StatsigUser;
+  sinceTime?: number;
+  previousDerivedFields?: Record<string, unknown>;
+};
+
+export default class StatsigNetwork extends NetworkCore {
+  private _initializeUrl: string;
+
+  constructor(
+    options: StatsigOptions | null,
+    emitter?: StatsigClientEmitEventFunc,
+  ) {
+    super(options, emitter);
+
+    this._initializeUrl = _getOverridableUrl(
+      options?.initializeUrl,
+      options?.api,
+      DEFAULT_ENDPOINT,
+      DEFAULT_API,
+    );
+  }
+
+  async fetchEvaluations(
+    sdkKey: string,
+    current: string | null,
+    user?: StatsigUser,
+  ): Promise<string | null> {
+    const cache = current
+      ? typedJsonParse<EvaluationResponse>(
+          current,
+          'has_updates',
+          'Failed to parse cached EvaluationResponse',
+        )
+      : null;
+
+    let data: EvaluationsFetchArgs = {
+      user,
+      hash: 'djb2',
+      deltasResponseRequested: false,
+    };
+
+    if (cache?.has_updates) {
+      data = {
+        ...data,
+        sinceTime: cache.time,
+        previousDerivedFields:
+          'derived_fields' in cache ? cache.derived_fields : {},
+        deltasResponseRequested: true,
+      };
+    }
+
+    return this._fetchEvaluations(sdkKey, cache, data);
+  }
+
+  private async _fetchEvaluations(
+    sdkKey: string,
+    cache: EvaluationResponse | null,
+    data: EvaluationsFetchArgs,
+  ): Promise<string | null> {
+    const response = await this.post({
+      sdkKey,
+      url: this._initializeUrl,
+      data,
+      retries: 2,
+    });
+
+    if (response?.code === 204) {
+      return '{"has_updates": false}';
+    }
+
+    if (response?.code !== 200) {
+      return response?.body ?? null;
+    }
+
+    if (
+      cache?.has_updates !== true ||
+      response.body?.includes('"is_delta":true') !== true
+    ) {
+      return response.body;
+    }
+
+    const result = resolveDeltasResponse(cache, response.body);
+    if (typeof result === 'string') {
+      return result;
+    }
+
+    // retry without deltas
+    return this._fetchEvaluations(sdkKey, cache, {
+      ...data,
+      ...result,
+      deltasResponseRequested: false,
+    });
+  }
+}