JavaScript SDK

Install#

$ npm install @darkship/sdk
$ pnpm add @darkship/sdk
$ yarn add @darkship/sdk

Initialise#

init() returns a client immediately and loads flags in the background. The key prefix selects the mode: ds_srv_ runs server mode, ds_cli_ runs client mode. The browser build refuses a ds_srv_ key at init.

import { init } from '@darkship/sdk';

export const ds = init({
  sdkKey: process.env.DARKSHIP_SDK_KEY!,
  // host: DARKSHIP_BASE_URL or baseUrl; changes arrive over SSE within seconds (polling is the fallback)
});

ds.on('error', (err) => logger.warn({ err }, 'darkship error'));
await ds.waitForReady({ timeout: 3000 });

import { init } from '@darkship/sdk';

export const ds = init({
  sdkKey: 'ds_cli_prod_Zk3...',
  context: { key: user.id, plan: user.plan, country: user.country },
});

ds.on('update', ({ changed }) => rerender(changed));
await ds.waitForReady({ timeout: 2000 });

Init options#

waitForReady#

await ds.waitForReady({ timeout }) resolves with true when a ruleset (or, in client mode, the first evaluation result) is available, and false on timeout. It never rejects. Evaluations before readiness return your default with reason NOT_READY.

Evaluate flags#

Each accessor takes the flag key, a context and a default in server mode: getBooleanValue(key, ctx, default). In client mode there is no context argument: getBooleanValue(key, default) uses the context set at init or by identify. They are synchronous and perform no I/O.

Other methods: allFlags(ctx) (values only; usable as a client bootstrap), refresh(), isReady(), close(); server: exportSnapshot(), snapshotVersion(), flagKeys(); client: identify() (alias setContext()).

const d = ds.getBooleanDetail('new-checkout-flow', ctx, false);
// { flagKey: 'new-checkout-flow', value: true, variationKey: 'on', reason: 'FALLTHROUGH', bucket: 4127, flagType: 'boolean' }

const bad = ds.getIntDetail('promo-banner-text', ctx, 0);
// { flagKey: 'promo-banner-text', value: 0, reason: 'ERROR', errorCode: 'TYPE_MISMATCH' }

Reasons and error codes#

Context#

A context is a plain object. key (the user id) is required: it is the default bucketing attribute and what key target lists match. email, name and groups are optional, conventional fields: target lists can match by email (normalised: NFC, trimmed, lowercased on both sides) or by groups (matches when any element is listed). Everything else is an attribute that rules can test. See target users by id, email or group.

type Context = {
  key: string;                       // stable id: user id, device id, org id
  email?: string;                    // matched case-insensitively by email lists and rules
  name?: string;
  groups?: string[];                 // any element may match a groups list
  [attribute: string]: string | number | boolean | string[] | undefined;
};

const ctx = {
  key: 'usr_marta',
  email: 'Marta@Acme.com',
  groups: ['beta-testers', 'acme-staff'],
  plan: 'pro', country: 'BR', app_version: '4.12.0', orgId: 'org_acme',
};

• Use a stable key. A random key per request defeats sticky rollouts.
• Don't send secrets or personal data you don't need for targeting. In server mode the context never leaves your process; in client mode it is sent for evaluation, used in memory and discarded.
• Browser: await ds.identify(newContext) replaces the context, triggers one re-fetch and emits update if any value changed.

Events#

ds.on('ready',  ({ version }) => log.info('ruleset', version));
ds.on('update', ({ version, changed }) => log.info('flags changed', changed));
ds.on('error',  (err) => log.warn(err.code, err.message));   // never thrown, only emitted
ds.on('stale', () => log.warn('serving the last good ruleset'));
ds.on('recovered', () => log.info('control plane reachable again'));

Telemetry and privacy#

The SDK counts evaluations in memory per flag × variation × one-minute window and flushes the counters to POST /v1/telemetry/counters on an interval, when a size threshold is reached, and on close(). These are the only fields that leave your process:

Error handling and defaults#

Evaluation never throws. When anything is wrong you get the default you passed, plus a reason in the *Detail variants and an error event for connectivity problems.

init() itself throws synchronously only for programmer errors: no key, a malformed prefix, or a server key in a browser build.

Shutdown#

process.on('SIGTERM', async () => {
  await ds.close({ timeout: 2000 });   // stop polling, flush counters (best effort), release timers
  process.exit(0);
});

In serverless functions call await ds.close() at the end of the invocation, or keep the client at module scope across warm invocations and flush before the runtime freezes.

Versions and support#

The package is at 0.1.0. Until 1.0, minor versions may include breaking changes, listed in the changelog. Server mode needs Node 18 or newer; client mode runs in evergreen browsers. Behaviour is verified against the shared conformance vectors through both the local and the remote path, and a change to targeting semantics ships in the same release as the eval service change.

Constructing the SDK with a ds_srv_ key in a browser, web worker or jsdom throws DarkshipConfigError("SERVER_KEY_IN_BROWSER").