@spfn/core 0.1.0-alpha.88 → 0.2.0-beta.1

package/dist/server/index.d.ts

@@ -1,62 +1,17 @@
 import { MiddlewareHandler, Hono } from 'hono';
 import { cors } from 'hono/cors';
 import { serve } from '@hono/node-server';
+import { NamedMiddleware, Router } from '@spfn/core/route';
+import { J as JobRouter, B as BossConfig } from '../boss-D-fGtVgM.js';
+import '@sinclair/typebox';
+import 'pg-boss';
+
+declare function loadEnvFiles(): void;
 
 /**
  * CORS configuration options - inferred from hono/cors
  */
 type CorsConfig = Parameters<typeof cors>[0];
-/**
- * SPFN Plugin Interface
- *
- * Allows packages to automatically hook into server lifecycle
- * Plugins are auto-discovered from @spfn/* packages in node_modules
- *
- * @example
- * ```typescript
- * // packages/auth/src/plugin.ts
- * export const spfnPlugin: ServerPlugin = {
- *   name: '@spfn/auth',
- *   afterInfrastructure: async () => {
- *     await initializeAuth();
- *   },
- *   beforeRoutes: async (app) => {
- *     app.route('/_auth', authRoutes);
- *   }
- * };
- * ```
- */
-interface ServerPlugin {
-    /**
-     * Plugin name (should match package name)
-     */
-    name: string;
-    /**
-     * Hook: Run after infrastructure (DB/Redis) initialization
-     * Use for: migrations, seeding, RBAC setup
-     */
-    afterInfrastructure?: () => Promise<void>;
-    /**
-     * Hook: Run before routes are loaded
-     * Use for: mounting plugin routes, adding middleware
-     */
-    beforeRoutes?: (app: Hono) => Promise<void>;
-    /**
-     * Hook: Run after all routes are loaded
-     * Use for: final setup, fallback handlers
-     */
-    afterRoutes?: (app: Hono) => Promise<void>;
-    /**
-     * Hook: Run after server starts successfully
-     * Use for: notifications, health checks
-     */
-    afterStart?: (instance: ServerInstance) => Promise<void>;
-    /**
-     * Hook: Run before graceful shutdown
-     * Use for: cleanup plugin resources
-     */
-    beforeShutdown?: () => Promise<void>;
-}
 /**
  * Server Configuration Options
  *
@@ -99,28 +54,70 @@ interface ServerConfig {
     use?: MiddlewareHandler[];
     /**
      * Global middlewares with names for route-level skip control
-     * Each middleware can be skipped per route using meta.skipMiddlewares
+     * Use defineMiddleware() for type-safe middleware definitions
      *
      * @example
      * ```typescript
-     * import { authMiddleware } from '@spfn/auth';
+     * import { defineMiddleware } from '@spfn/core/server';
+     *
+     * const authMiddleware = defineMiddleware('auth', async (c, next) => {
+     *   // auth logic
+     *   await next();
+     * });
      *
-     * export default {
-     *   middlewares: [
-     *     { name: 'auth', handler: authMiddleware() },
-     *     { name: 'rateLimit', handler: rateLimitMiddleware() },
-     *   ]
-     * } satisfies ServerConfig;
+     * export default defineServerConfig()
+     *   .middlewares([authMiddleware, rateLimitMiddleware])
+     *   .build();
      * ```
      */
-    middlewares?: Array<{
-        name: string;
-        handler: MiddlewareHandler;
-    }>;
+    middlewares?: readonly NamedMiddleware[];
     /**
-     * Routes directory path (default: src/server/routes)
+     * define-route based router
+     * Routes defined with route.get()...handler() style
+     * Will be automatically registered before file-based routes
+     *
+     * @example
+     * ```typescript
+     * import { defineRouter, route } from '@spfn/core/route';
+     *
+     * const appRouter = defineRouter({
+     *   getUser: route.get('/users/:id')...
+     *   createUser: route.post('/users')...
+     * });
+     *
+     * export default defineServerConfig()
+     *   .routes(appRouter)
+     *   .build();
+     * ```
+     */
+    routes?: Router<any>;
+    /**
+     * Background jobs router
+     * Jobs defined with job()...handler() style
+     * Uses pg-boss for PostgreSQL-based job queue
+     *
+     * @example
+     * ```typescript
+     * import { job, defineJobRouter } from '@spfn/core/job';
+     *
+     * const sendEmail = job('send-email')
+     *   .input(Type.Object({ to: Type.String() }))
+     *   .handler(async (input) => { ... });
+     *
+     * const jobRouter = defineJobRouter({ sendEmail });
+     *
+     * export default defineServerConfig()
+     *   .routes(appRouter)
+     *   .jobs(jobRouter)
+     *   .build();
+     * ```
      */
-    routesPath?: string;
+    jobs?: JobRouter<any>;
+    /**
+     * pg-boss configuration options
+     * Only used if jobs router is provided
+     */
+    jobsConfig?: Omit<BossConfig, 'connectionString'>;
     /**
      * Enable debug mode (default: NODE_ENV === 'development')
      */
@@ -456,7 +453,7 @@ declare module 'hono' {
  * 2. server.config.ts -> Partial customization
  * 3. app.ts -> Full control (no auto config)
  */
-declare function createServer(config?: ServerConfig, plugins?: ServerPlugin[]): Promise<Hono>;
+declare function createServer(config?: ServerConfig): Promise<Hono>;
 
 /**
  * Start SPFN Server
@@ -475,4 +472,141 @@ declare function createServer(config?: ServerConfig, plugins?: ServerPlugin[]):
  */
 declare function startServer(config?: ServerConfig): Promise<ServerInstance>;
 
-export { type AppFactory, type ServerConfig, type ServerInstance, type ServerPlugin, createServer, startServer };
+/**
+ * Server Config Builder
+ *
+ * Provides a fluent API for building server configuration
+ */
+
+declare class ServerConfigBuilder {
+    private config;
+    private lifecycles;
+    /**
+     * Set server port
+     */
+    port(port: number): this;
+    /**
+     * Set server hostname
+     */
+    host(host: string): this;
+    /**
+     * Set CORS configuration
+     */
+    cors(cors: ServerConfig['cors']): this;
+    /**
+     * Configure built-in middleware
+     */
+    middleware(middleware: ServerConfig['middleware']): this;
+    /**
+     * Add custom middleware
+     */
+    use(handlers: MiddlewareHandler[]): this;
+    /**
+     * Add named middlewares for route-level skip control
+     */
+    middlewares(middlewares: ServerConfig['middlewares']): this;
+    /**
+     * Register define-route based router
+     *
+     * Automatically applies:
+     * - Global middlewares from router._globalMiddlewares (via .use())
+     * - Package routers from router._packageRouters (via .packages())
+     *
+     * @example
+     * ```typescript
+     * const appRouter = defineRouter({
+     *   getUser: route.get('/users/:id')...
+     * })
+     * .packages([authRouter, cmsAppRouter])
+     * .use([authMiddleware]);
+     *
+     * export default defineServerConfig()
+     *   .routes(appRouter)  // middlewares auto-applied
+     *   .build();
+     * ```
+     */
+    routes(router: Router<any>): this;
+    /**
+     * Register background jobs router
+     *
+     * @example
+     * ```typescript
+     * import { job, defineJobRouter } from '@spfn/core/job';
+     *
+     * const sendEmail = job('send-email')
+     *   .input(Type.Object({ to: Type.String() }))
+     *   .handler(async (input) => { ... });
+     *
+     * const jobRouter = defineJobRouter({ sendEmail });
+     *
+     * export default defineServerConfig()
+     *   .routes(appRouter)
+     *   .jobs(jobRouter)
+     *   .build();
+     * ```
+     */
+    jobs(router: JobRouter<any>, config?: Omit<BossConfig, 'connectionString'>): this;
+    /**
+     * Enable/disable debug mode
+     */
+    debug(enabled: boolean): this;
+    /**
+     * Configure database settings
+     */
+    database(database: ServerConfig['database']): this;
+    /**
+     * Configure server timeout settings
+     */
+    timeout(timeout: ServerConfig['timeout']): this;
+    /**
+     * Configure graceful shutdown settings
+     */
+    shutdown(shutdown: ServerConfig['shutdown']): this;
+    /**
+     * Configure health check endpoint
+     */
+    healthCheck(healthCheck: ServerConfig['healthCheck']): this;
+    /**
+     * Configure infrastructure initialization
+     */
+    infrastructure(infrastructure: ServerConfig['infrastructure']): this;
+    /**
+     * Configure lifecycle hooks
+     * Can be called multiple times - hooks will be executed in registration order
+     */
+    lifecycle(lifecycle: ServerConfig['lifecycle']): this;
+    /**
+     * Build and return the final configuration
+     */
+    build(): ServerConfig;
+    private mergeLifecycles;
+}
+/**
+ * Create a new server configuration builder
+ *
+ * @example
+ * ```typescript
+ * // server.config.ts
+ * import { defineServerConfig, route, defineRouter } from '@spfn/core/server';
+ * import { Type } from '@sinclair/typebox';
+ *
+ * const appRouter = defineRouter({
+ *   getUser: route.get('/users/:id')
+ *     .input(Type.Object({ id: Type.String() }))
+ *     .handler(async (c) => {
+ *       const { id } = await c.data();
+ *       return c.success({ id, name: 'John' });
+ *     }),
+ * });
+ *
+ * export default defineServerConfig()
+ *   .port(3000)
+ *   .routes(appRouter)
+ *   .middleware({ logger: true, cors: true })
+ *   .debug(true)
+ *   .build();
+ * ```
+ */
+declare function defineServerConfig(): ServerConfigBuilder;
+
+export { type AppFactory, type ServerConfig, type ServerInstance, createServer, defineServerConfig, loadEnvFiles, startServer };