@btst/stack 1.0.1 → 1.1.1

package/src/types.ts

@@ -0,0 +1,209 @@
+import type { Route, createRouter } from "@btst/yar";
+import type { Adapter, DatabaseDefinition, DbPlugin } from "@btst/db";
+import type { Endpoint, Router } from "better-call";
+
+/**
+ * Backend plugin definition
+ * Defines API routes and data access for a feature
+ *
+ * Note: Each plugin defines its own schema using createDbPlugin().
+ * Better Stack composes all plugin schemas together at runtime using Better DB's .use() method.
+ * You can optionally provide a base schema via the dbSchema config option.
+ *
+ * @template TRoutes - The exact shape of routes this plugin provides (preserves keys and endpoint types)
+ */
+export interface BackendPlugin<
+	TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>,
+> {
+	name: string;
+
+	/**
+	 * Create API endpoints for this plugin
+	 * Returns an object with named endpoints that will be composed into the router
+	 *
+	 * @param adapter - Better DB adapter instance with methods:
+	 *   create, update, updateMany, delete, deleteMany, findOne, findMany, count
+	 */
+	routes: (adapter: Adapter) => TRoutes;
+	dbPlugin: DbPlugin;
+}
+
+/**
+ * Frontend plugin definition
+ * Defines pages, components, loaders, and React Query hooks for a feature
+ *
+ * @template TOverrides - The shape of overridable components/functions this plugin requires
+ * Example: { Link: ComponentType<{href: string}>, navigate: (path: string) => void }
+ * @template TRoutes - The exact shape of routes this plugin provides (preserves keys and route types)
+ */
+export interface ClientPlugin<
+	TOverrides = Record<string, never>,
+	TRoutes extends Record<string, Route> = Record<string, Route>,
+> {
+	name: string;
+
+	/**
+	 * Define routes (pages) for this plugin
+	 * Returns yar routes that will be composed into the router
+	 */
+	routes: () => TRoutes;
+
+	/**
+	 * Optional sitemap generator for this plugin. Should return absolute URLs.
+	 * Implementations can call their own API endpoints to include dynamic routes.
+	 */
+	sitemap?: () => Promise<Sitemap> | Sitemap;
+}
+
+/**
+ * Configuration for creating the backend library
+ */
+export interface BackendLibConfig<
+	TPlugins extends Record<string, BackendPlugin<any>> = Record<
+		string,
+		BackendPlugin<any>
+	>,
+> {
+	basePath: string;
+	dbSchema?: DatabaseDefinition;
+	plugins: TPlugins;
+	adapter: (db: DatabaseDefinition) => Adapter;
+}
+
+/**
+ * Configuration for creating the client library
+ */
+export interface ClientLibConfig<
+	TPlugins extends Record<string, ClientPlugin<any, any>> = Record<
+		string,
+		ClientPlugin<any, any>
+	>,
+> {
+	plugins: TPlugins;
+	baseURL?: string;
+	basePath?: string;
+}
+
+/**
+ * Utility type to extract override types from plugins
+ * Maps plugin names to their override types
+ */
+export type InferPluginOverrides<
+	TPlugins extends Record<string, ClientPlugin<any, any>>,
+> = {
+	[K in keyof TPlugins]: TPlugins[K] extends ClientPlugin<infer TOverrides, any>
+		? TOverrides
+		: never;
+};
+
+/**
+ * Type for the pluginOverrides prop in BetterStackContext
+ * Allows partial overrides per plugin
+ */
+export type PluginOverrides<
+	TPlugins extends Record<string, ClientPlugin<any, any>>,
+> = {
+	[K in keyof TPlugins]?: Partial<InferPluginOverrides<TPlugins>[K]>;
+};
+
+/**
+ * Extract all routes from all client plugins, merging them into a single record
+ */
+export type PluginRoutes<
+	TPlugins extends Record<string, ClientPlugin<any, any>>,
+> = MergeAllPluginRoutes<TPlugins>;
+
+/**
+ * Prefix all backend plugin route keys with the plugin name
+ * Example: { messages: { list: Endpoint } } => { messages_list: Endpoint }
+ */
+export type PrefixedPluginRoutes<
+	TPlugins extends Record<string, BackendPlugin<any>>,
+> = UnionToIntersection<
+	{
+		[PluginKey in keyof TPlugins]: TPlugins[PluginKey] extends BackendPlugin<
+			infer TRoutes
+		>
+			? {
+					[RouteKey in keyof TRoutes as `${PluginKey & string}_${RouteKey & string}`]: TRoutes[RouteKey];
+				}
+			: never;
+	}[keyof TPlugins]
+> extends infer U
+	? U extends Record<string, Endpoint>
+		? U
+		: Record<string, Endpoint>
+	: Record<string, Endpoint>;
+
+/**
+ * Result of creating the backend library
+ */
+export interface BackendLib<
+	TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>,
+> {
+	handler: (request: Request) => Promise<Response>; // API route handler
+	router: Router; // Better-call router
+	dbSchema: DatabaseDefinition; // Better-db schema
+}
+
+/**
+ * Helper type to extract routes from a client plugin
+ */
+export type ExtractPluginRoutes<T> = T extends ClientPlugin<any, infer TRoutes>
+	? TRoutes
+	: never;
+
+/**
+ * Helper type to merge all routes from all plugins into a single record
+ */
+export type MergeAllPluginRoutes<
+	TPlugins extends Record<string, ClientPlugin<any, any>>,
+> = UnionToIntersection<
+	{
+		[K in keyof TPlugins]: ExtractPluginRoutes<TPlugins[K]>;
+	}[keyof TPlugins]
+> extends infer U
+	? U extends Record<string, Route>
+		? U
+		: Record<string, Route>
+	: Record<string, Route>;
+
+/**
+ * Utility type to convert union to intersection
+ */
+type UnionToIntersection<U> = (
+	U extends unknown
+		? (k: U) => void
+		: never
+) extends (k: infer I) => void
+	? I
+	: never;
+
+/**
+ * Result of creating the client library
+ */
+export interface ClientLib<
+	TRoutes extends Record<string, Route> = Record<string, Route>,
+> {
+	router: ReturnType<typeof createRouter<TRoutes, {}>>;
+	generateSitemap: () => Promise<Sitemap>;
+}
+
+/**
+ * Minimal sitemap entry shape aligned with Next.js MetadataRoute.Sitemap
+ */
+export type SitemapEntry = {
+	url: string; // absolute
+	lastModified?: string | Date;
+	changeFrequency?:
+		| "always"
+		| "hourly"
+		| "daily"
+		| "weekly"
+		| "monthly"
+		| "yearly"
+		| "never";
+	priority?: number;
+};
+
+export type Sitemap = Array<SitemapEntry>;

package/dist/plugins/index.cjs

@@ -1,15 +0,0 @@
-'use strict';
-
-const utils = require('../shared/stack.CktCg4PJ.cjs');
-require('better-call/client');
-
-function defineClientPlugin(plugin) {
-  return plugin;
-}
-function defineBackendPlugin(plugin) {
-  return plugin;
-}
-
-exports.createApiClient = utils.createApiClient;
-exports.defineBackendPlugin = defineBackendPlugin;
-exports.defineClientPlugin = defineClientPlugin;

package/dist/plugins/index.d.cts

@@ -1,64 +0,0 @@
-import { C as ClientPlugin, B as BackendPlugin } from '../shared/stack.DORw_1ps.cjs';
-export { I as InferPluginOverrides, c as PluginOverrides } from '../shared/stack.DORw_1ps.cjs';
-import { Endpoint } from 'better-call';
-export { Endpoint, Router } from 'better-call';
-export { c as createApiClient } from '../shared/stack.DrUAVfIH.cjs';
-export { Adapter, DatabaseDefinition, DbPlugin } from '@btst/db';
-export { Route } from '@btst/yar';
-import 'better-call/client';
-
-/**
- * Plugin utilities and types for building standalone plugins
- *
- * This module exports everything needed to create custom plugins
- * for Better Stack outside of this package.
- *
- * Note: Backend and Client plugins are separate to prevent SSR issues
- * and enable better code splitting. Import them separately:
- * - Backend: import type { BackendPlugin } from "@btst/stack/plugins"
- * - Client: import type { ClientPlugin } from "@btst/stack/plugins"
- */
-
-/**
- * Helper to define a client plugin with full type inference
- *
- * Automatically infers route keys, hook names, and their types without needing casts.
- *
- * @example
- * ```ts
- * const messagesPlugin = defineClientPlugin({
- *   name: "messages",
- *   routes: () => ({
- *     messagesList: createRoute("/messages", () => ({ ... }))
- *   }),
- *   hooks: () => ({
- *     useMessages: () => { ... }
- *   })
- * });
- * // No casts needed - route keys, hook names, and types are all preserved!
- * ```
- *
- * @template TPlugin - The exact plugin definition (auto-inferred)
- */
-declare function defineClientPlugin<TPlugin extends ClientPlugin<any, any>>(plugin: TPlugin): TPlugin;
-/**
- * Helper to define a backend plugin with full type inference
- *
- * @example
- * ```ts
- * const messagesPlugin = defineBackendPlugin({
- *   name: "messages",
- *   dbPlugin: createDbPlugin("messages", messagesSchema),
- *   routes: (adapter) => ({
- *     list: endpoint("/messages", { method: "GET" }, async () => { ... }),
- *     create: endpoint("/messages", { method: "POST" }, async () => { ... })
- *   })
- * });
- * // Route keys "list" and "create" are preserved in types!
- * ```
- *
- * @template TRoutes - The exact shape of routes (auto-inferred from routes function)
- */
-declare function defineBackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>>(plugin: BackendPlugin<TRoutes>): BackendPlugin<TRoutes>;
-
-export { BackendPlugin, ClientPlugin, defineBackendPlugin, defineClientPlugin };

package/dist/plugins/index.d.mts

@@ -1,64 +0,0 @@
-import { C as ClientPlugin, B as BackendPlugin } from '../shared/stack.DORw_1ps.mjs';
-export { I as InferPluginOverrides, c as PluginOverrides } from '../shared/stack.DORw_1ps.mjs';
-import { Endpoint } from 'better-call';
-export { Endpoint, Router } from 'better-call';
-export { c as createApiClient } from '../shared/stack.DrUAVfIH.mjs';
-export { Adapter, DatabaseDefinition, DbPlugin } from '@btst/db';
-export { Route } from '@btst/yar';
-import 'better-call/client';
-
-/**
- * Plugin utilities and types for building standalone plugins
- *
- * This module exports everything needed to create custom plugins
- * for Better Stack outside of this package.
- *
- * Note: Backend and Client plugins are separate to prevent SSR issues
- * and enable better code splitting. Import them separately:
- * - Backend: import type { BackendPlugin } from "@btst/stack/plugins"
- * - Client: import type { ClientPlugin } from "@btst/stack/plugins"
- */
-
-/**
- * Helper to define a client plugin with full type inference
- *
- * Automatically infers route keys, hook names, and their types without needing casts.
- *
- * @example
- * ```ts
- * const messagesPlugin = defineClientPlugin({
- *   name: "messages",
- *   routes: () => ({
- *     messagesList: createRoute("/messages", () => ({ ... }))
- *   }),
- *   hooks: () => ({
- *     useMessages: () => { ... }
- *   })
- * });
- * // No casts needed - route keys, hook names, and types are all preserved!
- * ```
- *
- * @template TPlugin - The exact plugin definition (auto-inferred)
- */
-declare function defineClientPlugin<TPlugin extends ClientPlugin<any, any>>(plugin: TPlugin): TPlugin;
-/**
- * Helper to define a backend plugin with full type inference
- *
- * @example
- * ```ts
- * const messagesPlugin = defineBackendPlugin({
- *   name: "messages",
- *   dbPlugin: createDbPlugin("messages", messagesSchema),
- *   routes: (adapter) => ({
- *     list: endpoint("/messages", { method: "GET" }, async () => { ... }),
- *     create: endpoint("/messages", { method: "POST" }, async () => { ... })
- *   })
- * });
- * // Route keys "list" and "create" are preserved in types!
- * ```
- *
- * @template TRoutes - The exact shape of routes (auto-inferred from routes function)
- */
-declare function defineBackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>>(plugin: BackendPlugin<TRoutes>): BackendPlugin<TRoutes>;
-
-export { BackendPlugin, ClientPlugin, defineBackendPlugin, defineClientPlugin };

package/dist/plugins/index.d.ts

@@ -1,64 +0,0 @@
-import { C as ClientPlugin, B as BackendPlugin } from '../shared/stack.DORw_1ps.js';
-export { I as InferPluginOverrides, c as PluginOverrides } from '../shared/stack.DORw_1ps.js';
-import { Endpoint } from 'better-call';
-export { Endpoint, Router } from 'better-call';
-export { c as createApiClient } from '../shared/stack.DrUAVfIH.js';
-export { Adapter, DatabaseDefinition, DbPlugin } from '@btst/db';
-export { Route } from '@btst/yar';
-import 'better-call/client';
-
-/**
- * Plugin utilities and types for building standalone plugins
- *
- * This module exports everything needed to create custom plugins
- * for Better Stack outside of this package.
- *
- * Note: Backend and Client plugins are separate to prevent SSR issues
- * and enable better code splitting. Import them separately:
- * - Backend: import type { BackendPlugin } from "@btst/stack/plugins"
- * - Client: import type { ClientPlugin } from "@btst/stack/plugins"
- */
-
-/**
- * Helper to define a client plugin with full type inference
- *
- * Automatically infers route keys, hook names, and their types without needing casts.
- *
- * @example
- * ```ts
- * const messagesPlugin = defineClientPlugin({
- *   name: "messages",
- *   routes: () => ({
- *     messagesList: createRoute("/messages", () => ({ ... }))
- *   }),
- *   hooks: () => ({
- *     useMessages: () => { ... }
- *   })
- * });
- * // No casts needed - route keys, hook names, and types are all preserved!
- * ```
- *
- * @template TPlugin - The exact plugin definition (auto-inferred)
- */
-declare function defineClientPlugin<TPlugin extends ClientPlugin<any, any>>(plugin: TPlugin): TPlugin;
-/**
- * Helper to define a backend plugin with full type inference
- *
- * @example
- * ```ts
- * const messagesPlugin = defineBackendPlugin({
- *   name: "messages",
- *   dbPlugin: createDbPlugin("messages", messagesSchema),
- *   routes: (adapter) => ({
- *     list: endpoint("/messages", { method: "GET" }, async () => { ... }),
- *     create: endpoint("/messages", { method: "POST" }, async () => { ... })
- *   })
- * });
- * // Route keys "list" and "create" are preserved in types!
- * ```
- *
- * @template TRoutes - The exact shape of routes (auto-inferred from routes function)
- */
-declare function defineBackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>>(plugin: BackendPlugin<TRoutes>): BackendPlugin<TRoutes>;
-
-export { BackendPlugin, ClientPlugin, defineBackendPlugin, defineClientPlugin };

package/dist/plugins/index.mjs

@@ -1,11 +0,0 @@
-export { c as createApiClient } from '../shared/stack.3OUyGp_E.mjs';
-import 'better-call/client';
-
-function defineClientPlugin(plugin) {
-  return plugin;
-}
-function defineBackendPlugin(plugin) {
-  return plugin;
-}
-
-export { defineBackendPlugin, defineClientPlugin };

package/dist/shared/stack.DrUAVfIH.d.cts

@@ -1,17 +0,0 @@
-import { createClient } from 'better-call/client';
-import { Router, Endpoint } from 'better-call';
-
-interface CreateApiClientOptions {
-    baseURL?: string;
-    basePath?: string;
-}
-/**
- * Creates a Better Call API client with proper URL handling for both server and client side
- * @param options - Configuration options
- * @param options.baseURL - The base URL (e.g., 'http://localhost:3000'). If not provided, uses relative URLs (same domain)
- * @param options.basePath - The API base path (defaults to '/')
- * @template TRouter - The router type (Router or Record<string, Endpoint>)
- */
-declare function createApiClient<TRouter extends Router | Record<string, Endpoint> = Record<string, Endpoint>>(options?: CreateApiClientOptions): ReturnType<typeof createClient<TRouter>>;
-
-export { createApiClient as c };

package/dist/shared/stack.DrUAVfIH.d.mts

@@ -1,17 +0,0 @@
-import { createClient } from 'better-call/client';
-import { Router, Endpoint } from 'better-call';
-
-interface CreateApiClientOptions {
-    baseURL?: string;
-    basePath?: string;
-}
-/**
- * Creates a Better Call API client with proper URL handling for both server and client side
- * @param options - Configuration options
- * @param options.baseURL - The base URL (e.g., 'http://localhost:3000'). If not provided, uses relative URLs (same domain)
- * @param options.basePath - The API base path (defaults to '/')
- * @template TRouter - The router type (Router or Record<string, Endpoint>)
- */
-declare function createApiClient<TRouter extends Router | Record<string, Endpoint> = Record<string, Endpoint>>(options?: CreateApiClientOptions): ReturnType<typeof createClient<TRouter>>;
-
-export { createApiClient as c };

package/dist/shared/stack.DrUAVfIH.d.ts

@@ -1,17 +0,0 @@
-import { createClient } from 'better-call/client';
-import { Router, Endpoint } from 'better-call';
-
-interface CreateApiClientOptions {
-    baseURL?: string;
-    basePath?: string;
-}
-/**
- * Creates a Better Call API client with proper URL handling for both server and client side
- * @param options - Configuration options
- * @param options.baseURL - The base URL (e.g., 'http://localhost:3000'). If not provided, uses relative URLs (same domain)
- * @param options.basePath - The API base path (defaults to '/')
- * @template TRouter - The router type (Router or Record<string, Endpoint>)
- */
-declare function createApiClient<TRouter extends Router | Record<string, Endpoint> = Record<string, Endpoint>>(options?: CreateApiClientOptions): ReturnType<typeof createClient<TRouter>>;
-
-export { createApiClient as c };