feat: scoped caching support (#234)

* feat: scoped caching support

* refactor: flag cache options docs

* fixup! refactor: flag cache options docs

---------

Co-authored-by: Nicklas Lundin <[email protected]>

Author: andreas-karlsson

.eslintrc

@@ -4,7 +4,7 @@
     "@spotify/eslint-config-typescript",
     "@spotify/eslint-config-react",
     "prettier",
-    "plugin:es/restrict-to-es2015"
+    "plugin:es/restrict-to-es2018"
   ],
   "plugins": ["@spotify/eslint-plugin"],
   "settings": {
@@ -13,13 +13,12 @@
     }
   },
   "rules": {
-    "es/no-async-functions": "off",
-    "es/no-trailing-function-commas": "off",
     "es/no-rest-spread-properties": "off",
     "es/no-optional-chaining": "off",
     "es/no-nullish-coalescing-operators": "off",
     "no-inner-declarations": "off",
     "@typescript-eslint/no-use-before-define": "off",
-    "no-param-reassign": "off"
+    "no-param-reassign": "off",
+    "@typescript-eslint/no-shadow": "off"
   }
 }

api/sdk.api.md

@@ -4,6 +4,24 @@
 
 ```ts
 
+import { BinaryReader } from '@bufbuild/protobuf/wire';
+import { BinaryWriter } from '@bufbuild/protobuf/wire';
+
+// @public
+export interface CacheOptions {
+    // Warning: (ae-forgotten-export) The symbol "CacheEntry" needs to be exported by the entry point index.d.ts
+    //
+    // @internal (undocumented)
+    entries?: AsyncIterable<CacheEntry>;
+    scope?: CacheScope;
+}
+
+// Warning: (ae-forgotten-export) The symbol "CacheProvider" needs to be exported by the entry point index.d.ts
+// Warning: (ae-missing-release-tag) "CacheScope" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public
+export type CacheScope = (provider: CacheProvider) => CacheProvider;
+
 // @public
 export namespace Closer {
     export function combine(...closers: Closer[]): Closer;
@@ -15,14 +33,15 @@ export type Closer = () => void;
 // @public
 export class Confidence implements EventSender, Trackable, FlagResolver {
     // @internal
-    constructor(config: Configuration, parent?: Confidence);
+    constructor({ context, ...config }: Configuration, parent?: Confidence);
     clearContext(): void;
+    // Warning: (ae-incompatible-release-tags) The symbol "config" is marked as @public, but its signature references "Configuration" which is marked as @internal
     readonly config: Configuration;
     // Warning: (ae-forgotten-export) The symbol "Subscribe" needs to be exported by the entry point index.d.ts
     //
     // @internal
     readonly contextChanges: Subscribe<string[]>;
-    static create({ clientSecret, region, timeout, environment, fetchImplementation, logger, resolveBaseUrl, disableTelemetry, applyDebounce, waitUntil, }: ConfidenceOptions): Confidence;
+    static create(options: ConfidenceOptions): Confidence;
     get environment(): string;
     evaluateFlag(path: string, defaultValue: string): FlagEvaluation<string>;
     // (undocumented)
@@ -44,6 +63,8 @@ export class Confidence implements EventSender, Trackable, FlagResolver {
     protected resolveFlags(): AccessiblePromise<void>;
     setContext(context: Context): boolean;
     subscribe(onStateChange?: StateObserver): () => void;
+    // (undocumented)
+    toOptions(signal?: AbortSignal): ConfidenceOptions;
     track(name: string, data?: EventData): void;
     track(manager: Trackable.Manager): Closer;
     withContext(context: Context): Confidence;
@@ -52,7 +73,10 @@ export class Confidence implements EventSender, Trackable, FlagResolver {
 // @public
 export interface ConfidenceOptions {
     applyDebounce?: number;
+    cache?: CacheOptions;
     clientSecret: string;
+    // (undocumented)
+    context?: Context;
     disableTelemetry?: boolean;
     environment: 'client' | 'backend';
     fetchImplementation?: SimpleFetch;
@@ -64,21 +88,19 @@ export interface ConfidenceOptions {
     waitUntil?: WaitUntil;
 }
 
-// @public
-export interface Configuration {
+// Warning: (ae-internal-missing-underscore) The name "Configuration" should be prefixed with an underscore because the declaration is marked as @internal
+//
+// @internal
+export interface Configuration extends ConfidenceOptions {
+    // (undocumented)
+    readonly cacheProvider: CacheProvider;
     // (undocumented)
     readonly clientSecret: string;
-    readonly environment: 'client' | 'backend';
     // Warning: (ae-forgotten-export) The symbol "EventSenderEngine" needs to be exported by the entry point index.d.ts
-    //
-    // @internal
     readonly eventSenderEngine: EventSenderEngine;
     // Warning: (ae-forgotten-export) The symbol "FlagResolverClient" needs to be exported by the entry point index.d.ts
-    //
-    // @internal
     readonly flagResolverClient: FlagResolverClient;
     readonly logger: Logger;
-    readonly timeout: number;
 }
 
 // @public

packages/sdk/src/AccessiblePromise.ts

@@ -2,7 +2,7 @@ function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
   return typeof value === 'object' && value !== null && 'then' in value && typeof value.then === 'function';
 }
 
-export class AccessiblePromise<T> {
+export class AccessiblePromise<T> implements Promise<T> {
   #state: 'PENDING' | 'RESOLVED' | 'REJECTED';
   #value: any;
 
@@ -27,6 +27,7 @@ export class AccessiblePromise<T> {
   }
 
   protected chain<S>(value: any, rejected?: boolean): AccessiblePromise<S> {
+    if (value instanceof AccessiblePromise) return value;
     return new AccessiblePromise(value, rejected);
   }
 
@@ -112,7 +113,12 @@ export class AccessiblePromise<T> {
     return this.orSupply(() => value);
   }
 
-  static resolve<T = void>(value?: T | PromiseLike<T>): AccessiblePromise<T> {
+  get [Symbol.toStringTag]() {
+    return 'AccessiblePromise';
+  }
+
+  static resolve<T = void>(value?: T | PromiseLike<T>): AccessiblePromise<Awaited<T>> {
+    if (value instanceof AccessiblePromise) return value;
     return new AccessiblePromise(value);
   }
 

packages/sdk/src/Confidence.test.ts

@@ -29,6 +29,9 @@ describe('Confidence', () => {
       logger: {},
       eventSenderEngine: eventSenderEngineMock,
       flagResolverClient: flagResolverClientMock,
+      cacheProvider: () => {
+        throw new Error('Not implemented');
+      },
     });
     flagResolverClientMock.resolve.mockImplementation((context, _flags) => {
       const flagResolution = new Promise<FlagResolution>(resolve => {

packages/sdk/src/Confidence.ts

@@ -1,9 +1,4 @@
-import {
-  CachingFlagResolverClient,
-  FetchingFlagResolverClient,
-  FlagResolverClient,
-  PendingResolution,
-} from './FlagResolverClient';
+import { FetchingFlagResolverClient, FlagResolverClient, PendingResolution } from './FlagResolverClient';
 import { EventSenderEngine } from './EventSenderEngine';
 import { Value } from './Value';
 import { EventData, EventSender } from './events';
@@ -19,6 +14,7 @@ import { FlagResolution } from './FlagResolution';
 import { AccessiblePromise } from './AccessiblePromise';
 import { Telemetry } from './Telemetry';
 import { SimpleFetch } from './fetch-util';
+import { CacheOptions, CacheProvider, FlagCache } from './flag-cache';
 
 /**
  * Confidence options, to be used for easier initialization of Confidence
@@ -48,19 +44,21 @@ export interface ConfidenceOptions {
    * This is particularly useful in serverless environments where you need to ensure certain operations complete before the environment is reclaimed.
    */
   waitUntil?: WaitUntil;
+  /**
+   * Configuration options for the Confidence SDK's flag caching system.
+   * @see {@link CacheOptions}
+   */
+  cache?: CacheOptions;
+  context?: Context;
 }
 
 /**
  * Confidence configuration
- * @public
+ * @internal
  */
-export interface Configuration {
-  /** Environment: can be either client of backend */
-  readonly environment: 'client' | 'backend';
+export interface Configuration extends ConfidenceOptions {
   /** Debug logger */
   readonly logger: Logger;
-  /** Resolve timeout */
-  readonly timeout: number;
   /** Event Sender Engine
    * @internal */
   readonly eventSenderEngine: EventSenderEngine;
@@ -69,6 +67,7 @@ export interface Configuration {
   readonly flagResolverClient: FlagResolverClient;
   /* @internal */
   readonly clientSecret: string;
+  readonly cacheProvider: CacheProvider;
 }
 
 /**
@@ -79,7 +78,7 @@ export class Confidence implements EventSender, Trackable, FlagResolver {
   /** Internal Confidence configurations */
   readonly config: Configuration;
   private readonly parent?: Confidence;
-  private _context: Map<string, Value> = new Map();
+  private _context: Map<string, Value>;
   private contextChanged?: Observer<string[]>;
 
   /**
@@ -93,9 +92,10 @@ export class Confidence implements EventSender, Trackable, FlagResolver {
   private readonly flagStateSubject: Subscribe<State>;
 
   /** @internal */
-  constructor(config: Configuration, parent?: Confidence) {
+  constructor({ context = {}, ...config }: Configuration, parent?: Confidence) {
     this.config = config;
     this.parent = parent;
+    this._context = new Map(Object.entries(context));
     this.contextChanges = subject(observer => {
       let parentSubscription: Closer | void;
       if (parent) {
@@ -336,6 +336,18 @@ export class Confidence implements EventSender, Trackable, FlagResolver {
     );
   }
 
+  toOptions(signal?: AbortSignal): ConfidenceOptions {
+    const cache = this.config.cacheProvider(this.config.clientSecret).toOptions(signal);
+    return {
+      clientSecret: this.config.clientSecret,
+      region: this.config.region,
+      timeout: this.config.timeout,
+      environment: this.config.environment,
+      cache,
+      context: this.getContext(),
+    };
+  }
+
   /**
    * Creates a Confidence instance
    * @param clientSecret - clientSecret found on the Confidence console
@@ -347,18 +359,20 @@ export class Confidence implements EventSender, Trackable, FlagResolver {
    * @param resolveBaseUrl - custom backend resolve URL
    * @returns
    */
-  static create({
-    clientSecret,
-    region,
-    timeout,
-    environment,
-    fetchImplementation = defaultFetchImplementation(),
-    logger = defaultLogger(),
-    resolveBaseUrl,
-    disableTelemetry = false,
-    applyDebounce = 10,
-    waitUntil,
-  }: ConfidenceOptions): Confidence {
+  static create(options: ConfidenceOptions): Confidence {
+    const {
+      clientSecret,
+      region,
+      timeout,
+      environment,
+      fetchImplementation = defaultFetchImplementation(),
+      logger = defaultLogger(),
+      resolveBaseUrl,
+      disableTelemetry = false,
+      applyDebounce = 10,
+      waitUntil,
+      cache = {},
+    } = options;
     if (environment !== 'client' && environment !== 'backend') {
       throw new Error(`Invalid environment: ${environment}. Must be 'client' or 'backend'.`);
     }
@@ -373,7 +387,8 @@ export class Confidence implements EventSender, Trackable, FlagResolver {
     if (!clientSecret) {
       logger.error?.(`Confidence: confidence cannot be instantiated without a client secret`);
     }
-    let flagResolverClient: FlagResolverClient = new FetchingFlagResolverClient({
+    const cacheProvider = FlagCache.provider(clientSecret, cache);
+    const flagResolverClient: FlagResolverClient = new FetchingFlagResolverClient({
       clientSecret,
       fetchImplementation,
       sdk,
@@ -385,10 +400,8 @@ export class Confidence implements EventSender, Trackable, FlagResolver {
       logger,
       applyDebounce,
       waitUntil,
+      cacheProvider,
     });
-    if (environment === 'client') {
-      flagResolverClient = new CachingFlagResolverClient(flagResolverClient, Number.POSITIVE_INFINITY);
-    }
     const estEventSizeKb = 1;
     const flushTimeoutMilliseconds = 500;
     // default grpc payload limit is 4MB, so we aim for a 1MB batch-size
@@ -408,12 +421,11 @@ export class Confidence implements EventSender, Trackable, FlagResolver {
       logger,
     });
     return new Confidence({
-      environment: environment,
+      ...options,
       flagResolverClient,
       eventSenderEngine,
-      timeout,
       logger,
-      clientSecret,
+      cacheProvider,
     });
   }
 }

packages/sdk/src/FlagResolution.ts

@@ -51,7 +51,8 @@ export class ReadyFlagResolution implements FlagResolution {
     resolveResponse: ResolveFlagsResponse,
     private readonly applier?: Applier,
   ) {
-    for (const { flag, variant, value, reason, flagSchema, shouldApply } of resolveResponse.resolvedFlags) {
+    for (const resolvedFlag of resolveResponse.resolvedFlags) {
+      const { flag, variant, value, reason, flagSchema } = resolvedFlag;
       const name = flag.slice(FLAG_PREFIX.length);
 
       const schema = flagSchema ? Schema.parse({ structSchema: flagSchema }) : Schema.ANY;
@@ -60,7 +61,12 @@ export class ReadyFlagResolution implements FlagResolution {
         value: value! as Value.Struct,
         variant,
         reason: toEvaluationReason(reason),
-        shouldApply,
+        set shouldApply(value) {
+          resolvedFlag.shouldApply = value;
+        },
+        get shouldApply() {
+          return resolvedFlag.shouldApply;
+        },
       });
     }
     this.resolveToken = base64FromBytes(resolveResponse.resolveToken);
@@ -83,6 +89,7 @@ export class ReadyFlagResolution implements FlagResolution {
 
       if (flag.shouldApply && this.applier) {
         this.applier?.(name);
+        flag.shouldApply = false;
       }
 
       if (reason !== 'MATCH') {