@toggld/js 0.0.0-stage → 0.9.0

package/dist/details-AiMdctXB.mjs

@@ -0,0 +1,365 @@
+import { d as discard, h as withTimeout, m as refusalMessage, t as WireError } from "./wire-CrkBeqnM.mjs";
+// src/internal/telemetry.ts
+const DEFAULT_FLUSH_INTERVAL_MS = 3e4;
+const MAX_CELLS = 1e4;
+const MAX_COUNT = 1e9;
+const BATCH_SIZE = 1e3;
+/** A client that does not report: file mode, or `telemetry: false`. */
+const noTelemetry = {
+	record: () => {},
+	flush: () => Promise.resolve(),
+	close: () => Promise.resolve()
+};
+/** The configured flush interval, or the default for a missing or unusable one. */
+const flushInterval = (telemetry) => {
+	const configured = telemetry === false ? void 0 : telemetry?.flushIntervalMs;
+	return configured !== void 0 && Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_FLUSH_INTERVAL_MS;
+};
+/**
+* The counting half: bounded, synchronous `record`, and `take`, which turns the
+* counts so far into batches ready to send (each with a fresh `windowId`) and
+* starts a new window.
+*/
+const makeRollups = () => {
+	let cells = /* @__PURE__ */ new Map();
+	let openedAt;
+	return {
+		isEmpty: () => cells.size === 0,
+		size: () => cells.size,
+		openedAt: () => openedAt,
+		take: (instanceId) => {
+			const rollups = [...cells.values()];
+			cells = /* @__PURE__ */ new Map();
+			openedAt = void 0;
+			const batches = [];
+			for (let i = 0; i < rollups.length; i += BATCH_SIZE) batches.push({
+				sdkInstanceId: instanceId,
+				windowId: crypto.randomUUID(),
+				rollups: rollups.slice(i, i + BATCH_SIZE)
+			});
+			return batches;
+		},
+		record: (flagKey, resolution) => {
+			if (flagKey.length === 0 || flagKey.length > 256 || (resolution.variant?.length ?? 0) > 256) return;
+			const variant = resolution.variant ?? "";
+			const now = Date.now();
+			const bucketStart = (/* @__PURE__ */ new Date(Math.floor(now / 6e4) * 6e4)).toISOString();
+			const key = JSON.stringify([
+				flagKey,
+				variant,
+				resolution.reason,
+				bucketStart
+			]);
+			const cell = cells.get(key);
+			if (cell) {
+				if (cell.count < MAX_COUNT) cells.set(key, {
+					...cell,
+					count: cell.count + 1
+				});
+			} else if (cells.size < MAX_CELLS) cells.set(key, {
+				flagKey,
+				variant,
+				reason: resolution.reason,
+				bucketStart,
+				count: 1
+			});
+			else return;
+			openedAt ??= now;
+		}
+	};
+};
+/** Send one batch; `true` once the API acknowledged it. Never rejects. */
+const sendBatch = async (send, batch, timeoutMs, signal) => {
+	try {
+		const response = await withTimeout(timeoutMs, (s) => send("POST", "/v1/telemetry", batch, s), signal);
+		discard(response);
+		return response.status >= 200 && response.status < 300;
+	} catch {
+		return false;
+	}
+};
+const startTelemetry = (send, options) => {
+	const instanceId = crypto.randomUUID();
+	const interval = flushInterval(options.telemetry);
+	const timeoutMs = options.timeoutMs ?? 5e3;
+	const rollups = makeRollups();
+	const pending = [];
+	let tail = Promise.resolve();
+	const serialized = (signal) => {
+		const run = tail.then(() => flushNow(signal));
+		tail = run.catch(() => {});
+		return run;
+	};
+	const flushNow = async (signal) => {
+		for (let pass = 0; pass < 2; pass++) {
+			if (pending.length === 0) pending.push(...rollups.take(instanceId));
+			while (pending.length > 0) {
+				if (!await sendBatch(send, pending[0], timeoutMs, signal)) return;
+				pending.shift();
+			}
+		}
+	};
+	const periodic = new AbortController();
+	let timer;
+	const schedule = () => {
+		timer = setTimeout(() => {
+			serialized(periodic.signal).then(() => {
+				if (!periodic.signal.aborted) schedule();
+			});
+		}, interval);
+		if (options.unref === true) timer?.unref?.();
+	};
+	schedule();
+	let closing;
+	return {
+		flush: () => serialized(void 0),
+		close: () => closing ??= (async () => {
+			clearTimeout(timer);
+			periodic.abort();
+			await withTimeout(timeoutMs, (signal) => serialized(signal)).catch(() => {});
+		})(),
+		record: rollups.record
+	};
+};
+/**
+* {@link startTelemetry} on the first count: no id, timer, or request before
+* a client has something to report. Remote mode uses it, since most remote
+* clients only evaluate single flags, which the API counts itself.
+*/
+const lazyTelemetry = (start) => {
+	let started;
+	let closed = false;
+	return {
+		record: (flagKey, resolution) => {
+			if (closed) return;
+			(started ??= start()).record(flagKey, resolution);
+		},
+		flush: () => started?.flush() ?? Promise.resolve(),
+		close: () => {
+			closed = true;
+			return started?.close() ?? Promise.resolve();
+		}
+	};
+};
+/** How often `flush` looks whether a send in flight has ended. */
+const FLUSH_POLL_MS = 25;
+/**
+* Telemetry flushed by the requests that record it, for runtimes where
+* nothing may run between requests (the serverless client, ADR-0020). All of
+* its state is plain data (counts, numbers, batches), never a promise, so
+* any request of the isolate or process may send it: on Workers, I/O started
+* by one request cannot be awaited by another.
+*
+* - **Due** when the oldest count not sent is `flushIntervalMs` old (default
+*   30 seconds), there are {@link REQUEST_FLUSH_CELLS} cells, or a failed
+*   window waits for its retry; checked by the request that records or
+*   finishes a read ({@link RequestTelemetry.check}).
+* - **At most one send in flight.** It holds a lease (the time its sends may
+*   take, with their timeouts) instead of a promise: a runtime may stop a
+*   `waitUntil` without settling it, and the lease lets a later request send.
+* - **Failed windows** stay queued with their `windowId` and are retried
+*   first, one interval later; meanwhile new counts add up in the bounded
+*   cells. The queue holds at most one take (10,000 cells, so at most 10
+*   batches of 1,000). The API does not deduplicate windows, so a window
+*   resent after a lost response is counted twice, which is accepted.
+* - Nothing random runs before the first send: Workers refuse random values
+*   in global scope, where the client is created. The instance id is made on
+*   the first send.
+*/
+const makeRequestTelemetry = (send, options) => {
+	const interval = flushInterval(options.telemetry);
+	const timeoutMs = options.timeoutMs ?? 5e3;
+	const rollups = makeRollups();
+	let instanceId;
+	let pending = [];
+	let lease = {
+		id: 0,
+		until: 0
+	};
+	let leases = 0;
+	let retryAt = 0;
+	const due = (now) => {
+		if (now < lease.until || now < retryAt) return false;
+		if (pending.length > 0 || rollups.size() >= 1e3) return true;
+		const openedAt = rollups.openedAt();
+		return openedAt !== void 0 && now - openedAt >= interval;
+	};
+	const run = async () => {
+		const id = ++leases;
+		try {
+			for (let pass = 0; pass < 2; pass++) {
+				if (pending.length === 0 && !rollups.isEmpty()) pending = rollups.take(instanceId ??= crypto.randomUUID());
+				const batches = [...pending];
+				if (batches.length === 0) return;
+				lease = {
+					id,
+					until: Date.now() + timeoutMs * (batches.length + 1)
+				};
+				for (const batch of batches) {
+					if (!await sendBatch(send, batch, timeoutMs, void 0)) {
+						retryAt = Date.now() + interval;
+						return;
+					}
+					const index = pending.indexOf(batch);
+					if (index >= 0) pending.splice(index, 1);
+					retryAt = 0;
+				}
+			}
+		} finally {
+			if (lease.id === id) lease = {
+				id,
+				until: 0
+			};
+		}
+	};
+	return {
+		record: rollups.record,
+		check: (waitUntil) => {
+			if (!due(Date.now())) return;
+			const sending = run().catch(() => {});
+			if (waitUntil !== void 0) waitUntil(sending);
+		},
+		flush: async () => {
+			const deadline = Date.now() + timeoutMs;
+			while (Date.now() < lease.until) {
+				const left = deadline - Date.now();
+				if (left <= 0) return;
+				await new Promise((resolve) => setTimeout(resolve, Math.min(FLUSH_POLL_MS, left)));
+			}
+			const left = deadline - Date.now();
+			if (left <= 0) return;
+			await withTimeout(left, () => run()).catch(() => {});
+		}
+	};
+};
+// src/internal/remote.ts
+/** The details of an OFREP success. */
+const okDetails = (key, s) => ({
+	flagKey: key,
+	value: s.value,
+	variant: s.variant,
+	reason: s.reason,
+	errorCode: void 0,
+	errorMessage: void 0,
+	flagMetadata: s.metadata ?? {}
+});
+/** The details of an OFREP failure: the caller's `fallback` with the server's error code. */
+const wireErrorDetails = (fallback, e) => ({
+	flagKey: e.key,
+	value: fallback,
+	variant: void 0,
+	reason: "ERROR",
+	errorCode: e.errorCode,
+	errorMessage: e.errorDetails,
+	flagMetadata: e.metadata ?? {}
+});
+/** Why the API refused an OFREP request whose response is not an OFREP failure. */
+const rejectedMessage = (response) => refusalMessage(response, "The SDK key cannot evaluate flags (HTTP 403).");
+/** A body of the wrong shape is a `PARSE_ERROR`; anything else (network, timeout, not JSON) is `GENERAL`. */
+const codeFor = (e) => e instanceof WireError ? "PARSE_ERROR" : "GENERAL";
+// ../spec/src/index.ts
+/** True when `value` is assignable to a flag declared as `type`. */
+const valueMatchesType = (value, type) => {
+	switch (type) {
+		case "boolean": return typeof value === "boolean";
+		case "string": return typeof value === "string";
+		case "number": return typeof value === "number" && Number.isFinite(value);
+		case "object": return typeof value === "object" && value !== null;
+	}
+};
+/**
+* The sync stream's WebSocket subprotocol name. Offered first by clients (the
+* server echoes the first offer back, completing the RFC 6455 negotiation).
+*/
+const SYNC_PROTOCOL = "toggld.sync.v1";
+/**
+* Subprotocol entry carrying the bearer credential on a sync WebSocket
+* upgrade: `toggld.bearer.<token>`. The standard `WebSocket` constructor
+* cannot set an `Authorization` header, so the token rides the
+* `Sec-WebSocket-Protocol` offer instead (a recognized pattern — it stays out
+* of URLs and access logs). Servers accept either this or a real
+* `Authorization: Bearer` header.
+*/
+const SYNC_BEARER_PROTOCOL_PREFIX = "toggld.bearer.";
+/**
+* Heartbeat on the evaluation stream and the sync stream: the client sends the
+* text frame {@link STREAM_PING} (not JSON) and the server answers {@link STREAM_PONG}.
+* Without it, a connection that a proxy or a sleeping laptop dropped silently
+* would look open forever. Plain fixed strings, so a Durable Object can answer
+* with an auto-response without waking from hibernation.
+*/
+const STREAM_PING = "ping";
+const STREAM_PONG = "pong";
+/** How often the client pings, and how long it waits for the pong before it reconnects. */
+const STREAM_PING_INTERVAL_MS = 3e4;
+const STREAM_PONG_TIMEOUT_MS = 1e4;
+const TARGETING_KEY = "targetingKey";
+/** Reads the targeting key from a context, if present and a non-empty string. */
+const targetingKeyOf = (ctx) => {
+	const v = ctx[TARGETING_KEY];
+	return typeof v === "string" && v.length > 0 ? v : void 0;
+};
+/** Reads an arbitrary attribute, treating `targetingKey` like any other field. */
+const attributeOf = (ctx, attribute) => Object.prototype.hasOwnProperty.call(ctx, attribute) ? ctx[attribute] : void 0;
+const Resolution = {
+	/** A successful resolution. */
+	ok: (args) => ({
+		value: args.value,
+		variant: args.variant,
+		reason: args.reason,
+		errorCode: void 0,
+		errorMessage: void 0,
+		flagMetadata: args.flagMetadata ?? {}
+	}),
+	/** An abnormal resolution carrying an error code and a fallback value. */
+	error: (args) => ({
+		value: args.value,
+		variant: args.variant,
+		reason: "ERROR",
+		errorCode: args.errorCode,
+		errorMessage: args.errorMessage,
+		flagMetadata: args.flagMetadata ?? {}
+	})
+};
+const isBoolean = (v) => typeof v === "boolean";
+const isString = (v) => typeof v === "string";
+const isNumber = (v) => typeof v === "number" && Number.isFinite(v);
+const isObject = (v) => valueMatchesType(v, "object");
+const GUARDS = {
+	boolean: isBoolean,
+	string: isString,
+	number: isNumber,
+	object: isObject
+};
+const errorDetails = (key, value, errorCode, errorMessage, flagMetadata = {}) => ({
+	flagKey: key,
+	value,
+	variant: void 0,
+	reason: "ERROR",
+	errorCode,
+	errorMessage,
+	flagMetadata: { ...flagMetadata }
+});
+/**
+* Enforce the requested value type on resolved details: a value of another
+* type serves the caller's default with `TYPE_MISMATCH`. Error details pass
+* through unchanged.
+*/
+const enforceType = (d, key, defaultValue, type) => {
+	if (d.errorCode !== void 0 || GUARDS[type](d.value)) return d;
+	return errorDetails(key, defaultValue, "TYPE_MISMATCH", `Flag '${key}' value is not of type ${type}`, d.flagMetadata);
+};
+const syncCredentialProblem = (options) => {
+	const key = options.sdkKey;
+	if (typeof key !== "string" || key.trim() === "") return "missing-key";
+	if (key.startsWith("ffp_")) return "public-token";
+	let url;
+	try {
+		url = new URL(options.endpoint ?? "");
+	} catch {
+		url = void 0;
+	}
+	if (url === void 0 || url.protocol !== "https:" && url.protocol !== "http:") return "invalid-endpoint";
+};
+const invalidEndpointMessage = (endpoint) => `[toggld] \`endpoint\` must be the http(s) URL of the Toggld API, such as https://api.toggld.io (got ${JSON.stringify(endpoint)}).`;
+export { wireErrorDetails as _, Resolution as a, noTelemetry as b, STREAM_PONG as c, SYNC_PROTOCOL as d, attributeOf as f, rejectedMessage as g, okDetails as h, syncCredentialProblem as i, STREAM_PONG_TIMEOUT_MS as l, codeFor as m, errorDetails as n, STREAM_PING as o, targetingKeyOf as p, invalidEndpointMessage as r, STREAM_PING_INTERVAL_MS as s, enforceType as t, SYNC_BEARER_PROTOCOL_PREFIX as u, lazyTelemetry as v, startTelemetry as x, makeRequestTelemetry as y };

package/dist/effect.d.mts

@@ -0,0 +1,17 @@
+import { a as ErrorCode, c as FlagValue, i as ToggldClientOptions, l as Reason, n as EvaluationMode, o as EvaluationContext, r as SyncOptions, s as FlagMetadata, t as EvaluationDetails } from "./types-BHn_vrQq.mjs";
+import { n as ToggldClientShape, t as ToggldClient } from "./effectService-CGZnDaqS.mjs";
+import { Layer } from "effect";
+/**
+ * A self-contained `Layer` providing {@link ToggldClient}. Building it waits
+ * for the first snapshot for up to `sync.readyTimeoutMs` (default 5 s), like
+ * `ToggldClient.create`; set it to `0` not to wait, and `yield* flags.ready`
+ * where you need the data. In sync mode (the default) background sync lives
+ * in the layer's scope: closing it (e.g. `ManagedRuntime.dispose`) stops sync,
+ * closes the stream, and flushes telemetry.
+ *
+ * Options that can never sync — no `sdkKey`, a public token (`ffp_…`), or no
+ * valid `endpoint` in sync mode — make the layer die with a `TypeError`, as do
+ * `mode: "local"`, `sync.file`, and `file` without `mode: "file"`.
+ */
+export declare const layer: (options: ToggldClientOptions) => Layer.Layer<ToggldClient>;
+export { type ErrorCode, type EvaluationContext, type EvaluationDetails, type EvaluationMode, type FlagMetadata, type FlagValue, type Reason, type SyncOptions, ToggldClient, type ToggldClientOptions, type ToggldClientShape };

package/dist/effect.mjs

@@ -0,0 +1,75 @@
+import { t as makeCore } from "./core-BQfyNOoT.mjs";
+import { t as ToggldClient } from "./effectService-DPD-fNCI.mjs";
+import { Effect, Layer } from "effect";
+// src/effect.ts
+/**
+* `@toggld/js/effect` — the native Effect API. Needs the optional `effect`
+* peer dependency (`^4.0.5`); the default `@toggld/js` entry does not.
+*
+* The client as a scoped service: build a {@link layer} from your options,
+* compose it into your runtime, and `yield* ToggldClient` to evaluate. The
+* layer's scope owns the client: closing it stops sync, closes the stream, and
+* sends remaining telemetry.
+*
+* ```ts
+* import { Effect } from "effect"
+* import { ToggldClient, layer } from "@toggld/js/effect"
+*
+* const program = Effect.gen(function* () {
+*   const flags = yield* ToggldClient
+*   return yield* flags.getBooleanValue("new-checkout", false, { targetingKey: "user-123" })
+* })
+*
+* program.pipe(Effect.provide(layer({ sdkKey, endpoint })), Effect.runPromise)
+* ```
+*
+* Like `ToggldClient.create`, the layer runs sync mode by default and waits
+* for the first snapshot for up to `sync.readyTimeoutMs`; pass `mode: "file"`
+* to evaluate from a flag file, or `mode: "remote"` to send each evaluation to
+* the API instead.
+*
+* This is a thin wrapper over the dependency-free core in `./internal/core.ts`,
+* which is the implementation of both entries. In-process (sync and file
+* mode) evaluations are synchronous effects; remote ones are interruptible (interrupting one aborts
+* its request).
+*/
+/** Lift a core call: a plain (in-process) result stays synchronous; a remote one is interruptible. */
+const lift = (core, run) => core.synchronous ? Effect.sync(() => run()) : Effect.promise((signal) => Promise.resolve(run(signal)));
+const fromCore = (core) => {
+	const typed = (key, defaultValue, context, type) => lift(core, (signal) => core.typed(key, defaultValue, context, type, signal));
+	const value = (details) => Effect.map(details, (d) => d.value);
+	return {
+		ready: Effect.promise(() => core.ready()),
+		flushTelemetry: Effect.promise(() => core.flushTelemetry()),
+		evaluate: (key, defaultValue, context) => lift(core, (signal) => core.evaluate(key, defaultValue, context, signal)),
+		evaluateAll: (context) => lift(core, (signal) => core.evaluateAll(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"))
+	};
+};
+/**
+* Create a client owned by the current scope: it closes when the scope does.
+* Waits for the first snapshot like `ToggldClient.create`, bounded by
+* `sync.readyTimeoutMs`.
+*/
+const make = (options) => Effect.acquireRelease(Effect.sync(() => makeCore(options)), (core) => Effect.promise(() => core.close())).pipe(Effect.tap((core) => Effect.promise(() => core.waitForReady())), Effect.map(fromCore));
+/**
+* A self-contained `Layer` providing {@link ToggldClient}. Building it waits
+* for the first snapshot for up to `sync.readyTimeoutMs` (default 5 s), like
+* `ToggldClient.create`; set it to `0` not to wait, and `yield* flags.ready`
+* where you need the data. In sync mode (the default) background sync lives
+* in the layer's scope: closing it (e.g. `ManagedRuntime.dispose`) stops sync,
+* closes the stream, and flushes telemetry.
+*
+* Options that can never sync — no `sdkKey`, a public token (`ffp_…`), or no
+* valid `endpoint` in sync mode — make the layer die with a `TypeError`, as do
+* `mode: "local"`, `sync.file`, and `file` without `mode: "file"`.
+*/
+const layer = (options) => Layer.effect(ToggldClient, make(options));
+export { ToggldClient, layer };

package/dist/effectService-CGZnDaqS.d.mts

@@ -0,0 +1,48 @@
+import { c as FlagValue, o as EvaluationContext, t as EvaluationDetails } from "./types-BHn_vrQq.mjs";
+import { Context, Effect } from "effect";
+/** The evaluation surface of a Toggld client. Every method is non-failing. */
+interface ToggldClientShape {
+  /**
+   * Completes once the client is ready to evaluate.
+   *
+   * - `@toggld/js/effect`: on the first synced snapshot in sync mode, the
+   *   first read of the file in file mode;
+   *   immediately in remote mode. The layer already waits for this for up to
+   *   `sync.readyTimeoutMs`; this effect has no timeout of its own.
+   * - `@toggld/js/serverless/effect`: immediately (it is a remote client).
+   *
+   * In sync and file modes, until a snapshot arrives, evaluations resolve to
+   * the caller's default with `PROVIDER_NOT_READY`.
+   */
+  readonly ready: Effect.Effect<void>;
+  /**
+   * Send buffered telemetry. Failed windows remain queued for retry. Sync
+   * mode counts every evaluation; remote mode only `evaluateAll` entries (the
+   * API counts single evaluations); the serverless client every read that
+   * resolves a flag, and completes at once if a send is already in flight.
+   * Completes at once in file mode or with `telemetry: false`.
+   */
+  readonly flushTelemetry: Effect.Effect<void>;
+  /** Resolve a flag, returning full details with an untyped (JSON) value. */
+  readonly evaluate: (key: string, defaultValue: FlagValue, context?: EvaluationContext) => Effect.Effect<EvaluationDetails<FlagValue>>;
+  /** Resolve every flag for the environment (one request in remote mode; in-process otherwise). */
+  readonly evaluateAll: (context?: EvaluationContext) => Effect.Effect<ReadonlyArray<EvaluationDetails<FlagValue>>>;
+  readonly getBooleanValue: (key: string, defaultValue: boolean, context?: EvaluationContext) => Effect.Effect<boolean>;
+  readonly getBooleanDetails: (key: string, defaultValue: boolean, context?: EvaluationContext) => Effect.Effect<EvaluationDetails<boolean>>;
+  readonly getStringValue: (key: string, defaultValue: string, context?: EvaluationContext) => Effect.Effect<string>;
+  readonly getStringDetails: (key: string, defaultValue: string, context?: EvaluationContext) => Effect.Effect<EvaluationDetails<string>>;
+  readonly getNumberValue: (key: string, defaultValue: number, context?: EvaluationContext) => Effect.Effect<number>;
+  readonly getNumberDetails: (key: string, defaultValue: number, context?: EvaluationContext) => Effect.Effect<EvaluationDetails<number>>;
+  readonly getObjectValue: <T extends FlagValue>(key: string, defaultValue: T, context?: EvaluationContext) => Effect.Effect<T>;
+  readonly getObjectDetails: <T extends FlagValue>(key: string, defaultValue: T, context?: EvaluationContext) => Effect.Effect<EvaluationDetails<T>>;
+}
+declare const ToggldClient_base: Context.ServiceClass<ToggldClient, "@toggld/js/ToggldClient", ToggldClientShape>;
+/**
+ * The Toggld client as an Effect service. Build a layer from options and
+ * compose it into your runtime, then `yield* ToggldClient` to evaluate flags.
+ * One tag for both Effect entries: `layer` from `@toggld/js/effect` (sync,
+ * file, or remote mode) and `layer` from `@toggld/js/serverless/effect` provide it, so
+ * program code is the same with either.
+ */
+declare class ToggldClient extends ToggldClient_base {}
+export { ToggldClientShape as n, ToggldClient as t };

package/dist/effectService-DPD-fNCI.mjs

@@ -0,0 +1,17 @@
+import { Context } from "effect";
+// src/internal/effectService.ts
+/**
+* The Effect service shared by `@toggld/js/effect` and
+* `@toggld/js/serverless/effect`: the {@link ToggldClient} tag and its
+* {@link ToggldClientShape}. It imports only `effect` and types, so the
+* serverless Effect entry can use it without the main client's `node:` imports.
+*/
+/**
+* The Toggld client as an Effect service. Build a layer from options and
+* compose it into your runtime, then `yield* ToggldClient` to evaluate flags.
+* One tag for both Effect entries: `layer` from `@toggld/js/effect` (sync,
+* file, or remote mode) and `layer` from `@toggld/js/serverless/effect` provide it, so
+* program code is the same with either.
+*/
+var ToggldClient = class extends Context.Service()("@toggld/js/ToggldClient") {};
+export { ToggldClient as t };

package/dist/index.d.mts

@@ -0,0 +1,54 @@
+import { a as ErrorCode, c as FlagValue, i as ToggldClientOptions, l as Reason, n as EvaluationMode, o as EvaluationContext, r as SyncOptions, s as FlagMetadata, t as EvaluationDetails } from "./types-BHn_vrQq.mjs";
+/**
+ * A Toggld client. Create one with {@link ToggldClient.create} and {@link
+ * ToggldClient.close} it on shutdown to stop background sync.
+ */
+export declare class ToggldClient {
+  #private;
+  private constructor();
+  /**
+   * 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 create(options: ToggldClientOptions): Promise<ToggldClient>;
+  /**
+   * 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(): Promise<void>;
+  /** Send buffered counts without failing evaluations. Failed windows remain queued. */
+  flushTelemetry(): Promise<void>;
+  /** Resolve a flag, returning full details with an untyped (JSON) value. */
+  evaluate(key: string, defaultValue: FlagValue, context?: EvaluationContext): Promise<EvaluationDetails<FlagValue>>;
+  /** Resolve every flag for the environment (one request in remote mode; in-process in sync and file modes). */
+  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>>;
+  /**
+   * 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(): Promise<void>;
+}
+export type { ErrorCode, EvaluationContext, EvaluationDetails, EvaluationMode, FlagMetadata, FlagValue, Reason, SyncOptions, ToggldClientOptions };