Migrate io-ts-http documentation to Docusaurus website following Diátaxis framework

Update documentation to follow Microsoft Writing Style Guide

chore: prettier

Remove io-ts-http-documentation-migration-plan.md

Author: youngjungithub

Diff for: packages/io-ts-http/README.md

@@ -0,0 +1,112 @@
+---
+sidebar_position: 2
+---
+
+# Understanding io-ts-http
+
+## Introduction
+
+Use `io-ts-http` as the definition language for api-ts specifications. It helps you
+define precise API contracts for web servers. This article explains the key concepts and
+design principles behind `io-ts-http`.
+
+## Core concepts
+
+### API contract as a type system
+
+Express your API contract through TypeScript's type system with runtime validation using
+`io-ts`. This approach offers three main benefits:
+
+1. **Type safety**: Use the same types for both clients and servers to ensure
+   compatibility.
+2. **Runtime validation**: Validate data at runtime, unlike TypeScript's types which are
+   erased during compilation.
+3. **Parse, don't validate**: Not only validate input but also parse it into the correct
+   shape and types.
+
+### Building blocks
+
+`io-ts-http` has three main components:
+
+1. **`apiSpec`**: Create the top-level definition of your API and organize routes under
+   operation names.
+2. **`httpRoute`**: Define individual routes with their paths, methods, request schemas,
+   and response schemas.
+3. **`httpRequest`**: Specify the expected shape of HTTP requests, including parameters,
+   query strings, headers, and bodies.
+
+## How it works
+
+When you define an API with `io-ts-http`, you create a specification that works in
+multiple ways:
+
+1. **Server-side**: Validate and parse incoming requests to ensure they match your API
+   contract.
+2. **Client-side**: Ensure requests are properly formed before sending them to the
+   server.
+3. **Documentation**: Generate API documentation such as OpenAPI specifications.
+
+The same specification works everywhere, eliminating discrepancies between your
+implementation and documentation.
+
+### Property flattening
+
+Property flattening is an important concept in `io-ts-http`. When you decode HTTP
+requests, the system flattens properties from different sources (path parameters, query
+parameters, headers, and body) into a single object.
+
+For example, if you have:
+
+- A path parameter `id`
+- A query parameter `filter`
+- A body with properties `name` and `email`
+
+The decoded object becomes:
+
+```typescript
+{
+  id: string,
+  filter: string,
+  name: string,
+  email: string
+}
+```
+
+This makes it easier to work with the data without accessing different parts of the
+request separately.
+
+## Design principles
+
+### 1. Type safety first
+
+`io-ts-http` prioritizes type safety. It uses `io-ts` codecs to ensure your API
+contracts are type-checked at compile time and validated at runtime.
+
+### 2. Separation of concerns
+
+The library separates:
+
+- Defining what your API looks like (`apiSpec` and `httpRoute`)
+- Defining how requests and responses should be structured (`httpRequest`)
+- Processing HTTP requests and responses (handled by other packages)
+
+### 3. Flexibility
+
+`io-ts-http` is flexible. It doesn't dictate how to implement your server or client—only
+how to define your API contract. You can use it with any HTTP framework or client
+library.
+
+## When to use io-ts-http
+
+Use `io-ts-http` when you need to:
+
+1. Build a TypeScript API with type safety between client and server
+2. Validate complex request structures with nested objects, arrays, or optional fields
+3. Generate documentation from your code to keep it current
+4. Implement the "Parse, Don't Validate" pattern for robust error handling
+
+## Conclusion
+
+`io-ts-http` offers a powerful way to define type-safe API contracts for your entire
+application stack. By centralizing your API definition in a single source of truth, you
+can ensure consistency and reduce errors in your application.

Diff for: website/docs/explanation/io-ts-http-concepts.md

@@ -0,0 +1,234 @@
+# Advanced HTTP route patterns
+
+Learn advanced patterns for defining HTTP routes with `io-ts-http` beyond the basic
+usage examples.
+
+## Work with non-object body types
+
+By default, `httpRequest` assumes the request body is a JSON object. Sometimes you need
+to accept other types like strings, numbers, or arrays.
+
+### Accept a string body
+
+Use `t.intersection` to combine `httpRequest` with a custom type that accepts a string
+body:
+
+```typescript
+import * as t from 'io-ts';
+import { httpRoute, httpRequest } from '@api-ts/io-ts-http';
+
+const StringBodyRoute = httpRoute({
+  path: '/example/{id}',
+  method: 'POST',
+  request: t.intersection([
+    httpRequest({
+      params: { id: t.string },
+    }),
+    t.type({
+      body: t.string,
+    }),
+  ]),
+  response: {
+    200: t.string,
+  },
+});
+
+// Decoded type
+type DecodedType = {
+  id: string;
+  body: string;
+};
+```
+
+This approach breaks the abstraction slightly by exposing a `body` property in the
+decoded type, but it works effectively.
+
+### Accept an array body
+
+Similarly, accept an array body:
+
+```typescript
+const ArrayBodyRoute = httpRoute({
+  path: '/batch-process',
+  method: 'POST',
+  request: t.intersection([
+    httpRequest({}),
+    t.type({
+      body: t.array(t.string),
+    }),
+  ]),
+  response: {
+    200: t.type({
+      processed: t.number,
+    }),
+  },
+});
+
+// Decoded type
+type DecodedType = {
+  body: string[];
+};
+```
+
+## Create conditional request parameters
+
+Sometimes you need parameters that are required only when other parameters have specific
+values.
+
+### Use union types
+
+Use `t.union` with multiple `httpRequest` objects to handle conditional parameters:
+
+```typescript
+const SearchRoute = httpRoute({
+  path: '/search',
+  method: 'GET',
+  request: t.union([
+    // When searching by keyword
+    httpRequest({
+      query: {
+        type: t.literal('keyword'),
+        keyword: t.string,
+      },
+    }),
+    // When searching by category
+    httpRequest({
+      query: {
+        type: t.literal('category'),
+        categoryId: NumberFromString,
+      },
+    }),
+    // When searching by both
+    httpRequest({
+      query: {
+        type: t.literal('combined'),
+        keyword: t.string,
+        categoryId: NumberFromString,
+      },
+    }),
+  ]),
+  response: {
+    200: t.array(
+      t.type({
+        id: t.string,
+        title: t.string,
+      }),
+    ),
+  },
+});
+
+// Decoded type will be a union:
+type DecodedType =
+  | { type: 'keyword'; keyword: string }
+  | { type: 'category'; categoryId: number }
+  | { type: 'combined'; keyword: string; categoryId: number };
+```
+
+## Add optional headers
+
+HTTP headers are often optional. Use the `optional` combinator to define optional
+headers:
+
+```typescript
+import { httpRequest, optional } from '@api-ts/io-ts-http';
+
+const RequestWithOptionalHeaders = httpRoute({
+  path: '/resource',
+  method: 'GET',
+  request: httpRequest({
+    headers: {
+      authorization: t.string,
+      'cache-control': optional(t.string),
+      'if-modified-since': optional(t.string),
+    },
+  }),
+  response: {
+    200: t.object,
+  },
+});
+
+// Decoded type
+type DecodedType = {
+  authorization: string;
+  'cache-control'?: string;
+  'if-modified-since'?: string;
+};
+```
+
+## Handle file uploads
+
+File uploads typically use `multipart/form-data` encoding. While `io-ts-http` doesn't
+directly support file uploads, you can treat the file as an opaque object in the type
+system and handle the file processing separately:
+
+```typescript
+const FileUploadRoute = httpRoute({
+  path: '/upload',
+  method: 'POST',
+  request: httpRequest({
+    body: {
+      // In the type system, just indicate a file is expected
+      // Your server framework will handle the actual file
+      file: t.unknown,
+      description: optional(t.string),
+    },
+  }),
+  response: {
+    200: t.type({
+      fileId: t.string,
+      size: t.number,
+    }),
+  },
+});
+```
+
+## Combine multiple request sources
+
+Sometimes you need to extract information from multiple sources, such as getting an ID
+from the path, authentication from headers, and data from the body:
+
+```typescript
+const ComplexRoute = httpRoute({
+  path: '/users/{userId}/profile',
+  method: 'PUT',
+  request: httpRequest({
+    params: {
+      userId: NumberFromString,
+    },
+    headers: {
+      authorization: t.string,
+    },
+    body: {
+      name: t.string,
+      email: t.string,
+      preferences: t.type({
+        theme: t.union([t.literal('light'), t.literal('dark')]),
+        notifications: t.boolean,
+      }),
+    },
+  }),
+  response: {
+    200: t.type({
+      success: t.boolean,
+    }),
+  },
+});
+
+// Decoded type
+type DecodedType = {
+  userId: number;
+  authorization: string;
+  name: string;
+  email: string;
+  preferences: {
+    theme: 'light' | 'dark';
+    notifications: boolean;
+  };
+};
+```
+
+## Summary
+
+These advanced patterns help you define complex HTTP routes that accurately reflect your
+API's requirements. By combining `io-ts` with `httpRequest` and `httpRoute`, you can
+create type-safe APIs with sophisticated validation logic.