@toggld/js 0.0.0-stage → 0.9.0

package/dist/serverless-effect.mjs

@@ -0,0 +1,121 @@
+import { n as memoryCache, t as createServerlessCore } from "./serverless-B_Vyg8Nd.mjs";
+import { t as ToggldClient } from "./effectService-DPD-fNCI.mjs";
+import { Context, Effect, Layer, Option } from "effect";
+// src/serverless-effect.ts
+/**
+* `@toggld/js/serverless/effect` — the serverless client (`@toggld/js/serverless`)
+* as the same Effect service that `@toggld/js/effect` provides. Needs the
+* optional `effect` peer dependency (`^4.0.5`), and no `node:` module.
+*
+* Program code is the same with either entry: `yield* ToggldClient`, then the
+* same {@link ToggldClientShape}. Only the layer changes.
+*
+* ```ts
+* import { Effect, ManagedRuntime } from "effect"
+* import { ToggldClient, layer, withRequest } from "@toggld/js/serverless/effect"
+*
+* const program = Effect.gen(function* () {
+*   const flags = yield* ToggldClient
+*   return yield* flags.getBooleanValue("new-checkout", false, { targetingKey: "user-123" })
+* })
+*
+* // Cloudflare Workers: one layer per isolate, one request scope per request.
+* const runtime = ManagedRuntime.make(layer({ sdkKey, endpoint }))
+* export default {
+*   fetch: (request, env, ctx) =>
+*     runtime.runPromise(program.pipe(withRequest(ctx))).then((on) => new Response(String(on))),
+* }
+* ```
+*
+* **One bulk request per request scope and context.** Inside
+* {@link withRequest} (or {@link requestLayer}), the first evaluation for a
+* context sends one bulk request, and every later one in that scope with the
+* same context uses its answer, as a `forRequest` view does. Outside a request
+* scope, each evaluation sends its own bulk request (like remote mode), so
+* provide one per incoming request.
+*
+* The optional {@link WaitUntil} service runs follow-up work after the
+* response: cache writes (inline and bounded without it) and telemetry sends
+* (started without being awaited without it). `withRequest(ctx)` provides it
+* when `ctx` has a `waitUntil`. Reads are counted for analytics as with
+* `@toggld/js/serverless` (`telemetry` option); `flushTelemetry` sends the
+* counts now.
+*
+* Interrupting an evaluation outside a request scope aborts its bulk request.
+* Inside one, the request is shared by the scope's other evaluations, so it is
+* not aborted; `timeoutMs` bounds it.
+*/
+/**
+* The current request's `waitUntil`. Provide it per request (Workers, Vercel)
+* with {@link withRequest}, {@link withWaitUntil}, or {@link waitUntilLayer};
+* leave it out where the runtime freezes after the handler returns (AWS
+* Lambda). It only affects cache writes and telemetry sends.
+*/
+var WaitUntil = class extends Context.Service()("@toggld/js/serverless/WaitUntil") {};
+/**
+* The evaluation state of one incoming request: its bulk results. Create it
+* with {@link withRequest} or {@link requestLayer}, once per request; do not
+* share it between requests.
+*/
+var RequestScope = class extends Context.Service()("@toggld/js/serverless/RequestScope") {};
+/** The {@link WaitUntil} service of one request. Calls `source.waitUntil` as a method, as Workers requires. */
+const service = (source) => ({ waitUntil: (promise) => source.waitUntil(promise) });
+const hasWaitUntil = (ctx) => typeof ctx?.waitUntil === "function";
+/**
+* Run `self` as one incoming request: a fresh {@link RequestScope} (one bulk
+* request per context), plus {@link WaitUntil} when `ctx` has a `waitUntil`
+* (a Workers `ExecutionContext`, Vercel). Without `ctx` (AWS Lambda), cache
+* writes run inline.
+*/
+const withRequest = (ctx) => (self) => Effect.provide(self, requestLayer(ctx));
+/** {@link withRequest} as a layer. Build it once per incoming request. */
+const requestLayer = (ctx) => {
+	const scope = Layer.sync(RequestScope, () => ({ views: /* @__PURE__ */ new Map() }));
+	return hasWaitUntil(ctx) ? Layer.merge(scope, Layer.succeed(WaitUntil, service(ctx))) : scope;
+};
+/** The same as {@link withRequest} with a `waitUntil` source: a request scope and its {@link WaitUntil}. */
+const withWaitUntil = (source) => withRequest(source);
+/** {@link WaitUntil} and a fresh {@link RequestScope} as a layer, for one request. */
+const waitUntilLayer = (source) => requestLayer(source);
+/** The current request's `waitUntil`, or none (inline cache writes). */
+const currentWaitUntil = Effect.map(Effect.serviceOption(WaitUntil), (found) => Option.isSome(found) ? (promise) => found.value.waitUntil(promise.catch(() => {})) : void 0);
+/** The view of the current request scope for this client, or a one-evaluation view outside one. */
+const viewFor = (core) => Effect.flatMap(currentWaitUntil, (waitUntil) => Effect.map(Effect.serviceOption(RequestScope), (scope) => {
+	if (Option.isNone(scope)) return core.view(waitUntil, true);
+	let view = scope.value.views.get(core);
+	if (view === void 0) {
+		view = core.view(waitUntil);
+		scope.value.views.set(core, view);
+	}
+	return view;
+}));
+const fromCore = (core) => {
+	const run = (evaluate) => Effect.flatMap(viewFor(core), (view) => Effect.promise((signal) => evaluate(view, signal)));
+	const typed = (key, defaultValue, context, type) => run((view, signal) => core.typed(view, key, defaultValue, context, type, signal));
+	const value = (details) => Effect.map(details, (d) => d.value);
+	return {
+		ready: Effect.void,
+		flushTelemetry: Effect.promise(() => core.flushTelemetry()),
+		evaluate: (key, defaultValue, context) => run((view, signal) => core.evaluate(view, key, defaultValue, context, signal)),
+		evaluateAll: (context) => run((view, signal) => core.evaluateAll(view, context, signal)),
+		getBooleanDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "boolean"),
+		getBooleanValue: (key, defaultValue, context) => value(typed(key, defaultValue, context, "boolean")),
+		getStringDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "string"),
+		getStringValue: (key, defaultValue, context) => value(typed(key, defaultValue, context, "string")),
+		getNumberDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "number"),
+		getNumberValue: (key, defaultValue, context) => value(typed(key, defaultValue, context, "number")),
+		getObjectDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "object"),
+		getObjectValue: (key, defaultValue, context) => value(typed(key, defaultValue, context, "object"))
+	};
+};
+/**
+* A `Layer` providing {@link ToggldClient} with one serverless client for the
+* layer's scope. Build it once per isolate or process (a module-scope
+* `ManagedRuntime`), not per request, and provide {@link withRequest} per
+* request. Building it makes no request, and it holds no resource.
+*
+* Options that can never work (no `sdkKey`, a public token, or an invalid
+* `endpoint`) make the layer die with a `TypeError`.
+*/
+const layer = (options) => Layer.effect(ToggldClient, Effect.sync(() => fromCore(createServerlessCore(options))));
+export { RequestScope, ToggldClient, WaitUntil, layer, memoryCache, requestLayer, waitUntilLayer, withRequest, withWaitUntil };

package/dist/serverless.d.mts

@@ -0,0 +1,3 @@
+import { a as ErrorCode, c as FlagValue, l as Reason, o as EvaluationContext, s as FlagMetadata, t as EvaluationDetails } from "./types-BHn_vrQq.mjs";
+import { a as createServerlessClient, c as CachedFlagFailure, d as MemoryCacheOptions, f as memoryCache, i as WaitUntilContext, l as CachedFlagSuccess, n as ServerlessClientOptions, o as CachedEvaluations, r as ServerlessRequestClient, s as CachedFlagEvaluation, t as ServerlessClient, u as EvaluationCache } from "./serverless-e__iCjpQ.mjs";
+export { type CachedEvaluations, type CachedFlagEvaluation, type CachedFlagFailure, type CachedFlagSuccess, type ErrorCode, type EvaluationCache, type EvaluationContext, type EvaluationDetails, type FlagMetadata, type FlagValue, type MemoryCacheOptions, type Reason, ServerlessClient, ServerlessClientOptions, ServerlessRequestClient, WaitUntilContext, createServerlessClient, memoryCache };

package/dist/serverless.mjs

@@ -0,0 +1,38 @@
+import { n as memoryCache, t as createServerlessCore } from "./serverless-B_Vyg8Nd.mjs";
+// src/serverless.ts
+/**
+* Create a serverless client. Call it once per isolate or process, in module
+* scope (or lazily on the first request, where Worker bindings are
+* available). It makes no request until the first evaluation.
+*
+* Throws a `TypeError` for options that can never work: no `sdkKey`, a public
+* token (`ffp_…`), or an `endpoint` that is not an http(s) URL.
+*/
+const createServerlessClient = (options) => {
+	const core = createServerlessCore(options);
+	return {
+		forRequest: (ctx) => {
+			const context = ctx;
+			const waitUntil = typeof context?.waitUntil === "function" ? (promise) => context.waitUntil(promise.catch(() => {})) : void 0;
+			return makeRequestClient(core, core.view(waitUntil));
+		},
+		flushTelemetry: () => core.flushTelemetry()
+	};
+};
+const makeRequestClient = (core, view) => {
+	const details = (key, defaultValue, context, type) => core.typed(view, key, defaultValue, context, type);
+	const value = async (key, defaultValue, context, type) => (await details(key, defaultValue, context, type)).value;
+	return {
+		evaluate: (key, defaultValue, context) => core.evaluate(view, key, defaultValue, context),
+		evaluateAll: (context) => core.evaluateAll(view, context),
+		getBooleanValue: (key, defaultValue, context) => value(key, defaultValue, context, "boolean"),
+		getBooleanDetails: (key, defaultValue, context) => details(key, defaultValue, context, "boolean"),
+		getStringValue: (key, defaultValue, context) => value(key, defaultValue, context, "string"),
+		getStringDetails: (key, defaultValue, context) => details(key, defaultValue, context, "string"),
+		getNumberValue: (key, defaultValue, context) => value(key, defaultValue, context, "number"),
+		getNumberDetails: (key, defaultValue, context) => details(key, defaultValue, context, "number"),
+		getObjectValue: (key, defaultValue, context) => value(key, defaultValue, context, "object"),
+		getObjectDetails: (key, defaultValue, context) => details(key, defaultValue, context, "object")
+	};
+};
+export { createServerlessClient, memoryCache };

package/dist/types-BHn_vrQq.d.mts

@@ -0,0 +1,211 @@
+/**
+ * A resolved flag value. OpenFeature permits `boolean | string | number |
+ * structure`; we model the union as JSON, which also covers arrays and null for
+ * "object" typed flags.
+ */
+type FlagValue = null | boolean | number | string | ReadonlyArray<FlagValue> | {
+  readonly [key: string]: FlagValue;
+};
+/**
+ * Flag metadata: "arbitrary properties, with keys of type string, and values of
+ * type boolean, string, or number." (Requirement 2.2.10)
+ */
+type MetadataValue = string | number | boolean;
+type FlagMetadata = {
+  readonly [key: string]: MetadataValue;
+};
+/**
+ * An OpenFeature evaluation context: an optional `targetingKey` identifying the
+ * subject (Requirement 3.1.1) plus arbitrary custom JSON-valued attributes
+ * (Requirement 3.1.2).
+ */
+type EvaluationContext = {
+  readonly [attribute: string]: FlagValue;
+};
+/**
+ * Resolution reasons. (Requirement 2.2.5)
+ */
+type Reason = "STATIC" | "DEFAULT" | "TARGETING_MATCH" | "SPLIT" | "CACHED" | "DISABLED" | "UNKNOWN" | "STALE" | "ERROR";
+/**
+ * OpenFeature error codes.
+ * @see https://openfeature.dev/specification/types
+ */
+type ErrorCode = "PROVIDER_NOT_READY" | "PROVIDER_FATAL" | "FLAG_NOT_FOUND" | "PARSE_ERROR" | "TYPE_MISMATCH" | "TARGETING_KEY_MISSING" | "INVALID_CONTEXT" | "GENERAL";
+/**
+ * How the client resolves flags.
+ *
+ * - `"sync"` (default) — the client keeps a copy of the flag rules current in
+ *   the background (a snapshot fetch plus a live WebSocket stream, with a
+ *   safety poll) and evaluates flags **in your process** with the bundled
+ *   engine: zero server requests per evaluation, microsecond latency,
+ *   identical resolutions to the server, and it keeps working from its last
+ *   copy if the API is unreachable. Needs a secret SDK key (`ffk_…`) and a
+ *   long-lived process. On serverless and edge runtimes, use
+ *   `@toggld/js/serverless` instead. Tune it with {@link ToggldClientOptions.sync}.
+ * - `"file"` — evaluates in your process from a flag file on disk
+ *   ({@link ToggldClientOptions.file}), watched for edits. No network, key, or
+ *   endpoint. For local development, tests, CI, and pinned rulesets.
+ * - `"remote"` — every evaluation is an HTTP request to the flag API's OFREP
+ *   endpoints; the server evaluates and returns the value. For public tokens
+ *   (`ffp_…`), which cannot read flag definitions, and runtimes that keep no
+ *   memory between requests.
+ *
+ * `"local"` (from `@toggld/node`) was renamed: creating a client with it
+ * throws a `TypeError`. Use `"sync"`, or `"file"` for a flag file.
+ */
+type EvaluationMode = "sync" | "file" | "remote";
+/** Tuning for the background sync (sync mode, the default). Ignored in file and remote modes. */
+interface SyncOptions {
+  /**
+   * How updates reach the client.
+   *
+   * - `"ws"` (default) — a live WebSocket stream (`/sync/v1/stream`) pushes a
+   *   fresh snapshot on every change, with the snapshot poll below as a
+   *   safety net (it also serves runtimes where the stream is unavailable —
+   *   the client degrades to polling automatically). The client sends a
+   *   heartbeat every 30 seconds to servers that support it, and reconnects
+   *   when no answer arrives within 10 seconds.
+   * - `"poll"` — no stream; only the periodic snapshot poll.
+   */
+  readonly transport?: "ws" | "poll";
+  /**
+   * Delay after each snapshot poll, in milliseconds. Default `30000`.
+   * Polling stays active while the stream is healthy to recover changes from
+   * other Node instances and dropped announcements. With successful reads,
+   * allow this delay plus two request timeouts and scheduling delays.
+   * Use a positive, finite value. Until the first snapshot arrives, the client
+   * retries faster (exponential from 250 ms).
+   */
+  readonly pollIntervalMs?: number;
+  /**
+   * Delay after each snapshot poll while the stream is healthy **and** the
+   * server promises durable delivery, in milliseconds. Default `300000`
+   * (5 minutes). Values below {@link pollIntervalMs} use `pollIntervalMs`.
+   *
+   * The stream is healthy when it is open, has delivered a snapshot, and has
+   * answered a heartbeat. Durable delivery means the server cannot lose a
+   * change before it pushes it, as the hosted API does. Against a server that
+   * does not promise it, the client always polls every `pollIntervalMs`. When the stream drops or misses a heartbeat, the client
+   * returns to `pollIntervalMs` at once, counted from its last poll.
+   */
+  readonly streamPollIntervalMs?: number;
+  /**
+   * How long `ToggldClient.create` (and building the Effect `layer`) waits for
+   * the first snapshot before resolving anyway, in milliseconds. Default
+   * `5000`. A client that isn't ready by then warns once, and evaluates to
+   * caller defaults (`PROVIDER_NOT_READY`) while sync keeps retrying in the
+   * background. (In file mode, `create` waits for the first read of the file
+   * instead.)
+   */
+  readonly readyTimeoutMs?: number;
+  /**
+   * Custom `WebSocket` constructor for the stream transport. Defaults to the
+   * global `WebSocket` (Node ≥ 22). Useful for tests or proxies.
+   */
+  readonly webSocketConstructor?: typeof globalThis.WebSocket;
+}
+/** Configuration for a {@link https://toggld.io Toggld} client. */
+interface ToggldClientOptions {
+  /**
+   * An **evaluation** (or management) API key, sent as `Authorization: Bearer
+   * <sdkKey>`. The key is scoped to one tenant + environment server-side, so a
+   * client always evaluates against exactly that environment. Sync mode, the
+   * default, requires a secret key (`ffk_…`): public browser tokens (`ffp_…`)
+   * cannot read flag definitions, so creating a sync-mode client with one
+   * throws a `TypeError`. Use `mode: "remote"` with a public token.
+   *
+   * Optional **only** in file mode, which reads its flags from disk and never
+   * authenticates. Required in sync and remote modes.
+   */
+  readonly sdkKey?: string;
+  /**
+   * Base URL of the flag API, e.g. `https://toggld-api.example.workers.dev` or
+   * `http://localhost:3000` in local development. No trailing path — the client
+   * appends the OFREP and sync routes (`/ofrep/v1/...`, `/sync/v1/...`).
+   *
+   * Optional **only** in file mode, which makes no requests. Required in sync
+   * and remote modes.
+   */
+  readonly endpoint?: string;
+  /**
+   * Evaluation mode: `"sync"` (default), `"file"`, or `"remote"`. Use
+   * `"remote"` with a public token, and `"file"` to evaluate from a flag file.
+   * On serverless and edge runtimes, use `@toggld/js/serverless`. See
+   * {@link EvaluationMode}.
+   *
+   * The `TOGGLD_FLAGS_FILE` environment variable, when set and not empty,
+   * makes any client read that file in file mode, so a deployed app can be
+   * redirected to a file with no code change. It overrides {@link file}.
+   *
+   * `"local"` was renamed and throws a `TypeError`: use `"sync"`, or
+   * `"file"` with {@link file}.
+   */
+  readonly mode?: EvaluationMode;
+  /**
+   * The flag file to evaluate from in file mode (ADR-0013). Default
+   * `./toggld.flags.json`. The file is a flag snapshot on disk; generate one
+   * with `npx @toggld/js pull`. It is **watched**: edits are adopted live, with
+   * no restart, and the client also re-reads it every 30 seconds as a safety
+   * net (which picks the file up if it is created after the client starts).
+   * `create` waits for the first read; if it fails, the client warns and
+   * serves your fallback values until the file loads.
+   *
+   * Only valid with `mode: "file"`; with any other mode it throws a
+   * `TypeError`. `TOGGLD_FLAGS_FILE` overrides it.
+   */
+  readonly file?: string;
+  /** Tuning for sync mode, the default. Ignored in file and remote modes. */
+  readonly sync?: SyncOptions;
+  /**
+   * Evaluation telemetry for flag analytics, on by default: grouped counts
+   * per flag, variant, reason, and minute (no context or values), sent to
+   * `POST /v1/telemetry` every `flushIntervalMs` (default `30000`) and on
+   * `close()`.
+   *
+   * - Sync mode reports every evaluation, including each `evaluateAll` entry.
+   * - Remote mode reports each entry `evaluateAll` returns: the API does not
+   *   count bulk requests in analytics. Single evaluations are counted by the
+   *   API, so they are not reported. Its flush timer does not keep the process
+   *   alive, and it does not report on Workers or edge runtimes (use
+   *   `@toggld/js/serverless` there).
+   * - File mode never reports.
+   *
+   * Set `false` to send nothing: those evaluations are then not in analytics.
+   */
+  readonly telemetry?: false | {
+    readonly flushIntervalMs?: number;
+  };
+  /**
+   * Attributes merged into the evaluation context of **every** request, under
+   * any per-call context (per-call attributes win on key collision). Handy for
+   * process-wide dimensions such as `region` or `serviceVersion`.
+   */
+  readonly defaultContext?: EvaluationContext;
+  /** Per-request timeout in milliseconds. Default `5000`. */
+  readonly timeoutMs?: number;
+  /**
+   * Custom `fetch` implementation. Defaults to the global `fetch`. Useful for
+   * tests, proxies, or injecting retries/instrumentation.
+   */
+  readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * The outcome of evaluating a single flag — OpenFeature "evaluation details"
+ * with a value typed to the requested flag type. Mirrors {@link
+ * https://openfeature.dev/specification/sections/evaluation-details}.
+ *
+ * On any abnormal evaluation (network failure, unknown flag, type mismatch, a
+ * server-reported error) the call still resolves: `value` holds the caller's
+ * default, `reason` is `"ERROR"`, and `errorCode`/`errorMessage` describe what
+ * went wrong. Evaluation never throws.
+ */
+interface EvaluationDetails<T extends FlagValue> {
+  readonly flagKey: string;
+  readonly value: T;
+  readonly variant: string | undefined;
+  readonly reason: Reason;
+  readonly errorCode: ErrorCode | undefined;
+  readonly errorMessage: string | undefined;
+  readonly flagMetadata: FlagMetadata;
+}
+export { ErrorCode as a, FlagValue as c, ToggldClientOptions as i, Reason as l, EvaluationMode as n, EvaluationContext as o, SyncOptions as r, FlagMetadata as s, EvaluationDetails as t };