@toggld/js 0.0.0-stage → 0.9.0

package/dist/wire-CrkBeqnM.mjs

@@ -0,0 +1,447 @@
+// src/internal/http.ts
+/**
+* The small HTTP layer the SDK needs: authenticated JSON requests through the
+* configured `fetch`, and a timeout that bounds a whole request, body included.
+*/
+/** A request that ran out of time. */
+var TimeoutError = class extends Error {
+	constructor(ms) {
+		super(`The request timed out after ${ms} ms`);
+		this.name = "TimeoutError";
+	}
+};
+/** A request abandoned because its caller went away (the client closed). */
+var AbortedError = class extends Error {
+	constructor() {
+		super("The request was cancelled");
+		this.name = "AbortedError";
+	}
+};
+/**
+* Run `run` with a signal that aborts after `ms`, or when `outer` aborts. The
+* returned promise settles at that moment even if `run` ignores its signal: a
+* custom `fetch` that never settles must not stall a poll or a shutdown.
+*/
+const withTimeout = (ms, run, outer) => new Promise((resolve, reject) => {
+	if (outer?.aborted) return reject(new AbortedError());
+	const controller = new AbortController();
+	let settled = false;
+	const done = () => {
+		settled = true;
+		clearTimeout(timer);
+		outer?.removeEventListener("abort", onOuter);
+	};
+	const onOuter = () => {
+		if (settled) return;
+		done();
+		const error = new AbortedError();
+		controller.abort(error);
+		reject(error);
+	};
+	const timer = setTimeout(() => {
+		if (settled) return;
+		done();
+		const error = new TimeoutError(ms);
+		controller.abort(error);
+		reject(error);
+	}, ms);
+	outer?.addEventListener("abort", onOuter, { once: true });
+	let pending;
+	try {
+		pending = run(controller.signal);
+	} catch (error) {
+		pending = Promise.reject(error);
+	}
+	pending.then((a) => {
+		if (settled) return;
+		done();
+		resolve(a);
+	}, (error) => {
+		if (settled) return;
+		done();
+		reject(error);
+	});
+});
+/**
+* A transport failure: `fetch` itself threw. Node's `fetch` rejects with a bare
+* "fetch failed" and keeps the reason (DNS, refused connection, TLS) in
+* `cause`, so the message carries that too.
+*/
+var TransportError = class extends Error {
+	constructor(method, url, cause) {
+		const inner = typeof cause === "object" && cause !== null && "cause" in cause ? cause.cause : void 0;
+		const reason = inner === void 0 ? describe(cause) : `${describe(cause)}: ${describe(inner)}`;
+		super(`Transport error (${method} ${url}): ${reason}`, { cause });
+		this.name = "TransportError";
+	}
+};
+/** A readable message for an arbitrary thrown value. */
+const describe = (e) => typeof e === "object" && e !== null && "message" in e && typeof e.message === "string" ? e.message : String(e);
+/**
+* The URL of an API path under `endpoint`. The endpoint is a base URL, and it
+* may carry a path prefix (a proxy on the customer's own domain, such as
+* `https://flags.example.com/toggld`): trailing slashes are dropped and
+* `path` (which starts with `/`) is appended, so the prefix is kept. A
+* `new URL(path, endpoint)` join would drop it. Every request the SDK sends,
+* and the sync stream's WebSocket URL, is built here.
+*/
+const apiUrl = (endpoint, path) => {
+	const url = new URL(endpoint);
+	url.pathname = url.pathname.replace(/\/+$/, "") + path;
+	return url;
+};
+/**
+* A request function bound to the endpoint and key, with a `URL` input.
+* `encode` turns a JSON body into what `fetch` receives: the string itself by
+* default (any runtime), or a UTF-8 `Buffer` in the main entry, which earlier
+* versions passed to a custom `fetch`.
+*/
+const makeSend = (options, encode = (json) => json) => {
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+	const endpoint = options.endpoint ?? "";
+	const authorization = `Bearer ${options.sdkKey ?? ""}`;
+	return async (method, path, body, signal, extra) => {
+		const url = apiUrl(endpoint, path);
+		const headers = {
+			...extra,
+			authorization
+		};
+		const init = {
+			method,
+			headers,
+			signal
+		};
+		if (body !== void 0) {
+			headers["content-type"] = "application/json";
+			init.body = encode(JSON.stringify(body));
+		}
+		try {
+			return await fetchImpl(url, init);
+		} catch (error) {
+			throw new TransportError(method, url.toString(), error);
+		}
+	};
+};
+/**
+* Why the API refused a request whose body is not an answer: a rejected key
+* (401), a key without access (403, worded by the caller), or a rate limit (429).
+*/
+const refusalMessage = (response, forbidden) => {
+	switch (response.status) {
+		case 401: return "The API rejected the SDK key (HTTP 401). Check that `sdkKey` is a valid, unrevoked key.";
+		case 403: return forbidden;
+		case 429: {
+			const retryAfter = response.headers.get("retry-after");
+			return `The API rate limit was reached (HTTP 429)${retryAfter ? `. Retry after ${retryAfter} seconds` : ""}.`;
+		}
+		default: return `The API refused the request (HTTP ${response.status}).`;
+	}
+};
+/** Read a JSON body; a body that is not JSON is a transport-level failure, not a shape one. */
+const readJson = async (response, request) => {
+	try {
+		return await response.json();
+	} catch (error) {
+		throw new Error(`The response body is not valid JSON (${response.status} ${request})`, { cause: error });
+	}
+};
+/** Drop a body nobody reads, so its connection can be reused. */
+const discard = (response) => {
+	response.body?.cancel().catch(() => {});
+};
+// src/internal/wire.ts
+/** A response or document that does not have the expected shape. */
+var WireError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "WireError";
+	}
+};
+const fail = (path, expected) => {
+	throw new WireError(`Expected ${expected} at ${path}`);
+};
+const isRecord = (u) => typeof u === "object" && u !== null && !Array.isArray(u);
+const has = (o, key) => Object.hasOwn(o, key);
+const record = (u, path) => isRecord(u) ? u : fail(path, "an object");
+const array = (u, path) => Array.isArray(u) ? u : fail(path, "an array");
+const string = (u, path) => typeof u === "string" ? u : fail(path, "a string");
+const boolean = (u, path) => typeof u === "boolean" ? u : fail(path, "a boolean");
+const number = (u, path) => typeof u === "number" ? u : fail(path, "a number");
+const finite = (u, path) => typeof u === "number" && Number.isFinite(u) ? u : fail(path, "a finite number");
+const literal = (values, u, path) => typeof u === "string" && values.has(u) ? u : fail(path, `one of ${[...values].join(", ")}`);
+const arrayOf = (u, path, item) => array(u, path).map((v, i) => item(v, `${path}[${i}]`));
+/** Copy `key` into `out` when it is present, decoded; absent stays absent. */
+const optional = (out, from, key, path, decode) => {
+	if (has(from, key)) out[key] = decode(from[key], `${path}.${key}`);
+};
+/**
+* A JSON value: `null`, a boolean, a finite number, a string, or an array or
+* plain object of those. Returned as is, not copied, as the schema does.
+*/
+const isJson = (u) => {
+	if (u === null || typeof u === "string" || typeof u === "boolean") return true;
+	if (typeof u === "number") return Number.isFinite(u);
+	if (Array.isArray(u)) {
+		for (let i = 0; i < u.length; i++) if (!isJson(u[i])) return false;
+		return true;
+	}
+	if (typeof u !== "object") return false;
+	const proto = Object.getPrototypeOf(u);
+	if (proto !== null && proto !== Object.prototype) return false;
+	for (const key in u) if (has(u, key) && !isJson(u[key])) return false;
+	return true;
+};
+const json = (u, path) => isJson(u) ? u : fail(path, "a JSON value");
+const REASON_LIST = [
+	"STATIC",
+	"DEFAULT",
+	"TARGETING_MATCH",
+	"SPLIT",
+	"CACHED",
+	"DISABLED",
+	"UNKNOWN",
+	"STALE",
+	"ERROR"
+];
+const ERROR_CODE_LIST = [
+	"PROVIDER_NOT_READY",
+	"PROVIDER_FATAL",
+	"FLAG_NOT_FOUND",
+	"PARSE_ERROR",
+	"TYPE_MISMATCH",
+	"TARGETING_KEY_MISSING",
+	"INVALID_CONTEXT",
+	"GENERAL"
+];
+const FLAG_TYPE_LIST = [
+	"boolean",
+	"string",
+	"number",
+	"object"
+];
+const OPERATOR_LIST = [
+	"eq",
+	"ne",
+	"in",
+	"notIn",
+	"lt",
+	"lte",
+	"gt",
+	"gte",
+	"contains",
+	"startsWith",
+	"endsWith",
+	"exists",
+	"notExists"
+];
+const LIST_MODE_LIST = [
+	"none",
+	"inline",
+	"remote"
+];
+const REASONS = new Set(REASON_LIST);
+const ERROR_CODES = new Set(ERROR_CODE_LIST);
+const FLAG_TYPES = new Set(FLAG_TYPE_LIST);
+const OPERATORS = new Set(OPERATOR_LIST);
+const LIST_MODES = new Set(LIST_MODE_LIST);
+const metadataValue = (u, path) => typeof u === "string" || typeof u === "boolean" || typeof u === "number" && Number.isFinite(u) ? u : fail(path, "a string, finite number, or boolean");
+/** Flag metadata, copied (the result is a new object). */
+const metadata = (u, path) => {
+	const o = record(u, path);
+	const out = {};
+	for (const key of Object.keys(o)) out[key] = metadataValue(o[key], `${path}.${key}`);
+	return out;
+};
+const decodeOfrepSuccess = (u, path = "response") => {
+	const o = record(u, path);
+	if (!has(o, "value")) fail(`${path}.value`, "a JSON value");
+	const out = {
+		key: string(o.key, `${path}.key`),
+		value: json(o.value, `${path}.value`),
+		reason: literal(REASONS, o.reason, `${path}.reason`)
+	};
+	optional(out, o, "variant", path, string);
+	optional(out, o, "metadata", path, metadata);
+	return out;
+};
+const decodeOfrepFailure = (u, path = "response") => {
+	const o = record(u, path);
+	const out = {
+		key: string(o.key, `${path}.key`),
+		errorCode: literal(ERROR_CODES, o.errorCode, `${path}.errorCode`)
+	};
+	optional(out, o, "errorDetails", path, string);
+	optional(out, o, "metadata", path, metadata);
+	return out;
+};
+/**
+* A bulk response. Each entry is a success or a failure, tried in that order,
+* as the schema's union does; one malformed entry rejects the response.
+*/
+const decodeOfrepBulk = (u) => {
+	const o = record(u, "response");
+	if (has(o, "metadata")) metadata(o.metadata, "response.metadata");
+	return arrayOf(o.flags, "response.flags", (entry, path) => {
+		try {
+			return {
+				ok: true,
+				...decodeOfrepSuccess(entry, path)
+			};
+		} catch (error) {
+			if (!(error instanceof WireError)) throw error;
+			return {
+				ok: false,
+				...decodeOfrepFailure(entry, path)
+			};
+		}
+	});
+};
+const decodeOfrepBulkFailure = (u) => {
+	const o = record(u, "response");
+	const out = { errorCode: literal(ERROR_CODES, o.errorCode, "response.errorCode") };
+	optional(out, o, "errorDetails", "response", string);
+	return out;
+};
+const condition = (u, path) => {
+	const o = record(u, path);
+	const out = {
+		attribute: string(o.attribute, `${path}.attribute`),
+		operator: literal(OPERATORS, o.operator, `${path}.operator`)
+	};
+	optional(out, o, "value", path, json);
+	return out;
+};
+const split = (u, path) => {
+	const o = record(u, path);
+	const weight = finite(o.weight, `${path}.weight`);
+	if (weight < 0) fail(`${path}.weight`, "a number of at least 0");
+	return {
+		variant: string(o.variant, `${path}.variant`),
+		weight
+	};
+};
+const serve = (u, path) => {
+	const o = record(u, path);
+	if (o.type === "variant") return {
+		type: "variant",
+		variant: string(o.variant, `${path}.variant`)
+	};
+	if (o.type === "rollout") {
+		const out = { type: "rollout" };
+		optional(out, o, "bucketBy", path, string);
+		out.splits = arrayOf(o.splits, `${path}.splits`, split);
+		return out;
+	}
+	return fail(`${path}.type`, `"variant" or "rollout"`);
+};
+const segmentRef = (u, path) => {
+	const o = record(u, path);
+	const out = { segment: string(o.segment, `${path}.segment`) };
+	optional(out, o, "negate", path, boolean);
+	return out;
+};
+const rule = (u, path) => {
+	const o = record(u, path);
+	const out = { id: string(o.id, `${path}.id`) };
+	optional(out, o, "description", path, string);
+	out.conditions = arrayOf(o.conditions, `${path}.conditions`, condition);
+	optional(out, o, "segments", path, (v, p) => arrayOf(v, p, segmentRef));
+	out.serve = serve(o.serve, `${path}.serve`);
+	return out;
+};
+const variants = (u, path) => {
+	const o = record(u, path);
+	const out = {};
+	for (const key of Object.keys(o)) out[key] = json(o[key], `${path}.${key}`);
+	return out;
+};
+const decodeFlag = (u, path = "flag") => {
+	const o = record(u, path);
+	const out = { key: string(o.key, `${path}.key`) };
+	optional(out, o, "name", path, string);
+	optional(out, o, "description", path, string);
+	out.type = literal(FLAG_TYPES, o.type, `${path}.type`);
+	out.enabled = boolean(o.enabled, `${path}.enabled`);
+	out.variants = variants(o.variants, `${path}.variants`);
+	out.defaultVariant = string(o.defaultVariant, `${path}.defaultVariant`);
+	optional(out, o, "offVariant", path, string);
+	out.targeting = arrayOf(o.targeting, `${path}.targeting`, rule);
+	out.metadata = metadata(o.metadata, `${path}.metadata`);
+	out.createdAt = string(o.createdAt, `${path}.createdAt`);
+	out.updatedAt = string(o.updatedAt, `${path}.updatedAt`);
+	return out;
+};
+const segmentRule = (u, path) => {
+	const o = record(u, path);
+	const out = { id: string(o.id, `${path}.id`) };
+	optional(out, o, "description", path, string);
+	out.conditions = arrayOf(o.conditions, `${path}.conditions`, condition);
+	return out;
+};
+const decodeSegment = (u, path = "segment") => {
+	const o = record(u, path);
+	const out = { key: string(o.key, `${path}.key`) };
+	optional(out, o, "name", path, string);
+	optional(out, o, "description", path, string);
+	out.keyAttribute = string(o.keyAttribute, `${path}.keyAttribute`);
+	out.rules = arrayOf(o.rules, `${path}.rules`, segmentRule);
+	out.listMode = literal(LIST_MODES, o.listMode, `${path}.listMode`);
+	optional(out, o, "members", path, (v, p) => arrayOf(v, p, string));
+	out.version = number(o.version, `${path}.version`);
+	out.createdAt = string(o.createdAt, `${path}.createdAt`);
+	out.updatedAt = string(o.updatedAt, `${path}.updatedAt`);
+	return out;
+};
+/** An ordered config version: a non-negative safe integer. */
+const isConfigVersion = (u) => typeof u === "number" && Number.isSafeInteger(u) && u >= 0;
+/** `version`, `flags`, and `segments`: what a snapshot and a stream message share. */
+const snapshotBody = (o, path) => {
+	const out = { version: string(o.version, `${path}.version`) };
+	out.flags = arrayOf(o.flags, `${path}.flags`, decodeFlag);
+	optional(out, o, "segments", path, (v, p) => arrayOf(v, p, decodeSegment));
+	return out;
+};
+/**
+* A snapshot from `GET /sync/v1/flags` or a flag file. `configVersion` is
+* checked strictly here, as the schema does; envelope keys a pulled file
+* carries (`$schema`, `toggld`) are dropped.
+*/
+const decodeSnapshot = (u) => {
+	const o = record(u, "snapshot");
+	const body = snapshotBody(o, "snapshot");
+	if (!has(o, "configVersion")) return body;
+	if (!isConfigVersion(o.configVersion)) fail("snapshot.configVersion", "a non-negative integer");
+	return {
+		version: body.version,
+		configVersion: o.configVersion,
+		...withoutVersion(body)
+	};
+};
+const withoutVersion = ({ flags, segments }) => segments === void 0 ? { flags } : {
+	flags,
+	segments
+};
+/**
+* A server→client sync stream message. Only `type: "snapshot"` exists today; an
+* unknown type throws, and the caller skips it.
+*
+* The capabilities (`delivery`, `heartbeat`) describe the server, and an
+* unusable `configVersion` only loses ordering, so all three are read leniently:
+* a value a later server adds counts as best-effort / no heartbeat / unordered
+* instead of rejecting the snapshot it rides on.
+*/
+const decodeStreamMessage = (u) => {
+	const o = record(u, "message");
+	if (o.type !== "snapshot") fail("message.type", `"snapshot"`);
+	const body = snapshotBody(o, "message");
+	return {
+		snapshot: isConfigVersion(o.configVersion) ? {
+			version: body.version,
+			configVersion: o.configVersion,
+			...withoutVersion(body)
+		} : body,
+		durable: o.delivery === "durable",
+		heartbeat: o.heartbeat === true
+	};
+};
+export { decodeOfrepSuccess as a, isRecord as c, discard as d, makeSend as f, withTimeout as h, decodeOfrepFailure as i, apiUrl as l, refusalMessage as m, decodeOfrepBulk as n, decodeSnapshot as o, readJson as p, decodeOfrepBulkFailure as r, decodeStreamMessage as s, WireError as t, describe as u };

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@toggld/js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.0",
+  "description": "Toggld server SDK for JavaScript (Node.js, Bun, Deno): in-process flag evaluation kept current by a background sync (or read from a flag file), and a remote client for serverless and edge runtimes (Cloudflare Workers, AWS Lambda) via @toggld/js/serverless, with one bulk request per incoming request. Zero dependencies; optional native Effect API via @toggld/js/effect.",
+  "license": "Apache-2.0",
+  "homepage": "https://toggld.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toggld/toggld.git",
+    "directory": "packages/js"
+  },
+  "bugs": {
+    "url": "https://github.com/toggld/toggld/issues"
+  },
+  "keywords": [
+    "feature-flags",
+    "openfeature",
+    "toggld",
+    "effect",
+    "serverless",
+    "cloudflare-workers",
+    "aws-lambda",
+    "edge"
+  ],
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "toggld": "./dist/cli.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./serverless": {
+      "types": "./dist/serverless.d.mts",
+      "default": "./dist/serverless.mjs"
+    },
+    "./serverless/effect": {
+      "types": "./dist/serverless-effect.d.mts",
+      "default": "./dist/serverless-effect.mjs"
+    },
+    "./effect": {
+      "types": "./dist/effect.d.mts",
+      "default": "./dist/effect.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.5"
+  },
+  "peerDependenciesMeta": {
+    "effect": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "effect": "4.0.6",
+    "miniflare": "5.20261023.1-beta",
+    "tsdown": "^0.23.2",
+    "typescript": "6.0.3",
+    "unrun": "^0.3.1",
+    "@toggld/engine": "0.1.0",
+    "@toggld/schema": "0.1.0",
+    "@toggld/server": "0.1.0",
+    "@toggld/spec": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }