@btst/stack 3.0.0-rc.1 → 3.0.0-rc.3

package/src/__tests__/package-metadata.test.ts

@@ -0,0 +1,315 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { promisify } from "node:util";
+import { createMemoryAdapter } from "@btst/adapter-memory";
+import type { DatabaseDefinition } from "@btst/db";
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+const execFileAsync = promisify(execFile);
+
+describe("published dependency alignment", () => {
+	it("uses the Better DB release that shares the Better Auth 1.6.16 cohort", async () => {
+		const manifest = JSON.parse(
+			await readFile(resolve("package.json"), "utf8"),
+		) as {
+			dependencies?: Record<string, string>;
+			devDependencies?: Record<string, string>;
+			peerDependencies?: Record<string, string>;
+		};
+
+		expect(manifest.dependencies?.["@btst/db"]).toBe("2.2.3");
+		expect(manifest.devDependencies?.["@btst/adapter-memory"]).toBe("2.2.3");
+		expect(manifest.devDependencies?.["@btst/yar"]).toBe("1.3.2");
+		expect(manifest.peerDependencies?.["@btst/yar"]).toBe(">=1.3.2");
+		expect(manifest.peerDependencies?.["better-call"]).toBe("1.3.6");
+	});
+});
+
+describe("published canonical stack constructors", () => {
+	it("exposes only canonical names through ESM, CJS, declarations and typesVersions", async () => {
+		const manifest = JSON.parse(
+			await readFile(resolve("package.json"), "utf8"),
+		) as {
+			exports?: Record<string, unknown>;
+			typesVersions?: Record<string, Record<string, string[]>>;
+		};
+		expect(manifest.exports).toHaveProperty("./api");
+		expect(manifest.exports).toHaveProperty("./client");
+		expect(manifest.exports).toHaveProperty("./client/hooks");
+		expect(manifest.typesVersions?.["*"]?.api).toEqual([
+			"./dist/api/index.d.ts",
+		]);
+		expect(manifest.typesVersions?.["*"]?.client).toEqual([
+			"./dist/client/index.d.ts",
+		]);
+		expect(manifest.typesVersions?.["*"]?.["client/hooks"]).toEqual([
+			"./dist/client/hooks/index.d.ts",
+		]);
+
+		const apiDeclaration = await readFile(
+			resolve("dist/api/index.d.ts"),
+			"utf8",
+		);
+		const clientDeclaration = await readFile(
+			resolve("dist/client/index.d.ts"),
+			"utf8",
+		);
+		const apiCjsDeclaration = await readFile(
+			resolve("dist/api/index.d.cts"),
+			"utf8",
+		);
+		const clientCjsDeclaration = await readFile(
+			resolve("dist/client/index.d.cts"),
+			"utf8",
+		);
+		const clientEsm = await readFile(resolve("dist/client/index.mjs"), "utf8");
+		const clientCjs = await readFile(resolve("dist/client/index.cjs"), "utf8");
+		const pluginClientEsm = await readFile(
+			resolve("dist/plugins/client/index.mjs"),
+			"utf8",
+		);
+		const pluginClientCjs = await readFile(
+			resolve("dist/plugins/client/index.cjs"),
+			"utf8",
+		);
+		for (const serverSafeClientEntry of [
+			clientEsm,
+			clientCjs,
+			pluginClientEsm,
+			pluginClientCjs,
+		]) {
+			expect(serverSafeClientEntry).not.toContain("hooks/use-list-state");
+			expect(serverSafeClientEntry).not.toMatch(/from ['\"]react['\"]/);
+			expect(serverSafeClientEntry).not.toContain('require("react")');
+		}
+		for (const declaration of [apiDeclaration, apiCjsDeclaration]) {
+			expect(declaration).toContain("function createBackendStack");
+			expect(declaration).toContain("BackendStackConfig");
+			expect(declaration).toContain("BackendStack<");
+			expect(declaration).not.toContain("const stack:");
+			expect(declaration).not.toContain("BackendLib");
+		}
+		for (const declaration of [clientDeclaration, clientCjsDeclaration]) {
+			expect(declaration).toContain("function createClientStack");
+			expect(declaration).toContain("ClientStackConfig");
+			expect(declaration).toContain("ClientStack<");
+			expect(declaration).not.toContain("createStackClient");
+			expect(declaration).not.toContain("ClientLib");
+		}
+
+		const apiSpecifier = "@btst/stack/api";
+		const clientSpecifier = "@btst/stack/client";
+		const clientHooksSpecifier = "@btst/stack/client/hooks";
+		const esmApi = await import(apiSpecifier);
+		const esmClient = await import(clientSpecifier);
+		const esmClientHooks = await import(clientHooksSpecifier);
+		const require = createRequire(import.meta.url);
+		const cjsApi = require(apiSpecifier);
+		const cjsClient = require(clientSpecifier);
+		const cjsClientHooks = require(clientHooksSpecifier);
+
+		expect(esmApi.createBackendStack).toBeTypeOf("function");
+		expect(esmClient.createClientStack).toBeTypeOf("function");
+		expect(cjsApi.createBackendStack).toBeTypeOf("function");
+		expect(cjsClient.createClientStack).toBeTypeOf("function");
+		expect("stack" in esmApi).toBe(false);
+		expect("createStackClient" in esmClient).toBe(false);
+		expect("stack" in cjsApi).toBe(false);
+		expect("createStackClient" in cjsClient).toBe(false);
+		expect(esmClient.useListState).toBeUndefined();
+		expect(cjsClient.useListState).toBeUndefined();
+		expect(esmClientHooks.useListState).toBeTypeOf("function");
+		expect(cjsClientHooks.useListState).toBeTypeOf("function");
+
+		await execFileAsync(
+			process.execPath,
+			[
+				require.resolve("typescript/lib/tsc.js"),
+				"--project",
+				"consumer-tests/constructor-exports/tsconfig.json",
+			],
+			{ cwd: resolve(".") },
+		);
+		await execFileAsync(
+			process.execPath,
+			[
+				require.resolve("typescript/lib/tsc.js"),
+				"--project",
+				"consumer-tests/constructor-exports/tsconfig.cjs.json",
+			],
+			{ cwd: resolve(".") },
+		);
+	}, 30_000);
+
+	it("preserves prototype-like canonical IDs across public backend surfaces", async () => {
+		const apiSpecifier = "@btst/stack/api";
+		const pluginApiSpecifier = "@btst/stack/plugins/api";
+		const authorizationSpecifier = "@btst/stack/authorization";
+		const [{ createBackendStack }, pluginApi, authorization] =
+			await Promise.all([
+				import(apiSpecifier),
+				import(pluginApiSpecifier),
+				import(authorizationSpecifier),
+			]);
+		const permissions = authorization.definePermissions("prototype-id", {
+			echo: authorization.permission(),
+		});
+		const echo = pluginApi.defineOperation({
+			access: "public",
+			input: z.object({ value: z.string() }),
+			permission: permissions.echo,
+			facts: () => undefined,
+			execute: ({ input }: { input: { value: string } }) => input.value,
+		});
+		let observedContext:
+			| {
+					pluginRoutes: Record<string, Record<string, unknown>>;
+					endpointInventory?: Array<{ pluginName: string }>;
+			  }
+			| undefined;
+		let observedRouteOperations: Record<string, unknown> | undefined;
+		const prototypePlugin = pluginApi.defineBackendPlugin({
+			id: "__proto__",
+			dbPlugin: pluginApi.createDbPlugin("prototype-id-db", {}),
+			operations: () => ({ echo }),
+			infrastructureRoutes: {
+				health: {
+					access: "public",
+					rationale: "Exercises public stack composition in the package test.",
+				},
+			},
+			routes: (
+				_adapter: unknown,
+				context: typeof observedContext,
+				operations: Record<string, any>,
+			) => {
+				observedContext = context;
+				observedRouteOperations = operations;
+				return {
+					health: pluginApi.createEndpoint(
+						"/prototype-id",
+						{ method: "GET" },
+						async () => ({ ok: true }),
+					),
+				};
+			},
+			raw: () => ({ id: () => "__proto__" }),
+		});
+		const registrations: Record<string, unknown> = {
+			["__proto__"]: prototypePlugin,
+		};
+
+		const stack = createBackendStack({
+			plugins: registrations,
+			adapter: (db: DatabaseDefinition) => createMemoryAdapter(db)({}),
+		});
+		const requestApi = stack.forRequest(
+			new Request("https://app.example.com/api"),
+		).operations;
+
+		expect(Object.getPrototypeOf(stack.raw)).toBeNull();
+		expect(Object.hasOwn(stack.raw, "__proto__")).toBe(true);
+		expect(stack.raw.__proto__.id()).toBe("__proto__");
+		expect(Object.getPrototypeOf(stack.trusted)).toBeNull();
+		expect(Object.getPrototypeOf(stack.trusted.__proto__)).toBeNull();
+		expect(Object.getPrototypeOf(requestApi)).toBeNull();
+		expect(Object.getPrototypeOf(requestApi.__proto__)).toBeNull();
+		expect(Object.getPrototypeOf(observedContext?.pluginRoutes)).toBeNull();
+		expect(Object.getPrototypeOf(observedRouteOperations)).toBeNull();
+		expect(observedContext?.endpointInventory?.[0]?.pluginName).toBe(
+			"__proto__",
+		);
+		expect(stack.trusted.__proto__.echo).toBeTypeOf("function");
+		expect(requestApi.__proto__.echo).toBeTypeOf("function");
+	}, 30_000);
+});
+
+describe("published backend plugin factories", () => {
+	it("preserves all eight factory contracts through ESM, CJS and declarations", async () => {
+		const storageAdapter = {
+			type: "local" as const,
+			upload: async (_buffer: Buffer, { filename }: { filename: string }) => ({
+				url: `https://files.example/${filename}`,
+			}),
+			delete: async () => undefined,
+		};
+		const factories = [
+			{
+				specifier: "@btst/stack/plugins/ai-chat/api",
+				exportName: "aiChatBackendPlugin",
+				id: "aiChat",
+				args: [{ model: {} }],
+			},
+			{
+				specifier: "@btst/stack/plugins/blog/api",
+				exportName: "blogBackendPlugin",
+				id: "blog",
+				args: [],
+			},
+			{
+				specifier: "@btst/stack/plugins/cms/api",
+				exportName: "cmsBackendPlugin",
+				id: "cms",
+				args: [{ contentTypes: [] }],
+			},
+			{
+				specifier: "@btst/stack/plugins/comments/api",
+				exportName: "commentsBackendPlugin",
+				id: "comments",
+				args: [],
+			},
+			{
+				specifier: "@btst/stack/plugins/form-builder/api",
+				exportName: "formBuilderBackendPlugin",
+				id: "formBuilder",
+				args: [],
+			},
+			{
+				specifier: "@btst/stack/plugins/kanban/api",
+				exportName: "kanbanBackendPlugin",
+				id: "kanban",
+				args: [],
+			},
+			{
+				specifier: "@btst/stack/plugins/media/api",
+				exportName: "mediaBackendPlugin",
+				id: "media",
+				args: [{ storageAdapter }],
+			},
+			{
+				specifier: "@btst/stack/plugins/open-api/api",
+				exportName: "openApiBackendPlugin",
+				id: "openApi",
+				args: [],
+			},
+		] as const;
+		const require = createRequire(import.meta.url);
+
+		for (const factory of factories) {
+			const esm = (await import(factory.specifier)) as Record<
+				string,
+				(...args: any[]) => { id: string }
+			>;
+			const cjs = require(factory.specifier) as Record<
+				string,
+				(...args: any[]) => { id: string }
+			>;
+			expect(esm[factory.exportName]?.(...factory.args).id).toBe(factory.id);
+			expect(cjs[factory.exportName]?.(...factory.args).id).toBe(factory.id);
+		}
+
+		for (const project of [
+			"consumer-tests/backend-factories/tsconfig.json",
+			"consumer-tests/backend-factories/tsconfig.cjs.json",
+		]) {
+			await execFileAsync(
+				process.execPath,
+				[require.resolve("typescript/lib/tsc.js"), "--project", project],
+				{ cwd: resolve(".") },
+			);
+		}
+	}, 30_000);
+});

package/src/__tests__/page-component-overrides.test.tsx

@@ -1,5 +1,4 @@
 import { describe, it, expect } from "vitest";
-import { defineClientPlugin } from "../plugins/client";
 import type { ComponentType, ReactElement } from "react";
 import { defineRoute, defineRoutes } from "@btst/yar";
 
@@ -38,8 +37,8 @@ function createTestPlugin(config: {
 		detail?: ComponentType<{ params: { id: string } }>;
 	};
 }) {
-	return defineClientPlugin({
-		name: "test",
+	return {
+		id: "test",
 		routes: () =>
 			defineRoutes(
 				{
@@ -50,7 +49,7 @@ function createTestPlugin(config: {
 				},
 				{ pages: config.pageComponents },
 			),
-	});
+	};
 }
 
 describe("pageComponents overrides", () => {

package/src/__tests__/plugin-registration.test.tsx

@@ -0,0 +1,183 @@
+import { createMemoryAdapter } from "@btst/adapter-memory";
+import { defineDb } from "@btst/db";
+import { QueryClient } from "@tanstack/react-query";
+import { renderToString } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+import { createBackendStack } from "../api";
+import { createClientStack } from "../client";
+import { StackProvider, usePluginOverrides, useStack } from "../context";
+import { createDbPlugin, defineBackendPlugin } from "../plugins/api";
+import { createRoute, defineClientPlugin } from "../plugins/client";
+import { generateRouteDocsSchema } from "../plugins/route-docs/generator";
+
+function runtimeConfig<TPlugins extends Record<string, any>>(
+	plugins: TPlugins,
+) {
+	return {
+		api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+		site: { baseURL: "https://app.example.com", basePath: "/pages" },
+		queryClient: new QueryClient(),
+		plugins,
+	};
+}
+
+function identifiedClient(id: string) {
+	return defineClientPlugin({
+		id,
+		resolve: (runtime) => ({
+			routes: () => ({
+				probe: createRoute(`/${id}`, () => ({ PageComponent: () => null })),
+			}),
+			sitemap: () => [
+				{ url: `${runtime.site.baseURL}${runtime.site.basePath}/${id}` },
+			],
+		}),
+	});
+}
+
+function identifiedBackend(id: string) {
+	return defineBackendPlugin({
+		id,
+		dbPlugin: createDbPlugin(`${id}-db`, {}),
+		routes: () => ({}),
+	});
+}
+
+describe("canonical plugin registration IDs", () => {
+	it("rejects client aliases and duplicate resolved IDs before resolution", () => {
+		expect(() =>
+			createClientStack(
+				runtimeConfig({ alias: identifiedClient("actual") }) as any,
+			),
+		).toThrowError(/client.*key.*alias.*ID.*actual/i);
+
+		expect(() =>
+			createClientStack(
+				runtimeConfig({
+					first: identifiedClient("duplicate"),
+					second: identifiedClient("duplicate"),
+				}) as any,
+			),
+		).toThrowError(/client.*ID.*duplicate.*first.*second/i);
+	});
+
+	it("requires plugins to be an own client configuration property", () => {
+		const inheritedConfig = Object.assign(
+			Object.create({ plugins: { probe: identifiedClient("probe") } }),
+			{
+				api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+				site: { baseURL: "https://app.example.com", basePath: "/pages" },
+				queryClient: new QueryClient(),
+			},
+		);
+
+		expect(() => createClientStack(inheritedConfig as any)).toThrowError(
+			/plugins.*registration map/i,
+		);
+	});
+
+	it("rejects backend aliases and duplicate resolved IDs before adapter creation", () => {
+		const adapter = vi.fn(() => createMemoryAdapter(defineDb({}))({}));
+		expect(() =>
+			createBackendStack({
+				basePath: "/api/data",
+				plugins: { alias: identifiedBackend("actual") },
+				adapter,
+			} as any),
+		).toThrowError(/backend.*key.*alias.*ID.*actual/i);
+		expect(adapter).not.toHaveBeenCalled();
+
+		expect(() =>
+			createBackendStack({
+				basePath: "/api/data",
+				plugins: {
+					first: identifiedBackend("duplicate"),
+					second: identifiedBackend("duplicate"),
+				},
+				adapter,
+			} as any),
+		).toThrowError(/backend.*ID.*duplicate.*first.*second/i);
+		expect(adapter).not.toHaveBeenCalled();
+	});
+
+	it("binds provider runtime and overrides to the resolved client stack", async () => {
+		const plugin = defineClientPlugin<{ label: string }>()({
+			id: "probe",
+			resolve: (runtime) => ({
+				routes: () => ({
+					probe: createRoute("/probe", () => ({ PageComponent: () => null })),
+				}),
+				sitemap: () => [
+					{ url: `${runtime.site.baseURL}${runtime.site.basePath}/probe` },
+				],
+			}),
+		});
+		const stack = createClientStack({
+			...runtimeConfig({ probe: plugin }),
+			endpoints: { probe: { api: { basePath: "/api/probe" } } },
+		});
+		let observed:
+			| {
+					basePath: string;
+					apiBasePath?: string;
+					pluginBasePath?: string;
+					label: string;
+			  }
+			| undefined;
+
+		function Probe() {
+			const context = useStack();
+			const overrides = usePluginOverrides<{ label: string }>("probe");
+			observed = {
+				basePath: context.basePath,
+				apiBasePath: context.api?.basePath,
+				pluginBasePath: context.plugins?.probe?.api.basePath,
+				label: overrides.label,
+			};
+			return null;
+		}
+
+		renderToString(
+			<StackProvider stack={stack} overrides={{ probe: { label: "Resolved" } }}>
+				<Probe />
+			</StackProvider>,
+		);
+
+		expect(observed).toEqual({
+			basePath: "/pages",
+			apiBasePath: "/api/data",
+			pluginBasePath: "/api/probe",
+			label: "Resolved",
+		});
+		await expect(stack.generateSitemap()).resolves.toEqual([
+			{ url: "https://app.example.com/pages/probe" },
+		]);
+	});
+
+	it("uses the canonical ID in client context and route diagnostics", () => {
+		let contextPluginId: string | undefined;
+		const canonicalDefinition = defineClientPlugin({
+			id: "canonical",
+			resolve: () => ({
+				routes: (context) => {
+					contextPluginId = context?.plugins.canonical?.id;
+					return {
+						canonical: createRoute("/canonical", () => ({
+							PageComponent: () => null,
+						})),
+					};
+				},
+			}),
+		});
+
+		const stack = createClientStack(
+			runtimeConfig({ canonical: canonicalDefinition }),
+		);
+
+		expect(contextPluginId).toBe("canonical");
+		const schema = generateRouteDocsSchema(stack.context);
+		expect(schema.plugins).toMatchObject([
+			{ key: "canonical", name: "canonical" },
+		]);
+	});
+});

package/src/__tests__/plugin-registration.typecheck.tsx

@@ -0,0 +1,139 @@
+import type { DatabaseDefinition, DBAdapter } from "@btst/db";
+import { QueryClient } from "@tanstack/react-query";
+import { createBackendStack } from "../api";
+import { createClientStack } from "../client";
+import { StackProvider } from "../context";
+import {
+	createDbPlugin,
+	createEndpoint,
+	defineBackendPlugin,
+} from "../plugins/api";
+import { createRoute, defineClientPlugin } from "../plugins/client";
+
+interface ConsumerOverrides {
+	label: string;
+	format?: "short" | "long";
+}
+
+function consumerClientPlugin() {
+	return defineClientPlugin<ConsumerOverrides>()({
+		id: "consumerProbe",
+		resolve: () => ({
+			routes: () => ({
+				consumerProbe: createRoute("/consumer-probe", () => ({
+					PageComponent: () => null,
+				})),
+			}),
+		}),
+	});
+}
+
+function routeOnlyClientPlugin() {
+	return defineClientPlugin({
+		id: "routeOnly",
+		resolve: () => ({
+			routes: () => ({
+				routeOnly: createRoute("/route-only", () => ({
+					PageComponent: () => null,
+				})),
+			}),
+		}),
+	});
+}
+
+consumerClientPlugin().id satisfies "consumerProbe";
+routeOnlyClientPlugin().id satisfies "routeOnly";
+
+const queryClient = new QueryClient();
+const clientStack = createClientStack({
+	api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+	site: { baseURL: "https://app.example.com", basePath: "/pages" },
+	queryClient,
+	plugins: {
+		consumerProbe: consumerClientPlugin(),
+		routeOnly: routeOnlyClientPlugin(),
+	},
+});
+
+const routeOnlyStack = createClientStack({
+	api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+	site: { baseURL: "https://app.example.com", basePath: "/pages" },
+	queryClient,
+	plugins: { routeOnly: routeOnlyClientPlugin() },
+});
+
+<StackProvider
+	stack={clientStack}
+	router={{ navigate: () => undefined }}
+	overrides={{
+		consumerProbe: { label: "Probe", format: "short" },
+	}}
+/>;
+
+<StackProvider stack={clientStack} />;
+
+<StackProvider stack={routeOnlyStack} />;
+
+// @ts-expect-error No-override stacks do not accept activation-style empty blocks.
+<StackProvider stack={routeOnlyStack} overrides={{ routeOnly: {} }} />;
+
+<StackProvider
+	stack={clientStack}
+	overrides={{
+		consumerProbe: {
+			label: "Probe",
+			// @ts-expect-error Override values are inferred from the registered definition.
+			format: "wide",
+		},
+	}}
+/>;
+
+<StackProvider
+	stack={clientStack}
+	overrides={{
+		// @ts-expect-error Plugins without configurable fields are absent from overrides.
+		routeOnly: {},
+	}}
+/>;
+
+// @ts-expect-error Canonical providers consume API/site paths from the resolved stack.
+<StackProvider stack={clientStack} basePath="/other-pages" />;
+
+createClientStack({
+	api: { baseURL: "https://app.example.com", basePath: "/api/data" },
+	site: { baseURL: "https://app.example.com", basePath: "/pages" },
+	queryClient,
+	plugins: {
+		// @ts-expect-error Registration keys must equal a canonical client plugin ID.
+		alias: consumerClientPlugin(),
+	},
+});
+
+function consumerBackendPlugin() {
+	return defineBackendPlugin({
+		id: "consumerProbe",
+		dbPlugin: createDbPlugin("consumer-probe-db", {}),
+		routes: () => ({
+			probe: createEndpoint("/probe", { method: "GET" }, async () => ({
+				ok: true,
+			})),
+		}),
+	});
+}
+
+consumerBackendPlugin().id satisfies "consumerProbe";
+
+createBackendStack({
+	basePath: "/api/data",
+	plugins: { consumerProbe: consumerBackendPlugin() },
+	adapter: (_db: DatabaseDefinition) => null as unknown as DBAdapter,
+});
+
+createBackendStack({
+	basePath: "/api/data",
+	plugins: {
+		// @ts-expect-error Registration keys must equal a canonical backend plugin ID.
+		alias: consumerBackendPlugin(),
+	},
+	adapter: (_db: DatabaseDefinition) => null as unknown as DBAdapter,
+});