chore: add node-client-sdk types, options validation, and basic logger

Author: joker23

packages/sdk/node-client/__tests__/options.test.ts

@@ -0,0 +1,97 @@
+import type { NodeOptions } from '../src/NodeOptions';
+import validateOptions, { filterToBaseOptions, ValidatedOptions } from '../src/options';
+import { createMockLogger } from './testHelpers';
+
+// A value no option validator should accept regardless of the field's expected type
+const BOGUS_VALUE = Symbol('invalid-option-value');
+
+// Exhaustive over keyof ValidatedOptions: adding a new node-specific option fails to compile
+// here until a bogus case is added, which forces the wrong-type-warning test below to cover
+// it.
+const wrongTypedOptions: Record<keyof ValidatedOptions, unknown> = {
+  tlsParams: BOGUS_VALUE,
+  enableEventCompression: BOGUS_VALUE,
+  initialConnectionMode: BOGUS_VALUE,
+  plugins: BOGUS_VALUE,
+  localStoragePath: BOGUS_VALUE,
+  hash: BOGUS_VALUE,
+};
+
+const nodeOptionKeys = Object.keys(wrongTypedOptions) as (keyof ValidatedOptions)[];
+
+let logger: ReturnType<typeof createMockLogger>;
+
+beforeEach(() => {
+  logger = createMockLogger();
+});
+
+it('applies defaults when no node-specific options are provided', () => {
+  const out = validateOptions({}, logger);
+
+  expect(out.initialConnectionMode).toBe('streaming');
+  expect(out.plugins).toEqual([]);
+  expect(out.tlsParams).toBeUndefined();
+  expect(out.enableEventCompression).toBeUndefined();
+  expect(out.localStoragePath).toBeUndefined();
+  expect(out.hash).toBeUndefined();
+  expect(logger.warn).not.toHaveBeenCalled();
+});
+
+it('passes through valid node-specific options', () => {
+  const out = validateOptions(
+    {
+      initialConnectionMode: 'polling',
+      enableEventCompression: true,
+      localStoragePath: '/tmp/ld-cache',
+      hash: 'abc123',
+    },
+    logger,
+  );
+
+  expect(out.initialConnectionMode).toBe('polling');
+  expect(out.enableEventCompression).toBe(true);
+  expect(out.localStoragePath).toBe('/tmp/ld-cache');
+  expect(out.hash).toBe('abc123');
+  expect(logger.warn).not.toHaveBeenCalled();
+});
+
+it('warns and falls back to the default for an invalid initialConnectionMode', () => {
+  const out = validateOptions({ initialConnectionMode: 'STREAMING' as any }, logger);
+
+  expect(out.initialConnectionMode).toBe('streaming');
+  expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('initialConnectionMode'));
+});
+
+it('warns when TLS certificate verification is disabled', () => {
+  validateOptions({ tlsParams: { rejectUnauthorized: false } }, logger);
+
+  expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('rejectUnauthorized'));
+});
+
+it('strips every node-specific option from the base options but keeps base options', () => {
+  const opts: NodeOptions = {
+    initialConnectionMode: 'polling',
+    plugins: [],
+    tlsParams: {},
+    enableEventCompression: true,
+    localStoragePath: '/tmp/ld-cache',
+    hash: 'abc123',
+    sendEvents: false,
+  };
+
+  const base = filterToBaseOptions(opts) as Record<string, unknown>;
+
+  nodeOptionKeys.forEach((key) => {
+    expect(base).not.toHaveProperty(key);
+  });
+  expect(base).toHaveProperty('sendEvents', false);
+});
+
+it('warns for every validated option when given a value of the wrong type', () => {
+  nodeOptionKeys.forEach((key) => {
+    const fieldLogger = createMockLogger();
+    validateOptions({ [key]: wrongTypedOptions[key] } as unknown as NodeOptions, fieldLogger);
+
+    expect(fieldLogger.warn).toHaveBeenCalledWith(expect.stringContaining(key));
+  });
+});

packages/sdk/node-client/package.json

@@ -47,8 +47,12 @@
   "devDependencies": {
     "@eslint/js": "^9.0.0",
     "@types/jest": "^29.4.0",
+    "@types/node": "^25.9.1",
+    "@typescript-eslint/eslint-plugin": "^6.20.0",
+    "@typescript-eslint/parser": "^6.20.0",
     "eslint": "^9.0.0",
     "eslint-import-resolver-typescript": "^4.0.0",
+    "eslint-plugin-import": "^2.27.5",
     "eslint-plugin-import-x": "^4.0.0",
     "eslint-plugin-jest": "^28.0.0",
     "globals": "^16.0.0",

packages/sdk/node-client/src/LDClient.ts

@@ -0,0 +1,49 @@
+import type {
+  ConnectionMode,
+  LDClient as LDClientBase,
+  LDContext,
+  LDIdentifyOptions,
+  LDIdentifyResult,
+  LDStartOptions,
+  LDWaitForInitializationResult,
+} from '@launchdarkly/js-client-sdk-common';
+
+export type { LDStartOptions };
+
+export interface LDClient extends Omit<LDClientBase, 'identify'> {
+  /**
+   * Identifies a context to LaunchDarkly and returns a promise which resolves to an object
+   * containing the result of the identify operation.
+   *
+   * @param context The context to identify @see {@link LDContext}
+   * @param identifyOptions Optional configuration @see {@link LDIdentifyOptions}.
+   * @returns an identify result @see {@link LDIdentifyResult}
+   */
+  identify(context: LDContext, identifyOptions?: LDIdentifyOptions): Promise<LDIdentifyResult>;
+
+  /**
+   * Starts the client by performing the first identify with the initial context. Must be
+   * called after {@link createClient}. The returned promise resolves when the first
+   * identify completes (or times out, or fails).
+   *
+   * @param options Optional configuration. See {@link LDStartOptions}.
+   */
+  start(options?: LDStartOptions): Promise<LDWaitForInitializationResult>;
+
+  /**
+   * Sets the data source connection mode.
+   *
+   * @see {@link ConnectionMode}
+   */
+  setConnectionMode(mode: ConnectionMode): Promise<void>;
+
+  /**
+   * Returns the current data source connection mode.
+   */
+  getConnectionMode(): ConnectionMode;
+
+  /**
+   * Returns true if the client is in offline mode.
+   */
+  isOffline(): boolean;
+}

packages/sdk/node-client/src/LDCommon.ts

@@ -0,0 +1,46 @@
+export type {
+  LDIdentifyOptions,
+  AutoEnvAttributes,
+  BasicLogger,
+  BasicLoggerOptions,
+  EvaluationSeriesContext,
+  EvaluationSeriesData,
+  Hook,
+  HookMetadata,
+  IdentifySeriesContext,
+  IdentifySeriesData,
+  IdentifySeriesResult,
+  IdentifySeriesStatus,
+  LDContext,
+  LDContextCommon,
+  LDContextMeta,
+  LDContextStrict,
+  LDEvaluationDetail,
+  LDEvaluationDetailTyped,
+  LDEvaluationReason,
+  LDFlagSet,
+  LDFlagValue,
+  LDTimeoutError,
+  LDInspection,
+  LDLogger,
+  LDLogLevel,
+  LDMultiKindContext,
+  LDSingleKindContext,
+  TrackSeriesContext,
+  LDPluginBase,
+  LDPluginEnvironmentMetadata,
+  LDPluginSdkMetadata,
+  LDPluginApplicationMetadata,
+  LDPluginMetadata,
+  LDIdentifyResult,
+  LDIdentifySuccess,
+  LDIdentifyError,
+  LDIdentifyTimeout,
+  LDIdentifyShed,
+  LDDebugOverride,
+  LDWaitForInitializationOptions,
+  LDWaitForInitializationResult,
+  LDWaitForInitializationComplete,
+  LDWaitForInitializationFailed,
+  LDWaitForInitializationTimeout,
+} from '@launchdarkly/js-client-sdk-common';

packages/sdk/node-client/src/LDPlugin.ts

@@ -0,0 +1,8 @@
+import { Hook, LDPluginBase } from '@launchdarkly/js-client-sdk-common';
+
+import { LDClient } from './LDClient';
+
+/**
+ * Interface for plugins to the LaunchDarkly SDK.
+ */
+export interface LDPlugin extends LDPluginBase<LDClient, Hook> {}

packages/sdk/node-client/src/NodeOptions.ts

@@ -1,3 +1,7 @@
+import { ConnectionMode, LDOptions as LDOptionsBase } from '@launchdarkly/js-client-sdk-common';
+
+import type { LDPlugin } from './LDPlugin';
+
 /**
  * Additional parameters to pass to the Node HTTPS API for secure requests.  These can include any
  * of the TLS-related parameters supported by `https.request()`, such as `ca`, `cert`, and `key`.
@@ -20,7 +24,7 @@ export interface LDTLSOptions {
 /**
  * Configuration options for the Node client-side SDK.
  */
-export interface NodeOptions {
+export interface NodeOptions extends LDOptionsBase {
   /**
    * Additional parameters to pass to the Node HTTPS API for secure requests.  These can include any
    * of the TLS-related parameters supported by `https.request()`, such as `ca`, `cert`, and `key`.
@@ -42,4 +46,26 @@ export interface NodeOptions {
    * Defaults to `<cwd>/ldclient-user-cache`.
    */
   localStoragePath?: string;
+
+  /**
+   * Sets the mode to use for connections when the SDK is initialized.
+   *
+   * @remarks
+   * Possible values are offline, streaming, or polling. See {@link ConnectionMode} for more information.
+   *
+   * Defaults to streaming.
+   */
+  initialConnectionMode?: ConnectionMode;
+
+  /**
+   * A list of plugins to be used with the SDK.
+   */
+  plugins?: LDPlugin[];
+
+  /**
+   * The Secure Mode hash for the configured context.
+   *
+   * @see https://docs.launchdarkly.com/sdk/features/secure-mode
+   */
+  hash?: string;
 }

packages/sdk/node-client/src/basicLogger.ts

@@ -0,0 +1,36 @@
+import { format } from 'util';
+
+import {
+  BasicLogger,
+  BasicLoggerOptions,
+  LDLogger,
+} from '@launchdarkly/js-client-sdk-common';
+
+/**
+ * Provides a basic {@link LDLogger} implementation.
+ *
+ * Output is written to `console.log` using Node's `util.format` so multiple arguments and
+ * format specifiers (`%s`, `%d`, etc.) are formatted the way Node consumers expect.
+ *
+ * If you do not pass a logger via {@link LDOptions.logger}, the SDK falls back to
+ * a logger equivalent to `basicLogger({ level: 'info' })`.
+ *
+ * @example
+ * ```javascript
+ * const ldOptions = {
+ *   logger: basicLogger({ level: 'warn' }),
+ * };
+ * ```
+ */
+export default function basicLogger(options: BasicLoggerOptions = {}): LDLogger {
+  return new BasicLogger({
+    ...options,
+    destination:
+      options.destination ??
+      ((line: string) => {
+        // eslint-disable-next-line no-console
+        console.log(line);
+      }),
+    formatter: options.formatter ?? format,
+  });
+}

packages/sdk/node-client/src/options.ts

@@ -0,0 +1,86 @@
+import {
+  ConnectionMode,
+  LDLogger,
+  LDOptions as LDOptionsBase,
+  OptionMessages,
+  TypeValidator,
+  TypeValidators,
+} from '@launchdarkly/js-client-sdk-common';
+
+import type { LDTLSOptions, NodeOptions } from './NodeOptions';
+import type { LDPlugin } from './LDPlugin';
+
+class ConnectionModeValidator implements TypeValidator {
+  is(u: unknown): u is ConnectionMode {
+    return u === 'offline' || u === 'streaming' || u === 'polling';
+  }
+  getType(): string {
+    return 'ConnectionMode (offline | streaming | polling)';
+  }
+}
+
+export interface ValidatedOptions {
+  tlsParams?: LDTLSOptions;
+  enableEventCompression?: boolean;
+  initialConnectionMode: ConnectionMode;
+  plugins: LDPlugin[];
+  localStoragePath?: string;
+  hash?: string;
+}
+
+const optDefaults: ValidatedOptions = {
+  tlsParams: undefined,
+  enableEventCompression: undefined,
+  initialConnectionMode: 'streaming',
+  plugins: [],
+  localStoragePath: undefined,
+  hash: undefined,
+};
+
+// Keyed off ValidatedOptions so adding a Node-specific option fails to compile until a
+// validator is registered here (and a default in optDefaults), forcing validation/logging
+// coverage for the new field.
+const validators: Record<keyof ValidatedOptions, TypeValidator> = {
+  tlsParams: TypeValidators.Object,
+  enableEventCompression: TypeValidators.Boolean,
+  initialConnectionMode: new ConnectionModeValidator(),
+  plugins: TypeValidators.createTypeArray('LDPlugin[]', {}),
+  localStoragePath: TypeValidators.String,
+  hash: TypeValidators.String,
+};
+
+export function filterToBaseOptions(opts: NodeOptions): LDOptionsBase {
+  const baseOptions: LDOptionsBase = { ...opts };
+
+  // Strip Node-specific keys so the common options validator does not warn about them.
+  Object.keys(optDefaults).forEach((key) => {
+    delete (baseOptions as any)[key];
+  });
+  return baseOptions;
+}
+
+export default function validateOptions(opts: NodeOptions, logger: LDLogger): ValidatedOptions {
+  const output: ValidatedOptions = { ...optDefaults };
+
+  Object.entries(validators).forEach((entry) => {
+    const [key, validator] = entry as [keyof ValidatedOptions, TypeValidator];
+    const value = opts[key];
+    if (value !== undefined) {
+      if (validator.is(value)) {
+        // @ts-ignore The type inference has some problems here.
+        output[key as keyof ValidatedOptions] = value as any;
+      } else {
+        logger.warn(OptionMessages.wrongOptionType(key, validator.getType(), typeof value));
+      }
+    }
+  });
+
+  if (output.tlsParams?.rejectUnauthorized === false) {
+    logger.warn(
+      'TLS certificate verification is disabled via tlsParams.rejectUnauthorized=false. ' +
+        'This is insecure and should not be used in production.',
+    );
+  }
+
+  return output;
+}