chore(vue-sdk): Add LDVueClient hardening, provider, plugin, and base composables (#1769)

Author: joker23

packages/sdk/vue/__tests__/client/LDVueClient.test.ts

@@ -105,3 +105,83 @@ it('does not notify context subscribers when identify does not complete', async
 
   expect(onContext).not.toHaveBeenCalled();
 });
+
+it('transitions to failed state and resolves (not rejects) when the base start() rejects', async () => {
+  const error = new Error('network failure');
+  createBaseClientMock.mockReturnValue(
+    makeBaseClient({ start: jest.fn(() => Promise.reject(error)) }),
+  );
+  const client = createClient('env-id', { kind: 'user', key: 'k' });
+
+  const subscriber = jest.fn();
+  client.onInitializationStatusChange(subscriber);
+
+  const result = await client.start();
+
+  expect(result).toEqual({ status: 'failed', error });
+  expect(client.getInitializationState()).toBe('failed');
+  expect(client.getInitializationError()).toBe(error);
+  expect(subscriber).toHaveBeenCalledWith({ status: 'failed', error });
+
+  // Late subscriber should also receive the cached failed result.
+  const lateSubscriber = jest.fn();
+  client.onInitializationStatusChange(lateSubscriber);
+  expect(lateSubscriber).toHaveBeenCalledWith({ status: 'failed', error });
+});
+
+it('start() notifies init-status subscribers once even if called multiple times', async () => {
+  const startMock = jest.fn(() => Promise.resolve<Result>({ status: 'complete' }));
+  createBaseClientMock.mockReturnValue(makeBaseClient({ start: startMock }));
+  const client = createClient('env-id', { kind: 'user', key: 'k' });
+
+  const earlySubscriber = jest.fn();
+  client.onInitializationStatusChange(earlySubscriber);
+
+  await client.start();
+  await client.start();
+
+  expect(startMock).toHaveBeenCalledTimes(2);
+  // The second start() bypasses the wrapper's then handler, so early subscribers are only notified once.
+  expect(earlySubscriber).toHaveBeenCalledTimes(1);
+  expect(earlySubscriber).toHaveBeenCalledWith({ status: 'complete' });
+
+  // A subscriber registered after both starts should still receive the cached result.
+  const lateSubscriber = jest.fn();
+  client.onInitializationStatusChange(lateSubscriber);
+  expect(lateSubscriber).toHaveBeenCalledWith({ status: 'complete' });
+});
+
+it('notifies context subscribers when start resolves with timeout', async () => {
+  createBaseClientMock.mockReturnValue(
+    makeBaseClient({ start: jest.fn(() => Promise.resolve<Result>({ status: 'timeout' })) }),
+  );
+  const client = createClient('env-id', { kind: 'user', key: 'k' });
+
+  const onContext = jest.fn();
+  client.onContextChange(onContext);
+
+  await client.start();
+
+  expect(client.isReady()).toBe(true);
+  expect(client.getInitializationState()).toBe('timeout');
+  expect(onContext).toHaveBeenCalledWith({ kind: 'user', key: 'context-key' });
+});
+
+it('does not let a getContext() throw affect the initialization result', async () => {
+  const boom = new Error('getContext boom');
+  createBaseClientMock.mockReturnValue(
+    makeBaseClient({
+      start: jest.fn(() => Promise.resolve<Result>({ status: 'complete' })),
+      getContext: jest.fn(() => { throw boom; }),
+    }),
+  );
+  const client = createClient('env-id', { kind: 'user', key: 'k' });
+  const subscriber = jest.fn();
+  client.onInitializationStatusChange(subscriber);
+
+  const result = await client.start();
+
+  expect(result.status).toBe('complete');
+  expect(client.getInitializationState()).toBe('complete');
+  expect(subscriber).toHaveBeenCalledWith({ status: 'complete' });
+});

packages/sdk/vue/__tests__/client/mockClient.ts

@@ -0,0 +1,95 @@
+import type { LDEvaluationDetailTyped } from '@launchdarkly/js-client-sdk';
+
+import type { LDVueClient } from '../../src/client/LDClient';
+
+export interface MockControls {
+  setBool: (v: boolean) => void;
+  emitChange: (key: string) => void;
+  handlerCount: (event: string) => number;
+  emitInitStatus: (r: { status: string; error?: Error }) => void;
+  emitContextChange: (c: unknown) => void;
+  subscriberCount: () => number;
+}
+
+/**
+ * A controllable in-memory LDVueClient stand-in for component tests. Returns the client plus a
+ * `controls` object used to drive events from tests.
+ */
+export function makeMockClient(initial?: {
+  ready?: boolean;
+  initializedState?: string;
+  boolValue?: boolean;
+}): { client: LDVueClient; controls: MockControls } {
+  let ready = initial?.ready ?? true;
+  let initializedState = initial?.initializedState ?? 'complete';
+  let boolValue = initial?.boolValue ?? true;
+  let initError: Error | undefined;
+
+  const handlers = new Map<string, Set<(...args: unknown[]) => void>>();
+  const initStatusSubs = new Set<(r: { status: string; error?: Error }) => void>();
+  const contextSubs = new Set<(c: unknown) => void>();
+
+  const addHandler = (event: string, h: (...args: unknown[]) => void) => {
+    if (!handlers.has(event)) {
+      handlers.set(event, new Set());
+    }
+    handlers.get(event)!.add(h);
+  };
+
+  const notReadyDetail = <T>(def: T): LDEvaluationDetailTyped<T> => ({
+    value: def,
+    variationIndex: null,
+    reason: { kind: 'ERROR', errorKind: 'CLIENT_NOT_READY' },
+  });
+
+  const client = {
+    getContext: () => ({ kind: 'user', key: 'context-key' }),
+    getInitializationState: () => initializedState,
+    getInitializationError: () => initError,
+    onInitializationStatusChange: (cb: (r: { status: string; error?: Error }) => void) => {
+      initStatusSubs.add(cb);
+      return () => initStatusSubs.delete(cb);
+    },
+    onContextChange: (cb: (c: unknown) => void) => {
+      contextSubs.add(cb);
+      return () => contextSubs.delete(cb);
+    },
+    isReady: jest.fn(() => ready),
+    boolVariation: jest.fn(() => boolValue),
+    stringVariation: jest.fn((_key: string, def: string) => def),
+    numberVariation: jest.fn((_key: string, def: number) => def),
+    jsonVariation: jest.fn((_key: string, def: unknown) => def),
+    boolVariationDetail: jest.fn((_key: string, def: boolean) => notReadyDetail(def)),
+    stringVariationDetail: jest.fn((_key: string, def: string) => notReadyDetail(def)),
+    numberVariationDetail: jest.fn((_key: string, def: number) => notReadyDetail(def)),
+    jsonVariationDetail: jest.fn((_key: string, def: unknown) => notReadyDetail(def)),
+    allFlags: jest.fn(() => ({})),
+    variation: jest.fn(),
+    identify: jest.fn(),
+    track: jest.fn(),
+    flush: jest.fn(),
+    start: jest.fn(),
+    close: jest.fn(),
+    on: jest.fn((event: string, h: (...args: unknown[]) => void) => addHandler(event, h)),
+    off: jest.fn((event: string, h: (...args: unknown[]) => void) => handlers.get(event)?.delete(h)),
+  };
+
+  const controls: MockControls = {
+    setBool: (v: boolean) => {
+      boolValue = v;
+    },
+    emitChange: (key: string) =>
+      handlers.get(`change:${key}`)?.forEach((h) => h({ kind: 'user', key: 'context-key' })),
+    handlerCount: (event: string) => handlers.get(event)?.size ?? 0,
+    emitInitStatus: (r: { status: string; error?: Error }) => {
+      ready = true;
+      initializedState = r.status;
+      initError = r.error;
+      initStatusSubs.forEach((cb) => cb(r));
+    },
+    emitContextChange: (c: unknown) => contextSubs.forEach((cb) => cb(c)),
+    subscriberCount: () => initStatusSubs.size + contextSubs.size,
+  };
+
+  return { client: client as unknown as LDVueClient, controls };
+}

packages/sdk/vue/__tests__/client/provider/createLDProvider.test.ts

@@ -0,0 +1,98 @@
+/**
+ * @jest-environment jsdom
+ */
+import { mount } from '@vue/test-utils';
+import { defineComponent, h } from 'vue';
+
+import { useLDClient } from '../../../src/client/composables';
+import { createLDProvider } from '../../../src/client/provider/LDProvider';
+import { makeMockClient } from '../mockClient';
+
+jest.mock('../../../src/client/LDVueClient', () => ({
+  createClient: jest.fn(),
+}));
+
+import { createClient } from '../../../src/client/LDVueClient';
+
+const createClientMock = createClient as jest.Mock;
+
+beforeEach(() => {
+  createClientMock.mockReset();
+});
+
+it('creates a client internally and provides it to children', () => {
+  const { client } = makeMockClient();
+  createClientMock.mockReturnValue(client);
+
+  let injected: unknown;
+  const Child = defineComponent({
+    setup() {
+      injected = useLDClient();
+      return () => h('div');
+    },
+  });
+
+  const Provider = createLDProvider('env-id', { kind: 'user', key: 'k' });
+  mount(Provider, { slots: { default: () => h(Child) } });
+
+  expect(injected).toBe(client);
+  expect(createClientMock).toHaveBeenCalledWith('env-id', { kind: 'user', key: 'k' }, undefined);
+});
+
+it('starts the client automatically by default', () => {
+  const { client } = makeMockClient();
+  createClientMock.mockReturnValue(client);
+
+  const Provider = createLDProvider('env-id', { kind: 'user', key: 'k' });
+  mount(Provider, { slots: { default: () => h('div') } });
+
+  expect(client.start).toHaveBeenCalledTimes(1);
+});
+
+it('does not start the client when deferInitialization is true', () => {
+  const { client } = makeMockClient();
+  createClientMock.mockReturnValue(client);
+
+  const Provider = createLDProvider('env-id', { kind: 'user', key: 'k' }, { deferInitialization: true });
+  mount(Provider, { slots: { default: () => h('div') } });
+
+  expect(client.start).not.toHaveBeenCalled();
+});
+
+it('merges top-level bootstrap into startOptions', () => {
+  const { client } = makeMockClient();
+  createClientMock.mockReturnValue(client);
+  const bootstrap = { 'my-flag': true };
+
+  const Provider = createLDProvider('env-id', { kind: 'user', key: 'k' }, { bootstrap });
+  mount(Provider, { slots: { default: () => h('div') } });
+
+  expect(client.start).toHaveBeenCalledWith(expect.objectContaining({ bootstrap }));
+});
+
+it('top-level bootstrap takes precedence over startOptions.bootstrap', () => {
+  const { client } = makeMockClient();
+  createClientMock.mockReturnValue(client);
+  const topLevel = { 'my-flag': true };
+  const startLevel = { 'my-flag': false };
+
+  const Provider = createLDProvider(
+    'env-id',
+    { kind: 'user', key: 'k' },
+    { bootstrap: topLevel, startOptions: { bootstrap: startLevel } },
+  );
+  mount(Provider, { slots: { default: () => h('div') } });
+
+  expect(client.start).toHaveBeenCalledWith(expect.objectContaining({ bootstrap: topLevel }));
+});
+
+it('passes ldOptions to the client factory', () => {
+  const { client } = makeMockClient();
+  createClientMock.mockReturnValue(client);
+  const ldOptions = { wrapperName: 'my-wrapper' };
+
+  const Provider = createLDProvider('env-id', { kind: 'user', key: 'k' }, { ldOptions });
+  mount(Provider, { slots: { default: () => h('div') } });
+
+  expect(createClientMock).toHaveBeenCalledWith('env-id', { kind: 'user', key: 'k' }, ldOptions);
+});

packages/sdk/vue/__tests__/client/provider/provider.test.ts

@@ -0,0 +1,74 @@
+/**
+ * @jest-environment jsdom
+ */
+import { mount } from '@vue/test-utils';
+import { h, nextTick } from 'vue';
+
+import { createLDProviderWithClient } from '../../../src/client/provider/LDProvider';
+import { makeMockClient } from '../mockClient';
+
+it('renders the default slot when no gating slots are provided', () => {
+  const { client } = makeMockClient({ ready: false, initializedState: 'initializing' });
+  const Provider = createLDProviderWithClient(client);
+
+  const wrapper = mount(Provider, { slots: { default: () => h('div', 'app') } });
+
+  expect(wrapper.text()).toBe('app');
+});
+
+it('renders the #initializing slot while initializing, then the default slot once complete', async () => {
+  const { client, controls } = makeMockClient({ ready: false, initializedState: 'initializing' });
+  const Provider = createLDProviderWithClient(client);
+
+  const wrapper = mount(Provider, {
+    slots: {
+      default: () => h('div', 'app'),
+      initializing: () => h('div', 'loading'),
+    },
+  });
+
+  expect(wrapper.text()).toBe('loading');
+
+  controls.emitInitStatus({ status: 'complete' });
+  await nextTick();
+
+  expect(wrapper.text()).toBe('app');
+});
+
+it('renders the #failed slot with the error when initialization fails', async () => {
+  const { client, controls } = makeMockClient({ ready: false, initializedState: 'initializing' });
+  const Provider = createLDProviderWithClient(client);
+
+  const wrapper = mount(Provider, {
+    slots: {
+      default: () => h('div', 'app'),
+      failed: (props: { error?: Error }) => h('div', `failed:${props.error?.message}`),
+    },
+  });
+
+  controls.emitInitStatus({ status: 'failed', error: new Error('bad-key') });
+  await nextTick();
+
+  expect(wrapper.text()).toBe('failed:bad-key');
+});
+
+it('mounts without crashing when getContext() throws during setup', () => {
+  const { client } = makeMockClient();
+  // @ts-ignore -- simulates a context with a circular reference that clone() would throw on
+  client.getContext = jest.fn(() => { throw new Error('circular reference'); });
+
+  const Provider = createLDProviderWithClient(client);
+  expect(() => mount(Provider, { slots: { default: () => h('div', 'app') } })).not.toThrow();
+});
+
+it('unsubscribes from the client on unmount', () => {
+  const { client, controls } = makeMockClient();
+  const Provider = createLDProviderWithClient(client);
+
+  const wrapper = mount(Provider, { slots: { default: () => h('div', 'app') } });
+  expect(controls.subscriberCount()).toBe(2);
+
+  wrapper.unmount();
+
+  expect(controls.subscriberCount()).toBe(0);
+});