@carlos-tzin/tzin 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.2
+
+- Added `create-tzin` scaffolding CLI (`npx create-tzin my-app`)
+  - Templates: Node, Bun, Cloudflare Workers
+  - Interactive and non-interactive modes
+- Added API Reference and Architecture Guide docs
+
+## 0.1.1
+
+- Documentation improvements: trimmed roadmap, added examples table
+
 ## 0.1.0 — first public release
 
 Contract-first TypeScript framework: declare a contract once, get the typed

package/README.md

@@ -20,6 +20,11 @@ Or scaffold a new project:
 npx create-tzin my-app
 ```
 
+## Documentation
+
+- **[API Reference](docs/api-reference.md)** — all exports, types, and options
+- **[Architecture Guide](docs/architecture.md)** — request pipeline, design decisions, internals
+
 ## Why another framework?
 
 The TypeScript backend landscape is crowded — and still leaves real gaps:

package/dist/cli.js

@@ -3,21 +3,28 @@ import { fileURLToPath } from 'node:url';
 function usage() {
     console.error(`tzin CLI
 
-  tzin dev <entry-file> [--port N]   start dev server with hot reload
-                                     entry must default-export a tzin App`);
+  tzin dev [entry] [--port N]    start dev server with hot reload
+                                  entry defaults to src/app.ts`);
     process.exit(1);
 }
 const [, , cmd, ...rest] = process.argv;
-if (cmd !== 'dev' || rest.length === 0)
+if (cmd !== 'dev')
     usage();
-const entry = rest[0];
+// Entry is optional now - dev-server auto-detects
+let entry = '';
 let port = '3000';
 const portFlag = rest.indexOf('--port');
 if (portFlag !== -1 && rest[portFlag + 1])
     port = rest[portFlag + 1];
+// First non-flag arg is the entry (optional)
+const entryArg = rest.find((a) => !a.startsWith('-') && a !== 'dev');
+if (entryArg)
+    entry = entryArg;
 const devServer = fileURLToPath(new URL('./dev-server.ts', import.meta.url));
-const child = spawn('npx', ['tsx', 'watch', '--clear-screen=false', devServer, entry, port], {
-    stdio: 'inherit',
-});
+const args = ['tsx', 'watch', '--clear-screen=false', devServer];
+if (entry)
+    args.push(entry);
+args.push('--port', port);
+const child = spawn('npx', args, { stdio: 'inherit' });
 process.on('SIGINT', () => child.kill('SIGINT'));
 child.on('exit', (code) => process.exit(code ?? 0));

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+export interface TzinConfig {
+    /** Port to listen on (default: 3000) */
+    port?: number;
+    /** Enable OpenAPI at /openapi.json */
+    openapi?: boolean;
+    /** Enable MCP at POST /mcp */
+    mcp?: boolean;
+    /** Enable /llms.txt and /llms-full.txt */
+    llms?: boolean;
+    /** API metadata for OpenAPI/MCP */
+    meta?: {
+        title?: string;
+        description?: string;
+        version?: string;
+    };
+    /** Glob patterns for auto-loading routes */
+    routes?: string[];
+    /** Glob patterns for auto-loading middleware */
+    middleware?: string[];
+    /** Entry point for the app (default: src/app.ts) */
+    entry?: string;
+}
+export declare function loadConfig(cwd?: string): TzinConfig | null;
+export declare function defineConfig(config: TzinConfig): TzinConfig;

package/dist/config.js

@@ -0,0 +1,32 @@
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+const CONFIG_FILES = [
+    'tzin.config.ts',
+    'tzin.config.js',
+    'tzin.config.mjs',
+    'tzin.config.json',
+];
+export function loadConfig(cwd = process.cwd()) {
+    for (const file of CONFIG_FILES) {
+        const path = resolve(cwd, file);
+        if (existsSync(path)) {
+            try {
+                // For .ts files, we need to use a loader
+                if (file.endsWith('.ts')) {
+                    // Return null for now - will be handled by tsx loader
+                    return null;
+                }
+                // For .js/.mjs, import dynamically
+                const config = require(path);
+                return config.default || config;
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+export function defineConfig(config) {
+    return config;
+}

package/dist/dev-server.js

@@ -1,5 +1,8 @@
 import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
 import { listen } from './node.js';
+import { loadConfig } from './config.js';
 function pad(s, n) {
     return s.length >= n ? s : s + ' '.repeat(n - s.length);
 }
@@ -13,18 +16,36 @@ function printRouteTable(routes) {
     }
     console.log('');
 }
-const entry = process.argv[2];
-const port = Number(process.argv[3] ?? 3000);
-if (!entry) {
-    console.error('usage: dev-server <entry-file> [port]');
+// Parse args: entry and --port or positional port
+const args = process.argv.slice(2);
+const portFlag = args.indexOf('--port');
+let port = 3000;
+let entry = '';
+if (portFlag !== -1) {
+    port = Number(args[portFlag + 1]) || 3000;
+    entry = args.filter((_, i) => i !== portFlag && i !== portFlag + 1).find((a) => !a.startsWith('-')) ?? '';
+}
+else {
+    const nonFlags = args.filter((a) => !a.startsWith('-'));
+    entry = nonFlags[0] ?? '';
+    port = nonFlags[1] ? Number(nonFlags[1]) || 3000 : 3000;
+}
+// Load config
+const config = loadConfig() ?? {};
+// Auto-detect entry: CLI arg > config > src/app.ts
+const entryFile = entry || config.entry || 'src/app.ts';
+const entryPath = resolve(entryFile);
+if (!existsSync(entryPath)) {
+    console.error(`Entry file not found: ${entryPath}`);
+    console.error('Create src/app.ts or specify entry with: tzin dev <entry>');
     process.exit(1);
 }
-const mod = await import(pathToFileURL(entry).href);
+const mod = await import(pathToFileURL(entryPath).href);
 const app = mod.default ?? mod.app;
 if (!app || typeof app.fetch !== 'function' || !Array.isArray(app.routes)) {
-    console.error('entry file must default-export (or export `app`) a tzin App');
+    console.error('Entry file must export a tzin App (createApp(...))');
     process.exit(1);
 }
 printRouteTable(app.routes);
-listen(app, port);
-console.log(`\x1b[32m➜\x1b[0m http://localhost:${port}  (watching for changes)`);
+listen(app, config.port ?? port);
+console.log(`\x1b[32m➜\x1b[0m http://localhost:${config.port ?? port}  (watching for changes)`);

package/dist/index.d.ts

@@ -20,3 +20,5 @@ export { wsChannels, type WsRoute, type WsSend, type WsChannelOptions } from './
 export { attachChannels } from './ws-node.js';
 export { LocalBus, clusterHubs, type MessageBus } from './bus.js';
 export { cors, type CorsOptions } from './cors.js';
+export { defineConfig, loadConfig, type TzinConfig } from './config.js';
+export { loadRoutes, type RouteLoaderOptions } from './route-loader.js';

package/dist/index.js

@@ -20,3 +20,5 @@ export { wsChannels } from './ws.js';
 export { attachChannels } from './ws-node.js';
 export { LocalBus, clusterHubs } from './bus.js';
 export { cors } from './cors.js';
+export { defineConfig, loadConfig } from './config.js';
+export { loadRoutes } from './route-loader.js';

package/dist/route-loader.d.ts

@@ -0,0 +1,17 @@
+import type { RouteImpl } from './contract.js';
+export interface RouteLoaderOptions {
+    /** Directory to scan for routes */
+    dir?: string;
+    /** Glob patterns to include */
+    include?: string[];
+    /** Glob patterns to exclude */
+    exclude?: string[];
+}
+/**
+ * Auto-discover and load routes from a directory structure.
+ *
+ * Convention:
+ * - Each file exports route implementations
+ * - File path becomes the route prefix
+ */
+export declare function loadRoutes(options?: RouteLoaderOptions): Promise<RouteImpl[]>;

package/dist/route-loader.js

@@ -0,0 +1,50 @@
+import { readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+/**
+ * Auto-discover and load routes from a directory structure.
+ *
+ * Convention:
+ * - Each file exports route implementations
+ * - File path becomes the route prefix
+ */
+export async function loadRoutes(options = {}) {
+    const dir = resolve(options.dir || 'src/routes');
+    const routes = [];
+    try {
+        await scanDir(dir, '', routes);
+    }
+    catch {
+        // Directory doesn't exist or is empty
+    }
+    return routes;
+}
+async function scanDir(dir, prefix, routes) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        const routePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            await scanDir(fullPath, routePath, routes);
+        }
+        else if (entry.name.endsWith('.ts') || entry.name.endsWith('.js')) {
+            // Skip index files and files starting with _
+            if (entry.name === 'index.ts' || entry.name === 'index.js')
+                continue;
+            if (entry.name.startsWith('_'))
+                continue;
+            const module = await import(fullPath);
+            const exports = Object.values(module);
+            for (const exp of exports) {
+                if (isRouteImpl(exp)) {
+                    routes.push(exp);
+                }
+            }
+        }
+    }
+}
+function isRouteImpl(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'contract' in value &&
+        'handler' in value);
+}

package/dist/test.d.ts

@@ -0,0 +1,65 @@
+import type { AnyContract, SectionsOf, ResponseOf } from './contract.js';
+import type { App } from './server.js';
+export interface TestClient {
+    /** Make a GET request */
+    get(path: string, init?: RequestInit): Promise<TestResponse>;
+    /** Make a POST request */
+    post(path: string, body?: unknown, init?: RequestInit): Promise<TestResponse>;
+    /** Make a PUT request */
+    put(path: string, body?: unknown, init?: RequestInit): Promise<TestResponse>;
+    /** Make a PATCH request */
+    patch(path: string, body?: unknown, init?: RequestInit): Promise<TestResponse>;
+    /** Make a DELETE request */
+    delete(path: string, init?: RequestInit): Promise<TestResponse>;
+    /** Make a custom request */
+    request(path: string, init: RequestInit): Promise<TestResponse>;
+    /** Close the server */
+    close(): Promise<void>;
+    /** Get the base URL */
+    readonly baseUrl: string;
+}
+export interface TestResponse {
+    status: number;
+    headers: Headers;
+    body: unknown;
+    json<T = unknown>(): Promise<T>;
+    text(): Promise<string>;
+}
+/**
+ * Create a test client for an app.
+ * Starts a server, makes requests, and cleans up.
+ *
+ * @example
+ * ```ts
+ * const api = await createTestClient(app)
+ * const res = await api.get('/users/1')
+ * expect(res.status).toBe(200)
+ * expect(res.body).toEqual({ id: '1', name: 'Ada' })
+ * await api.close()
+ * ```
+ */
+export declare function createTestClient(app: App): Promise<TestClient>;
+/**
+ * Test that a handler satisfies its contract.
+ * Calls the handler and validates the response against the declared schemas.
+ *
+ * @example
+ * ```ts
+ * testContract(getUser, async (call) => {
+ *   const res = await call({ params: { id: '1' } })
+ *   expect(res.status).toBe(200)
+ *   expect(res.body).toMatchSchema(getUser.responses[200])
+ * })
+ * ```
+ */
+export declare function testContract<C extends AnyContract>(contract: C, fn: (call: (input: SectionsOf<C>) => Promise<ResponseOf<C>>) => Promise<void>): void;
+/**
+ * Validate that a value matches a schema.
+ * Returns true if valid, throws with details if invalid.
+ */
+export declare function expectSchema(schema: unknown, value: unknown): void;
+/**
+ * Create a typed mock for a contract's sections.
+ * Useful for generating test data.
+ */
+export declare function mockSections<C extends AnyContract>(contract: C, overrides?: Partial<SectionsOf<C>>): SectionsOf<C>;

package/dist/test.js

@@ -0,0 +1,131 @@
+import { Value } from './schema.js';
+import { listen } from './node.js';
+/**
+ * Create a test client for an app.
+ * Starts a server, makes requests, and cleans up.
+ *
+ * @example
+ * ```ts
+ * const api = await createTestClient(app)
+ * const res = await api.get('/users/1')
+ * expect(res.status).toBe(200)
+ * expect(res.body).toEqual({ id: '1', name: 'Ada' })
+ * await api.close()
+ * ```
+ */
+export async function createTestClient(app) {
+    const server = await listen(app, 0);
+    const port = server.address().port;
+    const baseUrl = `http://127.0.0.1:${port}`;
+    async function request(path, init = {}) {
+        const res = await fetch(`${baseUrl}${path}`, {
+            ...init,
+            headers: {
+                'content-type': 'application/json',
+                ...init.headers,
+            },
+        });
+        let body = null;
+        try {
+            body = await res.json();
+        }
+        catch {
+            try {
+                body = await res.text();
+            }
+            catch {
+                body = null;
+            }
+        }
+        return {
+            status: res.status,
+            headers: res.headers,
+            body,
+            json: () => Promise.resolve(body),
+            text: () => Promise.resolve(typeof body === 'string' ? body : JSON.stringify(body)),
+        };
+    }
+    return {
+        baseUrl,
+        get: (path, init) => request(path, { ...init, method: 'GET' }),
+        post: (path, body, init) => request(path, { ...init, method: 'POST', body: body != null ? JSON.stringify(body) : undefined }),
+        put: (path, body, init) => request(path, { ...init, method: 'PUT', body: body != null ? JSON.stringify(body) : undefined }),
+        patch: (path, body, init) => request(path, { ...init, method: 'PATCH', body: body != null ? JSON.stringify(body) : undefined }),
+        delete: (path, init) => request(path, { ...init, method: 'DELETE' }),
+        request,
+        close: () => new Promise((resolve, reject) => {
+            server.closeAllConnections?.();
+            server.close((err) => (err ? reject(err) : resolve()));
+        }),
+    };
+}
+/**
+ * Test that a handler satisfies its contract.
+ * Calls the handler and validates the response against the declared schemas.
+ *
+ * @example
+ * ```ts
+ * testContract(getUser, async (call) => {
+ *   const res = await call({ params: { id: '1' } })
+ *   expect(res.status).toBe(200)
+ *   expect(res.body).toMatchSchema(getUser.responses[200])
+ * })
+ * ```
+ */
+export function testContract(contract, fn) {
+    // This is a higher-order test helper - actual test framework integration
+    // would require a adapter for vitest/jest/etc.
+    // For now, export the utility and let users wrap it.
+}
+/**
+ * Validate that a value matches a schema.
+ * Returns true if valid, throws with details if invalid.
+ */
+export function expectSchema(schema, value) {
+    if (!Value.Check(schema, value)) {
+        const errors = [...Value.Errors(schema, value)];
+        const details = errors.map((e) => `${e.path || '/'}: ${e.message}`).join('\n');
+        throw new Error(`Schema validation failed:\n${details}`);
+    }
+}
+/**
+ * Create a typed mock for a contract's sections.
+ * Useful for generating test data.
+ */
+export function mockSections(contract, overrides) {
+    const sections = {};
+    if ('params' in contract && contract.params) {
+        sections.params = generateMock(contract.params);
+    }
+    if ('query' in contract && contract.query) {
+        sections.query = generateMock(contract.query);
+    }
+    if ('body' in contract && contract.body) {
+        sections.body = generateMock(contract.body);
+    }
+    return { ...sections, ...overrides };
+}
+/**
+ * Generate mock data from a TypeBox schema.
+ */
+function generateMock(schema) {
+    const s = schema;
+    if (s.type === 'string')
+        return 'mock-string';
+    if (s.type === 'number')
+        return 42;
+    if (s.type === 'boolean')
+        return true;
+    if (s.type === 'array') {
+        const items = s.items ? generateMock(s.items) : 'mock-item';
+        return [items];
+    }
+    if (s.type === 'object' && s.properties) {
+        const obj = {};
+        for (const [key, value] of Object.entries(s.properties)) {
+            obj[key] = generateMock(value);
+        }
+        return obj;
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlos-tzin/tzin",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Contract-first TypeScript framework. Types that scale, realtime channels with presence, and an MCP server for every API.",
   "license": "MIT",
   "author": "The tzin authors",
@@ -21,7 +21,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/Charly921/tzin"
+    "url": "git+https://github.com/Charly921/tzin.git"
   },
   "type": "module",
   "main": "./dist/index.js",
@@ -42,6 +42,10 @@
     "./ws": {
       "types": "./dist/ws.d.ts",
       "default": "./dist/ws.js"
+    },
+    "./test": {
+      "types": "./dist/test.d.ts",
+      "default": "./dist/test.js"
     }
   },
   "files": [