@geekmidas/testkit 10.0.0-alpha.20 → 10.0.0-alpha.22

package/dist/context.d.mts

@@ -0,0 +1,55 @@
+//#region src/context.d.ts
+/**
+ * The test a request belongs to.
+ *
+ * A feature test drives an app the way it runs deployed: a browser calls the
+ * API, the API calls the auth server, each over a URL. In a test those URLs are
+ * served in-process, and every request made on behalf of one test has to reach
+ * *that test's* transactions — its own call to the API, and the API's call to
+ * the auth server made while handling it.
+ *
+ * The id travels two ways. In-process, an `AsyncLocalStorage` carries it
+ * through every await a test and its handlers make. On the wire it is the
+ * `x-test-context-id` header, which a stamped `fetch` adds to every request made
+ * inside a context, so whatever serves the URL can find the context again —
+ * without any caller, including code under test, writing the header.
+ */
+/** The header a test context travels in between client and server. */
+export declare const TEST_CONTEXT_HEADER = "x-test-context-id";
+/**
+ * Which side of a URL the running code is on.
+ *
+ * `client` is the test itself and the frontend it renders — what a browser
+ * does. `server` is a handler serving a request. The difference matters for
+ * cookies: a browser attaches its cookies to what it sends, a server forwards
+ * only what it was handed. A server call that picked up the browser's cookies
+ * would hide the bug of a server that forgets to forward them.
+ */
+export type TestSide = 'client' | 'server';
+export interface TestContext {
+  readonly id: string;
+  readonly side: TestSide;
+}
+/** The context the running code belongs to, if any. */
+export declare function currentTestContext(): TestContext | undefined;
+/** Run `fn` as the client side of the test `id`. */
+export declare function runInTestContext<T>(id: string, fn: () => T): T;
+/**
+ * Run `fn` as a server handling a request for the test `id` — what whatever
+ * serves a URL in-process wraps each request in.
+ */
+export declare function runAsServer<T>(id: string, fn: () => T): T;
+/** The test a request was made for, read off its header. */
+export declare function testContextOf(request: Request): string | undefined;
+/** `fetch`, adding the current test's id to every request made inside one. */
+export declare function stampedFetch(inner: typeof fetch): typeof fetch;
+/**
+ * Stamp the global `fetch` with the current test's id.
+ *
+ * Install it after anything else that patches `fetch` — MSW's interceptor in
+ * particular — so the stamp is added before the request is intercepted.
+ * Returns what puts the previous `fetch` back.
+ */
+export declare function installContextFetch(): () => void;
+//#endregion
+//# sourceMappingURL=context.d.mts.map

package/dist/context.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.mts","names":[],"sources":["../src/context.ts"],"mappings":";;;;;;;;;;;;;;;;;qBAmBa;;;;;;;;;;YAWD;iBAEK;WACP;WACA,MAAM;;;wBAMA,sBAAsB;;wBAKtB,iBAAiB,GAAG,YAAY,UAAU,IAAI;;;;;wBAQ9C,YAAY,GAAG,YAAY,UAAU,IAAI;;wBAKzC,cAAc,SAAS;;wBAKvB,aAAa,cAAc,eAAe;;;;;;;;wBAoB1C"}

package/dist/context.mjs

@@ -0,0 +1,73 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/context.ts
+/**
+* The test a request belongs to.
+*
+* A feature test drives an app the way it runs deployed: a browser calls the
+* API, the API calls the auth server, each over a URL. In a test those URLs are
+* served in-process, and every request made on behalf of one test has to reach
+* *that test's* transactions — its own call to the API, and the API's call to
+* the auth server made while handling it.
+*
+* The id travels two ways. In-process, an `AsyncLocalStorage` carries it
+* through every await a test and its handlers make. On the wire it is the
+* `x-test-context-id` header, which a stamped `fetch` adds to every request made
+* inside a context, so whatever serves the URL can find the context again —
+* without any caller, including code under test, writing the header.
+*/
+/** The header a test context travels in between client and server. */
+const TEST_CONTEXT_HEADER = "x-test-context-id";
+const storage = new AsyncLocalStorage();
+/** The context the running code belongs to, if any. */
+function currentTestContext() {
+	return storage.getStore();
+}
+/** Run `fn` as the client side of the test `id`. */
+function runInTestContext(id, fn) {
+	return storage.run({
+		id,
+		side: "client"
+	}, fn);
+}
+/**
+* Run `fn` as a server handling a request for the test `id` — what whatever
+* serves a URL in-process wraps each request in.
+*/
+function runAsServer(id, fn) {
+	return storage.run({
+		id,
+		side: "server"
+	}, fn);
+}
+/** The test a request was made for, read off its header. */
+function testContextOf(request) {
+	return request.headers.get("x-test-context-id") ?? void 0;
+}
+/** `fetch`, adding the current test's id to every request made inside one. */
+function stampedFetch(inner) {
+	return (input, init) => {
+		const context = currentTestContext();
+		if (!context) return inner(input, init);
+		const request = new Request(input, init);
+		if (!request.headers.has("x-test-context-id")) request.headers.set(TEST_CONTEXT_HEADER, context.id);
+		return inner(request);
+	};
+}
+/**
+* Stamp the global `fetch` with the current test's id.
+*
+* Install it after anything else that patches `fetch` — MSW's interceptor in
+* particular — so the stamp is added before the request is intercepted.
+* Returns what puts the previous `fetch` back.
+*/
+function installContextFetch() {
+	const previous = globalThis.fetch;
+	globalThis.fetch = stampedFetch(previous);
+	return () => {
+		globalThis.fetch = previous;
+	};
+}
+//#endregion
+export { TEST_CONTEXT_HEADER, currentTestContext, installContextFetch, runAsServer, runInTestContext, stampedFetch, testContextOf };
+
+//# sourceMappingURL=context.mjs.map

package/dist/context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.mjs","names":[],"sources":["../src/context.ts"],"sourcesContent":["/**\n * The test a request belongs to.\n *\n * A feature test drives an app the way it runs deployed: a browser calls the\n * API, the API calls the auth server, each over a URL. In a test those URLs are\n * served in-process, and every request made on behalf of one test has to reach\n * *that test's* transactions — its own call to the API, and the API's call to\n * the auth server made while handling it.\n *\n * The id travels two ways. In-process, an `AsyncLocalStorage` carries it\n * through every await a test and its handlers make. On the wire it is the\n * `x-test-context-id` header, which a stamped `fetch` adds to every request made\n * inside a context, so whatever serves the URL can find the context again —\n * without any caller, including code under test, writing the header.\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\n/** The header a test context travels in between client and server. */\nexport const TEST_CONTEXT_HEADER = 'x-test-context-id';\n\n/**\n * Which side of a URL the running code is on.\n *\n * `client` is the test itself and the frontend it renders — what a browser\n * does. `server` is a handler serving a request. The difference matters for\n * cookies: a browser attaches its cookies to what it sends, a server forwards\n * only what it was handed. A server call that picked up the browser's cookies\n * would hide the bug of a server that forgets to forward them.\n */\nexport type TestSide = 'client' | 'server';\n\nexport interface TestContext {\n\treadonly id: string;\n\treadonly side: TestSide;\n}\n\nconst storage = new AsyncLocalStorage<TestContext>();\n\n/** The context the running code belongs to, if any. */\nexport function currentTestContext(): TestContext | undefined {\n\treturn storage.getStore();\n}\n\n/** Run `fn` as the client side of the test `id`. */\nexport function runInTestContext<T>(id: string, fn: () => T): T {\n\treturn storage.run({ id, side: 'client' }, fn);\n}\n\n/**\n * Run `fn` as a server handling a request for the test `id` — what whatever\n * serves a URL in-process wraps each request in.\n */\nexport function runAsServer<T>(id: string, fn: () => T): T {\n\treturn storage.run({ id, side: 'server' }, fn);\n}\n\n/** The test a request was made for, read off its header. */\nexport function testContextOf(request: Request): string | undefined {\n\treturn request.headers.get(TEST_CONTEXT_HEADER) ?? undefined;\n}\n\n/** `fetch`, adding the current test's id to every request made inside one. */\nexport function stampedFetch(inner: typeof fetch): typeof fetch {\n\treturn (input, init) => {\n\t\tconst context = currentTestContext();\n\t\tif (!context) return inner(input, init);\n\n\t\tconst request = new Request(input, init);\n\t\tif (!request.headers.has(TEST_CONTEXT_HEADER)) {\n\t\t\trequest.headers.set(TEST_CONTEXT_HEADER, context.id);\n\t\t}\n\t\treturn inner(request);\n\t};\n}\n\n/**\n * Stamp the global `fetch` with the current test's id.\n *\n * Install it after anything else that patches `fetch` — MSW's interceptor in\n * particular — so the stamp is added before the request is intercepted.\n * Returns what puts the previous `fetch` back.\n */\nexport function installContextFetch(): () => void {\n\tconst previous = globalThis.fetch;\n\tglobalThis.fetch = stampedFetch(previous);\n\treturn () => {\n\t\tglobalThis.fetch = previous;\n\t};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAmBA,MAAa,sBAAsB;AAkBnC,MAAM,UAAU,IAAI,kBAA+B;;AAGnD,SAAgB,qBAA8C;CAC7D,OAAO,QAAQ,SAAS;AACzB;;AAGA,SAAgB,iBAAoB,IAAY,IAAgB;CAC/D,OAAO,QAAQ,IAAI;EAAE;EAAI,MAAM;CAAS,GAAG,EAAE;AAC9C;;;;;AAMA,SAAgB,YAAe,IAAY,IAAgB;CAC1D,OAAO,QAAQ,IAAI;EAAE;EAAI,MAAM;CAAS,GAAG,EAAE;AAC9C;;AAGA,SAAgB,cAAc,SAAsC;CACnE,OAAO,QAAQ,QAAQ,IAAA,mBAAuB,KAAK,KAAA;AACpD;;AAGA,SAAgB,aAAa,OAAmC;CAC/D,QAAQ,OAAO,SAAS;EACvB,MAAM,UAAU,mBAAmB;EACnC,IAAI,CAAC,SAAS,OAAO,MAAM,OAAO,IAAI;EAEtC,MAAM,UAAU,IAAI,QAAQ,OAAO,IAAI;EACvC,IAAI,CAAC,QAAQ,QAAQ,IAAA,mBAAuB,GAC3C,QAAQ,QAAQ,IAAI,qBAAqB,QAAQ,EAAE;EAEpD,OAAO,MAAM,OAAO;CACrB;AACD;;;;;;;;AASA,SAAgB,sBAAkC;CACjD,MAAM,WAAW,WAAW;CAC5B,WAAW,QAAQ,aAAa,QAAQ;CACxC,aAAa;EACZ,WAAW,QAAQ;CACpB;AACD"}

package/dist/mailbox.cjs

@@ -0,0 +1,95 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/mailbox.ts
+/**
+* The mail a test sent, read from Mailpit.
+*
+* Locally, mail goes over real SMTP to Mailpit — the same client, the same
+* message, only the host differs. A test reads what arrived through Mailpit's
+* HTTP API, so a magic link is signed in with by opening the email that was
+* actually sent rather than a token pulled from somewhere else.
+*
+* Mailpit has one inbox for everything, and transactions do not reach it, so a
+* test keeps to its own mail by address: a unique recipient per test, read by
+* `to:`, and cleared afterwards.
+*/
+/** How long `last()` waits for mail that is still on its way. */
+const DEFAULT_TIMEOUT = 5e3;
+const POLL_INTERVAL = 50;
+/** A way to read the mail sent to one address. */
+function createMailbox(options) {
+	const inbox = options.inbox.replace(/\/$/, "");
+	const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+	const get = (path, init) => (options.fetch ?? globalThis.fetch)(`${inbox}${path}`, init);
+	return (address) => {
+		const query = `?query=${encodeURIComponent(`to:"${address}"`)}`;
+		const all = async () => {
+			const found = await json(await get(`/api/v1/search${query}`), inbox);
+			return Promise.all(found.messages.map(async ({ ID }) => email(await json(await get(`/api/v1/message/${ID}`), inbox))));
+		};
+		return {
+			all,
+			async last() {
+				const deadline = Date.now() + timeout;
+				for (;;) {
+					const [newest] = await all();
+					if (newest) return newest;
+					if (Date.now() >= deadline) throw new NoMail(address, timeout);
+					await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
+				}
+			},
+			async clear() {
+				const response = await get(`/api/v1/search${query}`, { method: "DELETE" });
+				if (!response.ok) throw new InboxUnreachable(inbox, response.status);
+			}
+		};
+	};
+}
+async function json(response, inbox) {
+	if (!response.ok) throw new InboxUnreachable(inbox, response.status);
+	return await response.json();
+}
+function email(message) {
+	const links = [...new Set([...(message.HTML ?? "").matchAll(/href="(https?:\/\/[^"]+)"/g), ...(message.Text ?? "").matchAll(/(https?:\/\/[^\s<>"]+)/g)].map(([, url]) => decodeEntities(url)))];
+	return {
+		id: message.ID,
+		from: message.From.Address,
+		to: message.To.map(({ Address }) => Address),
+		subject: message.Subject,
+		text: message.Text ?? "",
+		html: message.HTML ?? "",
+		links,
+		link: links[0]
+	};
+}
+/** `&amp;` in an HTML attribute is `&` in the URL it names. */
+function decodeEntities(url) {
+	return url.replaceAll("&amp;", "&");
+}
+/** No email to an address arrived in time. */
+var NoMail = class extends Error {
+	address;
+	timeout;
+	constructor(address, timeout) {
+		super(`No email to ${address} arrived within ${timeout}ms. Check that the code under test sends it, and to that address.`);
+		this.address = address;
+		this.timeout = timeout;
+		this.name = "NoMail";
+	}
+};
+/** Mailpit did not answer. */
+var InboxUnreachable = class extends Error {
+	inbox;
+	status;
+	constructor(inbox, status) {
+		super(`Mailpit at ${inbox} answered ${status}. Is it running? \`gkm test\` starts it when the app declares an Email construct.`);
+		this.inbox = inbox;
+		this.status = status;
+		this.name = "InboxUnreachable";
+	}
+};
+//#endregion
+exports.InboxUnreachable = InboxUnreachable;
+exports.NoMail = NoMail;
+exports.createMailbox = createMailbox;
+
+//# sourceMappingURL=mailbox.cjs.map

package/dist/mailbox.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.cjs","names":[],"sources":["../src/mailbox.ts"],"sourcesContent":["/**\n * The mail a test sent, read from Mailpit.\n *\n * Locally, mail goes over real SMTP to Mailpit — the same client, the same\n * message, only the host differs. A test reads what arrived through Mailpit's\n * HTTP API, so a magic link is signed in with by opening the email that was\n * actually sent rather than a token pulled from somewhere else.\n *\n * Mailpit has one inbox for everything, and transactions do not reach it, so a\n * test keeps to its own mail by address: a unique recipient per test, read by\n * `to:`, and cleared afterwards.\n */\n\n/** How long `last()` waits for mail that is still on its way. */\nconst DEFAULT_TIMEOUT = 5_000;\nconst POLL_INTERVAL = 50;\n\nexport interface MailboxOptions {\n\t/** Mailpit's HTTP address — what `gkm test` injects as `<ID>_INBOX_URL`. */\n\tinbox: string;\n\t/** The `fetch` to read it with. Defaults to the global one. */\n\tfetch?: typeof fetch;\n\t/** How long `last()` waits for mail to arrive. */\n\ttimeout?: number;\n}\n\n/** One email, as it arrived. */\nexport interface Email {\n\tid: string;\n\tfrom: string;\n\tto: string[];\n\tsubject: string;\n\ttext: string;\n\thtml: string;\n\t/** Every `http(s)` link in the email, in order. */\n\tlinks: string[];\n\t/** The first link — the one a sign-in or confirmation email is about. */\n\tlink: string | undefined;\n}\n\nexport interface Mailbox {\n\t/** The newest email to this address, waiting for one if none has arrived. */\n\tlast(): Promise<Email>;\n\t/** Every email to this address, newest first. */\n\tall(): Promise<Email[]>;\n\t/** Delete every email to this address. */\n\tclear(): Promise<void>;\n}\n\n/** A way to read the mail sent to one address. */\nexport function createMailbox(\n\toptions: MailboxOptions,\n): (address: string) => Mailbox {\n\tconst inbox = options.inbox.replace(/\\/$/, '');\n\tconst timeout = options.timeout ?? DEFAULT_TIMEOUT;\n\tconst get = (path: string, init?: RequestInit) =>\n\t\t(options.fetch ?? globalThis.fetch)(`${inbox}${path}`, init);\n\n\treturn (address) => {\n\t\tconst query = `?query=${encodeURIComponent(`to:\"${address}\"`)}`;\n\n\t\tconst all = async (): Promise<Email[]> => {\n\t\t\tconst found = await json<SearchResult>(\n\t\t\t\tawait get(`/api/v1/search${query}`),\n\t\t\t\tinbox,\n\t\t\t);\n\t\t\treturn Promise.all(\n\t\t\t\tfound.messages.map(async ({ ID }) =>\n\t\t\t\t\temail(await json<Message>(await get(`/api/v1/message/${ID}`), inbox)),\n\t\t\t\t),\n\t\t\t);\n\t\t};\n\n\t\treturn {\n\t\t\tall,\n\t\t\tasync last() {\n\t\t\t\tconst deadline = Date.now() + timeout;\n\t\t\t\tfor (;;) {\n\t\t\t\t\tconst [newest] = await all();\n\t\t\t\t\tif (newest) return newest;\n\t\t\t\t\tif (Date.now() >= deadline) throw new NoMail(address, timeout);\n\t\t\t\t\tawait new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));\n\t\t\t\t}\n\t\t\t},\n\t\t\tasync clear() {\n\t\t\t\tconst response = await get(`/api/v1/search${query}`, {\n\t\t\t\t\tmethod: 'DELETE',\n\t\t\t\t});\n\t\t\t\tif (!response.ok) {\n\t\t\t\t\tthrow new InboxUnreachable(inbox, response.status);\n\t\t\t\t}\n\t\t\t},\n\t\t};\n\t};\n}\n\ninterface SearchResult {\n\tmessages: { ID: string }[];\n}\n\ninterface Message {\n\tID: string;\n\tFrom: { Address: string };\n\tTo: { Address: string }[];\n\tSubject: string;\n\tText: string;\n\tHTML: string;\n}\n\nasync function json<T>(response: Response, inbox: string): Promise<T> {\n\tif (!response.ok) throw new InboxUnreachable(inbox, response.status);\n\treturn (await response.json()) as T;\n}\n\nfunction email(message: Message): Email {\n\tconst links = [\n\t\t...new Set(\n\t\t\t[\n\t\t\t\t...(message.HTML ?? '').matchAll(/href=\"(https?:\\/\\/[^\"]+)\"/g),\n\t\t\t\t...(message.Text ?? '').matchAll(/(https?:\\/\\/[^\\s<>\"]+)/g),\n\t\t\t].map(([, url]) => decodeEntities(url!)),\n\t\t),\n\t];\n\n\treturn {\n\t\tid: message.ID,\n\t\tfrom: message.From.Address,\n\t\tto: message.To.map(({ Address }) => Address),\n\t\tsubject: message.Subject,\n\t\ttext: message.Text ?? '',\n\t\thtml: message.HTML ?? '',\n\t\tlinks,\n\t\tlink: links[0],\n\t};\n}\n\n/** `&amp;` in an HTML attribute is `&` in the URL it names. */\nfunction decodeEntities(url: string): string {\n\treturn url.replaceAll('&amp;', '&');\n}\n\n/** No email to an address arrived in time. */\nexport class NoMail extends Error {\n\tconstructor(\n\t\treadonly address: string,\n\t\treadonly timeout: number,\n\t) {\n\t\tsuper(\n\t\t\t`No email to ${address} arrived within ${timeout}ms. Check that the ` +\n\t\t\t\t`code under test sends it, and to that address.`,\n\t\t);\n\t\tthis.name = 'NoMail';\n\t}\n}\n\n/** Mailpit did not answer. */\nexport class InboxUnreachable extends Error {\n\tconstructor(\n\t\treadonly inbox: string,\n\t\treadonly status: number,\n\t) {\n\t\tsuper(\n\t\t\t`Mailpit at ${inbox} answered ${status}. Is it running? \\`gkm test\\` ` +\n\t\t\t\t`starts it when the app declares an Email construct.`,\n\t\t);\n\t\tthis.name = 'InboxUnreachable';\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;AAcA,MAAM,kBAAkB;AACxB,MAAM,gBAAgB;;AAmCtB,SAAgB,cACf,SAC+B;CAC/B,MAAM,QAAQ,QAAQ,MAAM,QAAQ,OAAO,EAAE;CAC7C,MAAM,UAAU,QAAQ,WAAW;CACnC,MAAM,OAAO,MAAc,UACzB,QAAQ,SAAS,WAAW,MAAA,CAAO,GAAG,QAAQ,QAAQ,IAAI;CAE5D,QAAQ,YAAY;EACnB,MAAM,QAAQ,UAAU,mBAAmB,OAAO,QAAQ,EAAE;EAE5D,MAAM,MAAM,YAA8B;GACzC,MAAM,QAAQ,MAAM,KACnB,MAAM,IAAI,iBAAiB,OAAO,GAClC,KACD;GACA,OAAO,QAAQ,IACd,MAAM,SAAS,IAAI,OAAO,EAAE,SAC3B,MAAM,MAAM,KAAc,MAAM,IAAI,mBAAmB,IAAI,GAAG,KAAK,CAAC,CACrE,CACD;EACD;EAEA,OAAO;GACN;GACA,MAAM,OAAO;IACZ,MAAM,WAAW,KAAK,IAAI,IAAI;IAC9B,SAAS;KACR,MAAM,CAAC,UAAU,MAAM,IAAI;KAC3B,IAAI,QAAQ,OAAO;KACnB,IAAI,KAAK,IAAI,KAAK,UAAU,MAAM,IAAI,OAAO,SAAS,OAAO;KAC7D,MAAM,IAAI,SAAS,YAAY,WAAW,SAAS,aAAa,CAAC;IAClE;GACD;GACA,MAAM,QAAQ;IACb,MAAM,WAAW,MAAM,IAAI,iBAAiB,SAAS,EACpD,QAAQ,SACT,CAAC;IACD,IAAI,CAAC,SAAS,IACb,MAAM,IAAI,iBAAiB,OAAO,SAAS,MAAM;GAEnD;EACD;CACD;AACD;AAeA,eAAe,KAAQ,UAAoB,OAA2B;CACrE,IAAI,CAAC,SAAS,IAAI,MAAM,IAAI,iBAAiB,OAAO,SAAS,MAAM;CACnE,OAAQ,MAAM,SAAS,KAAK;AAC7B;AAEA,SAAS,MAAM,SAAyB;CACvC,MAAM,QAAQ,CACb,GAAG,IAAI,IACN,CACC,IAAI,QAAQ,QAAQ,GAAA,CAAI,SAAS,4BAA4B,GAC7D,IAAI,QAAQ,QAAQ,GAAA,CAAI,SAAS,yBAAyB,CAC3D,CAAC,CAAC,KAAK,GAAG,SAAS,eAAe,GAAI,CAAC,CACxC,CACD;CAEA,OAAO;EACN,IAAI,QAAQ;EACZ,MAAM,QAAQ,KAAK;EACnB,IAAI,QAAQ,GAAG,KAAK,EAAE,cAAc,OAAO;EAC3C,SAAS,QAAQ;EACjB,MAAM,QAAQ,QAAQ;EACtB,MAAM,QAAQ,QAAQ;EACtB;EACA,MAAM,MAAM;CACb;AACD;;AAGA,SAAS,eAAe,KAAqB;CAC5C,OAAO,IAAI,WAAW,SAAS,GAAG;AACnC;;AAGA,IAAa,SAAb,cAA4B,MAAM;CAEvB;CACA;CAFV,YACC,SACA,SACC;EACD,MACC,eAAe,QAAQ,kBAAkB,QAAQ,kEAElD;EANS,KAAA,UAAA;EACA,KAAA,UAAA;EAMT,KAAK,OAAO;CACb;AACD;;AAGA,IAAa,mBAAb,cAAsC,MAAM;CAEjC;CACA;CAFV,YACC,OACA,QACC;EACD,MACC,cAAc,MAAM,YAAY,OAAO,kFAExC;EANS,KAAA,QAAA;EACA,KAAA,SAAA;EAMT,KAAK,OAAO;CACb;AACD"}

package/dist/mailbox.d.cts

@@ -0,0 +1,58 @@
+//#region src/mailbox.d.ts
+/**
+ * The mail a test sent, read from Mailpit.
+ *
+ * Locally, mail goes over real SMTP to Mailpit — the same client, the same
+ * message, only the host differs. A test reads what arrived through Mailpit's
+ * HTTP API, so a magic link is signed in with by opening the email that was
+ * actually sent rather than a token pulled from somewhere else.
+ *
+ * Mailpit has one inbox for everything, and transactions do not reach it, so a
+ * test keeps to its own mail by address: a unique recipient per test, read by
+ * `to:`, and cleared afterwards.
+ */
+export interface MailboxOptions {
+  /** Mailpit's HTTP address — what `gkm test` injects as `<ID>_INBOX_URL`. */
+  inbox: string;
+  /** The `fetch` to read it with. Defaults to the global one. */
+  fetch?: typeof fetch;
+  /** How long `last()` waits for mail to arrive. */
+  timeout?: number;
+}
+/** One email, as it arrived. */
+export interface Email {
+  id: string;
+  from: string;
+  to: string[];
+  subject: string;
+  text: string;
+  html: string;
+  /** Every `http(s)` link in the email, in order. */
+  links: string[];
+  /** The first link — the one a sign-in or confirmation email is about. */
+  link: string | undefined;
+}
+export interface Mailbox {
+  /** The newest email to this address, waiting for one if none has arrived. */
+  last(): Promise<Email>;
+  /** Every email to this address, newest first. */
+  all(): Promise<Email[]>;
+  /** Delete every email to this address. */
+  clear(): Promise<void>;
+}
+/** A way to read the mail sent to one address. */
+export declare function createMailbox(options: MailboxOptions): (address: string) => Mailbox;
+/** No email to an address arrived in time. */
+export declare class NoMail extends Error {
+  readonly address: string;
+  readonly timeout: number;
+  constructor(address: string, timeout: number);
+}
+/** Mailpit did not answer. */
+export declare class InboxUnreachable extends Error {
+  readonly inbox: string;
+  readonly status: number;
+  constructor(inbox: string, status: number);
+}
+//#endregion
+//# sourceMappingURL=mailbox.d.cts.map

package/dist/mailbox.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.d.cts","names":[],"sources":["../src/mailbox.ts"],"mappings":";;;;;;;;;;;;;iBAiBiB;;EAEhB;;EAEA,eAAe;;EAEf;;;iBAIgB;EAChB;EACA;EACA;EACA;EACA;EACA;;EAEA;;EAEA;;iBAGgB;;EAEhB,QAAQ,QAAQ;;EAEhB,OAAO,QAAQ;;EAEf,SAAS;;;wBAIM,cACf,SAAS,kBACN,oBAAoB;;qBA0FX,eAAe;WAEjB;WACA;EAFV,YACU,iBACA;;;qBAWE,yBAAyB;WAE3B;WACA;EAFV,YACU,eACA"}

package/dist/mailbox.d.mts

@@ -0,0 +1,58 @@
+//#region src/mailbox.d.ts
+/**
+ * The mail a test sent, read from Mailpit.
+ *
+ * Locally, mail goes over real SMTP to Mailpit — the same client, the same
+ * message, only the host differs. A test reads what arrived through Mailpit's
+ * HTTP API, so a magic link is signed in with by opening the email that was
+ * actually sent rather than a token pulled from somewhere else.
+ *
+ * Mailpit has one inbox for everything, and transactions do not reach it, so a
+ * test keeps to its own mail by address: a unique recipient per test, read by
+ * `to:`, and cleared afterwards.
+ */
+export interface MailboxOptions {
+  /** Mailpit's HTTP address — what `gkm test` injects as `<ID>_INBOX_URL`. */
+  inbox: string;
+  /** The `fetch` to read it with. Defaults to the global one. */
+  fetch?: typeof fetch;
+  /** How long `last()` waits for mail to arrive. */
+  timeout?: number;
+}
+/** One email, as it arrived. */
+export interface Email {
+  id: string;
+  from: string;
+  to: string[];
+  subject: string;
+  text: string;
+  html: string;
+  /** Every `http(s)` link in the email, in order. */
+  links: string[];
+  /** The first link — the one a sign-in or confirmation email is about. */
+  link: string | undefined;
+}
+export interface Mailbox {
+  /** The newest email to this address, waiting for one if none has arrived. */
+  last(): Promise<Email>;
+  /** Every email to this address, newest first. */
+  all(): Promise<Email[]>;
+  /** Delete every email to this address. */
+  clear(): Promise<void>;
+}
+/** A way to read the mail sent to one address. */
+export declare function createMailbox(options: MailboxOptions): (address: string) => Mailbox;
+/** No email to an address arrived in time. */
+export declare class NoMail extends Error {
+  readonly address: string;
+  readonly timeout: number;
+  constructor(address: string, timeout: number);
+}
+/** Mailpit did not answer. */
+export declare class InboxUnreachable extends Error {
+  readonly inbox: string;
+  readonly status: number;
+  constructor(inbox: string, status: number);
+}
+//#endregion
+//# sourceMappingURL=mailbox.d.mts.map

package/dist/mailbox.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.d.mts","names":[],"sources":["../src/mailbox.ts"],"mappings":";;;;;;;;;;;;;iBAiBiB;;EAEhB;;EAEA,eAAe;;EAEf;;;iBAIgB;EAChB;EACA;EACA;EACA;EACA;EACA;;EAEA;;EAEA;;iBAGgB;;EAEhB,QAAQ,QAAQ;;EAEhB,OAAO,QAAQ;;EAEf,SAAS;;;wBAIM,cACf,SAAS,kBACN,oBAAoB;;qBA0FX,eAAe;WAEjB;WACA;EAFV,YACU,iBACA;;;qBAWE,yBAAyB;WAE3B;WACA;EAFV,YACU,eACA"}

package/dist/mailbox.mjs

@@ -0,0 +1,92 @@
+//#region src/mailbox.ts
+/**
+* The mail a test sent, read from Mailpit.
+*
+* Locally, mail goes over real SMTP to Mailpit — the same client, the same
+* message, only the host differs. A test reads what arrived through Mailpit's
+* HTTP API, so a magic link is signed in with by opening the email that was
+* actually sent rather than a token pulled from somewhere else.
+*
+* Mailpit has one inbox for everything, and transactions do not reach it, so a
+* test keeps to its own mail by address: a unique recipient per test, read by
+* `to:`, and cleared afterwards.
+*/
+/** How long `last()` waits for mail that is still on its way. */
+const DEFAULT_TIMEOUT = 5e3;
+const POLL_INTERVAL = 50;
+/** A way to read the mail sent to one address. */
+function createMailbox(options) {
+	const inbox = options.inbox.replace(/\/$/, "");
+	const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+	const get = (path, init) => (options.fetch ?? globalThis.fetch)(`${inbox}${path}`, init);
+	return (address) => {
+		const query = `?query=${encodeURIComponent(`to:"${address}"`)}`;
+		const all = async () => {
+			const found = await json(await get(`/api/v1/search${query}`), inbox);
+			return Promise.all(found.messages.map(async ({ ID }) => email(await json(await get(`/api/v1/message/${ID}`), inbox))));
+		};
+		return {
+			all,
+			async last() {
+				const deadline = Date.now() + timeout;
+				for (;;) {
+					const [newest] = await all();
+					if (newest) return newest;
+					if (Date.now() >= deadline) throw new NoMail(address, timeout);
+					await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
+				}
+			},
+			async clear() {
+				const response = await get(`/api/v1/search${query}`, { method: "DELETE" });
+				if (!response.ok) throw new InboxUnreachable(inbox, response.status);
+			}
+		};
+	};
+}
+async function json(response, inbox) {
+	if (!response.ok) throw new InboxUnreachable(inbox, response.status);
+	return await response.json();
+}
+function email(message) {
+	const links = [...new Set([...(message.HTML ?? "").matchAll(/href="(https?:\/\/[^"]+)"/g), ...(message.Text ?? "").matchAll(/(https?:\/\/[^\s<>"]+)/g)].map(([, url]) => decodeEntities(url)))];
+	return {
+		id: message.ID,
+		from: message.From.Address,
+		to: message.To.map(({ Address }) => Address),
+		subject: message.Subject,
+		text: message.Text ?? "",
+		html: message.HTML ?? "",
+		links,
+		link: links[0]
+	};
+}
+/** `&amp;` in an HTML attribute is `&` in the URL it names. */
+function decodeEntities(url) {
+	return url.replaceAll("&amp;", "&");
+}
+/** No email to an address arrived in time. */
+var NoMail = class extends Error {
+	address;
+	timeout;
+	constructor(address, timeout) {
+		super(`No email to ${address} arrived within ${timeout}ms. Check that the code under test sends it, and to that address.`);
+		this.address = address;
+		this.timeout = timeout;
+		this.name = "NoMail";
+	}
+};
+/** Mailpit did not answer. */
+var InboxUnreachable = class extends Error {
+	inbox;
+	status;
+	constructor(inbox, status) {
+		super(`Mailpit at ${inbox} answered ${status}. Is it running? \`gkm test\` starts it when the app declares an Email construct.`);
+		this.inbox = inbox;
+		this.status = status;
+		this.name = "InboxUnreachable";
+	}
+};
+//#endregion
+export { InboxUnreachable, NoMail, createMailbox };
+
+//# sourceMappingURL=mailbox.mjs.map

package/dist/mailbox.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.mjs","names":[],"sources":["../src/mailbox.ts"],"sourcesContent":["/**\n * The mail a test sent, read from Mailpit.\n *\n * Locally, mail goes over real SMTP to Mailpit — the same client, the same\n * message, only the host differs. A test reads what arrived through Mailpit's\n * HTTP API, so a magic link is signed in with by opening the email that was\n * actually sent rather than a token pulled from somewhere else.\n *\n * Mailpit has one inbox for everything, and transactions do not reach it, so a\n * test keeps to its own mail by address: a unique recipient per test, read by\n * `to:`, and cleared afterwards.\n */\n\n/** How long `last()` waits for mail that is still on its way. */\nconst DEFAULT_TIMEOUT = 5_000;\nconst POLL_INTERVAL = 50;\n\nexport interface MailboxOptions {\n\t/** Mailpit's HTTP address — what `gkm test` injects as `<ID>_INBOX_URL`. */\n\tinbox: string;\n\t/** The `fetch` to read it with. Defaults to the global one. */\n\tfetch?: typeof fetch;\n\t/** How long `last()` waits for mail to arrive. */\n\ttimeout?: number;\n}\n\n/** One email, as it arrived. */\nexport interface Email {\n\tid: string;\n\tfrom: string;\n\tto: string[];\n\tsubject: string;\n\ttext: string;\n\thtml: string;\n\t/** Every `http(s)` link in the email, in order. */\n\tlinks: string[];\n\t/** The first link — the one a sign-in or confirmation email is about. */\n\tlink: string | undefined;\n}\n\nexport interface Mailbox {\n\t/** The newest email to this address, waiting for one if none has arrived. */\n\tlast(): Promise<Email>;\n\t/** Every email to this address, newest first. */\n\tall(): Promise<Email[]>;\n\t/** Delete every email to this address. */\n\tclear(): Promise<void>;\n}\n\n/** A way to read the mail sent to one address. */\nexport function createMailbox(\n\toptions: MailboxOptions,\n): (address: string) => Mailbox {\n\tconst inbox = options.inbox.replace(/\\/$/, '');\n\tconst timeout = options.timeout ?? DEFAULT_TIMEOUT;\n\tconst get = (path: string, init?: RequestInit) =>\n\t\t(options.fetch ?? globalThis.fetch)(`${inbox}${path}`, init);\n\n\treturn (address) => {\n\t\tconst query = `?query=${encodeURIComponent(`to:\"${address}\"`)}`;\n\n\t\tconst all = async (): Promise<Email[]> => {\n\t\t\tconst found = await json<SearchResult>(\n\t\t\t\tawait get(`/api/v1/search${query}`),\n\t\t\t\tinbox,\n\t\t\t);\n\t\t\treturn Promise.all(\n\t\t\t\tfound.messages.map(async ({ ID }) =>\n\t\t\t\t\temail(await json<Message>(await get(`/api/v1/message/${ID}`), inbox)),\n\t\t\t\t),\n\t\t\t);\n\t\t};\n\n\t\treturn {\n\t\t\tall,\n\t\t\tasync last() {\n\t\t\t\tconst deadline = Date.now() + timeout;\n\t\t\t\tfor (;;) {\n\t\t\t\t\tconst [newest] = await all();\n\t\t\t\t\tif (newest) return newest;\n\t\t\t\t\tif (Date.now() >= deadline) throw new NoMail(address, timeout);\n\t\t\t\t\tawait new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));\n\t\t\t\t}\n\t\t\t},\n\t\t\tasync clear() {\n\t\t\t\tconst response = await get(`/api/v1/search${query}`, {\n\t\t\t\t\tmethod: 'DELETE',\n\t\t\t\t});\n\t\t\t\tif (!response.ok) {\n\t\t\t\t\tthrow new InboxUnreachable(inbox, response.status);\n\t\t\t\t}\n\t\t\t},\n\t\t};\n\t};\n}\n\ninterface SearchResult {\n\tmessages: { ID: string }[];\n}\n\ninterface Message {\n\tID: string;\n\tFrom: { Address: string };\n\tTo: { Address: string }[];\n\tSubject: string;\n\tText: string;\n\tHTML: string;\n}\n\nasync function json<T>(response: Response, inbox: string): Promise<T> {\n\tif (!response.ok) throw new InboxUnreachable(inbox, response.status);\n\treturn (await response.json()) as T;\n}\n\nfunction email(message: Message): Email {\n\tconst links = [\n\t\t...new Set(\n\t\t\t[\n\t\t\t\t...(message.HTML ?? '').matchAll(/href=\"(https?:\\/\\/[^\"]+)\"/g),\n\t\t\t\t...(message.Text ?? '').matchAll(/(https?:\\/\\/[^\\s<>\"]+)/g),\n\t\t\t].map(([, url]) => decodeEntities(url!)),\n\t\t),\n\t];\n\n\treturn {\n\t\tid: message.ID,\n\t\tfrom: message.From.Address,\n\t\tto: message.To.map(({ Address }) => Address),\n\t\tsubject: message.Subject,\n\t\ttext: message.Text ?? '',\n\t\thtml: message.HTML ?? '',\n\t\tlinks,\n\t\tlink: links[0],\n\t};\n}\n\n/** `&amp;` in an HTML attribute is `&` in the URL it names. */\nfunction decodeEntities(url: string): string {\n\treturn url.replaceAll('&amp;', '&');\n}\n\n/** No email to an address arrived in time. */\nexport class NoMail extends Error {\n\tconstructor(\n\t\treadonly address: string,\n\t\treadonly timeout: number,\n\t) {\n\t\tsuper(\n\t\t\t`No email to ${address} arrived within ${timeout}ms. Check that the ` +\n\t\t\t\t`code under test sends it, and to that address.`,\n\t\t);\n\t\tthis.name = 'NoMail';\n\t}\n}\n\n/** Mailpit did not answer. */\nexport class InboxUnreachable extends Error {\n\tconstructor(\n\t\treadonly inbox: string,\n\t\treadonly status: number,\n\t) {\n\t\tsuper(\n\t\t\t`Mailpit at ${inbox} answered ${status}. Is it running? \\`gkm test\\` ` +\n\t\t\t\t`starts it when the app declares an Email construct.`,\n\t\t);\n\t\tthis.name = 'InboxUnreachable';\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;AAcA,MAAM,kBAAkB;AACxB,MAAM,gBAAgB;;AAmCtB,SAAgB,cACf,SAC+B;CAC/B,MAAM,QAAQ,QAAQ,MAAM,QAAQ,OAAO,EAAE;CAC7C,MAAM,UAAU,QAAQ,WAAW;CACnC,MAAM,OAAO,MAAc,UACzB,QAAQ,SAAS,WAAW,MAAA,CAAO,GAAG,QAAQ,QAAQ,IAAI;CAE5D,QAAQ,YAAY;EACnB,MAAM,QAAQ,UAAU,mBAAmB,OAAO,QAAQ,EAAE;EAE5D,MAAM,MAAM,YAA8B;GACzC,MAAM,QAAQ,MAAM,KACnB,MAAM,IAAI,iBAAiB,OAAO,GAClC,KACD;GACA,OAAO,QAAQ,IACd,MAAM,SAAS,IAAI,OAAO,EAAE,SAC3B,MAAM,MAAM,KAAc,MAAM,IAAI,mBAAmB,IAAI,GAAG,KAAK,CAAC,CACrE,CACD;EACD;EAEA,OAAO;GACN;GACA,MAAM,OAAO;IACZ,MAAM,WAAW,KAAK,IAAI,IAAI;IAC9B,SAAS;KACR,MAAM,CAAC,UAAU,MAAM,IAAI;KAC3B,IAAI,QAAQ,OAAO;KACnB,IAAI,KAAK,IAAI,KAAK,UAAU,MAAM,IAAI,OAAO,SAAS,OAAO;KAC7D,MAAM,IAAI,SAAS,YAAY,WAAW,SAAS,aAAa,CAAC;IAClE;GACD;GACA,MAAM,QAAQ;IACb,MAAM,WAAW,MAAM,IAAI,iBAAiB,SAAS,EACpD,QAAQ,SACT,CAAC;IACD,IAAI,CAAC,SAAS,IACb,MAAM,IAAI,iBAAiB,OAAO,SAAS,MAAM;GAEnD;EACD;CACD;AACD;AAeA,eAAe,KAAQ,UAAoB,OAA2B;CACrE,IAAI,CAAC,SAAS,IAAI,MAAM,IAAI,iBAAiB,OAAO,SAAS,MAAM;CACnE,OAAQ,MAAM,SAAS,KAAK;AAC7B;AAEA,SAAS,MAAM,SAAyB;CACvC,MAAM,QAAQ,CACb,GAAG,IAAI,IACN,CACC,IAAI,QAAQ,QAAQ,GAAA,CAAI,SAAS,4BAA4B,GAC7D,IAAI,QAAQ,QAAQ,GAAA,CAAI,SAAS,yBAAyB,CAC3D,CAAC,CAAC,KAAK,GAAG,SAAS,eAAe,GAAI,CAAC,CACxC,CACD;CAEA,OAAO;EACN,IAAI,QAAQ;EACZ,MAAM,QAAQ,KAAK;EACnB,IAAI,QAAQ,GAAG,KAAK,EAAE,cAAc,OAAO;EAC3C,SAAS,QAAQ;EACjB,MAAM,QAAQ,QAAQ;EACtB,MAAM,QAAQ,QAAQ;EACtB;EACA,MAAM,MAAM;CACb;AACD;;AAGA,SAAS,eAAe,KAAqB;CAC5C,OAAO,IAAI,WAAW,SAAS,GAAG;AACnC;;AAGA,IAAa,SAAb,cAA4B,MAAM;CAEvB;CACA;CAFV,YACC,SACA,SACC;EACD,MACC,eAAe,QAAQ,kBAAkB,QAAQ,kEAElD;EANS,KAAA,UAAA;EACA,KAAA,UAAA;EAMT,KAAK,OAAO;CACb;AACD;;AAGA,IAAa,mBAAb,cAAsC,MAAM;CAEjC;CACA;CAFV,YACC,OACA,QACC;EACD,MACC,cAAc,MAAM,YAAY,OAAO,kFAExC;EANS,KAAA,QAAA;EACA,KAAA,SAAA;EAMT,KAAK,OAAO;CACb;AACD"}

package/dist/transactions.cjs

@@ -0,0 +1,114 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_rolldown_runtime = require("./rolldown-runtime-VH7oDXx4.cjs");
+let pg = require("pg");
+pg = require_rolldown_runtime.__toESM(pg, 1);
+let kysely = require("kysely");
+//#region src/transactions.ts
+/**
+* A transaction per database, per test — as each runs deployed.
+*
+* An app's database and a schema tenant such as the auth server's are separate
+* databases to the code using them: separate connections, credentials, roles
+* and search paths. A test keeps them that way. Each gets its own connection,
+* opened into a transaction the first time the test touches it, and every one
+* is rolled back when the test ends.
+*
+* Code under test must be free to use transactions itself, and better-auth
+* does — it also calls `db.connection()`, which Kysely refuses on a
+* `Transaction`. So what a test hands over is not a `Transaction` but a Kysely
+* over the one connection already inside the test's transaction, on which a
+* `BEGIN` becomes a savepoint and a `COMMIT` releases it. Nothing the code does
+* can end the transaction the test will roll back.
+*/
+/**
+* The connection settings for a database URL.
+*
+* `?search_path=` is not a libpq parameter: a URL carrying it connects and then
+* resolves every name against `public`. Postgres takes it as a startup option,
+* which is what a schema tenant's URL needs to reach its own tables.
+*/
+function connectionConfig(url) {
+	const parsed = new URL(url);
+	const searchPath = parsed.searchParams.get("search_path");
+	if (!searchPath) return { connectionString: url };
+	parsed.searchParams.delete("search_path");
+	return {
+		connectionString: parsed.toString(),
+		options: `-c search_path=${searchPath}`
+	};
+}
+/** Open a connection to `url` and begin the transaction a test will roll back. */
+async function openBoundTransaction(url) {
+	const client = new pg.default.Client(connectionConfig(url));
+	await client.connect();
+	await client.query("BEGIN");
+	return {
+		db: new kysely.Kysely({ dialect: new kysely.PostgresDialect({ pool: {
+			connect: async () => savepointing(client),
+			end: async () => {}
+		} }) }),
+		async rollback() {
+			try {
+				await client.query("ROLLBACK");
+			} finally {
+				await client.end();
+			}
+		}
+	};
+}
+/**
+* The client, with transaction control turned into savepoints.
+*
+* Kysely issues `begin`/`commit`/`rollback` as plain statements; this is the
+* one place they can be caught. A depth counter names the savepoints, so
+* nested transactions nest.
+*/
+function savepointing(client) {
+	let depth = 0;
+	const query = client.query.bind(client);
+	const wrapped = Object.create(client);
+	Object.assign(wrapped, {
+		query: (text, ...rest) => {
+			const statement = typeof text === "string" ? text.trim().toLowerCase() : void 0;
+			if (statement === "begin" || statement?.startsWith("start transaction")) {
+				depth++;
+				return query(`SAVEPOINT test_sp_${depth}`);
+			}
+			if (statement === "commit") return query(`RELEASE SAVEPOINT test_sp_${depth--}`);
+			if (statement === "rollback") return query(`ROLLBACK TO SAVEPOINT test_sp_${depth--}`);
+			return query(text, ...rest);
+		},
+		release: () => {}
+	});
+	return wrapped;
+}
+/**
+* The transactions one test has opened, by database.
+*
+* `get` opens a database's transaction the first time it is asked for and
+* hands back the same one after that — including to a caller that asks while
+* it is still opening. `rollbackAll` ends every one of them.
+*/
+var TransactionRegistry = class {
+	open = /* @__PURE__ */ new Map();
+	get(key, url) {
+		let transaction = this.open.get(key);
+		if (!transaction) {
+			transaction = openBoundTransaction(url);
+			this.open.set(key, transaction);
+		}
+		return transaction.then(({ db }) => db);
+	}
+	async rollbackAll() {
+		const transactions = [...this.open.values()];
+		this.open.clear();
+		const failed = (await Promise.allSettled(transactions.map(async (transaction) => (await transaction).rollback()))).find((result) => result.status === "rejected");
+		if (failed) throw failed.reason;
+	}
+};
+//#endregion
+exports.TransactionRegistry = TransactionRegistry;
+exports.connectionConfig = connectionConfig;
+exports.openBoundTransaction = openBoundTransaction;
+
+//# sourceMappingURL=transactions.cjs.map

package/dist/transactions.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactions.cjs","names":["Kysely","PostgresDialect"],"sources":["../src/transactions.ts"],"sourcesContent":["/**\n * A transaction per database, per test — as each runs deployed.\n *\n * An app's database and a schema tenant such as the auth server's are separate\n * databases to the code using them: separate connections, credentials, roles\n * and search paths. A test keeps them that way. Each gets its own connection,\n * opened into a transaction the first time the test touches it, and every one\n * is rolled back when the test ends.\n *\n * Code under test must be free to use transactions itself, and better-auth\n * does — it also calls `db.connection()`, which Kysely refuses on a\n * `Transaction`. So what a test hands over is not a `Transaction` but a Kysely\n * over the one connection already inside the test's transaction, on which a\n * `BEGIN` becomes a savepoint and a `COMMIT` releases it. Nothing the code does\n * can end the transaction the test will roll back.\n */\n\nimport { Kysely, PostgresDialect } from 'kysely';\nimport pg from 'pg';\n\n/** How to reach one database: a URL, and its search path as a startup option. */\nexport interface ConnectionConfig {\n\tconnectionString: string;\n\toptions?: string;\n}\n\n/**\n * The connection settings for a database URL.\n *\n * `?search_path=` is not a libpq parameter: a URL carrying it connects and then\n * resolves every name against `public`. Postgres takes it as a startup option,\n * which is what a schema tenant's URL needs to reach its own tables.\n */\nexport function connectionConfig(url: string): ConnectionConfig {\n\tconst parsed = new URL(url);\n\tconst searchPath = parsed.searchParams.get('search_path');\n\tif (!searchPath) return { connectionString: url };\n\n\tparsed.searchParams.delete('search_path');\n\treturn {\n\t\tconnectionString: parsed.toString(),\n\t\toptions: `-c search_path=${searchPath}`,\n\t};\n}\n\n/** One database's connection, inside a transaction the test will roll back. */\nexport interface BoundTransaction {\n\t/** Everything queried through this runs inside the test's transaction. */\n\treadonly db: Kysely<any>;\n\t/** Undo everything, and let the connection go. */\n\trollback(): Promise<void>;\n}\n\n/** Open a connection to `url` and begin the transaction a test will roll back. */\nexport async function openBoundTransaction(\n\turl: string,\n): Promise<BoundTransaction> {\n\tconst client = new pg.Client(connectionConfig(url));\n\tawait client.connect();\n\tawait client.query('BEGIN');\n\n\treturn {\n\t\tdb: new Kysely({\n\t\t\tdialect: new PostgresDialect({\n\t\t\t\t// A \"pool\" of the one connection. Released never, ended never: the\n\t\t\t\t// test owns it, and it closes in `rollback`.\n\t\t\t\tpool: {\n\t\t\t\t\tconnect: async () => savepointing(client),\n\t\t\t\t\tend: async () => {},\n\t\t\t\t} as unknown as pg.Pool,\n\t\t\t}),\n\t\t}),\n\t\tasync rollback() {\n\t\t\ttry {\n\t\t\t\tawait client.query('ROLLBACK');\n\t\t\t} finally {\n\t\t\t\tawait client.end();\n\t\t\t}\n\t\t},\n\t};\n}\n\n/**\n * The client, with transaction control turned into savepoints.\n *\n * Kysely issues `begin`/`commit`/`rollback` as plain statements; this is the\n * one place they can be caught. A depth counter names the savepoints, so\n * nested transactions nest.\n */\nfunction savepointing(client: pg.Client): pg.PoolClient {\n\tlet depth = 0;\n\tconst query = client.query.bind(client) as (...args: unknown[]) => unknown;\n\n\tconst wrapped = Object.create(client) as pg.PoolClient;\n\tObject.assign(wrapped, {\n\t\tquery: (text: unknown, ...rest: unknown[]) => {\n\t\t\tconst statement =\n\t\t\t\ttypeof text === 'string' ? text.trim().toLowerCase() : undefined;\n\n\t\t\tif (statement === 'begin' || statement?.startsWith('start transaction')) {\n\t\t\t\tdepth++;\n\t\t\t\treturn query(`SAVEPOINT test_sp_${depth}`);\n\t\t\t}\n\t\t\tif (statement === 'commit') {\n\t\t\t\treturn query(`RELEASE SAVEPOINT test_sp_${depth--}`);\n\t\t\t}\n\t\t\tif (statement === 'rollback') {\n\t\t\t\treturn query(`ROLLBACK TO SAVEPOINT test_sp_${depth--}`);\n\t\t\t}\n\t\t\treturn query(text, ...rest);\n\t\t},\n\t\trelease: () => {},\n\t});\n\treturn wrapped;\n}\n\n/**\n * The transactions one test has opened, by database.\n *\n * `get` opens a database's transaction the first time it is asked for and\n * hands back the same one after that — including to a caller that asks while\n * it is still opening. `rollbackAll` ends every one of them.\n */\nexport class TransactionRegistry<TKey = string> {\n\tprivate readonly open = new Map<TKey, Promise<BoundTransaction>>();\n\n\tget(key: TKey, url: string): Promise<Kysely<any>> {\n\t\tlet transaction = this.open.get(key);\n\t\tif (!transaction) {\n\t\t\ttransaction = openBoundTransaction(url);\n\t\t\tthis.open.set(key, transaction);\n\t\t}\n\t\treturn transaction.then(({ db }) => db);\n\t}\n\n\tasync rollbackAll(): Promise<void> {\n\t\tconst transactions = [...this.open.values()];\n\t\tthis.open.clear();\n\n\t\tconst results = await Promise.allSettled(\n\t\t\ttransactions.map(async (transaction) => (await transaction).rollback()),\n\t\t);\n\t\tconst failed = results.find(\n\t\t\t(result): result is PromiseRejectedResult => result.status === 'rejected',\n\t\t);\n\t\tif (failed) throw failed.reason;\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,iBAAiB,KAA+B;CAC/D,MAAM,SAAS,IAAI,IAAI,GAAG;CAC1B,MAAM,aAAa,OAAO,aAAa,IAAI,aAAa;CACxD,IAAI,CAAC,YAAY,OAAO,EAAE,kBAAkB,IAAI;CAEhD,OAAO,aAAa,OAAO,aAAa;CACxC,OAAO;EACN,kBAAkB,OAAO,SAAS;EAClC,SAAS,kBAAkB;CAC5B;AACD;;AAWA,eAAsB,qBACrB,KAC4B;CAC5B,MAAM,SAAS,IAAI,GAAA,QAAG,OAAO,iBAAiB,GAAG,CAAC;CAClD,MAAM,OAAO,QAAQ;CACrB,MAAM,OAAO,MAAM,OAAO;CAE1B,OAAO;EACN,IAAI,IAAIA,OAAAA,OAAO,EACd,SAAS,IAAIC,OAAAA,gBAAgB,EAG5B,MAAM;GACL,SAAS,YAAY,aAAa,MAAM;GACxC,KAAK,YAAY,CAAC;EACnB,EACD,CAAC,EACF,CAAC;EACD,MAAM,WAAW;GAChB,IAAI;IACH,MAAM,OAAO,MAAM,UAAU;GAC9B,UAAU;IACT,MAAM,OAAO,IAAI;GAClB;EACD;CACD;AACD;;;;;;;;AASA,SAAS,aAAa,QAAkC;CACvD,IAAI,QAAQ;CACZ,MAAM,QAAQ,OAAO,MAAM,KAAK,MAAM;CAEtC,MAAM,UAAU,OAAO,OAAO,MAAM;CACpC,OAAO,OAAO,SAAS;EACtB,QAAQ,MAAe,GAAG,SAAoB;GAC7C,MAAM,YACL,OAAO,SAAS,WAAW,KAAK,KAAK,CAAC,CAAC,YAAY,IAAI,KAAA;GAExD,IAAI,cAAc,WAAW,WAAW,WAAW,mBAAmB,GAAG;IACxE;IACA,OAAO,MAAM,qBAAqB,OAAO;GAC1C;GACA,IAAI,cAAc,UACjB,OAAO,MAAM,6BAA6B,SAAS;GAEpD,IAAI,cAAc,YACjB,OAAO,MAAM,iCAAiC,SAAS;GAExD,OAAO,MAAM,MAAM,GAAG,IAAI;EAC3B;EACA,eAAe,CAAC;CACjB,CAAC;CACD,OAAO;AACR;;;;;;;;AASA,IAAa,sBAAb,MAAgD;CAC/C,uBAAwB,IAAI,IAAqC;CAEjE,IAAI,KAAW,KAAmC;EACjD,IAAI,cAAc,KAAK,KAAK,IAAI,GAAG;EACnC,IAAI,CAAC,aAAa;GACjB,cAAc,qBAAqB,GAAG;GACtC,KAAK,KAAK,IAAI,KAAK,WAAW;EAC/B;EACA,OAAO,YAAY,MAAM,EAAE,SAAS,EAAE;CACvC;CAEA,MAAM,cAA6B;EAClC,MAAM,eAAe,CAAC,GAAG,KAAK,KAAK,OAAO,CAAC;EAC3C,KAAK,KAAK,MAAM;EAKhB,MAAM,UAAS,MAHO,QAAQ,WAC7B,aAAa,IAAI,OAAO,iBAAiB,MAAM,YAAA,CAAa,SAAS,CAAC,CACvE,EAAA,CACuB,MACrB,WAA4C,OAAO,WAAW,UAChE;EACA,IAAI,QAAQ,MAAM,OAAO;CAC1B;AACD"}

package/dist/transactions.d.cts

@@ -0,0 +1,38 @@
+import { Kysely } from "kysely";
+//#region src/transactions.d.ts
+/** How to reach one database: a URL, and its search path as a startup option. */
+export interface ConnectionConfig {
+  connectionString: string;
+  options?: string;
+}
+/**
+ * The connection settings for a database URL.
+ *
+ * `?search_path=` is not a libpq parameter: a URL carrying it connects and then
+ * resolves every name against `public`. Postgres takes it as a startup option,
+ * which is what a schema tenant's URL needs to reach its own tables.
+ */
+export declare function connectionConfig(url: string): ConnectionConfig;
+/** One database's connection, inside a transaction the test will roll back. */
+export interface BoundTransaction {
+  /** Everything queried through this runs inside the test's transaction. */
+  readonly db: Kysely<any>;
+  /** Undo everything, and let the connection go. */
+  rollback(): Promise<void>;
+}
+/** Open a connection to `url` and begin the transaction a test will roll back. */
+export declare function openBoundTransaction(url: string): Promise<BoundTransaction>;
+/**
+ * The transactions one test has opened, by database.
+ *
+ * `get` opens a database's transaction the first time it is asked for and
+ * hands back the same one after that — including to a caller that asks while
+ * it is still opening. `rollbackAll` ends every one of them.
+ */
+export declare class TransactionRegistry<TKey = string> {
+  private readonly open;
+  get(key: TKey, url: string): Promise<Kysely<any>>;
+  rollbackAll(): Promise<void>;
+}
+//#endregion
+//# sourceMappingURL=transactions.d.cts.map