@a_jackie_z/fastify 1.0.0 → 1.0.1

package/README.md

@@ -13,7 +13,7 @@ npm install @a_jackie_z/fastify
 ### Basic Setup
 
 ```typescript
-import { createFastify } from '@a_jackie_z/fastify'
+import { createFastify, runFastify } from '@a_jackie_z/fastify'
 import { Type } from '@sinclair/typebox'
 
 const app = await createFastify()
@@ -33,26 +33,31 @@ app.route({
   },
 })
 
-await app.listen({ port: 3000 })
+await runFastify(app, '0.0.0.0', 3000)
 ```
 
 ## Features
 
 - **JWT Authentication** - Built-in JWT support with global and route-level configuration
-- **Rate Limiting** - Flexible rate limiting at global and route levels
+- **Rate Limiting** - Global rate limiting for API protection
 - **Swagger Documentation** - Auto-generated API documentation with TypeBox schemas
 - **TypeBox Integration** - Type-safe request/response validation
-- **Logger Integration** - Uses `@a_jackie_z/logger` for consistent logging
+- **Custom Logger Support** - Integrate any Fastify-compatible logger
+- **Health Check Plugin** - Ready-to-use health check endpoint
+- **Plugin Helper** - Utility for creating reusable Fastify plugins
 
 ## Examples
 
 ### 1. Complete Setup with All Features
 
 ```typescript
-import { createFastify } from '@a_jackie_z/fastify'
+import { createFastify, runFastify } from '@a_jackie_z/fastify'
 import { Type } from '@sinclair/typebox'
 
 const app = await createFastify({
+  // Optional: Integrate your logger
+  // logger: yourFastifyLogger,
+  
   // Rate limiting
   rateLimit: {
     global: {
@@ -77,7 +82,7 @@ const app = await createFastify({
   },
 })
 
-await app.listen({ port: 3000 })
+await runFastify(app, '0.0.0.0', 3000)
 ```
 
 ### 2. Authentication Flow
@@ -259,42 +264,52 @@ app.route({
 })
 ```
 
-### 6. Rate Limiting
-
-#### Route-Specific Rate Limit
+### 6. Health Check Plugin
 
 ```typescript
-app.route({
-  method: 'GET',
-  url: '/limited',
-  config: {
-    rateLimit: {
-      max: 5,
-      timeWindow: '1 minute',
-    },
-  },
-  handler: async () => {
-    return { message: 'Strict rate limiting applied' }
-  },
-})
+import { createFastify, runFastify, healthPlugin } from '@a_jackie_z/fastify'
+
+const app = await createFastify()
+
+// Register health check plugin
+await app.register(healthPlugin)
+
+// Health endpoint available at: GET /v1/health
+// Response: { status: 200, message: 'ok' }
+
+await runFastify(app, '0.0.0.0', 3000)
 ```
 
-#### Disable Rate Limit for Specific Route
+### 7. Creating Custom Plugins
 
 ```typescript
-app.route({
-  method: 'GET',
-  url: '/unlimited',
-  config: {
-    rateLimit: false,
-  },
-  handler: async () => {
-    return { message: 'No rate limiting' }
-  },
+import { createFastify, runFastify, createFastifyPlugin } from '@a_jackie_z/fastify'
+import { Type } from '@sinclair/typebox'
+
+// Create a reusable plugin
+const myPlugin = createFastifyPlugin((app) => {
+  app.get('/plugin-route', {
+    schema: {
+      response: {
+        200: Type.Object({
+          message: Type.String(),
+        }),
+      },
+    },
+    handler: async () => {
+      return { message: 'From plugin' }
+    },
+  })
 })
+
+// Use the plugin
+const app = await createFastify()
+await app.register(myPlugin)
+
+await runFastify(app, '0.0.0.0', 3000)
 ```
 
-### 7. TypeBox Schema Validation
+### 8. TypeBox Schema Validation
 
 ```typescript
 app.route({
@@ -334,6 +349,7 @@ app.route({
 
 ```typescript
 interface CreateFastifyOptions {
+  logger?: FastifyServerOptions['loggerInstance'],
   rateLimit?: {
     global?: RateLimitPluginOptions
   }
@@ -347,7 +363,7 @@ interface CreateFastifyOptions {
     title: string
     version: string
     description: string
-    routePrefix?: string // Default: '/documentation'
+    routePrefix?: string // Default: '/docs/'
   }
 }
 ```
@@ -371,6 +387,27 @@ type JWTAuthorizationHandler = (
 ) => Promise<boolean> | boolean
 ```
 
+## API Reference
+
+### `createFastify(options?: CreateFastifyOptions): Promise<FastifyServer>`
+
+Creates and configures a Fastify server instance with TypeBox support and optional plugins.
+
+### `runFastify(fastify: FastifyServer, host: string, port: number): Promise<void>`
+
+Starts the Fastify server. Handles errors and exits the process if the server fails to start.
+
+**Parameters:**
+- `fastify` - The Fastify server instance
+- `host` - The host to bind to (e.g., '0.0.0.0' or 'localhost')
+- `port` - The port number to listen on
+
+**Example:**
+```typescript
+const app = await createFastify()
+await runFastify(app, '0.0.0.0', 3000)
+```
+
 ## Usage Patterns
 
 ### Pattern 1: Global JWT with Selective Public Routes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a_jackie_z/fastify",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A collection of Fastify plugins and utilities for building robust web applications.",
   "license": "MIT",
   "author": "Sang Lu <connect.with.sang@gmail.com>",