@afoures/http-client 0.0.0 → 0.1.0

package/docs/schema-integration.md

@@ -0,0 +1,221 @@
+# Schema Integration
+
+`@afoures/http-client` uses the [Standard Schema spec](https://github.com/standard-schema/standard-schema) for schema validation. Any compliant library works.
+
+## Zod
+
+```typescript
+import { z } from 'zod'
+
+const endpoint = new Endpoint({
+  method: 'POST',
+  pathname: '/users',
+  body: {
+    schema: z.object({
+      name: z.string().min(1),
+      email: z.string().email(),
+    }),
+  },
+  data: {
+    schema: z.object({
+      id: z.string(),
+      name: z.string(),
+      createdAt: z.string().datetime(),
+    }),
+  },
+})
+```
+
+### Transforms
+
+Zod transforms work for both input and output:
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users',
+  query: {
+    schema: z.object({
+      page: z.number().transform(String), // number input, string output
+    }),
+  },
+  data: {
+    schema: z.object({
+      createdAt: z.string().transform(s => new Date(s)), // parse ISO to Date
+    }),
+  },
+})
+
+// Input: { page: 1 }
+// Query string: ?page=1
+// Response: { createdAt: "2024-01-15T10:30:00Z" }
+// Output: { createdAt: Date }
+```
+
+## ArkType
+
+```typescript
+import { type } from 'arktype'
+
+const endpoint = new Endpoint({
+  method: 'POST',
+  pathname: '/users',
+  body: {
+    schema: type({
+      name: 'string>0',
+      email: 'string',
+      age: 'number?',
+    }),
+  },
+  data: {
+    schema: type({
+      id: 'string',
+      name: 'string',
+      'email?': 'string',
+    }),
+  },
+})
+```
+
+### Transforms
+
+```typescript
+import { type } from 'arktype'
+
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users',
+  data: {
+    schema: type({
+      id: 'string',
+      'createdAt': 'string.parse(v => new Date(v))',
+    }),
+  },
+})
+```
+
+## Valibot
+
+```typescript
+import * as v from 'valibot'
+
+const endpoint = new Endpoint({
+  method: 'POST',
+  pathname: '/users',
+  body: {
+    schema: v.object({
+      name: v.pipe(v.string(), v.minLength(1)),
+      email: v.pipe(v.string(), v.email()),
+    }),
+  },
+  data: {
+    schema: v.object({
+      id: v.string(),
+      name: v.string(),
+    }),
+  },
+})
+```
+
+### Transforms
+
+```typescript
+import * as v from 'valibot'
+
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users',
+  data: {
+    schema: v.object({
+      id: v.string(),
+      createdAt: v.pipe(v.string(), v.transform(s => new Date(s))),
+    }),
+  },
+})
+```
+
+## Input vs Output Types
+
+Schemas define both input validation and output parsing:
+
+- **Input** (`Schema.infer_input`): What you pass to the endpoint
+- **Output** (`Schema.infer_output`): What you get back after validation/transforms
+
+```typescript
+const schema = z.object({
+  id: z.string().transform(s => parseInt(s)),
+})
+
+// Input: string
+// Output: number
+
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/items',
+  query: {
+    schema: z.object({
+      id: z.string().transform(parseInt),
+    }),
+  },
+})
+
+// You pass: { query: { id: '123' } }  (string)
+// URL becomes: /items?id=123
+// After validation, id is: 123 (number)
+```
+
+## Reusable Schemas
+
+Share schemas across endpoints:
+
+```typescript
+import { z } from 'zod'
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+})
+
+const CreateUserSchema = UserSchema.omit({ id: true })
+
+const api = http_client({
+  origin: 'https://api.example.com',
+  endpoints: {
+    users: {
+      list: new Endpoint({
+        method: 'GET',
+        pathname: '/users',
+        data: { schema: z.array(UserSchema) },
+      }),
+      get: new Endpoint({
+        method: 'GET',
+        pathname: '/users/(:id)',
+        data: { schema: UserSchema },
+      }),
+      create: new Endpoint({
+        method: 'POST',
+        pathname: '/users',
+        body: { schema: CreateUserSchema },
+        data: { schema: UserSchema },
+      }),
+    },
+  },
+})
+```
+
+## Custom Schema Libraries
+
+Any library implementing the Standard Schema spec works:
+
+```typescript
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': {
+    readonly version: 1
+    readonly vendor: string
+    readonly validate: (value: Input) => StandardResult<Output>
+  }
+}
+```
+
+The HTTP client uses `schema['~standard'].validate()` for both input serialization and output parsing.

package/docs/serialization.md

@@ -0,0 +1,211 @@
+# Serialization
+
+Endpoints serialize path params, query strings, and request bodies using schemas. All serialization validates input and can transform data.
+
+## Params
+
+Path parameters are serialized from the `params` input into the URL pathname.
+
+### Without Schema
+
+If no schema is provided, params are inferred from the pathname pattern:
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users/(:id)',
+})
+
+const url = await endpoint.generate_url({
+  origin: 'https://api.example.com',
+  params: { id: '123' },
+})
+// https://api.example.com/users/123
+```
+
+### With Schema
+
+Use a schema to validate and transform params:
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users/(:id)',
+  params: {
+    schema: z.object({
+      id: z.string().uuid(),
+    }),
+  },
+})
+```
+
+### Custom Serialization
+
+Provide a `serialization` function to transform validated params:
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users/(:id)',
+  params: {
+    schema: z.object({ id: z.number() }),
+    serialization: (data) => ({ id: `user-${data.id}` }),
+  },
+})
+
+const url = await endpoint.generate_url({
+  origin: 'https://api.example.com',
+  params: { id: 123 },
+})
+// https://api.example.com/users/user-123
+```
+
+## Query
+
+Query parameters are serialized into the URL search string.
+
+### Object Schema
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users',
+  query: {
+    schema: z.object({
+      page: z.number().transform(String),
+      search: z.string().optional(),
+    }),
+  },
+})
+
+const url = await endpoint.generate_url({
+  origin: 'https://api.example.com',
+  query: { page: 1, search: 'john' },
+})
+// https://api.example.com/users?page=1&search=john
+```
+
+### Custom Serialization
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users',
+  query: {
+    schema: z.object({
+      tags: z.array(z.string()),
+    }),
+    serialization: (data) => {
+      const params = new URLSearchParams()
+      params.set('tags', data.tags.join(','))
+      return params
+    },
+  },
+})
+
+const url = await endpoint.generate_url({
+  origin: 'https://api.example.com',
+  query: { tags: ['admin', 'active'] },
+})
+// https://api.example.com/users?tags=admin,active
+```
+
+## Body
+
+Request bodies are serialized for POST, PUT, PATCH, and DELETE methods.
+
+### JSON (Default)
+
+For JSON-compatible schemas, JSON serialization is automatic:
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'POST',
+  pathname: '/users',
+  body: {
+    schema: z.object({
+      name: z.string(),
+      email: z.string().email(),
+    }),
+  },
+})
+
+const { body, content_type } = await endpoint.serialize_body({
+  body: { name: 'John', email: 'john@example.com' },
+})
+// body: '{"name":"John","email":"john@example.com"}'
+// content_type: 'application/json'
+```
+
+### Custom Serialization
+
+For non-JSON bodies (FormData, text, etc.):
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'POST',
+  pathname: '/upload',
+  body: {
+    schema: z.object({
+      file: z.instanceof(File),
+      name: z.string(),
+    }),
+    serialization: (data) => {
+      const formData = new FormData()
+      formData.append('file', data.file)
+      formData.append('name', data.name)
+      return { body: formData, content_type: 'multipart/form-data' }
+    },
+  },
+})
+```
+
+### URL-Encoded
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'POST',
+  pathname: '/login',
+  body: {
+    schema: z.object({
+      username: z.string(),
+      password: z.string(),
+    }),
+    serialization: (data) => {
+      const params = new URLSearchParams()
+      params.set('username', data.username)
+      params.set('password', data.password)
+      return { body: params, content_type: 'application/x-www-form-urlencoded' }
+    },
+  },
+})
+```
+
+### Plain Text
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'POST',
+  pathname: '/echo',
+  body: {
+    schema: z.string(),
+    serialization: (text) => ({
+      body: text,
+      content_type: 'text/plain',
+    }),
+  },
+})
+```
+
+## Validation Errors
+
+If input fails schema validation, a `SerializationError` is returned:
+
+```typescript
+const result = await endpoint.serialize_body({ body: { name: '' } })
+
+if (result instanceof SerializationError) {
+  console.log(result.message) // "Body serialization failed"
+  console.log(result.cause)    // Schema validation issues
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afoures/http-client",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "A typesafe and robust HTTP client",
   "homepage": "https://github.com/afoures/http-client#readme",
   "bugs": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "package.json",
     "README.md"
   ],
@@ -34,13 +35,13 @@
     "@standard-schema/spec": "^1.1.0"
   },
   "devDependencies": {
-    "@afoures/auto-release": "^0.3.0",
+    "@afoures/auto-release": "^0.4.1",
     "@arktype/attest": "^0.56.0",
-    "@types/node": "^24.10.13",
+    "@types/node": "^24.12.0",
     "msw": "^2.12.10",
-    "oxfmt": "^0.25.0",
-    "oxlint": "^1.48.0",
-    "tsdown": "^0.20.3",
+    "oxfmt": "^0.36.0",
+    "oxlint": "^1.51.0",
+    "tsdown": "^0.21.0",
     "typescript": "^5.9.3",
     "zod": "^4.3.6"
   },