@toggld/js 0.0.0-stage → 0.9.0

package/dist/index.mjs

@@ -0,0 +1,127 @@
+import { n as mapMaybe, t as makeCore } from "./core-BQfyNOoT.mjs";
+// src/index.ts
+/**
+* `@toggld/js` — the default entry: a plain Promise API with **zero runtime
+* dependencies**.
+*
+* ```ts
+* import { ToggldClient } from "@toggld/js"
+*
+* // Sync mode, the default: a copy of the flag rules stays current in the
+* // background and every evaluation is in-process — microseconds, zero server requests.
+* // `create` waits for the first snapshot (up to `sync.readyTimeoutMs`).
+* const client = await ToggldClient.create({ sdkKey, endpoint })
+* const on = await client.getBooleanValue("new-checkout", false, { targetingKey: "user-123" })
+* await client.close() // stops the sync, so a script can exit
+* ```
+*
+* Pass `mode: "file"` to evaluate from a flag file on disk (`file`, default
+* `./toggld.flags.json`), or `mode: "remote"` to send each evaluation to the
+* flag API over OFREP — for public tokens. On serverless and edge runtimes
+* (Cloudflare Workers, Vercel, AWS Lambda), use `@toggld/js/serverless`, the
+* remote client that sends one bulk request per incoming request.
+* Evaluation never throws: any failure resolves to the supplied default value,
+* with the reason/error available via the `*Details` methods.
+*
+* For an Effect app, `@toggld/js/effect` exposes the same client as a
+* service and `Layer` (it needs the optional `effect` peer dependency).
+*/
+/** Calls after `close()` reject, as they always have: the client is unusable then. */
+const closedError = () => /* @__PURE__ */ new Error("[toggld] The client is closed.");
+/**
+* A Toggld client. Create one with {@link ToggldClient.create} and {@link
+* ToggldClient.close} it on shutdown to stop background sync.
+*/
+var ToggldClient = class ToggldClient {
+	#core;
+	constructor(core) {
+		this.#core = core;
+	}
+	/**
+	* Create a client. In sync mode (the default) it resolves once the first
+	* flag snapshot has synced, or once `sync.readyTimeoutMs` (default 5 s) has
+	* elapsed. In that case it warns once, and the client serves caller defaults
+	* with `PROVIDER_NOT_READY` while sync keeps retrying in the background. In
+	* file mode it resolves after the first read of the file; in remote mode, at
+	* once.
+	*
+	* Rejects with a `TypeError` when a sync-mode client could never sync: no
+	* `sdkKey`, a public token (`ffp_…`), or no valid `endpoint`. Use a secret
+	* SDK key, or pass `mode: "remote"`. Also rejects options that no longer
+	* apply: `mode: "local"` (use `"sync"` or `"file"`), `sync.file` (use
+	* `mode: "file", file`), and `file` without `mode: "file"`.
+	*/
+	static async create(options) {
+		const core = makeCore(options);
+		await core.waitForReady();
+		return new ToggldClient(core);
+	}
+	/**
+	* Resolves once the client has flag data to evaluate with (immediately in
+	* remote mode). Useful if `create` resolved on the ready timeout and you
+	* want to await sync explicitly. It has no timeout of its own, and it never
+	* resolves while the key or endpoint is wrong. Rejects if the client is
+	* closed first.
+	*/
+	ready() {
+		if (this.#core.closed()) return Promise.reject(closedError());
+		return this.#core.ready();
+	}
+	/** Send buffered counts without failing evaluations. Failed windows remain queued. */
+	flushTelemetry() {
+		if (this.#core.closed()) return Promise.reject(closedError());
+		return this.#core.flushTelemetry();
+	}
+	/** Resolve a flag, returning full details with an untyped (JSON) value. */
+	evaluate(key, defaultValue, context) {
+		if (this.#core.closed()) return Promise.reject(closedError());
+		return Promise.resolve(this.#core.evaluate(key, defaultValue, context));
+	}
+	/** Resolve every flag for the environment (one request in remote mode; in-process in sync and file modes). */
+	evaluateAll(context) {
+		if (this.#core.closed()) return Promise.reject(closedError());
+		return Promise.resolve(this.#core.evaluateAll(context));
+	}
+	getBooleanValue(key, defaultValue, context) {
+		return this.#value(key, defaultValue, context, "boolean");
+	}
+	getBooleanDetails(key, defaultValue, context) {
+		return this.#details(key, defaultValue, context, "boolean");
+	}
+	getStringValue(key, defaultValue, context) {
+		return this.#value(key, defaultValue, context, "string");
+	}
+	getStringDetails(key, defaultValue, context) {
+		return this.#details(key, defaultValue, context, "string");
+	}
+	getNumberValue(key, defaultValue, context) {
+		return this.#value(key, defaultValue, context, "number");
+	}
+	getNumberDetails(key, defaultValue, context) {
+		return this.#details(key, defaultValue, context, "number");
+	}
+	getObjectValue(key, defaultValue, context) {
+		return this.#value(key, defaultValue, context, "object");
+	}
+	getObjectDetails(key, defaultValue, context) {
+		return this.#details(key, defaultValue, context, "object");
+	}
+	/**
+	* Stop background sync, close the stream, and send remaining telemetry
+	* (bounded by `timeoutMs`). The client is unusable afterwards. A sync-mode
+	* client's stream and poll (and a file-mode client's watcher) keep the process alive until you call this, so a
+	* script must close its client to exit.
+	*/
+	close() {
+		return this.#core.close();
+	}
+	#details(key, defaultValue, context, type) {
+		if (this.#core.closed()) return Promise.reject(closedError());
+		return Promise.resolve(this.#core.typed(key, defaultValue, context, type));
+	}
+	#value(key, defaultValue, context, type) {
+		if (this.#core.closed()) return Promise.reject(closedError());
+		return Promise.resolve(mapMaybe(this.#core.typed(key, defaultValue, context, type), (d) => d.value));
+	}
+};
+export { ToggldClient };

package/dist/serverless-B_Vyg8Nd.mjs

@@ -0,0 +1,259 @@
+import { c as isRecord, d as discard, f as makeSend, h as withTimeout, l as apiUrl, n as decodeOfrepBulk, p as readJson, r as decodeOfrepBulkFailure, u as describe } from "./wire-CrkBeqnM.mjs";
+import { _ as wireErrorDetails, g as rejectedMessage, h as okDetails, i as syncCredentialProblem, m as codeFor, n as errorDetails, r as invalidEndpointMessage, t as enforceType, y as makeRequestTelemetry } from "./details-AiMdctXB.mjs";
+// src/internal/cache.ts
+const CACHE_KEY_PREFIX = "toggld:v1:";
+/** JSON with object keys sorted at every level, so equal contexts give equal strings. */
+const canonicalJson = (u) => JSON.stringify(sorted(u)) ?? "null";
+const sorted = (u) => {
+	if (Array.isArray(u)) return u.map(sorted);
+	if (!isRecord(u)) return u;
+	const proto = Object.getPrototypeOf(u);
+	if (proto !== null && proto !== Object.prototype) return u;
+	const out = {};
+	for (const key of Object.keys(u).sort()) out[key] = sorted(u[key]);
+	return out;
+};
+const hex = (bytes) => Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, "0")).join("");
+/** SHA-256 (WebCrypto, available on Workers, Node.js 20+, Deno, and Bun) as lowercase hex. */
+const sha256Hex = async (text) => hex(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+/** The cache key of one bulk result. `keyHash` is {@link sha256Hex} of the SDK key, never the key. */
+const cacheKeyFor = async (endpoint, keyHash, canonicalContext) => CACHE_KEY_PREFIX + await sha256Hex(JSON.stringify([
+	endpoint,
+	keyHash,
+	canonicalContext
+]));
+/** A cached value, checked like a bulk response, or `undefined` if it does not have the shape. */
+const decodeCached = (u) => {
+	if (!isRecord(u) || typeof u.storedAt !== "number" || !Number.isFinite(u.storedAt)) return void 0;
+	try {
+		return decodeOfrepBulk({ flags: u.flags });
+	} catch {
+		return;
+	}
+};
+/** A bulk entry as it is cached: the OFREP entry, without the decoder's `ok` tag. */
+const toCached = (entry) => {
+	const { ok: _ok, ...rest } = entry;
+	return rest;
+};
+const deepFreeze = (u) => {
+	if (typeof u === "object" && u !== null && !Object.isFrozen(u)) {
+		Object.freeze(u);
+		for (const value of Object.values(u)) deepFreeze(value);
+	}
+	return u;
+};
+/**
+* An {@link EvaluationCache} in the memory of this isolate or process: a
+* bounded least-recently-used map, with entries that expire `ttlMs` after they
+* are stored. Expiry is checked on `get`; it starts no timer.
+*
+* It holds only plain data (a frozen copy of each value, never a promise or a
+* `Response`), so on Cloudflare Workers requests can share it safely. Each
+* isolate or process has its own: a new isolate starts empty.
+*
+* It trades freshness for fewer billable requests: for up to `ttlMs`, a
+* context that is already cached does not see a flag change.
+*/
+const memoryCache = (options = {}) => {
+	const ttlMs = options.ttlMs ?? 3e4;
+	const maxEntries = options.maxEntries ?? 1e3;
+	if (!(Number.isFinite(ttlMs) && ttlMs > 0)) throw new RangeError("[toggld] `ttlMs` of memoryCache must be a positive, finite number of milliseconds.");
+	if (!(Number.isSafeInteger(maxEntries) && maxEntries > 0)) throw new RangeError("[toggld] `maxEntries` of memoryCache must be a positive integer.");
+	const entries = /* @__PURE__ */ new Map();
+	return {
+		get: (key) => {
+			const entry = entries.get(key);
+			if (entry === void 0) return void 0;
+			entries.delete(key);
+			if (Date.now() >= entry.expiresAt) return void 0;
+			entries.set(key, entry);
+			return entry.value;
+		},
+		set: (key, value) => {
+			entries.delete(key);
+			entries.set(key, {
+				expiresAt: Date.now() + ttlMs,
+				value: deepFreeze(structuredClone(value))
+			});
+			while (entries.size > maxEntries) entries.delete(entries.keys().next().value);
+		}
+	};
+};
+// src/internal/serverless.ts
+const DEFAULT_SERVERLESS_TIMEOUT_MS = 1500;
+const BULK_PATH = "/ofrep/v1/evaluate/flags";
+const positive = (value, fallback) => value !== void 0 && Number.isFinite(value) && value > 0 ? value : fallback;
+const assertCredentials = (options) => {
+	switch (syncCredentialProblem(options)) {
+		case "missing-key": throw new TypeError("[toggld] `sdkKey` is required. The serverless client needs a secret SDK key (ffk_…).");
+		case "public-token": throw new TypeError("[toggld] `sdkKey` is a public token (ffp_…). The serverless client is a server SDK and needs a secret SDK key (ffk_…): public tokens are for browsers, and their budget is shared per IP address, which a server's traffic would exhaust. In the browser, use @toggld/browser.");
+		case "invalid-endpoint": throw new TypeError(invalidEndpointMessage(options.endpoint));
+		case void 0: return;
+	}
+};
+const bulkOf = (flags) => ({
+	ok: true,
+	flags,
+	byKey: new Map(flags.map((entry) => [entry.key, entry]))
+});
+/** A copy for one caller: results are shared by the reads of a view, so nobody may change them. */
+const own = (d) => ({
+	...d,
+	value: typeof d.value === "object" && d.value !== null ? structuredClone(d.value) : d.value,
+	flagMetadata: { ...d.flagMetadata }
+});
+const entryDetails = (entry, fallback) => own(entry.ok ? okDetails(entry.key, entry) : wireErrorDetails(fallback, entry));
+const createServerlessCore = (options) => {
+	assertCredentials(options);
+	const timeoutMs = positive(options.timeoutMs, DEFAULT_SERVERLESS_TIMEOUT_MS);
+	const send = makeSend(options);
+	const cache = options.cache;
+	const cacheEndpoint = apiUrl(options.endpoint, "").toString();
+	const telemetry = options.telemetry === false ? void 0 : makeRequestTelemetry(send, {
+		...options.telemetry ? { telemetry: options.telemetry } : {},
+		timeoutMs
+	});
+	const record = (entry) => {
+		telemetry?.record(entry.key, entry.ok ? {
+			variant: entry.variant,
+			reason: entry.reason
+		} : {
+			variant: void 0,
+			reason: "ERROR"
+		});
+	};
+	let keyHash;
+	const warned = /* @__PURE__ */ new Set();
+	const warnOnce = (kind, message) => {
+		if (warned.has(kind)) return;
+		warned.add(kind);
+		console.warn(`[toggld] ${message} The serverless client sends the bulk request instead.`);
+	};
+	const mergedContext = (context) => ({
+		...options.defaultContext,
+		...context
+	});
+	const fetchBulk = async (context, signal) => {
+		try {
+			return await withTimeout(timeoutMs, async (s) => {
+				const response = await send("POST", BULK_PATH, { context }, s);
+				const status = response.status;
+				if (status >= 200 && status < 300) return bulkOf(decodeOfrepBulk(await readJson(response, `POST ${BULK_PATH}`)));
+				if (status >= 400 && status < 500) try {
+					const failure = decodeOfrepBulkFailure(await response.json());
+					return {
+						ok: false,
+						errorCode: failure.errorCode,
+						message: failure.errorDetails ?? rejectedMessage(response)
+					};
+				} catch {
+					return {
+						ok: false,
+						errorCode: "GENERAL",
+						message: rejectedMessage(response)
+					};
+				}
+				discard(response);
+				return {
+					ok: false,
+					errorCode: "GENERAL",
+					message: `Unexpected response status ${status}`
+				};
+			}, signal);
+		} catch (error) {
+			return {
+				ok: false,
+				errorCode: codeFor(error),
+				message: describe(error)
+			};
+		}
+	};
+	const fromCache = async (cache, key) => {
+		let value;
+		try {
+			value = await withTimeout(timeoutMs, async () => cache.get(key));
+		} catch (error) {
+			warnOnce("get", `The evaluation cache's get failed: ${describe(error)}.`);
+			return;
+		}
+		if (value === void 0 || value === null) return void 0;
+		const flags = decodeCached(value);
+		if (flags === void 0) {
+			warnOnce("shape", "The evaluation cache returned a value that is not a cached bulk result.");
+			return;
+		}
+		return bulkOf(flags);
+	};
+	const store = async (cache, key, result, waitUntil) => {
+		const value = {
+			storedAt: Date.now(),
+			flags: result.flags.map(toCached)
+		};
+		const write = (async () => cache.set(key, value))().then(() => {}, (error) => warnOnce("set", `The evaluation cache's set failed: ${describe(error)}.`));
+		if (waitUntil !== void 0) return waitUntil(write);
+		await withTimeout(timeoutMs, () => write).catch(() => {});
+	};
+	const resolve = async (context, canonical, view, signal) => {
+		let key;
+		if (cache !== void 0) {
+			try {
+				keyHash ??= await sha256Hex(options.sdkKey);
+				key = await cacheKeyFor(cacheEndpoint, keyHash, canonical);
+			} catch (error) {
+				warnOnce("key", `Could not compute the evaluation cache key: ${describe(error)}.`);
+			}
+			if (key !== void 0) {
+				const hit = await fromCache(cache, key);
+				if (hit !== void 0) return hit;
+			}
+		}
+		const result = await fetchBulk(context, view.single ? signal : void 0);
+		if (cache !== void 0 && key !== void 0 && result.ok) await store(cache, key, result, view.waitUntil);
+		return result;
+	};
+	const load = (view, context, signal) => {
+		const merged = mergedContext(context);
+		const canonical = canonicalJson(merged);
+		let result = view.results.get(canonical);
+		if (result === void 0) {
+			result = resolve(merged, canonical, view, signal);
+			view.results.set(canonical, result);
+		}
+		return result;
+	};
+	const evaluate = async (view, key, defaultValue, context, signal) => {
+		const bulk = await load(view, context, signal);
+		try {
+			if (!bulk.ok) return errorDetails(key, defaultValue, bulk.errorCode, bulk.message);
+			const entry = bulk.byKey.get(key);
+			if (entry === void 0) return errorDetails(key, defaultValue, "FLAG_NOT_FOUND", `Flag '${key}' not found`);
+			record(entry);
+			return entryDetails(entry, defaultValue);
+		} finally {
+			telemetry?.check(view.waitUntil);
+		}
+	};
+	return {
+		view: (waitUntil, single = false) => ({
+			waitUntil,
+			single,
+			results: /* @__PURE__ */ new Map()
+		}),
+		load,
+		evaluate,
+		typed: async (view, key, defaultValue, context, type, signal) => enforceType(await evaluate(view, key, defaultValue, context, signal), key, defaultValue, type),
+		evaluateAll: async (view, context, signal) => {
+			const bulk = await load(view, context, signal);
+			try {
+				if (!bulk.ok) return [];
+				for (const entry of bulk.flags) record(entry);
+				return bulk.flags.map((entry) => entryDetails(entry, null));
+			} finally {
+				telemetry?.check(view.waitUntil);
+			}
+		},
+		flushTelemetry: () => telemetry?.flush() ?? Promise.resolve()
+	};
+};
+export { memoryCache as n, createServerlessCore as t };

package/dist/serverless-e__iCjpQ.d.mts

@@ -0,0 +1,206 @@
+import { a as ErrorCode, c as FlagValue, l as Reason, o as EvaluationContext, s as FlagMetadata, t as EvaluationDetails } from "./types-BHn_vrQq.mjs";
+/** One flag of a cached bulk result that resolved: the OFREP success entry. */
+interface CachedFlagSuccess {
+  readonly key: string;
+  readonly value: FlagValue;
+  readonly reason: Reason;
+  readonly variant?: string;
+  readonly metadata?: FlagMetadata;
+}
+/** One flag of a cached bulk result that failed to resolve: the OFREP failure entry. */
+interface CachedFlagFailure {
+  readonly key: string;
+  readonly errorCode: ErrorCode;
+  readonly errorDetails?: string;
+  readonly metadata?: FlagMetadata;
+}
+type CachedFlagEvaluation = CachedFlagSuccess | CachedFlagFailure;
+/**
+ * What the serverless client stores in an {@link EvaluationCache}: the flags of
+ * one bulk evaluation (`POST /ofrep/v1/evaluate/flags`) for one evaluation
+ * context, and when it was stored. Plain JSON: `JSON.stringify` and
+ * `JSON.parse` round-trip it, so any key-value store can hold it.
+ */
+interface CachedEvaluations {
+  /** When the client stored this result, in milliseconds since the epoch (`Date.now()`). */
+  readonly storedAt: number;
+  readonly flags: ReadonlyArray<CachedFlagEvaluation>;
+}
+/**
+ * A cache for bulk evaluation results, shared by requests (and, for a shared
+ * store, by isolates). The serverless client calls `get` before it sends a bulk
+ * request, and `set` after a successful one. **Expiry is the cache's job**: the
+ * client uses any value `get` returns, whatever its age. A value that `get`
+ * throws for, or that does not have the {@link CachedEvaluations} shape, is a
+ * miss. A `set` that throws is ignored.
+ *
+ * Keys start with `toggld:v1:` and are 64 hex characters after that: a SHA-256
+ * hash of the endpoint, a hash of the SDK key, and the evaluation context. They
+ * never contain the SDK key or the context.
+ */
+interface EvaluationCache {
+  get(key: string): CachedEvaluations | undefined | Promise<CachedEvaluations | undefined>;
+  set(key: string, value: CachedEvaluations): void | Promise<void>;
+}
+/** Options of {@link memoryCache}. */
+interface MemoryCacheOptions {
+  /**
+   * How long an entry is used, in milliseconds. Default `30000`. A flag change
+   * can take up to this long to show for a context that is already cached.
+   */
+  readonly ttlMs?: number;
+  /**
+   * How many entries are kept; the least recently used goes first. Default
+   * `1000`. An entry is one evaluation context's result, so this bounds the
+   * number of distinct contexts (usually users) held at once.
+   */
+  readonly maxEntries?: number;
+}
+/**
+ * An {@link EvaluationCache} in the memory of this isolate or process: a
+ * bounded least-recently-used map, with entries that expire `ttlMs` after they
+ * are stored. Expiry is checked on `get`; it starts no timer.
+ *
+ * It holds only plain data (a frozen copy of each value, never a promise or a
+ * `Response`), so on Cloudflare Workers requests can share it safely. Each
+ * isolate or process has its own: a new isolate starts empty.
+ *
+ * It trades freshness for fewer billable requests: for up to `ttlMs`, a
+ * context that is already cached does not see a flag change.
+ */
+declare const memoryCache: (options?: MemoryCacheOptions) => EvaluationCache;
+/** Configuration for {@link createServerlessClient}. */
+interface ServerlessClientOptions {
+  /**
+   * A **secret** SDK key (`ffk_…`), sent as `Authorization: Bearer <sdkKey>`.
+   * An evaluation key is enough. Public tokens (`ffp_…`) are for browsers, so
+   * `createServerlessClient` throws a `TypeError` for them.
+   */
+  readonly sdkKey: string;
+  /**
+   * Base URL of the flag API, such as `https://api.toggld.io`. It may have a
+   * path prefix, for a proxy on your own domain (`https://flags.example.com/toggld`):
+   * requests go to `<endpoint>/ofrep/v1/evaluate/flags`.
+   */
+  readonly endpoint: string;
+  /**
+   * Timeout of each bulk request (and each cache call), in milliseconds.
+   * Default `1500`. A request that runs out of time resolves every evaluation
+   * of its context to the caller's default with `GENERAL`.
+   */
+  readonly timeoutMs?: number;
+  /**
+   * Attributes merged into the evaluation context of every evaluation, under
+   * the per-call context (per-call attributes win).
+   */
+  readonly defaultContext?: EvaluationContext;
+  /**
+   * Custom `fetch`. Defaults to the global `fetch`. On Cloudflare Workers, a
+   * service binding to your own proxy Worker fits here:
+   * `fetch: (input, init) => env.FLAG_PROXY.fetch(input, init)`.
+   */
+  readonly fetch?: typeof globalThis.fetch;
+  /**
+   * An optional cache of bulk results, keyed by endpoint, SDK key, and
+   * evaluation context. Without one, every request view sends its own bulk
+   * request (per context), and changes show on the next request. With one, a
+   * cached context sends no request until the cache expires the entry: fewer
+   * billable requests, older values. {@link memoryCache} keeps entries in the
+   * isolate's memory; any key-value store (Workers KV, the Cache API, Redis)
+   * can implement {@link EvaluationCache}.
+   */
+  readonly cache?: EvaluationCache;
+  /**
+   * Evaluation telemetry, on by default. The API does not count bulk requests
+   * in your flag analytics (a bulk answer holds every flag, not the ones you
+   * read), so the client counts each read that resolves a flag, cache hits
+   * included, and sends the counts to `POST /v1/telemetry`: grouped per flag,
+   * variant, reason, and minute, with no evaluation context or values.
+   *
+   * A send is due when the oldest count is `flushIntervalMs` old (default
+   * `30000`) or 1,000 cells are counted, and a request view that reads a
+   * flag starts it: in the request's `waitUntil` when `forRequest(ctx)` has
+   * one, else without waiting for it (on AWS Lambda, which freezes after the
+   * handler returns, a send may then be cut off). Evaluations and responses
+   * never wait for telemetry, and at most one send runs at a time. Counts
+   * live in the client (one per isolate or process), so they are sent by a
+   * later request and lost if the isolate or process ends first.
+   *
+   * Sends go through the same `endpoint` and `fetch` as evaluations. Set
+   * `false` to send nothing: these reads are then not in analytics.
+   */
+  readonly telemetry?: false | {
+    readonly flushIntervalMs?: number;
+  };
+}
+/**
+ * The request context {@link ServerlessClient.forRequest} reads: the Workers
+ * `ExecutionContext`, or any object with `waitUntil` (Vercel's `waitUntil`
+ * from `@vercel/functions`, a Next.js middleware `event`, …). An object
+ * without `waitUntil`, such as the AWS Lambda `context`, counts as none.
+ */
+interface WaitUntilContext {
+  readonly waitUntil?: ((promise: Promise<unknown>) => void) | undefined;
+}
+/** The evaluation surface for one request. Every method resolves; none rejects. */
+interface ServerlessRequestClient {
+  /** Resolve a flag, returning full details with an untyped (JSON) value. */
+  evaluate(key: string, defaultValue: FlagValue, context?: EvaluationContext): Promise<EvaluationDetails<FlagValue>>;
+  /**
+   * Every flag of the environment for this context, from the same bulk request
+   * as the other reads. Empty if that request failed.
+   */
+  evaluateAll(context?: EvaluationContext): Promise<ReadonlyArray<EvaluationDetails<FlagValue>>>;
+  getBooleanValue(key: string, defaultValue: boolean, context?: EvaluationContext): Promise<boolean>;
+  getBooleanDetails(key: string, defaultValue: boolean, context?: EvaluationContext): Promise<EvaluationDetails<boolean>>;
+  getStringValue(key: string, defaultValue: string, context?: EvaluationContext): Promise<string>;
+  getStringDetails(key: string, defaultValue: string, context?: EvaluationContext): Promise<EvaluationDetails<string>>;
+  getNumberValue(key: string, defaultValue: number, context?: EvaluationContext): Promise<number>;
+  getNumberDetails(key: string, defaultValue: number, context?: EvaluationContext): Promise<EvaluationDetails<number>>;
+  getObjectValue<T extends FlagValue>(key: string, defaultValue: T, context?: EvaluationContext): Promise<T>;
+  getObjectDetails<T extends FlagValue>(key: string, defaultValue: T, context?: EvaluationContext): Promise<EvaluationDetails<T>>;
+}
+/** A serverless client. Create one per isolate or process (in module scope), and a request view per request. */
+interface ServerlessClient {
+  /**
+   * The evaluation surface for one incoming request. Its first evaluation for
+   * a context sends one bulk request; later reads with the same context
+   * (`defaultContext` merged in) use that answer, and concurrent first reads
+   * share it. A different context sends its own bulk request.
+   *
+   * `ctx` carries the request's `waitUntil` (Workers `ctx`, Vercel). With
+   * one, cache writes and telemetry sends run after the response. Without one
+   * (`forRequest()`, AWS Lambda, Node serverless functions), cache writes run
+   * inline, bounded by `timeoutMs`, and never fail an evaluation; telemetry
+   * sends start without being awaited (see {@link ServerlessClientOptions.telemetry}).
+   *
+   * Use the returned object only within that request, and create a new one
+   * for the next: on Workers, I/O started by one request cannot be awaited by
+   * another.
+   */
+  forRequest(ctx?: WaitUntilContext | object): ServerlessRequestClient;
+  /**
+   * Send the counted reads now, whether or not a send is due (see
+   * {@link ServerlessClientOptions.telemetry}). If a send is already in
+   * flight, it waits for that send first, then sends what is left. Bounded by
+   * `timeoutMs` as a whole; it never rejects, and a failed send stays queued
+   * for retry. With `telemetry: false`, it does nothing.
+   *
+   * Runtimes with a `waitUntil` (Workers, Vercel) do not need it. On runtimes
+   * without one, such as AWS Lambda, which freezes the process when the
+   * handler returns, call it before returning, or in the platform's shutdown
+   * hook if there is one. Awaiting it delays the response by up to
+   * `timeoutMs`.
+   */
+  flushTelemetry(): Promise<void>;
+}
+/**
+ * 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.
+ */
+declare const createServerlessClient: (options: ServerlessClientOptions) => ServerlessClient;
+export { createServerlessClient as a, CachedFlagFailure as c, MemoryCacheOptions as d, memoryCache as f, WaitUntilContext as i, CachedFlagSuccess as l, ServerlessClientOptions as n, CachedEvaluations as o, ServerlessRequestClient as r, CachedFlagEvaluation as s, ServerlessClient as t, EvaluationCache as u };

package/dist/serverless-effect.d.mts

@@ -0,0 +1,51 @@
+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 { n as ToggldClientShape, t as ToggldClient } from "./effectService-CGZnDaqS.mjs";
+import { c as CachedFlagFailure, d as MemoryCacheOptions, f as memoryCache, l as CachedFlagSuccess, n as ServerlessClientOptions, o as CachedEvaluations, s as CachedFlagEvaluation, u as EvaluationCache } from "./serverless-e__iCjpQ.mjs";
+import { Context, Effect, Layer } from "effect";
+declare const WaitUntil_base: Context.ServiceClass<WaitUntil, "@toggld/js/serverless/WaitUntil", {
+  readonly waitUntil: (promise: Promise<unknown>) => void;
+}>;
+/**
+ * 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.
+ */
+export declare class WaitUntil extends WaitUntil_base {}
+declare const RequestScope_base: Context.ServiceClass<RequestScope, "@toggld/js/serverless/RequestScope", {
+  readonly views: Map<unknown, unknown>;
+}>;
+/**
+ * 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.
+ */
+export declare class RequestScope extends RequestScope_base {}
+/** What {@link withWaitUntil} accepts: a Workers `ExecutionContext`, or any object with `waitUntil`. */
+export interface WaitUntilSource {
+  readonly waitUntil: (promise: Promise<unknown>) => void;
+}
+/**
+ * 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.
+ */
+export declare const withRequest: (ctx?: WaitUntilSource | object) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, WaitUntil | RequestScope>>;
+/** {@link withRequest} as a layer. Build it once per incoming request. */
+export declare const requestLayer: (ctx?: WaitUntilSource | object) => Layer.Layer<RequestScope | WaitUntil>;
+/** The same as {@link withRequest} with a `waitUntil` source: a request scope and its {@link WaitUntil}. */
+export declare const withWaitUntil: (source: WaitUntilSource) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, WaitUntil | RequestScope>>;
+/** {@link WaitUntil} and a fresh {@link RequestScope} as a layer, for one request. */
+export declare const waitUntilLayer: (source: WaitUntilSource) => Layer.Layer<RequestScope | WaitUntil>;
+/**
+ * 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`.
+ */
+export declare const layer: (options: ServerlessClientOptions) => Layer.Layer<ToggldClient>;
+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, type ServerlessClientOptions, ToggldClient, type ToggldClientShape, memoryCache };