@nanoflags/sdk 0.0.0-stage → 0.3.0

package/dist/node.cjs

@@ -0,0 +1,108 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_src = require("./src-B58PLGGE.cjs");
+// src/node.ts
+/**
+* @nanoflags/sdk/node — test-session propagation for Node servers.
+*
+* The session of the request being handled lives in AsyncLocalStorage: it follows the request
+* through awaits, timers and callbacks, is invisible to every other request, and disappears when
+* the request's async chain ends. Nothing is stored on the client or in module-level variables.
+*/
+const storage = new (require("node:async_hooks")).AsyncLocalStorage();
+/** Run `fn` with `token` as the current test session. An absent or malformed token runs `fn` outside any session. */
+function withSession(token, fn) {
+	return storage.run(require_src.isSessionToken(token) ? {
+		token,
+		evaluators: /* @__PURE__ */ new Map()
+	} : null, fn);
+}
+/** Token of the test session the current request belongs to, if any. */
+function currentSession() {
+	return storage.getStore()?.token;
+}
+/** Headers to add to downstream calls so the next service joins the same session. `{}` outside a session. */
+function sessionHeaders() {
+	const token = currentSession();
+	return token === void 0 ? {} : { [require_src.SESSION_HEADER]: token };
+}
+function passthrough(client) {
+	return {
+		active: false,
+		id: null,
+		expiresAt: null,
+		get revision() {
+			return client.revision;
+		},
+		boolean: (k, f, c) => client.boolean(k, f, c),
+		string: (k, f, c) => client.string(k, f, c),
+		number: (k, f, c) => client.number(k, f, c),
+		json: (k, f, c) => client.json(k, f, c),
+		evaluate: (k, f, c) => client.evaluate(k, f, c)
+	};
+}
+/**
+* Evaluator for the current request: session-scoped inside `withSession` / the middleware,
+* otherwise equivalent to the client. Resolved once per request and client. Never rejects.
+*/
+async function sessionFlags(client, options) {
+	const scope = storage.getStore();
+	if (!scope) return passthrough(client);
+	const hit = scope.evaluators.get(client);
+	if (hit) return hit;
+	let evaluator;
+	try {
+		evaluator = await client.session(scope.token, options);
+	} catch {
+		evaluator = passthrough(client);
+	}
+	scope.evaluators.set(client, evaluator);
+	return evaluator;
+}
+/**
+* Synchronous variant for code that runs after `sessionMiddleware` / `withSessionHandler` (which
+* resolve the session before the handler starts). Outside a resolved session it evaluates like the client.
+*/
+function flagsFor(client) {
+	return storage.getStore()?.evaluators.get(client) ?? passthrough(client);
+}
+function headerValue(v) {
+	const first = Array.isArray(v) ? v[0] : v;
+	return typeof first === "string" ? first.trim() : void 0;
+}
+/**
+* Express/Connect middleware. Reads `x-nanoflags-session`, resolves the session once, and runs the
+* rest of the request inside it. `req.flags` (and `flagsFor(client)`) is the request's evaluator —
+* session-scoped when the session is active, otherwise the plain client behaviour.
+*/
+function sessionMiddleware(client, options) {
+	return function nanoflagsSession(req, _res, next) {
+		withSession(headerValue(req.headers?.[require_src.SESSION_HEADER]), () => {
+			if (currentSession() === void 0) {
+				req.flags = passthrough(client);
+				return next();
+			}
+			sessionFlags(client, options).then((flags) => {
+				req.flags = flags;
+				next();
+			});
+		});
+	};
+}
+/**
+* Wrap a fetch-style handler (`(request, ...rest) => Response`): Node fetch servers, Hono, Next.js
+* route handlers on the Node runtime. The handler runs inside the request's session.
+*/
+function withSessionHandler(client, handler, options) {
+	return (request, ...rest) => withSession(request.headers.get(require_src.SESSION_HEADER)?.trim(), async () => {
+		await sessionFlags(client, options);
+		return handler(request, ...rest);
+	});
+}
+exports.SESSION_HEADER = require_src.SESSION_HEADER;
+exports.currentSession = currentSession;
+exports.flagsFor = flagsFor;
+exports.sessionFlags = sessionFlags;
+exports.sessionHeaders = sessionHeaders;
+exports.sessionMiddleware = sessionMiddleware;
+exports.withSession = withSession;
+exports.withSessionHandler = withSessionHandler;

package/dist/node.d.cts

@@ -0,0 +1,35 @@
+import { d as SessionOptions, i as FlagEvaluator, l as SESSION_HEADER, o as NanoFlagsClient, u as SessionEvaluator } from "./index-DZj6xbyg.cjs";
+type SessionClient = Pick<NanoFlagsClient, "session"> & FlagEvaluator & Pick<NanoFlagsClient, "revision">;
+/** Run `fn` with `token` as the current test session. An absent or malformed token runs `fn` outside any session. */
+export declare function withSession<T>(token: string | null | undefined, fn: () => T): T;
+/** Token of the test session the current request belongs to, if any. */
+export declare function currentSession(): string | undefined;
+/** Headers to add to downstream calls so the next service joins the same session. `{}` outside a session. */
+export declare function sessionHeaders(): Record<string, string>;
+/**
+ * Evaluator for the current request: session-scoped inside `withSession` / the middleware,
+ * otherwise equivalent to the client. Resolved once per request and client. Never rejects.
+ */
+export declare function sessionFlags(client: SessionClient, options?: SessionOptions): Promise<SessionEvaluator>;
+/**
+ * Synchronous variant for code that runs after `sessionMiddleware` / `withSessionHandler` (which
+ * resolve the session before the handler starts). Outside a resolved session it evaluates like the client.
+ */
+export declare function flagsFor(client: SessionClient): SessionEvaluator;
+export interface NodeRequestLike {
+  headers: Record<string, string | string[] | undefined>;
+}
+/**
+ * Express/Connect middleware. Reads `x-nanoflags-session`, resolves the session once, and runs the
+ * rest of the request inside it. `req.flags` (and `flagsFor(client)`) is the request's evaluator —
+ * session-scoped when the session is active, otherwise the plain client behaviour.
+ */
+export declare function sessionMiddleware(client: SessionClient, options?: SessionOptions): (req: NodeRequestLike & {
+  flags?: SessionEvaluator;
+}, _res: unknown, next: (err?: unknown) => void) => void;
+/**
+ * Wrap a fetch-style handler (`(request, ...rest) => Response`): Node fetch servers, Hono, Next.js
+ * route handlers on the Node runtime. The handler runs inside the request's session.
+ */
+export declare function withSessionHandler<A extends unknown[], R>(client: SessionClient, handler: (request: Request, ...rest: A) => R | Promise<R>, options?: SessionOptions): (request: Request, ...rest: A) => Promise<R>;
+export { SESSION_HEADER };

package/dist/node.d.ts

@@ -0,0 +1,35 @@
+import { d as SessionOptions, i as FlagEvaluator, l as SESSION_HEADER, o as NanoFlagsClient, u as SessionEvaluator } from "./index-DZj6xbyg.js";
+type SessionClient = Pick<NanoFlagsClient, "session"> & FlagEvaluator & Pick<NanoFlagsClient, "revision">;
+/** Run `fn` with `token` as the current test session. An absent or malformed token runs `fn` outside any session. */
+export declare function withSession<T>(token: string | null | undefined, fn: () => T): T;
+/** Token of the test session the current request belongs to, if any. */
+export declare function currentSession(): string | undefined;
+/** Headers to add to downstream calls so the next service joins the same session. `{}` outside a session. */
+export declare function sessionHeaders(): Record<string, string>;
+/**
+ * Evaluator for the current request: session-scoped inside `withSession` / the middleware,
+ * otherwise equivalent to the client. Resolved once per request and client. Never rejects.
+ */
+export declare function sessionFlags(client: SessionClient, options?: SessionOptions): Promise<SessionEvaluator>;
+/**
+ * Synchronous variant for code that runs after `sessionMiddleware` / `withSessionHandler` (which
+ * resolve the session before the handler starts). Outside a resolved session it evaluates like the client.
+ */
+export declare function flagsFor(client: SessionClient): SessionEvaluator;
+export interface NodeRequestLike {
+  headers: Record<string, string | string[] | undefined>;
+}
+/**
+ * Express/Connect middleware. Reads `x-nanoflags-session`, resolves the session once, and runs the
+ * rest of the request inside it. `req.flags` (and `flagsFor(client)`) is the request's evaluator —
+ * session-scoped when the session is active, otherwise the plain client behaviour.
+ */
+export declare function sessionMiddleware(client: SessionClient, options?: SessionOptions): (req: NodeRequestLike & {
+  flags?: SessionEvaluator;
+}, _res: unknown, next: (err?: unknown) => void) => void;
+/**
+ * Wrap a fetch-style handler (`(request, ...rest) => Response`): Node fetch servers, Hono, Next.js
+ * route handlers on the Node runtime. The handler runs inside the request's session.
+ */
+export declare function withSessionHandler<A extends unknown[], R>(client: SessionClient, handler: (request: Request, ...rest: A) => R | Promise<R>, options?: SessionOptions): (request: Request, ...rest: A) => Promise<R>;
+export { SESSION_HEADER };

package/dist/node.js

@@ -0,0 +1,101 @@
+import { i as SESSION_HEADER, o as isSessionToken } from "./src-DUF_NkBY.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+// src/node.ts
+/**
+* @nanoflags/sdk/node — test-session propagation for Node servers.
+*
+* The session of the request being handled lives in AsyncLocalStorage: it follows the request
+* through awaits, timers and callbacks, is invisible to every other request, and disappears when
+* the request's async chain ends. Nothing is stored on the client or in module-level variables.
+*/
+const storage = new AsyncLocalStorage();
+/** Run `fn` with `token` as the current test session. An absent or malformed token runs `fn` outside any session. */
+function withSession(token, fn) {
+	return storage.run(isSessionToken(token) ? {
+		token,
+		evaluators: /* @__PURE__ */ new Map()
+	} : null, fn);
+}
+/** Token of the test session the current request belongs to, if any. */
+function currentSession() {
+	return storage.getStore()?.token;
+}
+/** Headers to add to downstream calls so the next service joins the same session. `{}` outside a session. */
+function sessionHeaders() {
+	const token = currentSession();
+	return token === void 0 ? {} : { [SESSION_HEADER]: token };
+}
+function passthrough(client) {
+	return {
+		active: false,
+		id: null,
+		expiresAt: null,
+		get revision() {
+			return client.revision;
+		},
+		boolean: (k, f, c) => client.boolean(k, f, c),
+		string: (k, f, c) => client.string(k, f, c),
+		number: (k, f, c) => client.number(k, f, c),
+		json: (k, f, c) => client.json(k, f, c),
+		evaluate: (k, f, c) => client.evaluate(k, f, c)
+	};
+}
+/**
+* Evaluator for the current request: session-scoped inside `withSession` / the middleware,
+* otherwise equivalent to the client. Resolved once per request and client. Never rejects.
+*/
+async function sessionFlags(client, options) {
+	const scope = storage.getStore();
+	if (!scope) return passthrough(client);
+	const hit = scope.evaluators.get(client);
+	if (hit) return hit;
+	let evaluator;
+	try {
+		evaluator = await client.session(scope.token, options);
+	} catch {
+		evaluator = passthrough(client);
+	}
+	scope.evaluators.set(client, evaluator);
+	return evaluator;
+}
+/**
+* Synchronous variant for code that runs after `sessionMiddleware` / `withSessionHandler` (which
+* resolve the session before the handler starts). Outside a resolved session it evaluates like the client.
+*/
+function flagsFor(client) {
+	return storage.getStore()?.evaluators.get(client) ?? passthrough(client);
+}
+function headerValue(v) {
+	const first = Array.isArray(v) ? v[0] : v;
+	return typeof first === "string" ? first.trim() : void 0;
+}
+/**
+* Express/Connect middleware. Reads `x-nanoflags-session`, resolves the session once, and runs the
+* rest of the request inside it. `req.flags` (and `flagsFor(client)`) is the request's evaluator —
+* session-scoped when the session is active, otherwise the plain client behaviour.
+*/
+function sessionMiddleware(client, options) {
+	return function nanoflagsSession(req, _res, next) {
+		withSession(headerValue(req.headers?.[SESSION_HEADER]), () => {
+			if (currentSession() === void 0) {
+				req.flags = passthrough(client);
+				return next();
+			}
+			sessionFlags(client, options).then((flags) => {
+				req.flags = flags;
+				next();
+			});
+		});
+	};
+}
+/**
+* Wrap a fetch-style handler (`(request, ...rest) => Response`): Node fetch servers, Hono, Next.js
+* route handlers on the Node runtime. The handler runs inside the request's session.
+*/
+function withSessionHandler(client, handler, options) {
+	return (request, ...rest) => withSession(request.headers.get(SESSION_HEADER)?.trim(), async () => {
+		await sessionFlags(client, options);
+		return handler(request, ...rest);
+	});
+}
+export { SESSION_HEADER, currentSession, flagsFor, sessionFlags, sessionHeaders, sessionMiddleware, withSession, withSessionHandler };

package/dist/react.cjs

@@ -0,0 +1,65 @@
+"use client";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let react = require("react");
+// src/react.ts
+/**
+* @nanoflags/sdk/react — bindings built on useSyncExternalStore.
+* Components re-render when the bundle or the client status changes; evaluation stays local.
+*/
+const NanoFlagsContext = (0, react.createContext)(null);
+function NanoFlagsProvider({ client, context, children }) {
+	const serialized = JSON.stringify(context ?? {});
+	const value = (0, react.useMemo)(() => ({
+		client,
+		context: context ?? {}
+	}), [client, serialized]);
+	return (0, react.createElement)(NanoFlagsContext.Provider, { value }, children);
+}
+function useProvider() {
+	const value = (0, react.useContext)(NanoFlagsContext);
+	if (!value) throw new Error("useFlag/useFlagsStatus must be used inside <NanoFlagsProvider>.");
+	return value;
+}
+function useVersion(client) {
+	return (0, react.useSyncExternalStore)(client.subscribe, () => client.version, () => client.version);
+}
+/**
+* Value of a flag for the provider context (shallow-merged with `ctxOverride`).
+* The accessor is chosen from the type of `fallback`: boolean, string, number, otherwise JSON.
+* A missing flag, a missing bundle or a type mismatch returns `fallback`.
+*/
+function useFlag(key, fallback, ctxOverride) {
+	const { client, context } = useProvider();
+	const version = useVersion(client);
+	const override = JSON.stringify(ctxOverride ?? null);
+	const fb = typeof fallback === "object" ? JSON.stringify(fallback) : fallback;
+	return (0, react.useMemo)(() => {
+		const ctx = ctxOverride ? {
+			...context,
+			...ctxOverride
+		} : context;
+		if (typeof fallback === "boolean") return client.boolean(key, fallback, ctx);
+		if (typeof fallback === "string") return client.string(key, fallback, ctx);
+		if (typeof fallback === "number") return client.number(key, fallback, ctx);
+		return client.json(key, fallback, ctx);
+	}, [
+		client,
+		version,
+		key,
+		fb,
+		context,
+		override
+	]);
+}
+function useFlagsStatus() {
+	const { client } = useProvider();
+	const version = useVersion(client);
+	return (0, react.useMemo)(() => ({
+		status: client.status,
+		revision: client.revision,
+		hasBundle: client.status !== "not-ready"
+	}), [client, version]);
+}
+exports.NanoFlagsProvider = NanoFlagsProvider;
+exports.useFlag = useFlag;
+exports.useFlagsStatus = useFlagsStatus;

package/dist/react.d.cts

@@ -0,0 +1,28 @@
+/**
+ * @nanoflags/sdk/react — bindings built on useSyncExternalStore.
+ * Components re-render when the bundle or the client status changes; evaluation stays local.
+ */
+import { C as JsonValue, n as ClientStatus, o as NanoFlagsClient, x as Context } from "./index-DZj6xbyg.cjs";
+import { ReactElement, ReactNode } from "react";
+export interface NanoFlagsProviderProps {
+  client: NanoFlagsClient;
+  /** Evaluation context shared by every `useFlag` below this provider. */
+  context?: Context;
+  children?: ReactNode;
+}
+export declare function NanoFlagsProvider({ client, context, children }: NanoFlagsProviderProps): ReactElement;
+type Widen<T> = T extends boolean ? boolean : T extends string ? string : T extends number ? number : T;
+/**
+ * Value of a flag for the provider context (shallow-merged with `ctxOverride`).
+ * The accessor is chosen from the type of `fallback`: boolean, string, number, otherwise JSON.
+ * A missing flag, a missing bundle or a type mismatch returns `fallback`.
+ */
+export declare function useFlag<T extends JsonValue>(key: string, fallback: T, ctxOverride?: Context): Widen<T>;
+export interface FlagsStatus {
+  status: ClientStatus;
+  revision: number | null;
+  /** True when a bundle is loaded (status "ready" or "stale"). */
+  hasBundle: boolean;
+}
+export declare function useFlagsStatus(): FlagsStatus;
+export {};

package/dist/react.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @nanoflags/sdk/react — bindings built on useSyncExternalStore.
+ * Components re-render when the bundle or the client status changes; evaluation stays local.
+ */
+import { C as JsonValue, n as ClientStatus, o as NanoFlagsClient, x as Context } from "./index-DZj6xbyg.js";
+import { ReactElement, ReactNode } from "react";
+export interface NanoFlagsProviderProps {
+  client: NanoFlagsClient;
+  /** Evaluation context shared by every `useFlag` below this provider. */
+  context?: Context;
+  children?: ReactNode;
+}
+export declare function NanoFlagsProvider({ client, context, children }: NanoFlagsProviderProps): ReactElement;
+type Widen<T> = T extends boolean ? boolean : T extends string ? string : T extends number ? number : T;
+/**
+ * Value of a flag for the provider context (shallow-merged with `ctxOverride`).
+ * The accessor is chosen from the type of `fallback`: boolean, string, number, otherwise JSON.
+ * A missing flag, a missing bundle or a type mismatch returns `fallback`.
+ */
+export declare function useFlag<T extends JsonValue>(key: string, fallback: T, ctxOverride?: Context): Widen<T>;
+export interface FlagsStatus {
+  status: ClientStatus;
+  revision: number | null;
+  /** True when a bundle is loaded (status "ready" or "stale"). */
+  hasBundle: boolean;
+}
+export declare function useFlagsStatus(): FlagsStatus;
+export {};

package/dist/react.js

@@ -0,0 +1,62 @@
+"use client";
+import { createContext, createElement, useContext, useMemo, useSyncExternalStore } from "react";
+// src/react.ts
+/**
+* @nanoflags/sdk/react — bindings built on useSyncExternalStore.
+* Components re-render when the bundle or the client status changes; evaluation stays local.
+*/
+const NanoFlagsContext = createContext(null);
+function NanoFlagsProvider({ client, context, children }) {
+	const serialized = JSON.stringify(context ?? {});
+	const value = useMemo(() => ({
+		client,
+		context: context ?? {}
+	}), [client, serialized]);
+	return createElement(NanoFlagsContext.Provider, { value }, children);
+}
+function useProvider() {
+	const value = useContext(NanoFlagsContext);
+	if (!value) throw new Error("useFlag/useFlagsStatus must be used inside <NanoFlagsProvider>.");
+	return value;
+}
+function useVersion(client) {
+	return useSyncExternalStore(client.subscribe, () => client.version, () => client.version);
+}
+/**
+* Value of a flag for the provider context (shallow-merged with `ctxOverride`).
+* The accessor is chosen from the type of `fallback`: boolean, string, number, otherwise JSON.
+* A missing flag, a missing bundle or a type mismatch returns `fallback`.
+*/
+function useFlag(key, fallback, ctxOverride) {
+	const { client, context } = useProvider();
+	const version = useVersion(client);
+	const override = JSON.stringify(ctxOverride ?? null);
+	const fb = typeof fallback === "object" ? JSON.stringify(fallback) : fallback;
+	return useMemo(() => {
+		const ctx = ctxOverride ? {
+			...context,
+			...ctxOverride
+		} : context;
+		if (typeof fallback === "boolean") return client.boolean(key, fallback, ctx);
+		if (typeof fallback === "string") return client.string(key, fallback, ctx);
+		if (typeof fallback === "number") return client.number(key, fallback, ctx);
+		return client.json(key, fallback, ctx);
+	}, [
+		client,
+		version,
+		key,
+		fb,
+		context,
+		override
+	]);
+}
+function useFlagsStatus() {
+	const { client } = useProvider();
+	const version = useVersion(client);
+	return useMemo(() => ({
+		status: client.status,
+		revision: client.revision,
+		hasBundle: client.status !== "not-ready"
+	}), [client, version]);
+}
+export { NanoFlagsProvider, useFlag, useFlagsStatus };