VS Code Treatment Assignment Service (TAS) Client

Common errors

• TypeError: Cannot read properties of undefined (reading 'globalState')

  cause The `memento` argument passed to `getExperimentationService` or `getExperimentationServiceAsync` was `undefined` or not a valid `vscode.Memento` instance. This typically occurs when the package is used outside of a VS Code extension's `activate` context or `context.globalState` is not properly provided.
  fix Ensure your extension's `activate` function correctly receives `vscode.ExtensionContext` and that `context.globalState` is passed as the `memento` argument to the experimentation service initialization function.

• TypeError: experimentationService.getTreatmentVariableAsync is not a function

  cause Attempting to call `getTreatmentVariableAsync` on an `IExperimentationService` instance that was not properly awaited during its acquisition, or attempting to use `getTreatmentVariableAsync` on an outdated version of the service.
  fix Always use `await getExperimentationServiceAsync(...)` to get the service instance. Ensure you are calling `getTreatmentVariableAsync` on the `IExperimentationService` instance, not a raw promise or an uninitialized object. Verify your package version supports the async method.

• Telemetry Event: query-expfeature {...} (but no expected experiment data)

  cause The telemetry event `query-expfeature` is sent, but the associated common properties (`vscode.abexp.features` or `abexp.assignmentcontext`) or the expected treatment variable values are missing or are default values, indicating the experiment data was not successfully loaded.
  fix Verify that `getExperimentationServiceAsync` was used for initialization. Check network connectivity to TAS and ensure your `extensionName`, `extensionVersion`, and `targetPopulation` are correctly configured, as these are used for traffic filtering.

Warnings

• gotcha Using `getExperimentationService` (synchronous) instead of `getExperimentationServiceAsync` for initial service acquisition might lead to experiment values not being immediately available from cache, potentially serving default values until a background refresh or manual initialization completion. This can result in users not being assigned to the correct experiment group on first run.
  Fix: Always prefer `getExperimentationServiceAsync` for initial service acquisition. This method awaits the internal `initializePromise`, ensuring cached data is loaded before the service is used for querying treatment variables.
• gotcha Subsequent calls to `experimentationService.getTreatmentVariable(configId, name)` within the same user session will consistently return the *cached* value obtained during the first call or initialization. This design choice prevents unexpected mid-session user experience changes, even if a background refresh has occurred and new values are available in the cache.
  Fix: To explicitly force a refresh and retrieve the very latest treatment variable value from the TAS, use `await experimentationService.getTreatmentVariableAsync(configId, name)`. Be mindful that this might cause a network request and could alter the user experience mid-session.
• gotcha The `vscode-tas-client` package makes HTTP requests to the TAS server initially upon service acquisition and then periodically every 30 minutes for background refreshes. Extensions operating in environments with strict network policies, offline modes, or limited connectivity should account for this network activity.
  Fix: Ensure that the VS Code process (and by extension, the extension host) has appropriate network access to reach the TAS endpoints. For testing scenarios that require offline operation, consider mocking the `IExperimentationService`.
• gotcha This package is specifically designed for use within the VS Code extension host environment. It relies heavily on VS Code API objects like `vscode.Memento` (via `context.globalState`) and expects an `IExperimentationTelemetry` implementation. Attempting to use it in a standalone Node.js application, browser, or other non-VS Code contexts will lead to runtime errors.
  Fix: Develop and use this package exclusively within a VS Code extension. For unit testing, mock the `vscode.Memento` and `IExperimentationTelemetry` interfaces to simulate the VS Code environment.

Install

• npm install vscode-tas-client npm
• yarn add vscode-tas-client yarn
• pnpm add vscode-tas-client pnpm

Imports

• getExperimentationService
  wrong:

  const getExperimentationService = require('vscode-tas-client').getExperimentationService;

  correct:

  import { getExperimentationService } from 'vscode-tas-client';

  Initializes the experimentation service synchronously. For most cases, `getExperimentationServiceAsync` is preferred to ensure cached data is loaded.
• getExperimentationServiceAsync
  wrong:

  const getExperimentationServiceAsync = require('vscode-tas-client').getExperimentationServiceAsync;

  correct:

  import { getExperimentationServiceAsync } from 'vscode-tas-client';

  Asynchronous initialization; recommended as it awaits the internal `initializePromise` to ensure cached experiment data is loaded before the service instance is returned.
• IExperimentationService
  wrong:

  import IExperimentationService from 'vscode-tas-client';

  correct:

  import { IExperimentationService } from 'vscode-tas-client';

  TypeScript interface representing the experimentation service instance, providing methods like `getTreatmentVariable`.
• TargetPopulation
  wrong:

  const TargetPopulation = require('vscode-tas-client').TargetPopulation;

  correct:

  import { TargetPopulation } from 'vscode-tas-client';

  An enum used to specify the target user ring (e.g., `TargetPopulation.Public`, `TargetPopulation.Insiders`).
• IExperimentationTelemetry
  wrong:

  type IExperimentationTelemetry = any;

  correct:

  import { IExperimentationTelemetry } from 'vscode-tas-client';

  TypeScript interface for the telemetry service, which must be implemented and passed during service initialization to enable experiment analysis and counterfactual logging.

Quickstart

This quickstart initializes the `vscode-tas-client` experimentation service within a VS Code extension's `activate` function and demonstrates how to retrieve treatment variable values, including forcing a refresh for the latest data. It also includes a mock telemetry implementation.

import * as vscode from 'vscode';
import {
  getExperimentationServiceAsync,
  TargetPopulation,
  IExperimentationService,
  IExperimentationTelemetry,
} from 'vscode-tas-client';

// A mock implementation for IExperimentationTelemetry to satisfy the interface.
// In a real extension, you would likely use VS Code's built-in telemetry reporter.
class MockTelemetry implements IExperimentationTelemetry {
  public commonProperties: Record<string, string> = {};

  setCommonProperties(properties: Record<string, string>): void {
    this.commonProperties = { ...this.commonProperties, ...properties };
  }

  postEvent(eventName: string, props?: Record<string, any>): void {
    console.log(`Telemetry Event: ${eventName}`, { ...this.commonProperties, ...props });
  }

  dispose(): void {
    // No-op for mock telemetry
  }
}

export async function activate(context: vscode.ExtensionContext) {
  console.log('Extension "my-experiment-extension" is active!');

  const extensionName = 'my-experiment-extension';
  const extensionVersion = '1.0.0';
  // Determine the target population based on user settings or environment
  const targetPopulation = process.env.VSCODE_INSIDERS === 'true' ? TargetPopulation.Insiders : TargetPopulation.Public;
  const telemetry = new MockTelemetry();
  const memento = context.globalState;

  let experimentationService: IExperimentationService;

  try {
    // Initialize the experimentation service asynchronously to ensure cached data is loaded.
    experimentationService = await getExperimentationServiceAsync(
      extensionName,
      extensionVersion,
      targetPopulation,
      telemetry,
      memento
    );
    console.log('Experimentation service initialized.');

    // Query a treatment variable. 'vscode' is the standard configId.
    const myFeatureToggleValue = experimentationService.getTreatmentVariable('vscode', 'myFeatureToggle');
    console.log(`Value for 'myFeatureToggle': ${myFeatureToggleValue}`);

    // If you need to force a refresh and get the very latest value from TAS,
    // use getTreatmentVariableAsync. This will trigger a network request.
    const latestMyFeatureToggleValue = await experimentationService.getTreatmentVariableAsync('vscode', 'myFeatureToggle');
    console.log(`Latest value for 'myFeatureToggle' after refresh: ${latestMyFeatureToggleValue}`);

  } catch (error) {
    console.error('Failed to initialize experimentation service:', error);
  }
}

// Standard VS Code extension deactivate function.
export function deactivate() {
  console.log('Extension "my-experiment-extension" is deactivating!');
}