refactor: move Multi-Provider shared code to core package (#1324)

## Summary

- Consolidates duplicate Multi-Provider code from `server` and `web`
packages into `@openfeature/core` (shared package)
- Uses generics (`TProviderStatus`, `TProvider`) internally to support
both server and web SDKs from a single implementation

## Changes

### Moved to shared package (`@openfeature/core`):
- `BaseEvaluationStrategy` and base strategy classes
- `StatusTracker` for provider status management
- Error utilities (`AggregateError`, `constructAggregateError`)
- Common types (`ProviderEntryInput`, `RegisteredProvider`)

### SDK-specific strategy exports:
- Each SDK exports pre-configured `FirstMatchStrategy`,
`FirstSuccessfulStrategy`, and `ComparisonStrategy` classes
- These wrapper classes have `ProviderStatus` pre-bound, maintaining
backward compatibility
- Users can continue using `new FirstMatchStrategy()` without any
changes

### New tests:
- Added unit tests for `StatusTracker` (event handling, status priority)
- Added unit tests for `constructAggregateError` (including edge cases)

### Documentation:
- Updated Multi-Provider READMEs with clearer custom strategy examples
- Added `BaseEvaluationStrategy` class structure documentation

---------

Signed-off-by: Jonathan Norris <jonathan@taplytics.com>
Signed-off-by: Todd Baert <todd.baert@dynatrace.com>
Co-authored-by: Todd Baert <todd.baert@dynatrace.com>

Author: jonathannorris

packages/server/src/provider/multi-provider/README.md

@@ -103,10 +103,10 @@ client.track('purchase', { targetingKey: 'user123' }, { value: 99.99, currency:
 You can customize which providers receive tracking calls by overriding the `shouldTrackWithThisProvider` method in your custom strategy:
 
 ```typescript
-import { BaseEvaluationStrategy, StrategyPerProviderContext } from '@openfeature/server-sdk';
+import { FirstMatchStrategy, StrategyPerProviderContext } from '@openfeature/server-sdk';
 
-class CustomTrackingStrategy extends BaseEvaluationStrategy {
-  shouldTrackWithThisProvider(
+class CustomTrackingStrategy extends FirstMatchStrategy {
+  override shouldTrackWithThisProvider(
     strategyContext: StrategyPerProviderContext,
     context: EvaluationContext,
     trackingEventName: string,
@@ -129,24 +129,38 @@ class CustomTrackingStrategy extends BaseEvaluationStrategy {
 
 ## Custom Strategies
 
-It is also possible to implement your own strategy if the above options do not fit your use case. To do so, create a class which implements the "BaseEvaluationStrategy":
+It is also possible to implement your own strategy if the above options do not fit your use case. To do so, create a class which extends one of the built-in strategies or extends `BaseEvaluationStrategy` from `@openfeature/core`:
 
 ```typescript
-export abstract class BaseEvaluationStrategy {
-  public runMode: 'parallel' | 'sequential' = 'sequential';
+import { FirstMatchStrategy } from '@openfeature/server-sdk';
 
-  abstract shouldEvaluateThisProvider(
+class MyCustomStrategy extends FirstMatchStrategy {
+  // Override methods as needed
+  override shouldEvaluateThisProvider(
     strategyContext: StrategyPerProviderContext,
     evalContext: EvaluationContext,
-  ): boolean;
+  ): boolean {
+    // Custom logic here
+    return super.shouldEvaluateThisProvider(strategyContext, evalContext);
+  }
+}
+```
 
-  abstract shouldEvaluateNextProvider<T extends FlagValue>(
+The `BaseEvaluationStrategy` abstract class has the following structure:
+
+```typescript
+export abstract class BaseEvaluationStrategy {
+  public runMode: 'parallel' | 'sequential' = 'sequential';
+
+  shouldEvaluateThisProvider(strategyContext: StrategyPerProviderContext, evalContext: EvaluationContext): boolean;
+
+  shouldEvaluateNextProvider<T extends FlagValue>(
     strategyContext: StrategyPerProviderContext,
     context: EvaluationContext,
     result: ProviderResolutionResult<T>,
   ): boolean;
 
-  abstract shouldTrackWithThisProvider(
+  shouldTrackWithThisProvider(
     strategyContext: StrategyPerProviderContext,
     context: EvaluationContext,
     trackingEventName: string,
@@ -161,16 +175,14 @@ export abstract class BaseEvaluationStrategy {
 }
 ```
 
-The `runMode` property determines whether the list of providers will be evaluated sequentially or in parallel.
+The methods serve the following purposes:
+
+- **`runMode`**: Property that determines whether providers are evaluated `'sequential'` (default) or `'parallel'`.
 
-The `shouldEvaluateThisProvider` method is called just before a provider is evaluated by the Multi-Provider. If the function returns `false`, then
-the provider will be skipped instead of being evaluated. The function is called with details about the evaluation including the flag key and type.
-Check the type definitions for the full list.
+- **`shouldEvaluateThisProvider`**: Called before evaluating each provider. Return `false` to skip the provider. By default, skips providers in `NOT_READY` or `FATAL` status.
 
-The `shouldEvaluateNextProvider` function is called after a provider is evaluated. If it returns `true`, the next provider in the sequence will be called,
-otherwise no more providers will be evaluated. It is called with the same data as `shouldEvaluateThisProvider` as well as the details about the evaluation result. This function is not called when the `runMode` is `parallel`.
+- **`shouldEvaluateNextProvider`**: Called after evaluating a provider (sequential mode only). Return `true` to continue to the next provider, `false` to stop.
 
-The `shouldTrackWithThisProvider` method is called before sending a tracking event to each provider. Return `false` to skip tracking with that provider. By default, it only tracks with providers that are in a ready state (not `NOT_READY` or `FATAL`). Override this method to implement custom tracking logic based on the tracking event name, details, or provider characteristics.
+- **`shouldTrackWithThisProvider`**: Called before sending a tracking event to each provider. Return `false` to skip tracking. By default, skips providers in `NOT_READY` or `FATAL` status.
 
-The `determineFinalResult` function is called after all providers have been called, or the `shouldEvaluateNextProvider` function returned false. It is called
-with a list of results from all the individual providers' evaluations. It returns the final decision for evaluation result, or throws an error if needed.
+- **`determineFinalResult`**: Called after all providers have been evaluated. Takes the list of provider results and returns the final resolution. This is the only abstract method that must be implemented by subclasses.

packages/server/src/provider/multi-provider/index.ts

@@ -1,3 +1,2 @@
 export * from './multi-provider';
-export * from './errors';
 export * from './strategies';

packages/server/src/provider/multi-provider/multi-provider.ts

@@ -13,17 +13,27 @@ import type {
   ProviderMetadata,
   ResolutionDetails,
   TrackingEventDetails,
+  BaseProviderResolutionResult,
+  ProviderEntryInput,
+  RegisteredProvider,
+  BaseEvaluationStrategy,
 } from '@openfeature/core';
-import { DefaultLogger, ErrorCode, GeneralError, StandardResolutionReasons } from '@openfeature/core';
+import {
+  DefaultLogger,
+  ErrorCode,
+  GeneralError,
+  StandardResolutionReasons,
+  constructAggregateError,
+  throwAggregateErrorFromPromiseResults,
+  StatusTracker,
+} from '@openfeature/core';
+import { FirstMatchStrategy } from './strategies';
 import type { Provider } from '../provider';
+import { ProviderStatus } from '../provider';
 import type { Hook } from '../../hooks';
 import { OpenFeatureEventEmitter } from '../../events/open-feature-event-emitter';
-import { constructAggregateError, throwAggregateErrorFromPromiseResults } from './errors';
+import { ProviderEvents } from '../../events';
 import { HookExecutor } from './hook-executor';
-import { StatusTracker } from './status-tracker';
-import type { BaseEvaluationStrategy, ProviderResolutionResult } from './strategies';
-import { FirstMatchStrategy } from './strategies';
-import type { ProviderEntryInput, RegisteredProvider } from './types';
 
 export class MultiProvider implements Provider {
   readonly runsOn = 'server';
@@ -35,15 +45,19 @@ export class MultiProvider implements Provider {
 
   metadata: ProviderMetadata;
 
-  providerEntries: RegisteredProvider[] = [];
-  private providerEntriesByName: Record<string, RegisteredProvider> = {};
+  providerEntries: RegisteredProvider<Provider>[] = [];
+  private providerEntriesByName: Record<string, RegisteredProvider<Provider>> = {};
 
   private hookExecutor: HookExecutor;
-  private statusTracker = new StatusTracker(this.events);
+  private statusTracker = new StatusTracker<
+    (typeof ProviderEvents)[keyof typeof ProviderEvents],
+    ProviderStatus,
+    Provider
+  >(this.events, ProviderStatus, ProviderEvents);
 
   constructor(
-    readonly constructorProviders: ProviderEntryInput[],
-    private readonly evaluationStrategy: BaseEvaluationStrategy = new FirstMatchStrategy(),
+    readonly constructorProviders: ProviderEntryInput<Provider>[],
+    private readonly evaluationStrategy: BaseEvaluationStrategy<ProviderStatus, Provider> = new FirstMatchStrategy(),
     private readonly logger: Logger = new DefaultLogger(),
   ) {
     this.hookExecutor = new HookExecutor(this.logger);
@@ -60,7 +74,7 @@ export class MultiProvider implements Provider {
     };
   }
 
-  private registerProviders(constructorProviders: ProviderEntryInput[]) {
+  private registerProviders(constructorProviders: ProviderEntryInput<Provider>[]) {
     const providersByName: Record<string, Provider[]> = {};
 
     for (const constructorProvider of constructorProviders) {
@@ -147,7 +161,7 @@ export class MultiProvider implements Provider {
       throw new GeneralError('Hook context not available for evaluation');
     }
 
-    const tasks: Promise<[boolean, ProviderResolutionResult<T> | null]>[] = [];
+    const tasks: Promise<[boolean, BaseProviderResolutionResult<T, ProviderStatus, Provider> | null]>[] = [];
 
     for (const providerEntry of this.providerEntries) {
       const task = this.evaluateProviderEntry(
@@ -173,7 +187,7 @@ export class MultiProvider implements Provider {
     const results = await Promise.all(tasks);
     const resolutions = results
       .map(([, resolution]) => resolution)
-      .filter((r): r is ProviderResolutionResult<T> => Boolean(r));
+      .filter((r): r is BaseProviderResolutionResult<T, ProviderStatus, Provider> => Boolean(r));
 
     const finalResult = this.evaluationStrategy.determineFinalResult({ flagKey, flagType }, context, resolutions);
 
@@ -192,11 +206,11 @@ export class MultiProvider implements Provider {
     flagKey: string,
     flagType: FlagValueType,
     defaultValue: T,
-    providerEntry: RegisteredProvider,
+    providerEntry: RegisteredProvider<Provider>,
     hookContext: HookContext,
     hookHints: HookHints,
     context: EvaluationContext,
-  ): Promise<[boolean, ProviderResolutionResult<T> | null]> {
+  ): Promise<[boolean, BaseProviderResolutionResult<T, ProviderStatus, Provider> | null]> {
     let evaluationResult: ResolutionDetails<T> | undefined = undefined;
     const provider = providerEntry.provider;
     const strategyContext = {
@@ -211,19 +225,19 @@ export class MultiProvider implements Provider {
       return [true, null];
     }
 
-    let resolution: ProviderResolutionResult<T>;
+    let resolution: BaseProviderResolutionResult<T, ProviderStatus, Provider>;
 
     try {
       evaluationResult = await this.evaluateProviderAndHooks(flagKey, defaultValue, provider, hookContext, hookHints);
       resolution = {
         details: evaluationResult,
-        provider: provider,
+        provider,
         providerName: providerEntry.name,
       };
     } catch (error: unknown) {
       resolution = {
         thrownError: error,
-        provider: provider,
+        provider,
         providerName: providerEntry.name,
       };
     }

packages/server/src/provider/multi-provider/status-tracker.ts

@@ -0,0 +1,67 @@
+/**
+ * Pre-configured strategy exports for the server SDK.
+ * These classes extend the base strategies from @openfeature/core with the
+ * server-specific ProviderStatus enum already bound.
+ */
+import {
+  BaseFirstMatchStrategy,
+  BaseFirstSuccessfulStrategy,
+  BaseComparisonStrategy,
+  type BaseStrategyProviderContext,
+  type BaseStrategyPerProviderContext,
+  type BaseProviderResolutionResult,
+  type BaseProviderResolutionSuccessResult,
+  type BaseProviderResolutionErrorResult,
+  type BaseFinalResult,
+  type StrategyEvaluationContext,
+  type FlagValue,
+} from '@openfeature/core';
+import type { Provider } from '../provider';
+import { ProviderStatus } from '../provider';
+
+/**
+ * Pre-bound type aliases for server SDK.
+ * These types have the server-specific ProviderStatus and Provider types already applied,
+ * providing backward compatibility for existing consumers.
+ */
+export type StrategyProviderContext = BaseStrategyProviderContext<ProviderStatus, Provider>;
+export type StrategyPerProviderContext = BaseStrategyPerProviderContext<ProviderStatus, Provider>;
+export type ProviderResolutionResult<T extends FlagValue> = BaseProviderResolutionResult<T, ProviderStatus, Provider>;
+export type ProviderResolutionSuccessResult<T extends FlagValue> = BaseProviderResolutionSuccessResult<
+  T,
+  ProviderStatus,
+  Provider
+>;
+export type ProviderResolutionErrorResult = BaseProviderResolutionErrorResult<ProviderStatus, Provider>;
+export type FinalResult<T extends FlagValue> = BaseFinalResult<T, ProviderStatus, Provider>;
+export type { StrategyEvaluationContext };
+
+/**
+ * Evaluates providers in order and returns the first successful result.
+ * Providers that return FLAG_NOT_FOUND are skipped. Any other error stops evaluation.
+ */
+export class FirstMatchStrategy extends BaseFirstMatchStrategy<ProviderStatus, Provider> {
+  constructor() {
+    super(ProviderStatus);
+  }
+}
+
+/**
+ * Evaluates providers in order and returns the first successful result.
+ * Any error causes that provider to be skipped.
+ */
+export class FirstSuccessfulStrategy extends BaseFirstSuccessfulStrategy<ProviderStatus, Provider> {
+  constructor() {
+    super(ProviderStatus);
+  }
+}
+
+/**
+ * Evaluates all providers in parallel and compares results.
+ * If all providers agree, returns that result. Otherwise, returns the fallback provider's result.
+ */
+export class ComparisonStrategy extends BaseComparisonStrategy<ProviderStatus, Provider> {
+  constructor(fallbackProvider: Provider, onMismatch?: (resolutions: ProviderResolutionResult<FlagValue>[]) => void) {
+    super(ProviderStatus, fallbackProvider, onMismatch);
+  }
+}