Merge pull request #157 from bufferings/work

Fix documentation errors and improve code examples

Author: bufferings

README.md

@@ -55,7 +55,7 @@ app.get('/greeting', (ctx) => {
 
 // With path parameter
 app.get('/greeting/:name', (ctx) => {
-  const { name } = ctx.req.pathParams();
+  const { name } = ctx.req.params();
   return ctx.res.json({ message: `Hello, ${name}!` });
 });
 ```
@@ -308,6 +308,7 @@ Now you can visit http://localhost:3000/docs for interactive API documentation.
 - [`@korix/kori`](./packages/kori) - Core framework
 - [`@korix/nodejs-server`](./packages/nodejs-server) - Node.js HTTP server adapter
 - [`@korix/zod-schema-adapter`](./packages/zod-schema-adapter) - Zod schema adapter for request and response validation
+- [`@korix/standard-schema-adapter`](./packages/standard-schema-adapter) - Standard Schema adapter for validation with other schema libraries
 - [`@korix/zod-openapi-plugin`](./packages/zod-openapi-plugin) - OpenAPI document generation from Zod schemas
 - [`@korix/openapi-swagger-ui-plugin`](./packages/openapi-swagger-ui-plugin) - Interactive API documentation with Swagger UI
 

docs/en/guide/getting-started.md

@@ -14,18 +14,46 @@ Your API is running at `http://localhost:3000`
 
 ## Basic API
 
-Create your first endpoint:
+Create your first endpoint and run it:
 
 ```typescript
 import { createKori } from '@korix/kori';
+import { startNodejsServer } from '@korix/nodejs-server';
 
 const app = createKori();
 
 app.get('/hello', (ctx) => {
   return ctx.res.text('Hello, Kori!');
 });
 
-export { app };
+await startNodejsServer(app, { port: 3000 });
+```
+
+Your API is now running at `http://localhost:3000/hello`
+
+## Running the Server
+
+### Node.js Server
+
+The example above uses the Node.js server adapter. You can also configure hostname and other options:
+
+```typescript
+await startNodejsServer(app, {
+  port: 3000,
+  hostname: 'localhost',
+});
+```
+
+### Testing & Custom Environments
+
+For testing or custom deployments, you can use the `.start()` method to initialize the application and get a fetch handler:
+
+```typescript
+// Initialize the application
+const { fetchHandler } = await app.start();
+
+// Use the fetch handler directly (e.g., in tests)
+const response = await fetchHandler(new Request('http://localhost/hello'));
 ```
 
 ## Request & Response
@@ -81,8 +109,8 @@ app.log().info('Application will start');
 export { app };
 ```
 
-- **`app.log()`** - Application-level logger (outside of Kori context)
-- **`ctx.log()`** - Context-aware logger (inside Kori context: hooks and handlers)
+- `app.log()` - Application-level logger (outside of Kori context)
+- `ctx.log()` - Context-aware logger (inside Kori context: hooks and handlers)
 
 Sample log output:
 
@@ -206,9 +234,11 @@ Generate interactive API documentation from your validation schemas:
 
 ```typescript
 import { createKori } from '@korix/kori';
+import { startNodejsServer } from '@korix/nodejs-server';
 import {
   zodRequestSchema,
-  enableZodRequestValidation,
+  zodResponseSchema,
+  enableZodRequestAndResponseValidation,
 } from '@korix/zod-schema-adapter';
 import { zodOpenApiPlugin } from '@korix/zod-openapi-plugin';
 import { swaggerUiPlugin } from '@korix/openapi-swagger-ui-plugin';
@@ -219,27 +249,29 @@ const CreateUserSchema = z.object({
   age: z.number().int().min(0).optional(),
 });
 
+const UserResponseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  age: z.number().optional(),
+  createdAt: z.string(),
+});
+
 const app = createKori({
-  ...enableZodRequestValidation(),
+  ...enableZodRequestAndResponseValidation(),
 })
-  // Generate OpenAPI specification from Zod schemas
   .applyPlugin(
     zodOpenApiPlugin({
       info: { title: 'My API', version: '1.0.0' },
     }),
   )
-  // Serve interactive documentation UI
   .applyPlugin(swaggerUiPlugin());
 
 app.post('/users', {
   requestSchema: zodRequestSchema({ body: CreateUserSchema }),
-  responseSchema: zodResponseSchema({ default: z.any() }),
+  responseSchema: zodResponseSchema({ '201': UserResponseSchema }),
   handler: (ctx) => {
-    // Type-safe validated body access
     const { name, age } = ctx.req.validatedBody();
 
-    // Your business logic here (save to database, etc.)
-
     return ctx.res.status(201).json({
       id: '42',
       name,
@@ -249,7 +281,7 @@ app.post('/users', {
   },
 });
 
-export { app };
+await startNodejsServer(app, { port: 3000 });
 ```
 
 Visit `http://localhost:3000/docs` for interactive documentation!

docs/en/guide/handler-context.md

@@ -1,10 +1,10 @@
 # Handler Context
 
-The **Handler Context** manages request processing - accessing request data, building responses, and extending functionality per request. It's passed to every route handler and contains everything you need to process HTTP requests.
+The Handler Context manages request processing - accessing request data, building responses, and extending functionality per request. It's passed to every route handler and contains everything you need to process HTTP requests.
 
 ## What is Handler Context?
 
-The **KoriHandlerContext** is passed to every route handler and gives you access to request data, response builders, and the application environment:
+The KoriHandlerContext is passed to every route handler and gives you access to request data, response builders, and the application environment:
 
 ```typescript
 type KoriHandlerContext<Env, Req, Res> = {
@@ -23,14 +23,7 @@ type KoriHandlerContext<Env, Req, Res> = {
 };
 ```
 
-**Used for:**
-
-- Processing HTTP requests
-- Accessing request data
-- Building responses
-- Per-request logic
-
-Handler context supports request and response extensions for adding custom functionality.
+Use it for processing HTTP requests, accessing request data, building responses, and per-request logic. Handler context supports request and response extensions for adding custom functionality.
 
 ## Basic Usage
 
@@ -91,6 +84,13 @@ app.get('/users/:id/posts', async (ctx) => {
   const textData = await ctx.req.bodyText();
   const formData = await ctx.req.bodyFormData();
 
+  // Validated data (when using requestSchema)
+  // const { ... } = ctx.req.validatedParams();
+  // const { ... } = ctx.req.validatedQueries();
+  // const { ... } = ctx.req.validatedHeaders();
+  // const { ... } = ctx.req.validatedCookies();
+  // const { ... } = ctx.req.validatedBody();
+
   return ctx.res.json({
     userId: id,
     query: { limit, offset },

docs/en/guide/hook-execution.md

@@ -50,7 +50,7 @@ Request hooks execute for every matching request.
 
 Key behaviors:
 
-- `defer` callbacks execute in **reverse order** (LIFO)
+- `defer` callbacks execute in reverse order (LIFO)
 - `onRequest` can stop processing by returning a response
 - Hooks are captured when you define routes, not when requests arrive
 
@@ -127,8 +127,8 @@ app.get('/protected', (ctx) => {
 
 When an error occurs, `onError` hooks replace the normal execution flow:
 
-**Normal flow**: `onRequest` → Route Handler → `defer` callbacks
-**Error flow**: `onRequest` → Error occurs → `onError` hooks → `defer` callbacks
+- Normal flow: `onRequest` → Route Handler → `defer` callbacks
+- Error flow: `onRequest` → Error occurs → `onError` hooks → `defer` callbacks
 
 ```typescript
 const app = createKori()

docs/en/guide/instance-context.md

@@ -1,10 +1,10 @@
 # Instance Context
 
-The **Instance Context** manages your application's lifecycle - initialization, configuration, and shutdown. It's where you set up shared resources and configure your application environment.
+The Instance Context manages your application's lifecycle - initialization, configuration, and shutdown. It's where you set up shared resources and configure your application environment.
 
 ## What is Instance Context?
 
-The **KoriInstanceContext** handles application-wide concerns that happen once when your app starts up or shuts down:
+The KoriInstanceContext handles application-wide concerns that happen once when your app starts up or shuts down:
 
 ```typescript
 type KoriInstanceContext<Env extends KoriEnvironment> = {
@@ -20,11 +20,7 @@ type KoriInstanceContext<Env extends KoriEnvironment> = {
 };
 ```
 
-**Used for:**
-
-- Setting up database connections
-- Loading configuration
-- Initializing shared services
+Use it for setting up database connections, loading configuration, and initializing shared services.
 
 ## Context Extensions
 

docs/en/guide/openapi.md

@@ -20,6 +20,7 @@ import { zodOpenApiPlugin, openApiMeta } from '@korix/zod-openapi-plugin';
 import { swaggerUiPlugin } from '@korix/openapi-swagger-ui-plugin';
 import {
   zodRequestSchema,
+  zodResponseSchema,
   enableZodRequestValidation,
 } from '@korix/zod-schema-adapter';
 
@@ -66,6 +67,11 @@ const UserSchema = z.object({
   }),
 });
 
+const UserResponseSchema = z.object({
+  user: UserSchema,
+  message: z.string(),
+});
+
 // Add to your route
 app.post('/users', {
   pluginMeta: openApiMeta({
@@ -77,7 +83,7 @@ app.post('/users', {
     body: UserSchema,
   }),
   responseSchema: zodResponseSchema({
-    default: z.any(),
+    '201': UserResponseSchema,
   }),
   handler: (ctx) => {
     const user = ctx.req.validatedBody();
@@ -130,7 +136,11 @@ app.get('/products/:id', {
     }),
   }),
   responseSchema: zodResponseSchema({
-    default: z.any(),
+    '200': z.object({
+      id: z.number(),
+      name: z.string(),
+      price: z.number(),
+    }),
   }),
   handler: (ctx) => {
     const { id } = ctx.req.validatedParams();
@@ -366,9 +376,9 @@ app.post('/users', {
       email: z.string(),
     }),
   }),
-  handler: (ctx) => {
+  handler: async (ctx) => {
     // Handle request without automatic validation
-    const body = ctx.req.bodyJson(); // Returns unknown, not validated
+    const body = await ctx.req.bodyJson(); // Returns unknown, not validated
 
     // Your custom validation logic here
 

docs/en/guide/plugins.md

@@ -308,10 +308,10 @@ export function authPlugin<
 
 Plugin-specific loggers provide several advantages:
 
-- **Namespace isolation**: Logs are automatically prefixed with `plugin.{pluginName}`
-- **Better debugging**: Easy to filter logs by specific plugins
-- **Consistent formatting**: Inherits all bindings from the base logger
-- **Channel separation**: Plugin logs use dedicated channels for organization
+- Namespace isolation: Logs are automatically prefixed with `plugin.{pluginName}`
+- Better debugging: Easy to filter logs by specific plugins
+- Consistent formatting: Inherits all bindings from the base logger
+- Channel separation: Plugin logs use dedicated channels for organization
 
 ### Logger Output
 

docs/en/guide/request-validation.md

@@ -79,6 +79,10 @@ app.put('/users/:id', {
     headers: z.object({
       authorization: z.string().startsWith('Bearer '),
     }),
+    cookies: z.object({
+      sessionId: z.uuid(),
+      theme: z.enum(['light', 'dark']).optional(),
+    }),
     body: z.object({
       name: z.string().min(1).optional(),
       age: z.number().int().min(0).optional(),
@@ -89,13 +93,15 @@ app.put('/users/:id', {
     const { id } = ctx.req.validatedParams();
     const { notify, include } = ctx.req.validatedQueries();
     const { authorization } = ctx.req.validatedHeaders();
+    const { sessionId, theme } = ctx.req.validatedCookies();
     const updates = ctx.req.validatedBody();
 
     return ctx.res.json({
       userId: id,
       updates,
       willNotify: notify ?? false,
       token: authorization,
+      session: { id: sessionId, theme },
     });
   },
 });
@@ -143,6 +149,42 @@ app.post('/users', {
 });
 ```
 
+## Body Parse Type
+
+When defining content types, you can explicitly control how the request body is parsed using the `parseType` option. This is useful for non-standard content types or when you want to force a specific parsing method.
+
+The available parse types are: `'json'`, `'form'`, `'text'`, `'binary'`, and `'auto'` (default).
+
+```typescript
+const WebhookSchema = z.object({
+  event: z.string(),
+  payload: z.record(z.unknown()),
+});
+
+app.post('/webhook', {
+  requestSchema: zodRequestSchema({
+    body: {
+      content: {
+        // Parse custom content type as JSON
+        'application/vnd.custom+json': {
+          schema: WebhookSchema,
+          parseType: 'json',
+        },
+        // Parse binary data
+        'application/octet-stream': {
+          schema: z.instanceof(ArrayBuffer),
+          parseType: 'binary',
+        },
+      },
+    },
+  }),
+  handler: (ctx) => {
+    const body = ctx.req.validatedBody();
+    // ...
+  },
+});
+```
+
 ## Error Handling
 
 Kori provides flexible error handling for validation failures with multiple levels of customization.

docs/en/guide/routing.md

@@ -92,12 +92,12 @@ app.get('/files/:id{[0-9]+}', (ctx) => {
 
 The type inference works by parsing the route string at compile time and extracting parameter names, helping prevent typos and improve IDE autocompletion.
 
-**Important:** Type inference only works when you pass the route path as a string literal directly to the route method. It does **not** work for:
+Note that type inference only works when you pass the route path as a string literal directly to the route method. It does not work for:
 
-- Routes defined with variables: `const path = '/users/:id'; app.get(path, ...)` - no inference
-- Path parameters from parent routes (defined in `createChild` prefix) - these are not included in the inferred type
+- Routes defined with variables: `const path = '/users/:id'; app.get(path, ...)`
+- Path parameters from parent routes (defined in `createChild` prefix)
 
-Only parameters defined directly in the string literal of the route method itself will be type-safe.
+These parameters can still be accessed at runtime, but without autocomplete and typed as `string | undefined`.
 
 ### Accessing Individual Parameters