Merge pull request #108 from bufferings/work

Remove response abort functionality and simplify hook return mechanism

Author: bufferings

.changeset/remove-response-abort.md

@@ -0,0 +1,9 @@
+---
+'@korix/kori': patch
+'@korix/body-limit-plugin': patch
+'@korix/cors-plugin': patch
+---
+
+Remove response abort functionality and simplify hook return mechanism
+
+This change eliminates the complex abort pattern in favor of direct response returns from hooks, making the API more intuitive and reducing cognitive overhead for developers. Hooks can now return KoriResponse directly for early termination instead of using the abort mechanism.

docs/en/guide/context-evolution.md

@@ -9,7 +9,7 @@ Use method chaining to ensure type extensions are properly inherited:
 ```typescript
 // ✅ Good: Chained hooks preserve type extensions
 const app = createKori()
-  .onInit(async (ctx) => {
+  .onStart(async (ctx) => {
     const db = await connectDatabase();
     return ctx.withEnv({ db });
   })
@@ -20,13 +20,13 @@ const app = createKori()
   })
   .onRequest((ctx) => {
     // Both ctx.env.db and ctx.req.user are typed
-    ctx.req.log().info('Request', { userId: ctx.req.user?.id });
+    ctx.log().info('Request', { userId: ctx.req.user?.id });
   });
 
 // ❌ Avoid: Separate calls lose type information
 const app = createKori();
 
-app.onInit(async (ctx) => {
+app.onStart(async (ctx) => {
   const db = await connectDatabase();
   return ctx.withEnv({ db });
 }); // Type extension is lost
@@ -51,7 +51,7 @@ const app = createKori()
   // 2. Request ID tracking
   .onRequest((ctx) => {
     const requestId = crypto.randomUUID();
-    ctx.req.log().info('Request started', { requestId });
+    ctx.log().info('Request started', { requestId });
     return ctx.withReq({ requestId });
   })
   // 3. Timing
@@ -71,7 +71,7 @@ const app = createKori()
 
 // All extensions are available
 app.get('/api/data', (ctx) => {
-  ctx.req.log().info('Processing request', {
+  ctx.log().info('Processing request', {
     requestId: ctx.req.requestId,
     user: ctx.req.user?.id,
   });

docs/en/guide/error-handling.md

@@ -1,10 +1,10 @@
 # Error Handling
 
-Kori provides comprehensive error handling with built-in error responses, automatic content negotiation, and flexible error recovery patterns.
+Kori provides comprehensive error handling with built-in error responses and flexible error recovery patterns.
 
 ## Built-in Error Responses
 
-Kori includes ready-to-use error response methods that automatically format based on the client's `Accept` header:
+Kori includes ready-to-use error response methods that set the appropriate HTTP status code and return a JSON body:
 
 ```typescript
 app.get('/users/:id', async (ctx) => {
@@ -27,87 +27,93 @@ app.get('/users/:id', async (ctx) => {
 
 ```typescript
 // 400 Bad Request
-ctx.res.badRequest({ message: 'Invalid input data' });
+ctx.res.badRequest();
 
 // 401 Unauthorized
-ctx.res.unauthorized({ message: 'Authentication required' });
+ctx.res.unauthorized();
 
 // 403 Forbidden
-ctx.res.forbidden({ message: 'Insufficient permissions' });
+ctx.res.forbidden();
 
 // 404 Not Found
-ctx.res.notFound({ message: 'Resource not found' });
+ctx.res.notFound();
 
 // 405 Method Not Allowed
-ctx.res.methodNotAllowed({ message: 'Only GET and POST allowed' });
+ctx.res.methodNotAllowed();
+
+// 415 Unsupported Media Type
+ctx.res.unsupportedMediaType();
+
+// 408 Request Timeout
+ctx.res.timeout();
 
 // 500 Internal Server Error
-ctx.res.internalError({ message: 'Something went wrong' });
+ctx.res.internalError();
 ```
 
 ### Error Response Format
 
-All error responses return JSON format with a consistent structure:
+All error responses return JSON format with a consistent structure.
+
+#### Default Responses
+
+Without custom options, each method returns a standard message:
+
+```typescript
+// Default usage
+ctx.res.notFound();
+```
 
 ```json
 {
   "error": {
     "type": "NOT_FOUND",
-    "message": "User with ID 123 not found",
-    "code": "USER_NOT_FOUND"
+    "message": "Not Found"
   }
 }
 ```
 
+#### Custom Responses
+
 You can include additional fields in the error response:
 
 ```typescript
+// Custom usage
 ctx.res.notFound({
   message: 'User with ID 123 not found',
   code: 'USER_NOT_FOUND',
   details: { userId: 123, searchedAt: new Date().toISOString() },
 });
 ```
 
+```json
+{
+  "error": {
+    "type": "NOT_FOUND",
+    "message": "User with ID 123 not found",
+    "code": "USER_NOT_FOUND",
+    "details": {
+      "userId": 123,
+      "searchedAt": "2024-01-15T10:30:00.000Z"
+    }
+  }
+}
+```
+
 ## Global Error Handling
 
 Set up application-wide error handling with the `onError` hook:
 
 ```typescript
 const app = createKori().onError((ctx, error) => {
   // Log the error
-  ctx.req.log().error('Request failed', {
+  ctx.log().error('Request failed', {
     error: error.message,
     stack: error.stack,
     url: ctx.req.url().pathname,
   });
 
   // Return appropriate response
-  if (!ctx.res.isReady()) {
-    ctx.res.internalError({ message: 'Internal Server Error' });
-  }
-});
-```
-
-### Error Recovery Patterns
-
-Handle specific errors locally and let the global handler manage unexpected ones:
-
-```typescript
-app.get('/api/data', async (ctx) => {
-  try {
-    const data = await fetchExternalAPI();
-    return ctx.res.json(data);
-  } catch (error) {
-    if (error.code === 'NETWORK_ERROR') {
-      return ctx.res.badRequest({
-        message: 'External service unavailable',
-        code: 'SERVICE_UNAVAILABLE',
-      });
-    }
-
-    // Re-throw for global handler
-    throw error;
-  }
+  return ctx.res.internalError({ message: 'Internal Server Error' });
 });
 ```

docs/en/guide/getting-started.md

@@ -63,29 +63,37 @@ Monitor your application with built-in structured logging:
 ```typescript
 import { createKori } from '@korix/kori';
 
-const app = createKori().onInit(async (ctx) => {
-  // Application-level logging (for system events)
-  app.log().info('Application initializing');
+const app = createKori().onStart((ctx) => {
+  // Instance-level logging (within hooks)
+  ctx.log().info('Application initializing');
 });
 
 app.get('/hello', (ctx) => {
-  // Request-level logging (includes request context automatically)
-  ctx.req.log().info('Processing hello request');
+  // Request-level logging (within handlers)
+  ctx.log().info('Processing hello request');
 
   return ctx.res.text('Hello, Kori!');
 });
 
+// Application-level logging (outside of Kori context)
+app.log().info('Application ready');
+
 export { app };
 ```
 
+- **`app.log()`** - Application-level logger (outside of Kori context)
+- **`ctx.log()`** - Context-aware logger (inside Kori context: hooks and handlers)
+
 Sample log output:
 
 ```json
-{"level":"info","time":1704067200000,"name":"application","message":"Application initializing"}
-{"level":"info","time":1704067200100,"name":"request","message":"Processing hello request"}
+{"time":1754198335875,"level":"info","channel":"app","name":"instance","message":"Application ready","meta":{}}
+{"time":1754198335875,"level":"info","channel":"app","name":"instance","message":"Application initializing","meta":{}}
+{"time":1754198335879,"level":"info","channel":"sys","name":"instance","message":"Kori server started at http://127.0.0.1:3000","meta":{}}
+{"time":1754198349150,"level":"info","channel":"app","name":"request","message":"Processing hello request","meta":{}}
 ```
 
-Kori provides a simple console logger by default for quick development. For real applications, use high-performance loggers like Pino. We provide a Pino adapter for easy integration.
+Kori provides a simple console logger by default for quick development. For real applications, use high-performance loggers like Pino or LogTape. We provide the adapters for easy integration.
 
 ## Hooks
 
@@ -95,17 +103,18 @@ Add initialization and request lifecycle processing:
 import { createKori } from '@korix/kori';
 
 const app = createKori()
-  .onInit(async (ctx) => {
+  .onStart((ctx) => {
     // Runs once when application starts
     return ctx.withEnv({ applicationStartTime: new Date() });
   })
   .onRequest((ctx) => {
     // Runs before each request handler
-    ctx.req.log().info(`${ctx.req.method()} ${ctx.req.url().pathname}`);
-  })
-  .onResponse((ctx) => {
-    // Runs after each successful response
-    ctx.req.log().info(`Response: ${ctx.res.status()}`);
+    ctx.log().info(`${ctx.req.method()} ${ctx.req.url().pathname}`);
+
+    // Defer response logging until after handler completes
+    ctx.defer(() => {
+      ctx.log().info(`Response: ${ctx.res.getStatus()}`);
+    });
   });
 
 app.get('/hello', (ctx) => {

docs/en/guide/handler-context.md

@@ -11,12 +11,19 @@ type KoriHandlerContext<Env, Req, Res> = {
   env: Env; // Application environment
   req: Req; // Request object
   res: Res; // Response builder
+
   withReq<ReqExt>(reqExt: ReqExt): KoriHandlerContext<Env, Req & ReqExt, Res>;
   withRes<ResExt>(resExt: ResExt): KoriHandlerContext<Env, Req, Res & ResExt>;
+
+  defer(
+    callback: (ctx: KoriHandlerContext<Env, Req, Res>) => Promise<void> | void,
+  ): void;
+
+  log(): KoriLogger;
 };
 ```
 
-**Perfect for:**
+**Used for:**
 
 - Processing HTTP requests
 - Accessing request data
@@ -30,7 +37,7 @@ Handler context supports request and response extensions for adding custom funct
 Every route handler receives a `ctx` parameter containing environment, request, and response:
 
 ```typescript
-app.get('/api/users/:id', (ctx) => {
+app.get('/api/users/:id', async (ctx) => {
   // ctx.env - application environment
   // ctx.req - request data and methods
   // ctx.res - response building methods
@@ -63,7 +70,7 @@ app.get('/users', async (ctx) => {
 Access all incoming request data:
 
 ```typescript
-app.get('/users/:id/posts', (ctx) => {
+app.get('/users/:id/posts', async (ctx) => {
   // Path parameters
   const { id } = ctx.req.pathParams();
 
@@ -204,3 +211,38 @@ app.get('/users', async (ctx) => {
   }
 });
 ```
+
+## Deferred Processing (`ctx.defer()`)
+
+Schedule tasks to run after the handler completes but before the response is returned. Commonly used in `onRequest` hooks, but also available in handlers.
+
+### In onRequest Hook (Recommended)
+
+```typescript
+const app = createKori().onRequest((ctx) => {
+  // Add request ID for tracking
+  const requestId = crypto.randomUUID();
+
+  // Schedule post-response cleanup
+  ctx.defer(() => {
+    // Clean up request-specific resources
+    // Update metrics, close connections, etc.
+  });
+
+  return ctx.withReq({ requestId });
+});
+```
+
+### In Handler (When Needed)
+
+```typescript
+app.post('/api/process', async (ctx) => {
+  // Schedule cleanup for after response
+  ctx.defer(() => {
+    // Clean up temporary resources, update metrics, etc.
+  });
+
+  const result = await processData();
+  return ctx.res.json({ result });
+});
+```