typeowl-example-backend 1.0.0

package/README.md

@@ -0,0 +1,68 @@
+<p align="center">
+  <img src="../frontend/public/typeOwl.logo.png" alt="TypeOwl Logo" width="120" />
+</p>
+
+# TypeOwl Example Backend
+
+A Fastify API server that exposes types via TypeOwl.
+
+## Setup
+
+```bash
+npm install
+npm run dev
+```
+
+The server starts on `http://localhost:3001`.
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/users` | List all users |
+| GET | `/api/users/:id` | Get user by ID |
+| POST | `/api/users` | Create a new user |
+| DELETE | `/api/users/:id` | Delete a user |
+| GET | `/api/posts` | List all posts |
+| GET | `/api/posts/:id` | Get post by ID |
+| POST | `/api/posts` | Create a new post |
+
+## TypeOwl Endpoints
+
+| Path | Description |
+|------|-------------|
+| `/__typeowl` | JSON manifest (metadata + file pointers) |
+| `/__typeowl/types/users.d.ts` | User domain types |
+| `/__typeowl/types/posts.d.ts` | Post domain types |
+| `/__typeowl/types/common.d.ts` | Shared types (ApiError, etc.) |
+| `/__typeowl/types/index.d.ts` | All types + ApiEndpoints |
+
+## How It Works
+
+```typescript
+import { createTypeOwl } from 'typeowl/server';
+import { z } from 'zod';
+
+const typeowl = createTypeOwl({ version: '1.0.0' });
+
+// Register types by domain
+typeowl
+  .domain('users')
+  .registerZod('User', UserSchema)
+  .registerZod('CreateUserInput', CreateUserSchema);
+
+// Register endpoints
+typeowl
+  .domain('main')
+  .get('/api/users', 'User[]')
+  .post('/api/users', 'User', { body: 'CreateUserInput' });
+
+// Handle TypeOwl requests in your server
+app.get('/__typeowl/*', (req, reply) => {
+  const response = typeowl.handleRequest(req.url);
+  if (response) {
+    return reply.type(response.contentType).send(response.body);
+  }
+});
+```
+

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "typeowl-example-backend",
+  "version": "1.0.0",
+  "description": "Example backend using TypeOwl for type sharing",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "start": "node dist/server.js",
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@fastify/cors": "^9.0.1",
+    "fastify": "^4.26.0",
+    "typeowl": "file:../..",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  }
+}

package/src/server.ts

@@ -0,0 +1,239 @@
+/**
+ * 🦉 TypeOwl Example Backend
+ * 
+ * Demonstrates THREE ways to define API types:
+ * 
+ * 🔴 OPTION 1: No TypeOwl - Raw handlers, no type exposure
+ *    → Frontend uses `any` or manual types
+ * 
+ * 🟡 OPTION 2: Static types only - Types extracted from src/types/
+ *    → Frontend can force-cast using exposed static types
+ * 
+ * 🟢 OPTION 3: typeowl.endpoint() - Full type generation + validation
+ *    → Frontend gets auto-generated endpoint types
+ * 
+ * Run: npm run dev
+ */
+
+import Fastify from 'fastify';
+import cors from '@fastify/cors';
+import { z } from 'zod';
+import { initTypeOwl } from 'typeowl/server';
+
+// Import types from our types folder (for use in this file)
+import type { Blog, Product } from './types/index.js';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 🦉 TYPEOWL - Auto-loads from typeowl.server.config.ts
+// ═══════════════════════════════════════════════════════════════════════════
+
+const typeowl = await initTypeOwl();
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 📦 ZOD SCHEMAS (for typeowl.endpoint validation)
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Common params schema
+const IdParamsSchema = z.object({ id: z.string() });
+
+// User schemas
+const UserSchema = z.object({
+  id: z.string(),
+  email: z.string().email(),
+  name: z.string(),
+  role: z.enum(['admin', 'user', 'guest']),
+});
+
+const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string(),
+  role: z.enum(['admin', 'user', 'guest']).default('user'),
+});
+
+// Health check (untyped endpoint)
+const HealthSchema = z.object({
+  status: z.string(),
+  timestamp: z.string(),
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 🌐 FASTIFY SERVER
+// ═══════════════════════════════════════════════════════════════════════════
+
+const app = Fastify({ logger: false });
+
+await app.register(cors, { origin: true });
+
+// Mount TypeOwl routes (from config)
+await typeowl.mount(app);
+
+// ─── Sample Data ─────────────────────────────────────────────────────────────
+
+const blogs: Blog[] = [
+  { id: '1', title: 'Hello World', content: 'Welcome to TypeOwl!', published: true, createdAt: new Date().toISOString() },
+  { id: '2', title: 'Getting Started', content: 'Let me show you how...', published: true, createdAt: new Date().toISOString() },
+];
+
+const products: Product[] = [
+  { id: '1', name: 'TypeOwl Pro', price: 99, description: 'Full-featured type sharing', inStock: true },
+  { id: '2', name: 'TypeOwl Starter', price: 0, inStock: true },
+];
+
+type User = z.infer<typeof UserSchema>;
+const users: User[] = [
+  { id: '1', email: 'alice@example.com', name: 'Alice', role: 'admin' },
+  { id: '2', email: 'bob@example.com', name: 'Bob', role: 'user' },
+];
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 🔴 OPTION 1: No TypeOwl - Raw Fastify handlers
+// ═══════════════════════════════════════════════════════════════════════════
+// These endpoints are NOT registered with TypeOwl.
+// Frontend must use `any` or define types manually.
+
+app.get('/api/health', async () => {
+  return { status: 'ok', timestamp: new Date().toISOString() };
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 🟡 OPTION 2: Static types only - Types exposed via extract config
+// ═══════════════════════════════════════════════════════════════════════════
+// Blog type is extracted from src/types/Blog.ts via typeowl.server.config.ts
+// The TYPE is exposed, but endpoints are NOT mapped.
+// Frontend can force-cast responses using the exposed Blog type.
+
+app.get('/api/blogs', async () => blogs);
+
+app.get('/api/blogs/:id', async (request, reply) => {
+  const { id } = request.params as { id: string };
+  const blog = blogs.find(b => b.id === id);
+  if (!blog) return reply.code(404).send({ error: 'Blog not found' });
+  return blog;
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 🟢 OPTION 3: typeowl.endpoint() - Full type generation + validation
+// ═══════════════════════════════════════════════════════════════════════════
+// These endpoints have AUTOMATIC validation and type registration!
+// Schemas are extracted to TypeOwl AND used for runtime validation.
+// Frontend gets fully typed ApiEndpoints with body/params/response.
+
+// GET /api/users - List all users
+typeowl.endpoint(app, 'GET', '/api/users', {
+  response: z.array(UserSchema),
+  description: 'List all users',
+}, async () => {
+  return users;
+});
+
+// GET /api/users/:id - Get user by ID
+typeowl.endpoint(app, 'GET', '/api/users/:id', {
+  params: IdParamsSchema,
+  response: UserSchema,
+  description: 'Get user by ID',
+}, async ({ params, reply }) => {
+  const user = users.find(u => u.id === params.id);
+  if (!user) {
+    (reply as { code: (n: number) => { send: (d: unknown) => void } }).code(404).send({ error: 'User not found' });
+    return undefined as never;
+  }
+  return user;
+});
+
+// POST /api/users - Create user (with body validation!)
+typeowl.endpoint(app, 'POST', '/api/users', {
+  body: CreateUserSchema,
+  response: UserSchema,
+  description: 'Create a new user',
+}, async ({ body }) => {
+  // body is already validated and typed as { email: string, name: string, role: 'admin'|'user'|'guest' }
+  const newUser: User = {
+    id: String(users.length + 1),
+    email: body.email,
+    name: body.name,
+    role: body.role,
+  };
+  users.push(newUser);
+  return newUser;
+});
+
+// DELETE /api/users/:id - Delete user
+typeowl.endpoint(app, 'DELETE', '/api/users/:id', {
+  params: IdParamsSchema,
+  response: z.object({ success: z.boolean(), message: z.string() }),
+  description: 'Delete a user',
+}, async ({ params, reply }) => {
+  const index = users.findIndex(u => u.id === params.id);
+  if (index === -1) {
+    (reply as { code: (n: number) => { send: (d: unknown) => void } }).code(404).send({ error: 'User not found' });
+    return undefined as never;
+  }
+  users.splice(index, 1);
+  return { success: true, message: 'User deleted' };
+});
+// POST /api/blogs - Create a new blog
+typeowl.endpoint(app, 'POST', '/api/blogs', {
+  body:'BlogInput',
+  response: 'Blog',
+  description: 'Create a new blog',
+}, async ({ body }) => console.log(body));
+
+// GET /api/products - List all products
+typeowl.endpoint(app, 'GET', '/api/products', {
+  response: 'Product[]',
+  description: 'List all products',
+}, async () => products);
+
+// GET /api/products/:id - Get product by ID
+typeowl.endpoint(app, 'GET', '/api/products/:id', {
+  params: IdParamsSchema,
+  response: 'Product | null',  // Using extracted type reference!
+  description: 'Get product by ID',
+}, async ({ params, reply }) => {
+  const product = products.find(p => p.id === params.id);
+  if (!product) {
+    (reply as { code: (n: number) => { send: (d: unknown) => void } }).code(404).send({ error: 'Product not found' });
+    return undefined as never;
+  }
+  return product;
+});
+
+// ─── Start Server ────────────────────────────────────────────────────────────
+
+const PORT = 3001;
+
+app.listen({ port: PORT, host: '0.0.0.0' }, (err) => {
+  if (err) {
+    console.error(err);
+    process.exit(1);
+  }
+  
+  console.log(`
+\x1b[36m🦉 TypeOwl Example Backend\x1b[0m
+\x1b[2m──────────────────────────────\x1b[0m
+
+  Server:     \x1b[32mhttp://localhost:${PORT}\x1b[0m
+  
+  \x1b[31m🔴 No TypeOwl (raw handlers):\x1b[0m
+    GET  /api/health
+  
+  \x1b[33m🟡 Static types only (Blog exposed, endpoint not mapped):\x1b[0m
+    GET  /api/blogs
+    GET  /api/blogs/:id
+  
+  \x1b[32m🟢 typeowl.endpoint() (full type + validation):\x1b[0m
+    GET    /api/products
+    GET    /api/products/:id
+    GET    /api/users
+    GET    /api/users/:id
+    POST   /api/users      \x1b[33m← Try invalid body!\x1b[0m
+    DELETE /api/users/:id
+  
+  TypeOwl Endpoints:
+    \x1b[33mhttp://localhost:${PORT}/__typeowl\x1b[0m
+    \x1b[33mhttp://localhost:${PORT}/__typeowl/types/content.d.ts\x1b[0m
+    \x1b[33mhttp://localhost:${PORT}/__typeowl/types/endpoints.d.ts\x1b[0m
+
+  \x1b[2mPress Ctrl+C to stop\x1b[0m
+`);
+});

package/src/types/Blog.ts

@@ -0,0 +1,11 @@
+import { Author } from "./anothertype.js";
+
+export type Blog = {
+  id: string;
+  title: string;
+  content: string;
+  published: boolean;
+  createdAt: string;
+  author?: Author;
+}
+export type  BlogInput = Pick<Blog, 'title' | 'content'>;

package/src/types/Product.ts

@@ -0,0 +1,7 @@
+export interface Product {
+    id: string;
+    name: string;
+    price: number;
+    description?: string;
+    inStock: boolean;
+  }

package/src/types/anothertype.ts

@@ -0,0 +1,22 @@
+type Developer = {
+  id: string;
+  name: string;
+  email: string;
+  role: DeveloperRole;
+};
+enum DeveloperRole {
+    ADMIN = 'admin',
+    USER = 'user',
+    GUEST = 'guest',
+}
+type customeType<T extends string | number> = `custom_${T}`;
+type Author = {
+    isDeveloper: boolean;
+    developers: Map<string, Developer>;
+    customType: customeType<string>;
+};
+type NoUsageType = {
+    id: string;
+    noUsage: boolean;
+};
+export type { Author , NoUsageType};

package/src/types/index.ts

@@ -0,0 +1,5 @@
+import type { Product } from './Product.ts';
+import type { Blog ,BlogInput } from './Blog.ts';
+
+
+export type { Blog, Product , BlogInput};

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"]
+}
+

package/typeowl.server.config.ts

@@ -0,0 +1,201 @@
+/**
+ * 🦉 TypeOwl Server Configuration
+ * 
+ * This is the central configuration file for TypeOwl.
+ * All settings for type extraction, serving, and security are defined here.
+ */
+
+import { defineServerConfig } from 'typeowl/server';
+import type { FastifyInstance } from 'fastify';
+
+// Helper to cast app to your framework type
+const asFastify = (app: unknown) => app as FastifyInstance;
+
+export default defineServerConfig({
+  // ═══════════════════════════════════════════════════════════════════════════
+  // 📍 BASE CONFIGURATION
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Base path for TypeOwl endpoints.
+   * All type endpoints will be served under this path.
+   * 
+   * @default '/__typeowl'
+   * @example '/__typeowl' -> http://localhost:3001/__typeowl/types/content.d.ts
+   */
+  basePath: '/__typeowl',
+
+  /**
+   * Version string for cache invalidation.
+   * Change this when your types change to bust client caches.
+   * 
+   * @example '1.0.0', 'v2', process.env.npm_package_version
+   */
+  version: '1.0.0',
+
+  /**
+   * Include git commit hash in the manifest.
+   * Useful for debugging which version is deployed.
+   * 
+   * @default false
+   */
+  includeGitCommit: false,
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // 📦 TYPE EXTRACTION
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * 🔒 Allowed source files/directories for type extraction.
+   * Only files within these paths can have their types extracted.
+   * This is a security measure to prevent accidental exposure of sensitive types.
+   * 
+   * Can be:
+   * - Single file: './src/types.ts'
+   * - Single directory: './src/types/'
+   * - Multiple paths: ['./src/types/', './src/models/']
+   * 
+   * ⚠️ Required for extractAndRegister() to work.
+   */
+  typeSources: './src/types/',
+
+  /**
+   * Types to extract from source files.
+   * Maps domain names to source locations and type names.
+   * 
+   * Each domain becomes a separate .d.ts file:
+   * - content -> /__typeowl/types/content.d.ts
+   * - models -> /__typeowl/types/models.d.ts
+   * 
+   * @example
+   * extract: {
+   *   content: { from: './src/types/', types: ['Blog', 'Product'] },
+   *   models: { from: './src/models/', types: ['User', 'Order'] },
+   * }
+   */
+  extract: {
+    content: {
+      from: './src/types/',
+      types: '*',  // Extract ALL exported types automatically!
+    },
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // 🛡️ GUARD
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Guard settings for TypeOwl endpoints.
+   */
+  guard: {
+    /**
+     * When to enable TypeOwl endpoints:
+     * - true: Always enabled (use with caution in production!)
+     * - false: Always disabled
+     * - 'development': Only when NODE_ENV !== 'production'
+     * 
+     * @default 'development'
+     */
+    enabled: 'development',
+
+    /**
+     * API key required to access type endpoints.
+     * If set, clients must include the key via:
+     * - Header: X-TypeOwl-Key: your-api-key
+     * - Query param: ?key=your-api-key
+     * 
+     * @example process.env.TYPEOWL_API_KEY
+     */
+    // apiKey: process.env.TYPEOWL_API_KEY,
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // 🚀 SERVING MODE
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * How TypeOwl serves types:
+   * 
+   * - 'dynamic': Types served at runtime via registerRoutes.
+   *              Your server handles requests to /__typeowl/*.
+   *              Requires registerRoutes to be defined.
+   * 
+   * - 'static': Types generated as static files by CLI.
+   *             Run: npx typeowl generate
+   *             Files output to basePath (e.g., ./public/__typeowl/).
+   *             registerRoutes is optional (not needed for static hosting).
+   * 
+   * @default 'dynamic'
+   */
+  mode: 'dynamic',
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // 🔌 ROUTE REGISTRATION
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Register TypeOwl routes on your server framework.
+   * 
+   * This function receives:
+   * - appInstance: Your server instance (Fastify, Express, Hono, etc.)
+   * - typeowl: The TypeOwl handler for processing requests
+   * - config: This config object for reference
+   * 
+   * Called when you run: typeowl.mount(app)
+   * 
+   * @example
+   * // Fastify
+   * registerRoutes: (app, typeowl, config) => {
+   *   app.get('/__typeowl/*', (req, reply) => { ... });
+   * }
+   * 
+   * @example
+   * // Express
+   * registerRoutes: (app, typeowl, config) => {
+   *   app.use('/__typeowl', (req, res) => { ... });
+   * }
+   */
+  registerRoutes: (appInstance, typeowl, config) => {
+    const app = asFastify(appInstance);
+    const basePath = typeowl.getBasePath();
+    const guard = config.guard;
+
+    // Guard check helper
+    const checkGuard = (request: { headers: Record<string, string | string[] | undefined>; query: Record<string, string> }) => {
+      return typeowl.validateRequest(
+        { path: '', headers: request.headers, query: request.query },
+        guard
+      );
+    };
+
+    // Manifest endpoint: /__typeowl
+    app.get(`${basePath}`, async (request, reply) => {
+      const auth = checkGuard(request as never);
+      if (!auth.valid) return reply.code(401).send({ error: auth.error });
+      const response = typeowl.handleRequest(basePath);
+      if (response) return reply.type(response.contentType).send(response.body);
+      return reply.code(404).send({ error: 'Not found' });
+    });
+
+    // Manifest JSON endpoint: /__typeowl/manifest.json
+    app.get(`${basePath}/manifest.json`, async (request, reply) => {
+      const auth = checkGuard(request as never);
+      if (!auth.valid) return reply.code(401).send({ error: auth.error });
+      const response = typeowl.handleRequest(`${basePath}/manifest.json`);
+      if (response) return reply.type(response.contentType).send(response.body);
+      return reply.code(404).send({ error: 'Not found' });
+    });
+
+    // Type files endpoint: /__typeowl/types/{file}.d.ts
+    app.get(`${basePath}/types/:file`, async (request, reply) => {
+      const auth = checkGuard(request as never);
+      if (!auth.valid) return reply.code(401).send({ error: auth.error });
+      const { file } = request.params as { file: string };
+      const response = typeowl.handleRequest(`${basePath}/types/${file}`);
+      if (response) return reply.type(response.contentType).send(response.body);
+      return reply.code(404).send({ error: 'Not found' });
+    });
+
+    console.log(`  🦉 TypeOwl registered at ${basePath}`);
+  },
+});