blaizejs 0.5.3 → 0.6.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as zod from 'zod';
 import { z } from 'zod';
-import http, { IncomingMessage, ServerResponse } from 'node:http';
-import http2, { Http2ServerRequest, Http2ServerResponse } from 'node:http2';
+import http, { IncomingMessage, ServerResponse, Server as Server$1 } from 'node:http';
+import http2, { Http2ServerRequest, Http2ServerResponse, Http2Server } from 'node:http2';
 import { WriteStream } from 'node:fs';
 import { Readable } from 'node:stream';
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -1058,7 +1058,7 @@ declare function cors(userOptions?: CorsOptions | boolean): Middleware;
 /**
  * Create a middleware
  */
-declare function create$2<TState = {}, TServices = {}>(handlerOrOptions: MiddlewareFunction | MiddlewareOptions): Middleware<TState, TServices>;
+declare function create$1<TState = {}, TServices = {}>(handlerOrOptions: MiddlewareFunction | MiddlewareOptions): Middleware<TState, TServices>;
 /**
  * Create a middleware that only contributes state (no services)
  * Convenience helper for state-only middleware
@@ -2470,28 +2470,179 @@ interface PluginOptions<_T = any> {
     [key: string]: any;
 }
 /**
- * Plugin lifecycle hooks
+ * Plugin lifecycle hooks with full type safety
+ *
+ * Plugins execute in this order:
+ * 1. register() - Add middleware, routes
+ * 2. initialize() - Create resources
+ * 3. onServerStart() - Start background work
+ * 4. onServerStop() - Stop background work
+ * 5. terminate() - Cleanup resources
+ */
+interface PluginHooks<TState = {}, TServices = {}> {
+    /**
+     * Called when plugin is registered to server
+     *
+     * Use this hook to:
+     * - Add middleware via server.use()
+     * - Add routes via server.router.addRoute()
+     * - Subscribe to server events
+     *
+     * @param server - BlaizeJS server instance
+     * @example
+     * ```typescript
+     * register: async (server) => {
+     *   server.use(createMiddleware({
+     *     handler: async (ctx, next) => {
+     *       ctx.services.db = db;
+     *       await next();
+     *     },
+     *   }));
+     * }
+     * ```
+     */
+    register?: (server: Server<TState, TServices>) => void | Promise<void>;
+    /**
+     * Called during server initialization
+     *
+     * Use this hook to:
+     * - Create database connections
+     * - Initialize services
+     * - Allocate resources
+     *
+     * @example
+     * ```typescript
+     * initialize: async () => {
+     *   db = await Database.connect(config);
+     * }
+     * ```
+     */
+    initialize?: (server: Server<TState, TServices>) => void | Promise<void>;
+    /**
+     * Called when server starts listening
+     *
+     * Use this hook to:
+     * - Start background workers
+     * - Start cron jobs
+     * - Begin health checks
+     *
+     * @example
+     * ```typescript
+     * onServerStart: async () => {
+     *   worker = new BackgroundWorker();
+     *   await worker.start();
+     * }
+     * ```
+     */
+    onServerStart?: (server: Http2Server | Server$1) => void | Promise<void>;
+    /**
+     * Called when server stops listening
+     *
+     * Use this hook to:
+     * - Stop background workers
+     * - Flush buffers
+     * - Complete in-flight work
+     *
+     * @example
+     * ```typescript
+     * onServerStop: async () => {
+     *   await worker.stop({ graceful: true });
+     * }
+     * ```
+     */
+    onServerStop?: (server: Http2Server | Server$1) => void | Promise<void>;
+    /**
+     * Called during server termination
+     *
+     * Use this hook to:
+     * - Close database connections
+     * - Release file handles
+     * - Free memory
+     *
+     * @example
+     * ```typescript
+     * terminate: async () => {
+     *   await db?.close();
+     * }
+     * ```
+     */
+    terminate?: (server: Server<TState, TServices>) => void | Promise<void>;
+}
+/**
+ * Options for creating a plugin with createPlugin()
+ *
+ * @template TConfig - Plugin configuration shape
+ * @template TState - State added to context
+ * @template TServices - Services added to context
  */
-interface PluginHooks {
-    /** Called when the plugin is registered */
-    register: (app: Server<any, any>) => void | Promise<void>;
-    /** Called when the server is initialized */
-    initialize?: (app?: Server<any, any>) => void | Promise<void>;
-    /** Called when the server is terminated */
-    terminate?: (app?: Server<any, any>) => void | Promise<void>;
-    /** Called when the server starts */
-    onServerStart?: (server: any) => void | Promise<void>;
-    /** Called when the server stops */
-    onServerStop?: (server: any) => void | Promise<void>;
+interface CreatePluginOptions<TConfig, TState = {}, TServices = {}> {
+    /**
+     * Plugin name (e.g., '@blaizejs/metrics')
+     * Must be unique within a server instance
+     */
+    name: string;
+    /**
+     * Semantic version (e.g., '1.0.0')
+     * Used for compatibility checks
+     */
+    version: string;
+    /**
+     * Default configuration values
+     * Merged with user config when plugin is created
+     *
+     * @example
+     * ```typescript
+     * defaultConfig: {
+     *   enabled: true,
+     *   timeout: 30000,
+     * }
+     * ```
+     */
+    defaultConfig?: TConfig;
+    /**
+     * Setup function that returns lifecycle hooks
+     *
+     * Receives merged config (defaultConfig + userConfig).
+     * Returns partial hook object - all hooks optional.
+     *
+     * @param config - Merged configuration
+     * @returns Partial plugin hooks
+     *
+     * @example
+     * ```typescript
+     * setup: (config) => {
+     *   let db: Database;
+     *
+     *   return {
+     *     initialize: async () => {
+     *       db = await Database.connect(config);
+     *     },
+     *     terminate: async () => {
+     *       await db?.close();
+     *     },
+     *   };
+     * }
+     * ```
+     */
+    setup: (config: TConfig) => Partial<PluginHooks<TState, TServices>>;
 }
 /**
  * Plugin interface
  */
-interface Plugin<TState = {}, TServices = {}> extends PluginHooks {
+interface Plugin<TState = {}, TServices = {}> extends PluginHooks<TState, TServices> {
     /** Plugin name */
     name: string;
     /** Plugin version */
     version: string;
+    /**
+     * Called when plugin is registered to server
+     *
+     * This hook is always present - createPlugin provides a default empty async function
+     * if not specified by the plugin author.
+     *
+     * @override Makes register required (not optional like in PluginHooks)
+     */
+    register: (server: Server<TState, TServices>) => void | Promise<void>;
     /**
      * Type carriers for compile-time type information
      * These are never used at runtime but allow TypeScript to track types
@@ -2502,7 +2653,7 @@ interface Plugin<TState = {}, TServices = {}> extends PluginHooks {
 /**
  * Plugin factory function
  */
-type PluginFactory<TConfig = any, TState = {}, TServices = {}> = (options?: TConfig) => Plugin<TState, TServices>;
+type PluginFactory<TConfig = any, TState = {}, TServices = {}> = (options?: Partial<TConfig>) => Plugin<TState, TServices>;
 interface PluginLifecycleManager {
     initializePlugins(server: Server<any, any>): Promise<void>;
     terminatePlugins(server: Server<any, any>): Promise<void>;
@@ -2762,9 +2913,80 @@ declare function createMiddlewareArray<T extends ReadonlyArray<Middleware>>(...m
 declare function createPluginArray<T extends ReadonlyArray<Plugin<any, any>>>(...plugins: T): T;
 
 /**
- * Create a plugin with the given name, version, and setup function
+ * Create a type-safe plugin with full IntelliSense support
+ *
+ * This is the primary way to create plugins in BlaizeJS. It provides:
+ * - IntelliSense for all lifecycle hooks
+ * - Automatic config merging with defaults
+ * - Full type safety for state and services
+ * - Consistent DX with createMiddleware
+ *
+ * @template TConfig - Plugin configuration shape
+ * @template TState - State added to context (default: {})
+ * @template TServices - Services added to context (default: {})
+ *
+ * @param options - Plugin creation options
+ * @returns Plugin factory function
+ *
+ * @example Basic plugin with config
+ * ```typescript
+ * const createDbPlugin = createPlugin<
+ *   { host: string; port: number },
+ *   {},
+ *   { db: Database }
+ * >({
+ *   name: '@my-app/database',
+ *   version: '1.0.0',
+ *   defaultConfig: {
+ *     host: 'localhost',
+ *     port: 5432,
+ *   },
+ *   setup: (config) => {
+ *     let db: Database;
+ *
+ *     return {
+ *       register: async (server) => {
+ *         // Add typed middleware
+ *         server.use(createMiddleware<{}, { db: Database }>({
+ *           handler: async (ctx, next) => {
+ *             ctx.services.db = db;
+ *             await next();
+ *           },
+ *         }));
+ *       },
+ *
+ *       initialize: async () => {
+ *         db = await Database.connect(config);
+ *       },
+ *
+ *       terminate: async () => {
+ *         await db?.close();
+ *       },
+ *     };
+ *   },
+ * });
+ *
+ * // Usage
+ * const plugin = createDbPlugin({ host: 'prod.db.com' });
+ * ```
+ *
+ * @example Simple plugin without config
+ * ```typescript
+ * const loggerPlugin = createPlugin<{}, {}, { logger: Logger }>({
+ *   name: '@my-app/logger',
+ *   version: '1.0.0',
+ *   setup: () => ({
+ *     initialize: async () => {
+ *       console.log('Logger initialized');
+ *     },
+ *   }),
+ * });
+ *
+ * // Usage (no config needed)
+ * const plugin = loggerPlugin();
+ * ```
  */
-declare function create$1<TConfig = any, TState = {}, TServices = {}>(name: string, version: string, setup: (app: UnknownServer, options: TConfig) => void | Partial<PluginHooks> | Promise<void> | Promise<Partial<PluginHooks>>, defaultOptions?: Partial<TConfig>): PluginFactory<TConfig, TState, TServices>;
+declare function createPlugin<TConfig = {}, TState = {}, TServices = {}>(options: CreatePluginOptions<TConfig, TState, TServices>): PluginFactory<TConfig, TState, TServices>;
 
 /**
  * Create a GET route
@@ -3355,22 +3577,22 @@ declare const RouterAPI: {
     buildUrl: typeof buildUrl;
 };
 declare const MiddlewareAPI: {
-    createMiddleware: typeof create$2;
+    createMiddleware: typeof create$1;
     createServiceMiddleware: typeof serviceMiddleware;
     createStateMiddleware: typeof stateMiddleware;
     compose: typeof compose;
     cors: typeof cors;
 };
 declare const PluginsAPI: {
-    createPlugin: typeof create$1;
+    createPlugin: typeof createPlugin;
 };
 
 declare const Blaize: {
     createServer: typeof create;
-    createMiddleware: typeof create$2;
+    createMiddleware: typeof create$1;
     createServiceMiddleware: typeof serviceMiddleware;
     createStateMiddleware: typeof stateMiddleware;
-    createPlugin: typeof create$1;
+    createPlugin: typeof createPlugin;
     getCorrelationId: typeof getCorrelationId;
     Server: {
         createServer: typeof create;
@@ -3392,16 +3614,16 @@ declare const Blaize: {
         buildUrl: typeof buildUrl;
     };
     Middleware: {
-        createMiddleware: typeof create$2;
+        createMiddleware: typeof create$1;
         createServiceMiddleware: typeof serviceMiddleware;
         createStateMiddleware: typeof stateMiddleware;
         compose: typeof compose;
         cors: typeof cors;
     };
     Plugins: {
-        createPlugin: typeof create$1;
+        createPlugin: typeof createPlugin;
     };
     VERSION: string;
 };
 
-export { Blaize, BlaizeError, type BlaizeErrorResponse, type BodyLimits, type BufferedEvent, type BuildRoutesRegistry, type BuildSSEArgs, type CacheConfig, type CacheEntry, type ClientConfig, type CloseEvent, type ComposeMiddlewareServices, type ComposeMiddlewareStates, type ComposeMiddlewareTypes, type ComposePluginServices, type ComposePluginStates, type ComposePluginTypes, ConflictError, type ConflictErrorDetails, type ConnectionEntry, type ConnectionRegistry, type Context, type ContextOptions, type ContextRequest, type ContextResponse, type CorrelationOptions, type CorsHttpMethod, type CorsOptions, type CorsOrigin, type CorsOriginCacheConfig, type CorsOriginCacheEntry, type CorsPreflightInfo, type CorsStats, type CorsValidationResult, type CreateClient, type CreateContextFn, type CreateDeleteRoute, type CreateEnhancedClient, type CreateGetRoute, type CreateHeadRoute, type CreateOptionsRoute, type CreatePatchRoute, type CreatePostRoute, type CreatePutRoute, type CreateSSEMethod, type CreateSSERoute, type ErrorHandlerOptions, ErrorSeverity, type ErrorTransformContext, ErrorType, type EventHandlers, type ExtractMethod, type ExtractMiddlewareServices, type ExtractMiddlewareState, type ExtractMiddlewareTypes, type ExtractPluginServices, type ExtractPluginState, type ExtractPluginTypes, type ExtractSSEEvents, type ExtractSSEParams, type ExtractSSEQuery, type ExtractSSERoutes, type FileCache, type FindRouteFilesOptions, ForbiddenError, type ForbiddenErrorDetails, type GetContextFn, type HasSSEMethod, type Http2Options, type HttpMethod, type Infer, type InferContext, type InternalRequestArgs, InternalServerError, type InternalServerErrorDetails, type Matcher, type MergeServices, type MergeStates, type Middleware, MiddlewareAPI, type MiddlewareFunction, type MiddlewareOptions, type MultipartData, type MultipartError, type MultipartLimits, type NetworkErrorContext, type NextFunction, NotFoundError, type NotFoundErrorDetails, type ParseErrorContext, type ParseOptions, type ParseResult, type ParsedRoute, type ParserState, PayloadTooLargeError, type PayloadTooLargeErrorDetails, type Plugin, type PluginFactory, type PluginHooks, type PluginLifecycleManager, type PluginLifecycleOptions, type PluginOptions, PluginsAPI, type ProcessResponseOptions, type ProcessingConfig, type QueryParams, RateLimitError, type RateLimitErrorDetails, type ReconnectStrategy, type RegistryResult, type ReloadMetrics, type RequestHandler, type RequestOptions, type RequestParams, RequestTimeoutError, type Result, type Route, type RouteDefinition, type RouteEntry, type RouteHandler, type RouteMatch, type RouteMethodOptions, type RouteNode, type RouteOptions, type RouteRegistry, type RouteSchema, type Router, RouterAPI, type RouterOptions, type SSEBufferOverflowErrorDetails, type SSEBufferStrategy, type SSEClient, type SSEClientMetrics, type SSEClientOptions, type SSEConnectionErrorContext, type SSEConnectionErrorDetails, type SSEConnectionFactory, type SSEConnectionState, type SSEEvent, type SSEEventHandler, type SSEEventListener, type SSEHeartbeatErrorContext, type SSEMetrics, type SSEOptions, type SSERouteHandler, type SSERouteSchema, type SSESerializedEvent, type SSEStream, type SSEStreamClosedErrorDetails, type SSEStreamErrorContext, type SSEStreamExtended, type SSEStreamManager, type SafeComposeMiddlewareServices, type SafeComposeMiddlewareStates, type SafeComposePluginServices, type SafeComposePluginStates, type SafeExtractMiddlewareServices, type SafeExtractMiddlewareState, type SafeExtractPluginServices, type SafeExtractPluginState, type Server, ServerAPI, type ServerOptions, type ServerOptionsInput, type ServiceNotAvailableDetails, ServiceNotAvailableError, type Services, type StandardErrorResponse, type StartOptions, type State, type StopOptions, type StreamMetrics, type StreamOptions, type TimeoutErrorContext, type TypedSSEStream, UnauthorizedError, type UnauthorizedErrorDetails, type UnifiedRequest, type UnifiedResponse, type UnionToIntersection, type UnknownFunction, type UnknownServer, UnprocessableEntityError, UnsupportedMediaTypeError, type UnsupportedMediaTypeErrorDetails, type UploadProgress, type UploadedFile, VERSION, type ValidationConfig, ValidationError, type ValidationErrorDetails, type ValidationFieldError, type WatchOptions, asMiddlewareArray, asPluginArray, buildUrl, compilePathPattern, compose, cors, createDeleteRoute, createGetRoute, createHeadRoute, createMatcher, create$2 as createMiddleware, createMiddlewareArray, createOptionsRoute, createPatchRoute, create$1 as createPlugin, createPluginArray, createPostRoute, createPutRoute, createRouteFactory, create as createServer, serviceMiddleware as createServiceMiddleware, stateMiddleware as createStateMiddleware, extractParams, getCorrelationId, inferContext, isMiddleware, isPlugin, paramsToQuery };
+export { Blaize, BlaizeError, type BlaizeErrorResponse, type BodyLimits, type BufferedEvent, type BuildRoutesRegistry, type BuildSSEArgs, type CacheConfig, type CacheEntry, type ClientConfig, type CloseEvent, type ComposeMiddlewareServices, type ComposeMiddlewareStates, type ComposeMiddlewareTypes, type ComposePluginServices, type ComposePluginStates, type ComposePluginTypes, ConflictError, type ConflictErrorDetails, type ConnectionEntry, type ConnectionRegistry, type Context, type ContextOptions, type ContextRequest, type ContextResponse, type CorrelationOptions, type CorsHttpMethod, type CorsOptions, type CorsOrigin, type CorsOriginCacheConfig, type CorsOriginCacheEntry, type CorsPreflightInfo, type CorsStats, type CorsValidationResult, type CreateClient, type CreateContextFn, type CreateDeleteRoute, type CreateEnhancedClient, type CreateGetRoute, type CreateHeadRoute, type CreateOptionsRoute, type CreatePatchRoute, type CreatePluginOptions, type CreatePostRoute, type CreatePutRoute, type CreateSSEMethod, type CreateSSERoute, type ErrorHandlerOptions, ErrorSeverity, type ErrorTransformContext, ErrorType, type EventHandlers, type ExtractMethod, type ExtractMiddlewareServices, type ExtractMiddlewareState, type ExtractMiddlewareTypes, type ExtractPluginServices, type ExtractPluginState, type ExtractPluginTypes, type ExtractSSEEvents, type ExtractSSEParams, type ExtractSSEQuery, type ExtractSSERoutes, type FileCache, type FindRouteFilesOptions, ForbiddenError, type ForbiddenErrorDetails, type GetContextFn, type HasSSEMethod, type Http2Options, type HttpMethod, type Infer, type InferContext, type InternalRequestArgs, InternalServerError, type InternalServerErrorDetails, type Matcher, type MergeServices, type MergeStates, type Middleware, MiddlewareAPI, type MiddlewareFunction, type MiddlewareOptions, type MultipartData, type MultipartError, type MultipartLimits, type NetworkErrorContext, type NextFunction, NotFoundError, type NotFoundErrorDetails, type ParseErrorContext, type ParseOptions, type ParseResult, type ParsedRoute, type ParserState, PayloadTooLargeError, type PayloadTooLargeErrorDetails, type Plugin, type PluginFactory, type PluginHooks, type PluginLifecycleManager, type PluginLifecycleOptions, type PluginOptions, PluginsAPI, type ProcessResponseOptions, type ProcessingConfig, type QueryParams, RateLimitError, type RateLimitErrorDetails, type ReconnectStrategy, type RegistryResult, type ReloadMetrics, type RequestHandler, type RequestOptions, type RequestParams, RequestTimeoutError, type Result, type Route, type RouteDefinition, type RouteEntry, type RouteHandler, type RouteMatch, type RouteMethodOptions, type RouteNode, type RouteOptions, type RouteRegistry, type RouteSchema, type Router, RouterAPI, type RouterOptions, type SSEBufferOverflowErrorDetails, type SSEBufferStrategy, type SSEClient, type SSEClientMetrics, type SSEClientOptions, type SSEConnectionErrorContext, type SSEConnectionErrorDetails, type SSEConnectionFactory, type SSEConnectionState, type SSEEvent, type SSEEventHandler, type SSEEventListener, type SSEHeartbeatErrorContext, type SSEMetrics, type SSEOptions, type SSERouteHandler, type SSERouteSchema, type SSESerializedEvent, type SSEStream, type SSEStreamClosedErrorDetails, type SSEStreamErrorContext, type SSEStreamExtended, type SSEStreamManager, type SafeComposeMiddlewareServices, type SafeComposeMiddlewareStates, type SafeComposePluginServices, type SafeComposePluginStates, type SafeExtractMiddlewareServices, type SafeExtractMiddlewareState, type SafeExtractPluginServices, type SafeExtractPluginState, type Server, ServerAPI, type ServerOptions, type ServerOptionsInput, type ServiceNotAvailableDetails, ServiceNotAvailableError, type Services, type StandardErrorResponse, type StartOptions, type State, type StopOptions, type StreamMetrics, type StreamOptions, type TimeoutErrorContext, type TypedSSEStream, UnauthorizedError, type UnauthorizedErrorDetails, type UnifiedRequest, type UnifiedResponse, type UnionToIntersection, type UnknownFunction, type UnknownServer, UnprocessableEntityError, UnsupportedMediaTypeError, type UnsupportedMediaTypeErrorDetails, type UploadProgress, type UploadedFile, VERSION, type ValidationConfig, ValidationError, type ValidationErrorDetails, type ValidationFieldError, type WatchOptions, asMiddlewareArray, asPluginArray, buildUrl, compilePathPattern, compose, cors, createDeleteRoute, createGetRoute, createHeadRoute, createMatcher, create$1 as createMiddleware, createMiddlewareArray, createOptionsRoute, createPatchRoute, createPlugin, createPluginArray, createPostRoute, createPutRoute, createRouteFactory, create as createServer, serviceMiddleware as createServiceMiddleware, stateMiddleware as createStateMiddleware, extractParams, getCorrelationId, inferContext, isMiddleware, isPlugin, paramsToQuery };