@btst/stack 1.0.0

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

@@ -0,0 +1,138 @@
+import { Route, createRouter } from '@btst/yar';
+import { Adapter, DbPlugin, DatabaseDefinition } from '@btst/db';
+import { 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)
+ */
+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;
+}
+/**
+ * Hook function type
+ * Generic function type for React hooks returned by plugins
+ */
+type HookFunction = (...args: unknown[]) => unknown;
+/**
+ * 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)
+ */
+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: Create React Query hooks for this plugin
+     * These can be used directly in components without the loader
+     */
+    hooks?: () => Record<string, HookFunction>;
+    /**
+     * Optional: Default implementations for overridable components/functions
+     * These will be used if no override is provided in BetterStackContext
+     */
+    defaultOverrides?: Partial<TOverrides>;
+}
+/**
+ * Configuration for creating the backend library
+ */
+interface BackendLibConfig<TPlugins extends Record<string, BackendPlugin<any>> = Record<string, BackendPlugin<any>>> {
+    dbSchema?: DatabaseDefinition;
+    plugins: TPlugins;
+    adapter: (db: DatabaseDefinition) => Adapter;
+}
+/**
+ * Configuration for creating the client library
+ */
+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
+ */
+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
+ */
+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
+ */
+type PluginRoutes<TPlugins extends Record<string, ClientPlugin<any, any>>> = MergeAllPluginRoutes<TPlugins>;
+/**
+ * Extract all hooks from all client plugins, organized by plugin name
+ * For plugins without hooks, the type will be an empty object
+ */
+type PluginHooks<TPlugins extends Record<string, ClientPlugin<any, any>>> = {
+    [K in keyof TPlugins]: TPlugins[K]["hooks"] extends () => infer H ? H : {};
+};
+/**
+ * Prefix all backend plugin route keys with the plugin name
+ * Example: { messages: { list: Endpoint } } => { messages_list: Endpoint }
+ */
+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
+ */
+interface BackendLib<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>> {
+    handler: (request: Request) => Promise<Response>;
+    router: Router;
+    dbSchema: DatabaseDefinition;
+}
+/**
+ * Helper type to extract routes from a client plugin
+ */
+type ExtractPluginRoutes<T> = T extends ClientPlugin<any, infer TRoutes> ? TRoutes : never;
+/**
+ * Helper type to merge all routes from all plugins into a single record
+ */
+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
+ */
+interface ClientLib<TRoutes extends Record<string, Route> = Record<string, Route>, THooks extends Record<string, any> = Record<string, any>> {
+    router: ReturnType<typeof createRouter<TRoutes, {}>>;
+    hooks: THooks;
+}
+
+export type { BackendPlugin as B, ClientPlugin as C, InferPluginOverrides as I, PluginRoutes as P, PluginHooks as a, ClientLibConfig as b, ClientLib as c, PluginOverrides as d, PrefixedPluginRoutes as e, BackendLibConfig as f, BackendLib as g };

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

@@ -0,0 +1,138 @@
+import { Route, createRouter } from '@btst/yar';
+import { Adapter, DbPlugin, DatabaseDefinition } from '@btst/db';
+import { 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)
+ */
+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;
+}
+/**
+ * Hook function type
+ * Generic function type for React hooks returned by plugins
+ */
+type HookFunction = (...args: unknown[]) => unknown;
+/**
+ * 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)
+ */
+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: Create React Query hooks for this plugin
+     * These can be used directly in components without the loader
+     */
+    hooks?: () => Record<string, HookFunction>;
+    /**
+     * Optional: Default implementations for overridable components/functions
+     * These will be used if no override is provided in BetterStackContext
+     */
+    defaultOverrides?: Partial<TOverrides>;
+}
+/**
+ * Configuration for creating the backend library
+ */
+interface BackendLibConfig<TPlugins extends Record<string, BackendPlugin<any>> = Record<string, BackendPlugin<any>>> {
+    dbSchema?: DatabaseDefinition;
+    plugins: TPlugins;
+    adapter: (db: DatabaseDefinition) => Adapter;
+}
+/**
+ * Configuration for creating the client library
+ */
+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
+ */
+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
+ */
+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
+ */
+type PluginRoutes<TPlugins extends Record<string, ClientPlugin<any, any>>> = MergeAllPluginRoutes<TPlugins>;
+/**
+ * Extract all hooks from all client plugins, organized by plugin name
+ * For plugins without hooks, the type will be an empty object
+ */
+type PluginHooks<TPlugins extends Record<string, ClientPlugin<any, any>>> = {
+    [K in keyof TPlugins]: TPlugins[K]["hooks"] extends () => infer H ? H : {};
+};
+/**
+ * Prefix all backend plugin route keys with the plugin name
+ * Example: { messages: { list: Endpoint } } => { messages_list: Endpoint }
+ */
+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
+ */
+interface BackendLib<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>> {
+    handler: (request: Request) => Promise<Response>;
+    router: Router;
+    dbSchema: DatabaseDefinition;
+}
+/**
+ * Helper type to extract routes from a client plugin
+ */
+type ExtractPluginRoutes<T> = T extends ClientPlugin<any, infer TRoutes> ? TRoutes : never;
+/**
+ * Helper type to merge all routes from all plugins into a single record
+ */
+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
+ */
+interface ClientLib<TRoutes extends Record<string, Route> = Record<string, Route>, THooks extends Record<string, any> = Record<string, any>> {
+    router: ReturnType<typeof createRouter<TRoutes, {}>>;
+    hooks: THooks;
+}
+
+export type { BackendPlugin as B, ClientPlugin as C, InferPluginOverrides as I, PluginRoutes as P, PluginHooks as a, ClientLibConfig as b, ClientLib as c, PluginOverrides as d, PrefixedPluginRoutes as e, BackendLibConfig as f, BackendLib as g };

package/package.json

@@ -0,0 +1,129 @@
+{
+  "name": "@btst/stack",
+  "version": "1.0.0",
+  "description": "A composable, plugin-based library for building full-stack applications.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/olliethedev/better-stack.git"
+  },
+  "keywords": [
+    "fullstack",
+    "react",
+    "nextjs"
+  ],
+  "author": "olliethedev",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/olliethedev/better-stack/issues"
+  },
+  "homepage": "https://github.com/olliethedev/better-stack#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "unbuild --clean",
+    "stub": "unbuild --stub",
+    "test": "vitest",
+    "typecheck": "tsc --project tsconfig.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./api": {
+      "import": {
+        "types": "./dist/api/index.d.ts",
+        "default": "./dist/api/index.mjs"
+      },
+      "require": {
+        "types": "./dist/api/index.d.cts",
+        "default": "./dist/api/index.cjs"
+      }
+    },
+    "./client": {
+      "import": {
+        "types": "./dist/client/index.d.ts",
+        "default": "./dist/client/index.mjs"
+      },
+      "require": {
+        "types": "./dist/client/index.d.cts",
+        "default": "./dist/client/index.cjs"
+      }
+    },
+    "./context": {
+      "import": {
+        "types": "./dist/context/index.d.ts",
+        "default": "./dist/context/index.mjs"
+      },
+      "require": {
+        "types": "./dist/context/index.d.cts",
+        "default": "./dist/context/index.cjs"
+      }
+    },
+    "./plugins": {
+      "import": {
+        "types": "./dist/plugins/index.d.ts",
+        "default": "./dist/plugins/index.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/index.d.cts",
+        "default": "./dist/plugins/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/index.d.ts"
+      ],
+      "api": [
+        "./dist/api/index.d.ts"
+      ],
+      "client": [
+        "./dist/client/index.d.ts"
+      ],
+      "context": [
+        "./dist/context/index.d.ts"
+      ],
+      "plugins": [
+        "./dist/plugins/index.d.ts"
+      ]
+    }
+  },
+  "dependencies": {
+    "@btst/db": "1.0.2",
+    "@btst/yar": "1.1.0",
+    "better-call": "1.0.19",
+    "zod": "^4.1.5"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@tanstack/react-query": "^5.0.0"
+  },
+  "devDependencies": {
+    "@btst/adapter-memory": "1.0.2",
+    "@tanstack/react-query": "^5.0.0",
+    "@types/react": "^18.3.23",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "typescript": "catalog:",
+    "unbuild": "catalog:",
+    "vitest": "catalog:",
+    "vue": "^3.5.18"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ]
+}