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

package/src/__tests__/plugins.test.tsx

@@ -1,9 +1,14 @@
 import { describe, it, expect } from "vitest";
-import { stack } from "../api";
-import { createStackClient } from "../client";
+import { createBackendStack } from "../api";
+import { createClientStack } from "../client";
 import { defineBackendPlugin } from "../plugins/api";
 import { defineClientPlugin } from "../plugins/client";
-import type { BackendPlugin, ClientPlugin } from "../types";
+import type {
+	BackendPlugin,
+	ClientPlugin,
+	ClientPluginRegistration,
+	MatchingPluginRegistrations,
+} from "../types";
 import type {
 	BetterAuthDBSchema,
 	DatabaseDefinition,
@@ -14,6 +19,7 @@ import { createMemoryAdapter } from "@btst/adapter-memory";
 import { createEndpoint as endpoint } from "better-call";
 import { z } from "zod";
 import { createRoute } from "@btst/yar";
+import { QueryClient } from "@tanstack/react-query";
 
 /**
  * Adapter wrapper for testing
@@ -23,6 +29,20 @@ const testAdapter = (db: DatabaseDefinition): Adapter => {
 	return createMemoryAdapter(db)({});
 };
 
+function createThirdPartyClient<
+	const TPlugins extends Record<
+		string,
+		ClientPluginRegistration<any, any, any, any, any>
+	>,
+>(config: { plugins: TPlugins & MatchingPluginRegistrations<TPlugins> }) {
+	return createClientStack<TPlugins>({
+		api: { baseURL: "https://example.com", basePath: "/api" },
+		site: { baseURL: "https://example.com", basePath: "/pages" },
+		queryClient: new QueryClient(),
+		...config,
+	});
+}
+
 /**
  * Test schema for messages plugin
  * Using BetterAuthDBSchema format
@@ -58,7 +78,7 @@ const messagesSchema: BetterAuthDBSchema = {
  * Now using defineBackendPlugin for full type inference - no casts needed!
  */
 const messagesBackendPlugin = defineBackendPlugin({
-	name: "messages",
+	id: "messages",
 	dbPlugin: createDbPlugin("messages", messagesSchema),
 	routes: (adapter) => ({
 		list: endpoint(
@@ -152,23 +172,29 @@ const messageDetailLoader = async ({ params }: { params: { id: string } }) => {
  * Using Yar's createRoute() to create proper route handlers.
  */
 const messagesClientPlugin = defineClientPlugin({
-	name: "messages",
-	routes: () => ({
-		messagesList: createRoute("/messages", () => ({
-			PageComponent: MessagesListComponent,
-			loader: messagesListLoader,
-		})),
-		messageDetail: createRoute("/messages/:id", ({ params }) => ({
-			PageComponent: MessageDetailComponent,
-			loader: () => messageDetailLoader({ params }),
-		})),
+	id: "messages",
+	resolve: () => ({
+		routes: () => ({
+			messagesList: createRoute("/messages", () => ({
+				PageComponent: MessagesListComponent,
+				loader: messagesListLoader,
+			})),
+			messageDetail: createRoute("/messages/:id", ({ params }) => ({
+				PageComponent: MessageDetailComponent,
+				loader: () => messageDetailLoader({ params }),
+			})),
+		}),
 	}),
 });
+const resolvedMessagesClientPlugin = {
+	...messagesClientPlugin.resolve({} as never),
+	id: "messages" as const,
+};
 
 describe("3rd Party Plugin Support", () => {
 	describe("Backend Plugin", () => {
 		it("should create backend with custom plugin", () => {
-			const backend = stack({
+			const backend = createBackendStack({
 				basePath: "/api",
 				plugins: {
 					messages: messagesBackendPlugin,
@@ -202,7 +228,7 @@ describe("3rd Party Plugin Support", () => {
 			};
 
 			const notificationsPlugin = defineBackendPlugin({
-				name: "notifications",
+				id: "notifications",
 				dbPlugin: createDbPlugin("notifications", notificationsSchema),
 				routes: (adapter) => ({
 					list: endpoint(
@@ -223,7 +249,7 @@ describe("3rd Party Plugin Support", () => {
 				}),
 			});
 
-			const backend = stack({
+			const backend = createBackendStack({
 				basePath: "/api",
 				plugins: {
 					messages: messagesBackendPlugin,
@@ -237,7 +263,7 @@ describe("3rd Party Plugin Support", () => {
 		});
 
 		it("should generate routes for custom plugin", () => {
-			const backend = stack({
+			const backend = createBackendStack({
 				basePath: "/api",
 				plugins: {
 					messages: messagesBackendPlugin,
@@ -246,13 +272,13 @@ describe("3rd Party Plugin Support", () => {
 			});
 
 			// Check that routes are properly registered
-			// The router should have routes prefixed with plugin name
+			// The router should have routes prefixed with the plugin ID.
 			expect(backend.router).toBeDefined();
 			expect(typeof backend.router.handler).toBe("function");
 		});
 
 		it("should include plugin schema in database", () => {
-			const backend = stack({
+			const backend = createBackendStack({
 				basePath: "/api",
 				plugins: {
 					messages: messagesBackendPlugin,
@@ -269,7 +295,7 @@ describe("3rd Party Plugin Support", () => {
 
 	describe("Client Plugin", () => {
 		it("should create client with custom plugin", () => {
-			const client = createStackClient({
+			const client = createThirdPartyClient({
 				plugins: {
 					messages: messagesClientPlugin,
 				},
@@ -280,7 +306,7 @@ describe("3rd Party Plugin Support", () => {
 		});
 
 		it("should have routes from custom plugin", () => {
-			const client = createStackClient({
+			const client = createThirdPartyClient({
 				plugins: {
 					messages: messagesClientPlugin,
 				},
@@ -293,7 +319,7 @@ describe("3rd Party Plugin Support", () => {
 
 		it("should return correct route shape with Component and loader", async () => {
 			// Test the route object directly from the plugin - types are now preserved!
-			const routes = messagesClientPlugin.routes();
+			const routes = resolvedMessagesClientPlugin.routes();
 			const listRoute = routes.messagesList;
 
 			expect(listRoute).toBeDefined();
@@ -321,7 +347,7 @@ describe("3rd Party Plugin Support", () => {
 
 		it("should return correct route shape with params", async () => {
 			// Test the route object directly from the plugin - types are now preserved!
-			const routes = messagesClientPlugin.routes();
+			const routes = resolvedMessagesClientPlugin.routes();
 			const detailRoute = routes.messageDetail;
 
 			expect(detailRoute).toBeDefined();
@@ -345,7 +371,7 @@ describe("3rd Party Plugin Support", () => {
 		});
 
 		it("should have all expected routes defined", () => {
-			const routes = messagesClientPlugin.routes();
+			const routes = resolvedMessagesClientPlugin.routes();
 
 			// Verify all expected routes exist - types are fully inferred!
 			expect(routes.messagesList).toBeDefined();
@@ -358,7 +384,7 @@ describe("3rd Party Plugin Support", () => {
 
 		it("should maintain type safety across route definitions", async () => {
 			// This test verifies that TypeScript types are preserved
-			const routes = messagesClientPlugin.routes();
+			const routes = resolvedMessagesClientPlugin.routes();
 			const route = routes.messagesList;
 
 			// Route should be a function (Yar's handler)
@@ -388,16 +414,20 @@ describe("3rd Party Plugin Support", () => {
 			};
 
 			const notificationsClientPlugin = defineClientPlugin({
-				name: "notifications",
-				routes: () => ({
-					notificationsList: createRoute("/notifications", () => ({
-						PageComponent: NotificationsComponent,
-						loader: notificationsLoader,
-					})),
+				id: "notifications",
+				resolve: () => ({
+					routes: () => ({
+						notificationsList: createRoute("/notifications", () => ({
+							PageComponent: NotificationsComponent,
+							loader: notificationsLoader,
+						})),
+					}),
 				}),
 			});
+			const resolvedNotificationsClientPlugin =
+				notificationsClientPlugin.resolve({} as never);
 
-			const client = createStackClient({
+			const client = createThirdPartyClient({
 				plugins: {
 					messages: messagesClientPlugin,
 					notifications: notificationsClientPlugin,
@@ -408,8 +438,8 @@ describe("3rd Party Plugin Support", () => {
 			expect(client.router).toBeDefined();
 
 			// Verify both plugin routes are accessible from their definitions - full type safety!
-			const messagesRoutes = messagesClientPlugin.routes();
-			const notificationsRoutes = notificationsClientPlugin.routes();
+			const messagesRoutes = resolvedMessagesClientPlugin.routes();
+			const notificationsRoutes = resolvedNotificationsClientPlugin.routes();
 
 			expect(messagesRoutes.messagesList).toBeDefined();
 			expect(typeof messagesRoutes.messagesList).toBe("function");
@@ -425,7 +455,7 @@ describe("3rd Party Plugin Support", () => {
 		it("should use backend and client plugins independently", () => {
 			// Backend and client plugins are completely separate
 			// This prevents SSR issues and enables better code splitting
-			const backend = stack({
+			const backend = createBackendStack({
 				basePath: "/api",
 				plugins: {
 					messages: messagesBackendPlugin,
@@ -433,7 +463,7 @@ describe("3rd Party Plugin Support", () => {
 				adapter: testAdapter,
 			});
 
-			const client = createStackClient({
+			const client = createThirdPartyClient({
 				plugins: {
 					messages: messagesClientPlugin,
 				},
@@ -447,7 +477,7 @@ describe("3rd Party Plugin Support", () => {
 			// This test mimics the actual usage pattern in a Next.js app
 			// Uses router.getRoute() to match paths and get route handlers
 
-			const client = createStackClient({
+			const client = createThirdPartyClient({
 				plugins: {
 					messages: messagesClientPlugin,
 				},
@@ -494,7 +524,7 @@ describe("3rd Party Plugin Support", () => {
 
 		it("should handle parameterized routes correctly", async () => {
 			// Test that router.getRoute() correctly extracts path parameters
-			const client = createStackClient({
+			const client = createThirdPartyClient({
 				plugins: {
 					messages: messagesClientPlugin,
 				},
@@ -534,10 +564,10 @@ describe("3rd Party Plugin Support", () => {
 		it("should export all necessary types for building plugins", () => {
 			// This test verifies the types are available at compile time
 			const backendPlugin: BackendPlugin = messagesBackendPlugin;
-			const clientPlugin: ClientPlugin = messagesClientPlugin;
+			const clientPlugin: ClientPlugin = resolvedMessagesClientPlugin;
 
-			expect(backendPlugin.name).toBe("messages");
-			expect(clientPlugin.name).toBe("messages");
+			expect(backendPlugin.id).toBe("messages");
+			expect(clientPlugin.id).toBe("messages");
 		});
 	});
 });

package/src/__tests__/resource-factory.test.tsx

@@ -3,9 +3,11 @@ import { act, Suspense } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createClientStack } from "../client";
 import { StackProvider } from "../context";
 import {
 	createResourceQueryKeys,
+	defineClientPlugin,
 	runResourceMutation,
 	type ResourcesDeclaration,
 	type StackError,
@@ -333,11 +335,21 @@ describe("createResource hooks", () => {
 	}
 
 	async function render(ui: React.ReactElement) {
+		const stack = createClientStack({
+			api: { baseURL: "http://test.local", basePath: "/api/data" },
+			site: { baseURL: "http://test.local", basePath: "/pages" },
+			queryClient,
+			plugins: {
+				"test-plugin": defineClientPlugin<{ headers?: HeadersInit }>()({
+					id: "test-plugin",
+					resolve: () => ({ routes: () => ({}) }),
+				}),
+			},
+		});
 		await act(async () => {
 			root.render(
 				<StackProvider
-					basePath="/pages"
-					api={{ baseURL: "http://test.local", basePath: "/api/data" }}
+					stack={stack}
 					router={{ refresh }}
 					overrides={{
 						"test-plugin": {
@@ -382,6 +394,71 @@ describe("createResource hooks", () => {
 		expect(url).toContain("id=1");
 	});
 
+	it("resolves a resource through its registration-bound provider runtime", async () => {
+		fetchMock.mockResolvedValueOnce(
+			jsonResponse({ items: [{ id: "1", name: "canonical" }] }),
+		);
+		fetchMock.mockResolvedValueOnce(jsonResponse({ id: "2", name: "created" }));
+		let canonicalItems!: typeof items;
+		const stack = createClientStack({
+			api: { baseURL: "http://test.local", basePath: "/api/data" },
+			site: { baseURL: "http://test.local", basePath: "/pages" },
+			queryClient,
+			plugins: {
+				canonicalProbe: defineClientPlugin({
+					id: "canonicalProbe",
+					resolve: (runtime) => {
+						canonicalItems = createResource({
+							plugin: runtime.id,
+							resources,
+						});
+						return { routes: () => ({}) };
+					},
+				}),
+			},
+			endpoints: {
+				canonicalProbe: {
+					api: {
+						basePath: "/api/canonical",
+						browserHeaders: { "x-canonical": "bound" },
+						credentials: "include",
+					},
+				},
+			},
+		});
+
+		let captured: any;
+		let create: any;
+		function Probe() {
+			captured = canonicalItems.items.detail.use(["1"]);
+			create = canonicalItems.items.create.use();
+			return null;
+		}
+		await act(async () => {
+			root.render(
+				<StackProvider stack={stack} router={{ refresh }}>
+					<Probe />
+				</StackProvider>,
+			);
+		});
+		await waitFor(() => captured.isSuccess);
+		await act(async () => {
+			await create.mutateAsync({ name: "created" });
+		});
+
+		expect(captured.data).toEqual({ id: "1", name: "canonical" });
+		expect(
+			stack.provider.queryClient.getQueryData(["items", "detail", "2"]),
+		).toEqual({ id: "2", name: "created" });
+		const [requestUrl, requestInit] = fetchMock.mock.calls[0] ?? [];
+		const init = requestInit as RequestInit | undefined;
+		expect(String(requestUrl)).toContain(
+			"http://test.local/api/canonical/items",
+		);
+		expect(new Headers(init?.headers).get("x-canonical")).toBe("bound");
+		expect(init?.credentials).toBe("include");
+	});
+
 	it("use() respects the enabled option", async () => {
 		let captured: any;
 		function Probe() {

package/src/__tests__/resource-use-form.test.tsx

@@ -7,6 +7,7 @@ import { StackProvider } from "../context";
 import type { ResourcesDeclaration } from "../plugins/client";
 import { createResource } from "../plugins/client/hooks";
 import type { ResourceFormResult } from "../plugins/client/hooks";
+import { createEmptyTestClientStack } from "./client-stack-test-utils";
 
 (globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -106,8 +107,7 @@ describe("resource useForm", () => {
 		await act(async () => {
 			root.render(
 				<StackProvider
-					basePath="/pages"
-					api={{ baseURL: "http://test.local", basePath: "/api/data" }}
+					stack={createEmptyTestClientStack(queryClient)}
 					router={{ navigate, refresh }}
 					notify={{ success: notifySuccess, error: notifyError }}
 				>

package/src/__tests__/resource-use-select.test.tsx

@@ -7,6 +7,7 @@ import { StackProvider } from "../context";
 import type { ResourcesDeclaration } from "../plugins/client";
 import { createResource } from "../plugins/client/hooks";
 import type { ResourceSelectResult } from "../plugins/client/hooks";
+import { createEmptyTestClientStack } from "./client-stack-test-utils";
 
 (globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -97,10 +98,7 @@ describe("resource useSelect", () => {
 		}
 		await act(async () => {
 			root.render(
-				<StackProvider
-					basePath="/pages"
-					api={{ baseURL: "http://test.local", basePath: "/api/data" }}
-				>
+				<StackProvider stack={createEmptyTestClientStack(queryClient)}>
 					<QueryClientProvider client={queryClient}>
 						<Probe />
 					</QueryClientProvider>

package/src/__tests__/router-overrides.test.tsx

@@ -1,8 +1,11 @@
 import { describe, expect, it } from "vitest";
 import { renderToString } from "react-dom/server";
 import type { ComponentType } from "react";
+import { QueryClient } from "@tanstack/react-query";
+import { createClientStack } from "../client";
 import { StackProvider, usePluginOverrides, useStack } from "../context";
 import type { StackApiConfig, StackRouterConfig } from "../context";
+import { defineClientPlugin } from "../plugins/client";
 
 function resolveProvider({
 	pluginName,
@@ -12,7 +15,7 @@ function resolveProvider({
 	defaultValues,
 }: {
 	pluginName: string;
-	overrides?: Record<string, any>;
+	overrides?: { blog?: Record<string, any> };
 	router?: StackRouterConfig;
 	api?: StackApiConfig;
 	defaultValues?: Record<string, any>;
@@ -26,14 +29,23 @@ function resolveProvider({
 		};
 		return null;
 	}
+	const stack = createClientStack({
+		api: {
+			baseURL: api?.baseURL ?? "https://example.com",
+			basePath: api?.basePath ?? "/api/data",
+		},
+		site: { baseURL: "https://example.com", basePath: "/pages" },
+		queryClient: new QueryClient(),
+		plugins: {
+			blog: defineClientPlugin<Record<string, any>>()({
+				id: "blog",
+				resolve: () => ({ routes: () => ({}) }),
+			}),
+		},
+	});
 
 	renderToString(
-		<StackProvider
-			basePath="/pages"
-			overrides={overrides}
-			router={router}
-			api={api}
-		>
+		<StackProvider stack={stack} overrides={overrides} router={router}>
 			<Probe />
 		</StackProvider>,
 	);
@@ -78,7 +90,7 @@ describe("top-level router/api context", () => {
 			navigate,
 			refresh,
 		});
-		expect(resolved.stack.api).toBe(api);
+		expect(resolved.stack.api).toEqual(api);
 		expect(resolved.overrides).toEqual({});
 	});
 

package/src/__tests__/sitemap.test.ts

@@ -1,35 +1,49 @@
 import { describe, it, expect } from "vitest";
-import { createStackClient } from "../client";
+import { createClientStack } from "../client";
 import { defineClientPlugin } from "../plugins/client";
 import { createRoute } from "@btst/yar";
+import { QueryClient } from "@tanstack/react-query";
+
+function createStack(
+	plugins: Parameters<typeof createClientStack>[0]["plugins"],
+) {
+	return createClientStack({
+		api: { baseURL: "https://example.com", basePath: "/api" },
+		site: { baseURL: "https://example.com", basePath: "/pages" },
+		queryClient: new QueryClient(),
+		plugins,
+	});
+}
 
 describe("Client sitemap generation", () => {
 	it("aggregates sitemaps from multiple plugins and de-duplicates by URL", async () => {
 		const pluginA = defineClientPlugin({
-			name: "a",
-			routes: () => ({
-				a: createRoute("/a", () => ({ PageComponent: () => null })),
+			id: "a",
+			resolve: () => ({
+				routes: () => ({
+					a: createRoute("/a", () => ({ PageComponent: () => null })),
+				}),
+				sitemap: () => [
+					{ url: "https://example.com/a", priority: 0.8 },
+					{ url: "https://example.com/b", changeFrequency: "weekly" },
+				],
 			}),
-			sitemap: () => [
-				{ url: "https://example.com/a", priority: 0.8 },
-				{ url: "https://example.com/b", changeFrequency: "weekly" },
-			],
 		});
 
 		const pluginB = defineClientPlugin({
-			name: "b",
-			routes: () => ({
-				b: createRoute("/b", () => ({ PageComponent: () => null })),
+			id: "b",
+			resolve: () => ({
+				routes: () => ({
+					b: createRoute("/b", () => ({ PageComponent: () => null })),
+				}),
+				sitemap: async () => [
+					{ url: "https://example.com/b", priority: 0.5 }, // duplicate
+					{ url: "https://example.com/c", changeFrequency: "monthly" },
+				],
 			}),
-			sitemap: async () => [
-				{ url: "https://example.com/b", priority: 0.5 }, // duplicate
-				{ url: "https://example.com/c", changeFrequency: "monthly" },
-			],
 		});
 
-		const client = createStackClient({
-			plugins: { a: pluginA, b: pluginB },
-		});
+		const client = createStack({ a: pluginA, b: pluginB });
 
 		const entries = await client.generateSitemap();
 		const urls = entries.map((e) => e.url).sort();
@@ -47,13 +61,15 @@ describe("Client sitemap generation", () => {
 
 	it("returns empty array when no plugins provide a sitemap", async () => {
 		const noop = defineClientPlugin({
-			name: "noop",
-			routes: () => ({
-				home: createRoute("/", () => ({ PageComponent: () => null })),
+			id: "noop",
+			resolve: () => ({
+				routes: () => ({
+					home: createRoute("/", () => ({ PageComponent: () => null })),
+				}),
 			}),
 		});
 
-		const client = createStackClient({ plugins: { noop } });
+		const client = createStack({ noop });
 		const entries = await client.generateSitemap();
 		expect(entries).toEqual([]);
 	});