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

package/dist/router-Di7ENoah.d.ts

@@ -0,0 +1,151 @@
+import { TSchema } from '@sinclair/typebox';
+
+/**
+ * Event System Types
+ */
+
+/**
+ * Pub/Sub capable cache interface for multi-instance events
+ */
+interface PubSubCache {
+    /**
+     * Publish a message to a channel
+     */
+    publish(channel: string, message: unknown): Promise<void>;
+    /**
+     * Subscribe to a channel
+     */
+    subscribe(channel: string, handler: (message: unknown) => void | Promise<void>): Promise<void>;
+}
+/**
+ * Event handler function type
+ */
+type EventHandler<TPayload> = (payload: TPayload) => void | Promise<void>;
+/**
+ * Job queue sender function type (used by job module)
+ */
+type JobQueueSender = (queueName: string, payload: unknown) => Promise<void>;
+/**
+ * Event definition interface
+ */
+interface EventDef<TPayload = void> {
+    /**
+     * Unique event name
+     */
+    readonly name: string;
+    /**
+     * TypeBox payload schema (optional)
+     */
+    readonly schema?: TSchema;
+    /**
+     * Subscribe to this event (in-memory handler)
+     */
+    subscribe: (handler: EventHandler<TPayload>) => () => void;
+    /**
+     * Unsubscribe all handlers
+     */
+    unsubscribeAll: () => void;
+    /**
+     * Emit the event (triggers all subscribers and queued jobs)
+     */
+    emit: TPayload extends void ? () => Promise<void> : (payload: TPayload) => Promise<void>;
+    /**
+     * Enable cache-based pub/sub for multi-instance support
+     * Must await before emitting events to ensure subscription is ready
+     */
+    useCache: (cache: PubSubCache) => Promise<EventDef<TPayload>>;
+    /**
+     * Internal: Register a job queue to receive this event
+     * Called by job registration system
+     */
+    _registerJobQueue: (queueName: string, sender: JobQueueSender) => void;
+    /**
+     * Type inference helper
+     */
+    _payload: TPayload;
+}
+/**
+ * Infer payload type from EventDef
+ */
+type InferEventPayload$1<TEvent> = TEvent extends EventDef<infer TPayload> ? TPayload : never;
+
+/**
+ * Event Router
+ *
+ * Type-safe event router for SSE subscription
+ *
+ * @example
+ * ```typescript
+ * import { defineEvent, defineEventRouter } from '@spfn/core/event';
+ * import { Type } from '@sinclair/typebox';
+ *
+ * const userCreated = defineEvent('user.created', Type.Object({
+ *     userId: Type.String(),
+ * }));
+ *
+ * const orderPlaced = defineEvent('order.placed', Type.Object({
+ *     orderId: Type.String(),
+ *     amount: Type.Number(),
+ * }));
+ *
+ * export const eventRouter = defineEventRouter({
+ *     userCreated,
+ *     orderPlaced,
+ * });
+ *
+ * export type EventRouter = typeof eventRouter;
+ * ```
+ */
+
+/**
+ * Event Router Definition
+ */
+interface EventRouterDef<TEvents extends Record<string, EventDef<any>>> {
+    /**
+     * Event definitions
+     */
+    readonly events: TEvents;
+    /**
+     * Event names as array
+     */
+    readonly eventNames: (keyof TEvents)[];
+    /**
+     * Type inference helper - payload types by event name
+     */
+    readonly _types: {
+        [K in keyof TEvents]: TEvents[K]['_payload'];
+    };
+}
+/**
+ * Infer event names from EventRouter
+ */
+type InferEventNames<T> = T extends EventRouterDef<infer E> ? keyof E & string : never;
+/**
+ * Infer payload type for specific event
+ */
+type InferEventPayload<T extends EventRouterDef<any>, K extends InferEventNames<T>> = T['_types'][K];
+/**
+ * Infer all event payloads map
+ */
+type InferEventPayloads<T extends EventRouterDef<any>> = T['_types'];
+/**
+ * Define an event router for SSE subscription
+ *
+ * @example
+ * ```typescript
+ * export const eventRouter = defineEventRouter({
+ *     userCreated,
+ *     orderPlaced,
+ * });
+ *
+ * // Type inference
+ * type Names = InferEventNames<typeof eventRouter>;
+ * // 'userCreated' | 'orderPlaced'
+ *
+ * type Payload = InferEventPayload<typeof eventRouter, 'userCreated'>;
+ * // { userId: string }
+ * ```
+ */
+declare function defineEventRouter<TEvents extends Record<string, EventDef<any>>>(events: TEvents): EventRouterDef<TEvents>;
+
+export { type EventRouterDef as E, type InferEventNames as I, type JobQueueSender as J, type PubSubCache as P, type EventDef as a, type InferEventPayload as b, type InferEventPayloads as c, defineEventRouter as d, type EventHandler as e, type InferEventPayload$1 as f };

package/dist/server/index.d.ts

@@ -1,62 +1,47 @@
 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 BossOptions } from '../boss-DI1r4kTS.js';
+import { E as EventRouterDef } from '../router-Di7ENoah.js';
+import { S as SSEHandlerConfig } from '../types-B-e_f2dQ.js';
+import '@sinclair/typebox';
+import 'pg-boss';
 
 /**
- * CORS configuration options - inferred from hono/cors
+ * Load environment files for SPFN server
+ *
+ * Priority (high → low, later files don't override):
+ * 1. .env.server.local  - Server-only secrets (gitignored)
+ * 2. .env.server        - Server-only defaults
+ * 3. .env.{NODE_ENV}.local
+ * 4. .env.local         - Local overrides (gitignored)
+ * 5. .env.{NODE_ENV}
+ * 6. .env               - Defaults
  */
-type CorsConfig = Parameters<typeof cors>[0];
+declare function loadEnvFiles(): void;
+
 /**
- * SPFN Plugin Interface
- *
- * Allows packages to automatically hook into server lifecycle
- * Plugins are auto-discovered from @spfn/* packages in node_modules
+ * Workflow router interface for @spfn/core integration
  *
- * @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);
- *   }
- * };
- * ```
+ * This is a minimal interface that avoids circular dependency with @spfn/workflow.
+ * The actual WorkflowRouter from @spfn/workflow implements this interface.
  */
-interface ServerPlugin {
-    /**
-     * Plugin name (should match package name)
-     */
-    name: string;
+interface WorkflowRouterLike {
     /**
-     * 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
+     * Initialize the workflow engine
+     * Called by server during infrastructure initialization
+     *
+     * @internal
      */
-    beforeShutdown?: () => Promise<void>;
+    _init: (db: any, options?: {
+        largeOutputThreshold?: number;
+    }) => void;
 }
+/**
+ * CORS configuration options - inferred from hono/cors
+ */
+type CorsConfig = Parameters<typeof cors>[0];
 /**
  * Server Configuration Options
  *
@@ -99,28 +84,102 @@ 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 { defineMiddleware } from '@spfn/core/server';
+     *
+     * const authMiddleware = defineMiddleware('auth', async (c, next) => {
+     *   // auth logic
+     *   await next();
+     * });
+     *
+     * export default defineServerConfig()
+     *   .middlewares([authMiddleware, rateLimitMiddleware])
+     *   .build();
+     * ```
+     */
+    middlewares?: readonly NamedMiddleware[];
+    /**
+     * 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 { authMiddleware } from '@spfn/auth';
-     *
-     * export default {
-     *   middlewares: [
-     *     { name: 'auth', handler: authMiddleware() },
-     *     { name: 'rateLimit', handler: rateLimitMiddleware() },
-     *   ]
-     * } satisfies ServerConfig;
+     * 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();
      * ```
      */
-    middlewares?: Array<{
-        name: string;
-        handler: MiddlewareHandler;
-    }>;
+    jobs?: JobRouter<any>;
     /**
-     * Routes directory path (default: src/server/routes)
+     * pg-boss configuration options
+     * Only used if jobs router is provided
      */
-    routesPath?: string;
+    jobsConfig?: Omit<BossOptions, 'connectionString'>;
+    /**
+     * Event router for SSE (Server-Sent Events) subscription
+     * Enables real-time event streaming to frontend clients
+     *
+     * @example
+     * ```typescript
+     * import { defineEvent, defineEventRouter } from '@spfn/core/event';
+     *
+     * const userCreated = defineEvent('user.created', Type.Object({
+     *   userId: Type.String(),
+     * }));
+     *
+     * const eventRouter = defineEventRouter({ userCreated });
+     *
+     * export default defineServerConfig()
+     *   .routes(appRouter)
+     *   .events(eventRouter)  // → GET /events/stream
+     *   .build();
+     * ```
+     */
+    events?: EventRouterDef<any>;
+    /**
+     * SSE configuration options
+     * Only used if events router is provided
+     */
+    eventsConfig?: SSEHandlerConfig & {
+        /**
+         * SSE endpoint path
+         * @default '/events/stream'
+         */
+        path?: string;
+    };
     /**
      * Enable debug mode (default: NODE_ENV === 'development')
      */
@@ -296,6 +355,39 @@ interface ServerConfig {
          */
         redis?: boolean;
     };
+    /**
+     * Workflow router for workflow orchestration
+     *
+     * Automatically initializes the workflow engine after database is ready.
+     * Workflows are defined using @spfn/workflow package.
+     *
+     * @example
+     * ```typescript
+     * import { defineWorkflowRouter } from '@spfn/workflow';
+     *
+     * const workflowRouter = defineWorkflowRouter([
+     *     provisionTenant,
+     *     deprovisionTenant,
+     * ]);
+     *
+     * export default defineServerConfig()
+     *     .workflows(workflowRouter)
+     *     .build();
+     * ```
+     */
+    workflows?: WorkflowRouterLike;
+    /**
+     * Workflow engine configuration
+     * Only used if workflows router is provided
+     */
+    workflowsConfig?: {
+        /**
+         * Large output threshold in bytes
+         * Outputs larger than this will be stored in external storage
+         * @default 1024 * 1024 (1MB)
+         */
+        largeOutputThreshold?: number;
+    };
     /**
      * Server lifecycle hooks for custom infrastructure setup and management
      * Allows initialization of custom services and resources at different stages
@@ -456,7 +548,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 +567,193 @@ 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<BossOptions, 'connectionString'>): this;
+    /**
+     * Register event router for SSE (Server-Sent Events)
+     *
+     * Enables real-time event streaming to frontend clients.
+     * Events defined with defineEvent() can be subscribed by:
+     * - Backend: .subscribe() for internal handlers
+     * - Jobs: .on(event) for background processing
+     * - Frontend: SSE stream for real-time updates
+     *
+     * @example
+     * ```typescript
+     * import { defineEvent, defineEventRouter } from '@spfn/core/event';
+     *
+     * const userCreated = defineEvent('user.created', Type.Object({
+     *   userId: Type.String(),
+     * }));
+     *
+     * const eventRouter = defineEventRouter({ userCreated });
+     *
+     * export default defineServerConfig()
+     *   .routes(appRouter)
+     *   .events(eventRouter)  // → GET /events/stream
+     *   .build();
+     *
+     * // Custom path
+     * .events(eventRouter, { path: '/sse' })
+     * ```
+     */
+    events(router: EventRouterDef<any>, config?: SSEHandlerConfig & {
+        path?: string;
+    }): 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;
+    /**
+     * Register workflow router for workflow orchestration
+     *
+     * Automatically initializes the workflow engine after database is ready.
+     *
+     * @example
+     * ```typescript
+     * import { defineWorkflowRouter } from '@spfn/workflow';
+     *
+     * const workflowRouter = defineWorkflowRouter([
+     *     provisionTenant,
+     *     deprovisionTenant,
+     * ]);
+     *
+     * export default defineServerConfig()
+     *     .routes(appRouter)
+     *     .workflows(workflowRouter)
+     *     .build();
+     * ```
+     */
+    workflows(router: ServerConfig['workflows'], config?: ServerConfig['workflowsConfig']): 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({ params: Type.Object({ id: Type.String() }) })
+ *     .handler(async (c) => {
+ *       const { params } = await c.data();
+ *       return { id: params.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 };