typecompass 1.0.0

package/README.md

@@ -0,0 +1,364 @@
+# TypeCompass
+
+**Navigate your API with type-safe precision** 🧭
+
+TypeCompass is a lightweight TypeScript library that lets you define API contracts once and use them everywhere — with full type safety, automatic OpenAPI generation, and zero runtime overhead.
+
+## Features
+
+✨ **Type-Safe Contracts** - Define routes with Zod schemas, get full TypeScript inference  
+🔄 **Client & Server** - Use the same contract for backend validation and frontend calls  
+📚 **Auto OpenAPI** - Generate OpenAPI 3.0 specs automatically from your contracts  
+🎯 **Zero Runtime Cost** - Contracts are just types on the client side  
+🔗 **Combinable** - Merge multiple service contracts into one unified API  
+🎨 **Framework Agnostic** - Works with Express, Fastify, Hono, or any Node.js framework
+
+## Installation
+
+```bash
+npm install typecompass zod
+```
+
+## Quick Start
+
+### 1. Define a Contract
+
+```typescript
+// contracts/auth.contract.ts
+import { defineRoutes } from 'typecompass'
+import { z } from 'zod'
+
+export const AuthContract = defineRoutes({
+  login: {
+    method: "POST",
+    path: "/auth/login",
+    summary: "User Login",
+    tags: ["Auth"],
+    body: z.object({
+      email: z.string().email(),
+      password: z.string().min(8),
+    }),
+    responses: {
+      200: {
+        schema: z.object({
+          token: z.string(),
+          user: z.object({
+            id: z.string(),
+            email: z.string(),
+          }),
+        }),
+      },
+    },
+  },
+  
+  register: {
+    method: "POST",
+    path: "/auth/register",
+    summary: "User Registration",
+    tags: ["Auth"],
+    body: z.object({
+      email: z.string().email(),
+      password: z.string().min(8),
+      name: z.string(),
+    }),
+  },
+})
+```
+
+### 2. Use on the Backend
+
+```typescript
+// server.ts
+import express from 'express'
+import { AuthContract } from './contracts/auth.contract'
+
+const app = express()
+
+app.post('/auth/login', async (req, res) => {
+  // Validate with the contract schema
+  const data = AuthContract.login.body.parse(req.body)
+  
+  // TypeScript knows the shape of data!
+  const user = await loginUser(data.email, data.password)
+  
+  res.json({ token: user.token, user })
+})
+
+// Generate OpenAPI documentation
+app.get('/openapi.json', (req, res) => {
+  const spec = AuthContract.generateOpenApi({
+    title: "Auth API",
+    version: "1.0.0",
+    servers: [{ url: "https://api.example.com", description: "Production" }],
+  })
+  res.json(spec)
+})
+```
+
+### 3. Use on the Frontend
+
+```typescript
+// api/client.ts
+import { AuthContract } from '@mychange/api-contracts'
+import { initClient } from 'typecompass/client'
+import axios from 'axios'
+
+const axiosInstance = axios.create({
+  baseURL: 'https://api.example.com',
+})
+
+const client = initClient(AuthContract, axiosInstance)
+
+// Fully typed API calls!
+const response = await client.login({
+  body: {
+    email: "user@example.com",
+    password: "secret123",
+  }
+})
+
+// TypeScript knows response.data.token exists
+console.log(response.data.token)
+```
+
+## Combining Multiple Contracts
+
+For larger applications with multiple services:
+
+```typescript
+// contracts/index.ts
+import { combineContracts } from 'typecompass'
+import { AuthContract } from './auth.contract'
+import { UsersContract } from './users.contract'
+import { PaymentsContract } from './payments.contract'
+
+export const ApiContract = combineContracts({
+  auth: AuthContract,
+  users: UsersContract,
+  payments: PaymentsContract,
+})
+
+// Generate unified OpenAPI spec
+export const openApiSpec = ApiContract.generateOpenApi({
+  title: "MyChange API",
+  version: "1.0.0",
+  servers: [
+    { url: "https://api.mychange.com", description: "Production" },
+    { url: "http://localhost:3000", description: "Development" },
+  ],
+  securitySchemes: {
+    BearerAuth: {
+      type: "http",
+      scheme: "bearer",
+    },
+  },
+  defaultSecurity: ["BearerAuth"],
+})
+```
+
+### Client with Combined Contracts
+
+```typescript
+// Frontend usage
+import { ApiContract } from '@mychange/api-contracts'
+import { initCombinedClient } from 'typecompass/client'
+
+const client = initCombinedClient(ApiContract, axiosInstance)
+
+// Namespaced by service
+await client.auth.login({ body: {...} })
+await client.users.getProfile({ params: { id: "123" } })
+await client.payments.createCharge({ body: {...} })
+```
+
+## Advanced Features
+
+### Path Parameters
+
+```typescript
+const UsersContract = defineRoutes({
+  getUser: {
+    method: "GET",
+    path: "/users/:id",
+    summary: "Get User by ID",
+    params: z.object({
+      id: z.string(),
+    }),
+  },
+})
+
+// Client usage
+await client.getUser({ params: { id: "user-123" } })
+```
+
+### Query Parameters
+
+```typescript
+const ProductsContract = defineRoutes({
+  searchProducts: {
+    method: "GET",
+    path: "/products",
+    summary: "Search Products",
+    query: z.object({
+      q: z.string(),
+      category: z.string().optional(),
+      limit: z.number().default(10),
+    }),
+  },
+})
+
+// Client usage
+await client.searchProducts({ 
+  query: { q: "laptop", category: "electronics", limit: 20 } 
+})
+```
+
+### Custom Security
+
+```typescript
+const AdminContract = defineRoutes({
+  deleteUser: {
+    method: "DELETE",
+    path: "/admin/users/:id",
+    summary: "Delete User",
+    tags: ["Admin"],
+    security: ["BearerAuth", "AdminRole"],
+    params: z.object({
+      id: z.string(),
+    }),
+  },
+})
+```
+
+### Schema Examples
+
+Add examples to your schemas for better documentation:
+
+```typescript
+import { z } from 'zod'
+
+const createUserSchema = z.object({
+  email: z.string().email().example("john@example.com"),
+  name: z.string().example("John Doe"),
+  age: z.number().min(18).example(25),
+})
+```
+
+## Publishing Contracts
+
+For teams with separate frontend/backend repos, publish your contracts as an npm package:
+
+### 1. Create Contracts Package
+packages/api-contracts/package.json
+```json
+
+{
+  "name": "@mychange/api-contracts",
+  "version": "1.0.0",
+  "private": true,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "typecompass": "^1.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  }
+}
+```
+
+### 2. Export Combined Contract
+
+```typescript
+// packages/api-contracts/src/index.ts
+export { ApiContract } from './contracts'
+export type { ApiContract as ApiContractType } from './contracts'
+```
+
+### 3. Install in Frontend
+
+```bash
+npm install @mychange/api-contracts
+```
+
+```typescript
+import { ApiContract } from '@mychange/api-contracts'
+import { initCombinedClient } from 'typecompass/client'
+
+const api = initCombinedClient(ApiContract, axiosInstance)
+```
+
+## API Reference
+
+### `defineRoutes(routes)`
+
+Define a single service contract.
+
+**Parameters:**
+- `routes` - Object mapping route names to route configurations
+
+**Returns:** `Contract<T>`
+
+### `combineContracts(contracts)`
+
+Combine multiple contracts into one.
+
+**Parameters:**
+- `contracts` - Object mapping namespace to contracts
+
+**Returns:** `CombinedContract<T>`
+
+### `generateOpenApi(contract, config)`
+
+Generate OpenAPI 3.0 specification.
+
+**Parameters:**
+- `contract` - Contract or CombinedContract
+- `config` - OpenAPI configuration (title, version, servers, etc.)
+
+**Returns:** OpenAPI JSON object
+
+### `initClient(contract, api)`
+
+Initialize type-safe client for a single contract.
+
+**Parameters:**
+- `contract` - Contract to use
+- `api` - Axios-like API provider
+
+**Returns:** Typed client object
+
+### `initCombinedClient(contract, api)`
+
+Initialize type-safe client for combined contracts.
+
+**Parameters:**
+- `contract` - CombinedContract to use
+- `api` - Axios-like API provider
+
+**Returns:** Namespaced typed client object
+
+## Route Configuration
+
+```typescript
+interface RouteConfig {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
+  path: string                    // e.g., "/users/:id"
+  summary: string                 // Short description
+  tags?: string[]                 // For OpenAPI grouping
+  security?: string[]             // Security scheme names
+  body?: z.ZodType               // Request body schema
+  query?: z.ZodType              // Query parameters schema
+  params?: z.ZodType             // Path parameters schema
+  responses?: Record<number, ResponseConfig>
+  description?: string            // Long description
+}
+```
+
+## License
+
+MIT © MyChange
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "typecompass",
+  "version": "1.0.0",
+  "description": "Type-safe API contracts with OpenAPI generation for TypeScript",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "require": "./dist/client.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "openapi",
+    "typescript",
+    "api",
+    "contract",
+    "type-safe",
+    "zod",
+    "rest",
+    "client",
+    "server"
+  ],
+  "author": "MyChange",
+  "license": "MIT",
+  "peerDependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "typescript": "^5.0.0",
+    "zod": "^4.3.6"
+  }
+}