@configdirector/nuxt-sdk 1.6.1 → 1.8.0

package/dist/testing.d.mts

@@ -0,0 +1,352 @@
+//#region ../js-client-core/src/Emitter.d.ts
+type EventType = string | symbol;
+type EventsRecord = Record<EventType, any>;
+type Handler<TEventsRecord extends EventsRecord, TKey extends keyof TEventsRecord> = (payload: TEventsRecord[TKey]) => void;
+interface EventProvider<TEventsRecord extends EventsRecord> {
+  on<TName extends keyof TEventsRecord>(name: TName, handler: Handler<TEventsRecord, TName>): void;
+  off<TName extends keyof TEventsRecord>(name: TName, handler?: Handler<TEventsRecord, TName>): void;
+  clear(): void;
+}
+//#endregion
+//#region ../shared/src/types.d.ts
+type ConfigEnumLikeType = {
+  [key: string]: string | number;
+};
+type ConfigValueType = string | number | boolean | object | ConfigEnumLikeType;
+interface ConfigDirectorLogger {
+  debug(message: string, ...args: any): void;
+  info(message: string, ...args: any): void;
+  warn(message: string, ...args: any): void;
+  error(message: string, ...args: any): void;
+}
+type EvaluationReason = "found-match" | "config-state-missing" | "client-not-ready" | "type-mismatch" | "value-missing" | "invalid-number" | "invalid-json" | "invalid-boolean";
+type ConfigEvaluation = {
+  key: string;
+  value: ConfigValueType;
+  valueId?: string;
+  isDefaultValue: boolean;
+  reason: EvaluationReason;
+  context?: ConfigDirectorContext;
+};
+/**
+ * The user's context to be sent to ConfigDirector. This context will be used for targeting
+ * rules evaluation.
+ */
+type ConfigDirectorContext = {
+  /**
+   * The user's identifier. This should be a value that uniquely identifies an application
+   * user.
+   * In the case of anonymous users, you could generate a UUID or alternatively not provide
+   * the {@link id} and the SDK will generate a random UUID. However, keep in mind that this
+   * value is used for segmenting users in percentage rollouts, and changes to the {@link id}
+   * could result in the user being assigned to a different percentile.
+   */
+  id?: string;
+  /**
+   * The user's display name. This will be shown in the ConfigDirector dashboard and may be
+   * used for targeting rules.
+   */
+  name?: string;
+  /**
+   * Any arbitrary traits for the current user. They will be shown in the ConfigDirector
+   * dashboard and may be used for targeting rules.
+   */
+  traits?: {
+    [key: string]: unknown;
+  };
+  /**
+   * Whether or not to treat the context as anonymous during evaluation. When `true`, the
+   * context values will be used for targeting rules evaluation but the context will not be
+   * persisted and will not appear in the dashboard.
+   *
+   * @default false
+   */
+  anonymous?: boolean;
+};
+//#endregion
+//#region ../js-client-core/src/types.d.ts
+type ClientConnectAction = "initialization" | "context update" | "network resume";
+type ClientEvents = {
+  configsUpdated: {
+    keys: string[];
+    removedKeys: string[];
+  };
+  clientReady: {
+    action: ClientConnectAction;
+  };
+  contextUpdated: {
+    context: ConfigDirectorContext | undefined;
+  };
+  configEvaluated: {
+    evaluation: ConfigEvaluation;
+  };
+  connectionError: {
+    error: Error;
+  };
+};
+type WatchHandler<T extends ConfigValueType> = (message: T) => void;
+/**
+ * The ConfigDirector SDK client object.
+ *
+ * Applications should create a single instance of `ConfigDirectorClient`, and call
+ * {@link initialize} during application initialization.
+ *
+ * After initialization, to update the user's context, so that targeting rules are evaluated
+ * with the updated context, call {@link updateContext}.
+ */
+interface ConfigDirectorClient extends EventProvider<ClientEvents> {
+  /**
+   * Initializes the connection to ConfigDirector to retrieve config evaluations. Until
+   * initialization is successful, all flags will return their default value provided to
+   * {@link watch} or {@link getValue}.
+   *
+   * If the connection fails or is interrupted with a transient error (network error,
+   * internal server error, etc) the client will continue to attempt to connect. However,
+   * if the connection fails with a persistent error, like an invalid SDK key, the client will
+   * not attempt to re-connect and an error will be logged to the console or the provided
+   * logger.
+   *
+   * @param context The current user's context to be used for evaluating targeting rules (optional).
+   */
+  initialize(context?: ConfigDirectorContext): Promise<void>;
+  /**
+   * Updates the user's context and re-evaluates all config and flag values based on the new context.
+   *
+   * @param context The current user's context to be used for evaluating targeting rules (required).
+   */
+  updateContext(context: ConfigDirectorContext): Promise<void>;
+  /**
+   * Returns the current context the client is configured with, or undefined if there is no context.
+   *
+   * Note that the value returned does not updated immediately after calling {@link updateContext}. Only
+   * once the underlying connection was successful or timed out, the current context is updated. This is
+   * because while the context update is in progress, configs are still evaluated on the previous context.
+   *
+   */
+  get context(): ConfigDirectorContext | undefined;
+  /**
+   * Returns whether or not the client is ready after calling {@link initialize} or {@link updateContext}
+   *
+   * The definition of ready is that the connection to the server was successful, and config state
+   * was received.
+   */
+  get isReady(): boolean;
+  /**
+   * Whether the client is trying to get its very first payload from the server. Upon client creation,
+   * it is `false`. It becomes `true` when `initialize` is called on a client that has never received a
+   * payload, stays `true` through timeouts and retries, and becomes `false` when the first payload
+   * arrives, when a fatal connection error stops the retries, or on `close`. `updateContext` and
+   * `resumeNetwork` never set it, and once a payload has been received it is never `true` again.
+   */
+  get isInitializing(): boolean;
+  /**
+   * Evaluates a config and returns its value based on the current context and targeting rules
+   *
+   * @returns The evaluated config value, or the `defaultValue` if the config state was unavailable
+   * @param configKey The config key to evaluate
+   * @param defaultValue The default value to be returned if the config state is unavailable. For
+   * example, if the client cannot connect to the server due to network conditions, or if getValue
+   * is called before initialization is done.
+   */
+  getValue<T extends ConfigValueType>(configKey: string, defaultValue: T): T;
+  /**
+   * Watches for changes to a a config evaluation value. Whenever the config value changes, the
+   * provided callback function will be called with the new value. Changes can happen due to updates
+   * to the config in the ConfigDirector dashboard, or if the context is updated via {@link updateContext}.
+   *
+   * @returns An 'unwatch' function that can be called to remove the subscriber
+   *
+   * @param configKey The config key to watch
+   * @param defaultValue The default value to be referenced if the config state is unavailable
+   * @param callback The callback function to be called whenever the config value is updated
+   */
+  watch<T extends ConfigValueType>(configKey: string, defaultValue: T, callback: WatchHandler<T>): () => void;
+  /**
+   * Removes a particular subscriber to the given `configKey`, or all subscribers if no callback
+   * is provided.
+   *
+   * @param configKey The config key to remove subscribers from
+   * @param callback The subscriber to be removed. If not provided, all subscribers are removed for
+   * the given `configKey`.
+   */
+  unwatch<T extends ConfigValueType>(configKey: string, callback?: WatchHandler<T>): void;
+  /**
+   * Removes all subscribers from all config keys
+   */
+  unwatchAll(): void;
+  /**
+   * Pauses the network connection without clearing event handlers, watch handlers, or config
+   * state. Intended for mobile environments where the OS may kill background connections (e.g.
+   * when the app is backgrounded on iOS/Android).
+   *
+   * Call {@link resumeNetwork} to re-establish the connection.
+   */
+  pauseNetwork(): void;
+  /**
+   * Resumes a connection that was paused via {@link pauseNetwork}, using the last context that
+   * was provided to {@link initialize} or {@link updateContext}.
+   */
+  resumeNetwork(): Promise<void>;
+  /**
+   * Disposes of the client. All connections are closed, and all event and config key subscribers
+   * are removed.
+   *
+   * Intended to be called when your application shuts down
+   */
+  dispose(): void;
+}
+//#endregion
+//#region ../shared/src/testing/values.d.ts
+type TestJsonValue = boolean | number | string | null | TestJsonValue[] | {
+  [key: string]: TestJsonValue;
+};
+type TestValue = boolean | number | string | TestJsonValue[] | {
+  [key: string]: TestJsonValue;
+};
+type TestValues = Record<string, TestValue>;
+//#endregion
+//#region ../js-client-core/src/testing/TestClient.d.ts
+/**
+ * Options for {@link createTestClient}. Every option is optional.
+ */
+type TestClientOptions = {
+  /**
+   * The config values the test client serves once its client connects, keyed by config key. The
+   * config type follows from each value: a boolean, an integral number (`integer`), any other
+   * number (`float`), a string, or a plain object or array (`json`).
+   */
+  values?: TestValues;
+  /**
+   * The connection timeout of the SDK client, in milliseconds. It bounds how long a held
+   * `initialize` or `updateContext` waits. Defaults to the SDK's production timeout.
+   */
+  timeout?: number;
+  /**
+   * The logger the SDK client uses. Defaults to the SDK's console logger at `warn` level.
+   */
+  logger?: ConfigDirectorLogger;
+};
+/**
+ * A real ConfigDirector client connected to an in-memory server that the test controls.
+ *
+ * The client under {@link TestClient.client} is the SDK's production client: value parsing, watchers,
+ * events, and readiness behave as they do against ConfigDirector. Only the network connection and
+ * telemetry are replaced, so no request is ever made and nothing is left running after the client is
+ * disposed.
+ */
+interface TestClient {
+  /**
+   * The SDK client to hand to the code under test. It starts uninitialized, like a production
+   * client; `initialize` completes at once with the seeded values unless initialization is held.
+   */
+  readonly client: ConfigDirectorClient;
+  /**
+   * Stores `value` under `key` and, when the client is connected, delivers it as an update, so
+   * reads, watchers, and `configsUpdated` handlers see it.
+   */
+  setValue(key: string, value: TestValue): void;
+  /**
+   * Removes `key` and, when the client is connected, delivers a full update without it, so reads
+   * fall back to the in-code default value and watchers of `key` receive that default.
+   */
+  removeValue(key: string): void;
+  /**
+   * Replaces every stored value with `values`, disarms any armed hold or failure, and, when the
+   * client is connected, delivers the new values as a full update.
+   */
+  replaceValues(values: TestValues): void;
+  /**
+   * Makes the next `initialize` wait until {@link completeInitialization} or
+   * {@link failInitialization} is called, or until the client's timeout elapses.
+   */
+  holdInitialization(): void;
+  /**
+   * Delivers the stored values to a held `initialize`, so it completes with the client ready. When
+   * a hold is armed but no `initialize` has started, it disarms the hold instead.
+   */
+  completeInitialization(): void;
+  /**
+   * Fails a held `initialize` with an unrecoverable connection error, or arms the next `initialize`
+   * to fail. `initialize` completes promptly with the client not ready and `connectionError` fires.
+   */
+  failInitialization(): void;
+  /**
+   * Makes the next `updateContext` wait until {@link completeContextUpdate} or
+   * {@link failContextUpdate} is called, or until the client's timeout elapses.
+   */
+  holdContextUpdate(): void;
+  /**
+   * Delivers the stored values to a held `updateContext`, or disarms an armed hold that no
+   * `updateContext` has picked up.
+   */
+  completeContextUpdate(): void;
+  /**
+   * Fails a held `updateContext` with an unrecoverable connection error, or arms the next
+   * `updateContext` to fail.
+   */
+  failContextUpdate(): void;
+  /**
+   * The context of every `initialize` and `updateContext` call, in call order. `initialize` without
+   * a context records an empty context. Resumes are not recorded.
+   */
+  readonly contextUpdates: ConfigDirectorContext[];
+}
+//#endregion
+//#region ../js-client-core/src/testing/installTestClient.d.ts
+/**
+ * Makes every `ConfigDirectorProvider` mounted without a `client` prop, and every client
+ * `withProvider` would build, use `testClient.client` instead of building a client, until the
+ * returned function uninstalls it. Construction props such as `sdkKey` are ignored while installed;
+ * `context` and `hooks` apply to the installed client as they do for a `client` prop. A provider
+ * reads the installed client when it is constructed, so install before rendering.
+ *
+ * Installing again replaces the installed test client. Each uninstall function restores the test
+ * client that was installed when it was created, so nested installs are uninstalled in reverse order.
+ *
+ * @param testClient The test client whose `client` providers should use
+ * @returns A function that uninstalls it
+ *
+ * @example
+ * let uninstallTestClient: () => void;
+ * beforeEach(() => {
+ *   testClient = createTestClient({ values: { "new-checkout": true } });
+ *   uninstallTestClient = installTestClient(testClient);
+ * });
+ * afterEach(() => uninstallTestClient());
+ */
+declare const installTestClient: (testClient: TestClient) => (() => void);
+//#endregion
+//#region ../shared/src/errors.d.ts
+declare class ConfigDirectorConnectionError extends Error {
+  readonly name: string;
+  readonly status?: number;
+  constructor(message: string, status?: number);
+}
+declare class ConfigDirectorValidationError extends Error {
+  readonly name: string;
+  constructor(message: string);
+}
+//#endregion
+//#region src/testing.d.ts
+/**
+ * Creates a {@link TestClient}: a real `ConfigDirectorClient` connected to an in-memory server
+ * that the test controls. No network connection is opened and no telemetry is sent. Hand it to the
+ * ConfigDirector Nuxt plugin with `installTestClient` before the Nuxt app is created.
+ *
+ * @param options {@link TestClientOptions}: the initial values, the client's timeout, and its logger
+ * @returns A {@link TestClient} whose `client` the plugin provides to the app
+ *
+ * @example
+ * import { createTestClient, installTestClient } from "@configdirector/nuxt-sdk/testing";
+ *
+ * const testClient = createTestClient({ values: { "new-checkout": true } });
+ * installTestClient(testClient);
+ *
+ * test("shows the new checkout when the flag is on", async () => {
+ *   const component = await mountSuspended(Checkout);
+ *   expect(component.text()).toContain("New checkout");
+ * });
+ */
+declare const createTestClient: (options?: TestClientOptions) => TestClient;
+//#endregion
+export { ConfigDirectorConnectionError, ConfigDirectorValidationError, type TestClient, type TestClientOptions, type TestJsonValue, type TestValue, type TestValues, createTestClient, installTestClient };