@flagtide/core 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrian Turbiński
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @flagtide/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The framework-agnostic part of the flagtide SDK. It evaluates feature flags locally, with the same result as the Java server, and keeps them current over a WebSocket.
+
+```sh
+npm install @flagtide/core rxjs
+```
+
+```ts
+import { createFlagtideClient } from '@flagtide/core';
+
+const client = createFlagtideClient({
+  streamUrl: 'wss://flags.example.com/sdk/v1/stream',
+  sdkKey: 'fws_...',
+  context: { key: 'user-42', attributes: { plan: 'pro', appVersion: '2.4.0' } },
+});
+client.start();
+
+client.value('new-checkout', false);
+client.resolve('banner-text', 'Welcome').reason;
+client.status$.subscribe(console.log);
+```
+
+Evaluation reads the snapshot the client already holds, so it never waits for the network. A flag the client does not know, or one whose type differs from the fallback, returns the fallback with the reason `FLAG_NOT_FOUND` or `TYPE_MISMATCH`.
+
+## Connection behavior
+
+- The SDK key travels in the first frame, never in the URL.
+- A reconnect sends the last applied version and receives exactly the changes it missed, or a full snapshot when it is too far behind.
+- Reconnects use exponential backoff with full jitter: `random(0, min(30 s, 500 ms * 2^attempt))`.
+- A connection that stays silent for 40 seconds is treated as dead. The check compares timestamps, so a throttled background tab does not cause false alarms, and it runs again when the tab becomes visible.
+- The status is one of `connecting`, `live`, `stale` and `offline`.
+- The last snapshot is kept in `localStorage` (when it is usable) so a page can start without the server.
+
+## Server side rendering
+
+Do not open a socket on a server. Fetch the snapshot with `fetchSnapshot(baseUrl, sdkKey)`, pass it as `initialSnapshot`, and call `start()` only in the browser.
+
+## Evaluation without a connection
+
+`evaluate`, `indexSegments`, `bucketOf` and `murmur3x86_32` are exported for code that wants the algorithm alone, for example a Node service or a test. The algorithm is specified in `docs/evaluation-spec.md` of the repository and checked against shared test vectors in both Java and TypeScript.
+
+## Requirements
+
+RxJS 7.8 or later as a peer dependency, and a runtime with `WebSocket` (browsers, Node 22 and later).
+
+MIT licensed.

package/index.d.ts

@@ -0,0 +1,22 @@
+export { BUCKET_SPACE, bucketOf } from './lib/bucket.js';
+export { createFlagtideClient, FlagtideClient } from './lib/client.js';
+export type { FlagtideClientOptions } from './lib/client.js';
+export { backoffDelay, ConnectionManager, createBrowserEnvironment, createBrowserSocketFactory, DEFAULT_TIMING, } from './lib/connection-manager.js';
+export type { ConnectionManagerOptions, ConnectionStatus, ConnectionTiming, NetworkEnvironment, SocketControl, SocketFactory, SocketHandlers, StreamError, } from './lib/connection-manager.js';
+export { InvalidFlagConfigError, evaluate, indexSegments } from './lib/evaluate.js';
+export { fetchSnapshot } from './lib/fetch-snapshot.js';
+export type { FetchLike } from './lib/fetch-snapshot.js';
+export { FlagStore } from './lib/flag-store.js';
+export type { ApplyOutcome, FlagSnapshot } from './lib/flag-store.js';
+export { murmur3x86_32, murmur3x86_32OfText } from './lib/murmur3.js';
+export { FlagOverrides } from './lib/overrides.js';
+export { parseServerFrame, parseSnapshotBody } from './lib/protocol.js';
+export type * from './lib/protocol.js';
+export { flagTypeOf, jsonEquals, resolveFlag } from './lib/resolve.js';
+export type { Resolution, ResolutionReason } from './lib/resolve.js';
+export { compareSemanticVersions, parseSemanticVersion } from './lib/semver.js';
+export type { SemanticVersion } from './lib/semver.js';
+export { createLocalStore, createMemoryStore, createSnapshotStorage, createWebStore, snapshotStorageKey, } from './lib/storage.js';
+export type { KeyValueStore, SnapshotStorage } from './lib/storage.js';
+export { encodeUtf8, utf8Length } from './lib/utf8.js';
+export type * from './lib/types.js';

package/index.js

@@ -0,0 +1,13 @@
+export { BUCKET_SPACE, bucketOf } from './lib/bucket.js';
+export { createFlagtideClient, FlagtideClient } from './lib/client.js';
+export { backoffDelay, ConnectionManager, createBrowserEnvironment, createBrowserSocketFactory, DEFAULT_TIMING, } from './lib/connection-manager.js';
+export { InvalidFlagConfigError, evaluate, indexSegments } from './lib/evaluate.js';
+export { fetchSnapshot } from './lib/fetch-snapshot.js';
+export { FlagStore } from './lib/flag-store.js';
+export { murmur3x86_32, murmur3x86_32OfText } from './lib/murmur3.js';
+export { FlagOverrides } from './lib/overrides.js';
+export { parseServerFrame, parseSnapshotBody } from './lib/protocol.js';
+export { flagTypeOf, jsonEquals, resolveFlag } from './lib/resolve.js';
+export { compareSemanticVersions, parseSemanticVersion } from './lib/semver.js';
+export { createLocalStore, createMemoryStore, createSnapshotStorage, createWebStore, snapshotStorageKey, } from './lib/storage.js';
+export { encodeUtf8, utf8Length } from './lib/utf8.js';

package/lib/bucket.d.ts

@@ -0,0 +1,4 @@
+/** Number of buckets a context key is hashed into. One unit is 0.001 percent. */
+export declare const BUCKET_SPACE = 100000;
+/** The bucket, from 0 to 99999, of a context key for a flag: MurmurHash3 over `flagKey.salt.contextKey` modulo 100000. */
+export declare function bucketOf(flagKey: string, salt: string, contextKey: string): number;

package/lib/bucket.js

@@ -0,0 +1,7 @@
+import { murmur3x86_32OfText } from './murmur3.js';
+/** Number of buckets a context key is hashed into. One unit is 0.001 percent. */
+export const BUCKET_SPACE = 100000;
+/** The bucket, from 0 to 99999, of a context key for a flag: MurmurHash3 over `flagKey.salt.contextKey` modulo 100000. */
+export function bucketOf(flagKey, salt, contextKey) {
+    return murmur3x86_32OfText(`${flagKey}.${salt}.${contextKey}`) % BUCKET_SPACE;
+}

package/lib/client.d.ts

@@ -0,0 +1,66 @@
+import type { SchedulerLike, Observable } from 'rxjs';
+import type { ConnectionStatus, ConnectionTiming, NetworkEnvironment, SocketFactory, StreamError } from './connection-manager.js';
+import type { FlagSnapshot } from './flag-store.js';
+import { FlagOverrides } from './overrides.js';
+import type { Resolution } from './resolve.js';
+import type { KeyValueStore } from './storage.js';
+import type { EvaluationContext, FlagType, JsonValue } from './types.js';
+/** Everything {@link createFlagtideClient} accepts. Only `streamUrl` and `sdkKey` are required. */
+export interface FlagtideClientOptions {
+    /** The stream endpoint, for example `ws://localhost:18081/sdk/v1/stream`. */
+    readonly streamUrl: string;
+    /** The read-only SDK key of one environment. */
+    readonly sdkKey: string;
+    /** Who flags are evaluated for. Without it the client uses an anonymous id that is kept in storage. */
+    readonly context?: EvaluationContext;
+    /** A snapshot to start from, for example one rendered on the server. It wins over the stored snapshot. */
+    readonly initialSnapshot?: FlagSnapshot;
+    /** Where the last snapshot, the overrides and the anonymous id live. Defaults to `localStorage` when there is one. */
+    readonly store?: KeyValueStore;
+    readonly socketFactory?: SocketFactory;
+    readonly environment?: NetworkEnvironment;
+    readonly scheduler?: SchedulerLike;
+    readonly random?: () => number;
+    readonly timing?: Partial<ConnectionTiming>;
+}
+/**
+ * Evaluates flags locally and keeps them current over a stream connection.
+ *
+ * Evaluation never waits for the network: it reads the snapshot the client holds. Create one client per
+ * environment with {@link createFlagtideClient}.
+ */
+export declare class FlagtideClient {
+    /** Local overrides. A resolution reports `OVERRIDE` when one applies. */
+    readonly overrides: FlagOverrides;
+    private readonly flagStore;
+    private readonly manager;
+    private readonly storage;
+    private readonly contextChanged;
+    private currentContext;
+    constructor(options: FlagtideClientOptions);
+    get status$(): Observable<ConnectionStatus>;
+    get status(): ConnectionStatus;
+    get errors$(): Observable<StreamError>;
+    /** Emits after anything that can change a flag value: a snapshot, a delta, an override or a new context. */
+    get changes$(): Observable<void>;
+    /** The version of the environment the client holds, or `null` before it has any data. */
+    get version(): number | null;
+    get context(): EvaluationContext;
+    setContext(context: EvaluationContext): void;
+    /** The held state, for handing to the browser after server rendering. `null` before any data. */
+    snapshot(): FlagSnapshot | null;
+    /** Replaces the held state, for example with a snapshot fetched on the server or one handed over by the server. */
+    hydrate(snapshot: FlagSnapshot): void;
+    flagKeys(): readonly string[];
+    /** The declared type of a flag, or `undefined` when the flag is unknown. */
+    flagType(key: string): FlagType | undefined;
+    /** Evaluates a flag with its reason. The fallback is returned for unknown flags and for a type mismatch. */
+    resolve<T extends JsonValue>(key: string, fallback: T): Resolution<T>;
+    /** Evaluates a flag and returns only its value. */
+    value<T extends JsonValue>(key: string, fallback: T): T;
+    /** Opens the stream. Call it in browsers only: servers should use {@link fetchSnapshot} instead. */
+    start(): void;
+    stop(): void;
+}
+/** Creates a client. It does nothing until `start()` is called. */
+export declare function createFlagtideClient(options: FlagtideClientOptions): FlagtideClient;

package/lib/client.js

@@ -0,0 +1,121 @@
+import { Subject, map, merge } from 'rxjs';
+import { ConnectionManager, createBrowserEnvironment, createBrowserSocketFactory, } from './connection-manager.js';
+import { FlagStore } from './flag-store.js';
+import { FlagOverrides } from './overrides.js';
+import { resolveFlag } from './resolve.js';
+import { createLocalStore, createSnapshotStorage, snapshotStorageKey } from './storage.js';
+const SDK_NAME = 'flagtide-core/1.0.0';
+const ANONYMOUS_ID_KEY = 'flagtide:anonymous-id';
+function randomIdentifier() {
+    const generator = globalThis.crypto;
+    return generator?.randomUUID?.() ?? Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
+function anonymousContext(store) {
+    const known = store.get(ANONYMOUS_ID_KEY);
+    const key = known ?? randomIdentifier();
+    if (known === null) {
+        store.set(ANONYMOUS_ID_KEY, key);
+    }
+    return { key, attributes: {} };
+}
+/**
+ * Evaluates flags locally and keeps them current over a stream connection.
+ *
+ * Evaluation never waits for the network: it reads the snapshot the client holds. Create one client per
+ * environment with {@link createFlagtideClient}.
+ */
+export class FlagtideClient {
+    /** Local overrides. A resolution reports `OVERRIDE` when one applies. */
+    overrides;
+    flagStore;
+    manager;
+    storage;
+    contextChanged = new Subject();
+    currentContext;
+    constructor(options) {
+        const store = options.store ?? createLocalStore();
+        this.storage = createSnapshotStorage(store, options.sdkKey);
+        this.currentContext = options.context ?? anonymousContext(store);
+        this.overrides = new FlagOverrides(store, `${snapshotStorageKey(options.sdkKey)}:overrides`);
+        this.flagStore = new FlagStore(options.initialSnapshot ?? this.storage.load() ?? undefined);
+        if (options.initialSnapshot !== undefined) {
+            this.storage.save(options.initialSnapshot);
+        }
+        this.flagStore.changes$.subscribe(() => {
+            const snapshot = this.flagStore.snapshot();
+            if (snapshot !== null) {
+                this.storage.save(snapshot);
+            }
+        });
+        this.manager = new ConnectionManager({
+            url: options.streamUrl,
+            sdkKey: options.sdkKey,
+            store: this.flagStore,
+            clientId: this.currentContext.key,
+            sdk: SDK_NAME,
+            socketFactory: options.socketFactory ?? createBrowserSocketFactory(),
+            environment: options.environment ?? createBrowserEnvironment(),
+            ...(options.scheduler === undefined ? {} : { scheduler: options.scheduler }),
+            ...(options.random === undefined ? {} : { random: options.random }),
+            ...(options.timing === undefined ? {} : { timing: options.timing }),
+        });
+    }
+    get status$() {
+        return this.manager.status$;
+    }
+    get status() {
+        return this.manager.status;
+    }
+    get errors$() {
+        return this.manager.errors$;
+    }
+    /** Emits after anything that can change a flag value: a snapshot, a delta, an override or a new context. */
+    get changes$() {
+        return merge(this.flagStore.changes$.pipe(map(() => undefined)), this.overrides.changes$, this.contextChanged);
+    }
+    /** The version of the environment the client holds, or `null` before it has any data. */
+    get version() {
+        return this.flagStore.version;
+    }
+    get context() {
+        return this.currentContext;
+    }
+    setContext(context) {
+        this.currentContext = context;
+        this.contextChanged.next();
+    }
+    /** The held state, for handing to the browser after server rendering. `null` before any data. */
+    snapshot() {
+        return this.flagStore.snapshot();
+    }
+    /** Replaces the held state, for example with a snapshot fetched on the server or one handed over by the server. */
+    hydrate(snapshot) {
+        this.flagStore.hydrate(snapshot);
+    }
+    flagKeys() {
+        return this.flagStore.flagKeys();
+    }
+    /** The declared type of a flag, or `undefined` when the flag is unknown. */
+    flagType(key) {
+        return this.flagStore.flag(key)?.type;
+    }
+    /** Evaluates a flag with its reason. The fallback is returned for unknown flags and for a type mismatch. */
+    resolve(key, fallback) {
+        return resolveFlag(this.flagStore.flag(key), this.currentContext, this.flagStore.segments, fallback, this.overrides.get(key));
+    }
+    /** Evaluates a flag and returns only its value. */
+    value(key, fallback) {
+        return this.resolve(key, fallback).value;
+    }
+    /** Opens the stream. Call it in browsers only: servers should use {@link fetchSnapshot} instead. */
+    start() {
+        this.manager.start();
+    }
+    stop() {
+        this.manager.stop();
+    }
+}
+/** Creates a client. It does nothing until `start()` is called. */
+export function createFlagtideClient(options) {
+    return new FlagtideClient(options);
+}

package/lib/connection-manager.d.ts

@@ -0,0 +1,137 @@
+import { Observable } from 'rxjs';
+import type { SchedulerLike } from 'rxjs';
+import type { FlagStore } from './flag-store.js';
+/**
+ * What the SDK can say about the flags it serves.
+ *
+ * - `connecting`: the first attempt is in progress and nothing is confirmed yet
+ * - `live`: the stream is open and the data is confirmed current
+ * - `stale`: flags are served but cannot be confirmed current
+ * - `offline`: the browser has no network or the server has been unreachable for too long
+ */
+export type ConnectionStatus = 'connecting' | 'live' | 'offline' | 'stale';
+/** Callbacks a socket implementation reports to the connection manager. */
+export interface SocketHandlers {
+    open(): void;
+    message(text: string): void;
+    close(code: number): void;
+}
+/** The part of a socket the connection manager drives. */
+export interface SocketControl {
+    send(text: string): void;
+    close(code?: number): void;
+}
+/** Opens a socket to `url` and reports its events to `handlers`. */
+export type SocketFactory = (url: string, handlers: SocketHandlers) => SocketControl;
+/** The browser facts the connection manager reacts to. Inject a fake in tests, or use `createBrowserEnvironment`. */
+export interface NetworkEnvironment {
+    isOnline(): boolean;
+    readonly online$: Observable<boolean>;
+    readonly visible$: Observable<boolean>;
+}
+/** An error reported by the server or found in what it sent. `code` follows the close codes of the stream protocol. */
+export interface StreamError {
+    readonly code: number;
+    readonly message: string;
+}
+/** Backoff, heartbeat and offline limits. The defaults are the constants of the stream protocol. */
+export interface ConnectionTiming {
+    readonly backoffBaseMs: number;
+    readonly backoffCapMs: number;
+    readonly staleAfterMs: number;
+    readonly connectTimeoutMs: number;
+    readonly offlineAfterMs: number;
+}
+export declare const DEFAULT_TIMING: ConnectionTiming;
+export declare const CLOSE_UNAUTHORIZED = 4401;
+export declare const CLOSE_BAD_FRAME = 4400;
+export interface ConnectionManagerOptions {
+    readonly url: string;
+    readonly sdkKey: string;
+    readonly store: FlagStore;
+    readonly clientId?: string;
+    readonly sdk?: string;
+    readonly socketFactory: SocketFactory;
+    readonly environment?: NetworkEnvironment;
+    readonly scheduler?: SchedulerLike;
+    readonly random?: () => number;
+    readonly timing?: Partial<ConnectionTiming>;
+}
+/**
+ * The delay before reconnect attempt number `attempt` (zero based): `random(0, min(cap, base * 2^attempt))`.
+ * Full jitter keeps thousands of clients that lost the same server from reconnecting in step.
+ */
+export declare function backoffDelay(attempt: number, random: () => number, baseMs: number, capMs: number): number;
+type BrowserSocket = {
+    onopen: (() => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code: number;
+    }) => void) | null;
+    onerror: (() => void) | null;
+    send(data: string): void;
+    close(code?: number): void;
+};
+type SocketConstructor = new (url: string) => BrowserSocket;
+/** A socket factory on top of the `WebSocket` constructor of the runtime (browsers, Node 22 and later). */
+export declare function createBrowserSocketFactory(override?: SocketConstructor): SocketFactory;
+/** Online and visibility state from `window` and `document`. Outside a browser it reports online and never changes. */
+export declare function createBrowserEnvironment(): NetworkEnvironment;
+/**
+ * Keeps a stream connection to the server and feeds a {@link FlagStore}.
+ *
+ * It reconnects with exponential backoff and full jitter, resumes from the version the store holds, treats a
+ * silent connection as dead by comparing timestamps (background tabs throttle timers), and acknowledges
+ * every applied frame. All time comes from the injected scheduler and all randomness from the injected
+ * random source, so the behavior can be tested with a virtual clock.
+ */
+export declare class ConnectionManager {
+    private readonly options;
+    private readonly timing;
+    private readonly scheduler;
+    private readonly random;
+    private readonly environment;
+    private readonly statusSubject;
+    private readonly errorSubject;
+    private environmentSubscription;
+    private socket;
+    private generation;
+    private attempt;
+    private failingSince;
+    private lastFrameAt;
+    private silenceLimitMs;
+    private forceSnapshot;
+    private running;
+    private halted;
+    private retryTimer;
+    private watchdogTimer;
+    constructor(options: ConnectionManagerOptions);
+    get status$(): Observable<ConnectionStatus>;
+    get status(): ConnectionStatus;
+    get errors$(): Observable<StreamError>;
+    start(): void;
+    stop(): void;
+    private initialStatus;
+    private setStatus;
+    private now;
+    private connect;
+    private sendHello;
+    private receive;
+    private handle;
+    private handleDeltas;
+    private confirmed;
+    private acknowledge;
+    private connectionLost;
+    private scheduleReconnect;
+    private reconnectNow;
+    private statusWhileRetrying;
+    private networkChanged;
+    private armWatchdog;
+    private checkSilence;
+    private dropSocket;
+    private clearRetry;
+    private clearWatchdog;
+}
+export {};