filamentjs 0.1.0

package/.ai/instructions.md

@@ -0,0 +1,44 @@
+# Filament AI Development Guidelines
+
+## Architecture-specific patterns
+
+- **Meta merging**: Shallow merge with defaults - **arrays replace, not merge**
+- **Response flow order**: Middleware → Handler → Transformers → Finalizers
+  - Transformers only run on success
+  - Finalizers always run (even on errors)
+- **Type pattern**: All classes use `<T extends FrameworkMeta>` generic
+
+## Coding standards
+
+- Lines under 80 columns when possible
+- Comments are to document design and usage, not to repeat code.
+- When updating code, ensure that the READMEs and test cases are also up to date whith your changes.
+
+### Typescript
+
+- imports should be in this order: Native, public libraries, local modules. Alphabetize within this order. Local modules may be difficult to alphabetize, just do your best.
+
+### Markdown
+
+- Markdowns should have an empty line after all headers and before all lists.
+
+### Testing (Non-standard tooling)
+
+- **Assertions**: `test-battery` library, NOT chai/assert
+- **Test framework**: Node.js native test runner (`node:test`), NOT mocha/jest.
+  - Favour the native name `suite`, not its aliases like `describe`. Use
+    `test-battery` to handle the `test` part.
+- Integration tests use real HTTP servers on high-numbered ports (9876+)
+
+```typescript
+import { describe, it } from 'node:test';
+import TestBattery from 'test-battery';
+```
+
+## Protected files
+
+DO NOT modify: `/dist/*`, `package-lock.json`, `tsconfig.json` (ask first)
+
+## Adding route methods
+
+Follow pattern in `application.ts:62-81` - must update Route type and add handler

package/README.md

@@ -0,0 +1,273 @@
+# Filament
+
+A TypeScript API framework with metadata-driven middleware. Similar in purpose to Express but organized around typed endpoint metadata that controls middleware behavior.
+
+## Why Filament?
+
+### Best Features
+
+- **Type-Safe Metadata**: Full TypeScript support means your middleware logic is validated at compile time
+- **Zero Runtime Overhead**: Metadata inspection is fast—no reflection or complex routing logic
+- **Predictable Execution**: Registration order is everything—no magic, no surprises
+- **Immutable Request Context**: Middleware can't accidentally corrupt endpoint metadata
+- **Flexible Post-Processing**: Handle errors, transform responses, and finalize requests with dedicated hooks
+- **Express-Familiar API**: If you know Express, you know Filament—intuitive and approachable
+- **Minimal Dependencies**: Lightweight framework perfect for microservices and APIs
+- **Strongly Typed Middleware**: Know exactly what metadata your middleware needs before writing a single line
+
+## Core Concepts
+
+### 1. Endpoint Metadata (`EndpointMeta`)
+
+Every endpoint has metadata that describes its requirements and behavior. Middleware inspects this metadata to decide whether and how to execute.
+
+```typescript
+interface AppMeta extends FrameworkMeta {
+  requiresAuth: boolean;
+  rateLimit: number;
+  logLevel: 'debug' | 'info' | 'error';
+  tags: string[];
+}
+```
+
+### 2. Default Metadata
+
+You define a complete default metadata object when creating your app. Individual endpoints can override specific properties using `Partial<T>`.
+
+### 3. Single Middleware Chain
+
+Middleware runs in registration order. Each middleware inspects `req.endpointMeta` to decide what to do.
+
+### 4. Post-Request Processing
+
+Three types of post-request handlers:
+
+- **Error Handlers**: Run when errors occur
+- **Response Transformers**: Modify successful responses
+- **Finalizers**: Always run, regardless of success/failure
+
+## Quick Start
+
+```typescript
+import { createApp, FrameworkMeta } from 'filamentjs';
+
+// Define your metadata interface
+interface AppMeta extends FrameworkMeta {
+  requiresAuth: boolean;
+  rateLimit: number;
+  logLevel: 'debug' | 'info' | 'error';
+  tags: string[];
+}
+
+// Create default metadata
+const defaultMeta: AppMeta = {
+  requiresAuth: false,
+  rateLimit: 100,
+  logLevel: 'info',
+  tags: [],
+};
+
+// Create app
+const app = createApp<AppMeta>(defaultMeta);
+
+// Add middleware that inspects metadata
+app.use(async (req, res, next) => {
+  if (req.endpointMeta.requiresAuth) {
+    const token = req.headers.authorization;
+    if (!token) {
+      res.status(401).json({ error: 'Unauthorized' });
+      return;
+    }
+    // validate token...
+  }
+  await next();
+});
+
+// Define endpoints with custom metadata
+app.get('/public', {}, async (req, res) => {
+  res.json({ message: 'Public endpoint' });
+});
+
+app.get('/admin', 
+  { requiresAuth: true, logLevel: 'debug' },
+  async (req, res) => {
+    res.json({ message: 'Admin panel' });
+  }
+);
+
+// Start server
+app.listen(3000);
+```
+
+## API Reference
+
+### `createApp<T>(defaultMeta: T): Application<T>`
+
+Creates a new application instance with typed metadata.
+
+**Parameters:**
+
+- `defaultMeta`: Complete implementation of your metadata interface
+
+**Returns:** Application instance
+
+### Application Methods
+
+#### HTTP Methods
+
+```typescript
+app.get(path: string, meta: Partial<T>, handler: AsyncRequestHandler): void
+app.post(path: string, meta: Partial<T>, handler: AsyncRequestHandler): void
+app.put(path: string, meta: Partial<T>, handler: AsyncRequestHandler): void
+app.patch(path: string, meta: Partial<T>, handler: AsyncRequestHandler): void
+app.delete(path: string, meta: Partial<T>, handler: AsyncRequestHandler): void
+```
+
+#### Middleware Registration
+
+```typescript
+app.use(middleware: AsyncRequestHandler): void
+app.use(path: string, middleware: AsyncRequestHandler): void
+```
+
+#### Post-Request Handlers
+
+```typescript
+app.onError(handler: ErrorHandler<T>): void
+app.onTransform(handler: ResponseTransformer<T>): void
+app.onFinalize(handler: Finalizer<T>): void
+```
+
+#### Server Control
+
+```typescript
+app.listen(port: number, callback?: () => void): void
+app.close(): Promise<void>
+```
+
+## Request Object
+
+```typescript
+interface Request<T extends FrameworkMeta> {
+  method: HttpMethod;
+  path: string;
+  params: Record<string, string>;        // Path parameters
+  query: Record<string, string | string[]>;  // Query parameters
+  headers: Record<string, string | string[] | undefined>;
+  body?: unknown;                        // Parsed JSON body
+  endpointMeta: Readonly<T>;            // Endpoint metadata (read-only)
+}
+```
+
+## Response Object
+
+```typescript
+interface Response {
+  status(code: number): Response;
+  setHeader(name: string, value: string | string[]): Response;
+  json(data: unknown): void;
+  send(data: string | Buffer): void;
+  end(): void;
+}
+```
+
+## Request Lifecycle
+
+```text
+1. Incoming Request
+   ↓
+2. Route Matching → req.endpointMeta populated (readonly)
+   ↓
+3. Middleware Chain (in registration order)
+   - Each middleware inspects req.endpointMeta
+   - Decides whether to execute logic
+   - await next() continues chain
+   ↓
+4. Route Handler executes
+   ↓
+5. [If Success] Response Transformers (sequential, awaited)
+   ↓
+6. [If Error anywhere] Error Handlers (sequential, awaited)
+   ↓
+7. Finalizers (always run, sequential, awaited)
+   ↓
+8. Response sent
+```
+
+## Path Parameters
+
+Supports Express-style path parameters:
+
+```typescript
+app.get('/users/:id', {}, async (req, res) => {
+  const userId = req.params.id;  // string
+  res.json({ userId });
+});
+
+app.get('/posts/:postId/comments/:commentId', {}, async (req, res) => {
+  const { postId, commentId } = req.params;
+  res.json({ postId, commentId });
+});
+```
+
+## Metadata Merging
+
+- Endpoint metadata is merged with defaults using shallow merge
+- Arrays **always replace** (not concatenate)
+- Metadata is immutable at runtime
+
+```typescript
+const defaultMeta = {
+  requiresAuth: false,
+  tags: ['default'],
+};
+
+app.get('/endpoint', 
+  { requiresAuth: true, tags: ['custom'] },  // tags replaces, not appends
+  handler
+);
+// Result: { requiresAuth: true, tags: ['custom'] }
+```
+
+## Error Handling
+
+Errors thrown anywhere in the request lifecycle are caught and passed to error handlers:
+
+```typescript
+app.onError(async (err, req, res) => {
+  console.error('Error:', err);
+  res.status(500).json({ error: err.message });
+});
+```
+
+## Complete Example
+
+See `src/example.ts` for a complete working example with:
+
+- Authentication middleware
+- Rate limiting middleware
+- Logging middleware
+- Multiple endpoints with different metadata
+- Response transformers
+- Error handling
+- Finalizers
+
+## Design Decisions
+
+1. **Immutable Metadata**: `req.endpointMeta` is read-only to prevent middleware from creating hidden dependencies
+2. **Async by Default**: All handlers support `async/await`
+3. **Registration Order**: Middleware runs in strict registration order
+4. **Path Parameters**: Typed as `Record<string, string>` (no advanced type inference)
+5. **Array Replacement**: Arrays in metadata always replace (never merge)
+
+## TypeScript
+
+Full TypeScript support with strict typing:
+
+- Generic `Application<T>` for typed metadata
+- Type-safe request/response objects
+- Compile-time validation of metadata interfaces
+
+## License
+
+ISC

package/dist/src/application.d.ts

@@ -0,0 +1,76 @@
+import { FrameworkMeta, AsyncRequestHandler, ErrorHandler, Finalizer, ResponseTransformer } from './types.js';
+/**
+ * Main Application class for Filament
+ */
+export declare class Application<T extends FrameworkMeta> {
+    private routes;
+    private middlewares;
+    private errorHandlers;
+    private finalizers;
+    private transformers;
+    private defaultMeta;
+    private server?;
+    constructor(defaultMeta: T);
+    /**
+     * Register a route
+     */
+    private route;
+    /**
+     * Merge partial meta with defaults
+     */
+    private mergeMeta;
+    get(path: string, meta: Partial<T>, handler: AsyncRequestHandler<T>): void;
+    post(path: string, meta: Partial<T>, handler: AsyncRequestHandler<T>): void;
+    put(path: string, meta: Partial<T>, handler: AsyncRequestHandler<T>): void;
+    patch(path: string, meta: Partial<T>, handler: AsyncRequestHandler<T>): void;
+    delete(path: string, meta: Partial<T>, handler: AsyncRequestHandler<T>): void;
+    /**
+     * Register middleware
+     */
+    use(pathOrHandler: string | AsyncRequestHandler<T>, handler?: AsyncRequestHandler<T>): void;
+    /**
+     * Register error handler
+     */
+    onError(handler: ErrorHandler<T>): void;
+    /**
+     * Register finalizer
+     */
+    onFinalize(handler: Finalizer<T>): void;
+    /**
+     * Register response transformer
+     */
+    onTransform(handler: ResponseTransformer<T>): void;
+    /**
+     * Execute middleware chain
+     */
+    private executeMiddlewareChain;
+    /**
+     * Execute error handlers
+     */
+    private executeErrorHandlers;
+    /**
+     * Execute response transformers
+     */
+    private executeTransformers;
+    /**
+     * Execute finalizers
+     */
+    private executeFinalizers;
+    /**
+     * Handle incoming HTTP request
+     */
+    private handleRequest;
+    /**
+     * Start the server
+     */
+    listen(port: number): Promise<number>;
+    /**
+     * Stop the server
+     */
+    close(): Promise<void>;
+}
+/**
+ * Factory function to create an application
+ */
+export declare function createApp<T extends FrameworkMeta>(defaultMeta: T): Application<T>;
+//# sourceMappingURL=application.d.ts.map

package/dist/src/application.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../src/application.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,aAAa,EAIb,mBAAmB,EACnB,YAAY,EACZ,SAAS,EACT,mBAAmB,EAGpB,MAAM,YAAY,CAAC;AAIpB;;GAEG;AACH,qBAAa,WAAW,CAAC,CAAC,SAAS,aAAa;IAC9C,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,UAAU,CAAsB;IACxC,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,WAAW,CAAI;IACvB,OAAO,CAAC,MAAM,CAAC,CAAc;gBAEjB,WAAW,EAAE,CAAC;IAI1B;;OAEG;IACH,OAAO,CAAC,KAAK;IAmBb;;OAEG;IACH,OAAO,CAAC,SAAS;IASjB,GAAG,CACD,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAChB,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC9B,IAAI;IAIP,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAChB,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC9B,IAAI;IAIP,GAAG,CACD,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAChB,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC9B,IAAI;IAIP,KAAK,CACH,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAChB,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC9B,IAAI;IAIP,MAAM,CACJ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAChB,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC9B,IAAI;IAIP;;OAEG;IACH,GAAG,CACD,aAAa,EAAE,MAAM,GAAG,mBAAmB,CAAC,CAAC,CAAC,EAC9C,OAAO,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC/B,IAAI;IAQP;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAIvC;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAIvC;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI;IAIlD;;OAEG;YACW,sBAAsB;IAmBpC;;OAEG;YACW,oBAAoB;IAmBlC;;OAEG;YACW,mBAAmB;IAWjC;;OAEG;YACW,iBAAiB;IAW/B;;OAEG;YACW,aAAa;IAsH3B;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA6B3C;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAYvB;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,aAAa,EAAE,WAAW,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAEjF"}

package/dist/src/application.js

@@ -0,0 +1,313 @@
+import http from 'http';
+import { URL } from 'url';
+import { ResponseImpl } from './response.js';
+import { pathToRegex, matchPath } from './router.js';
+/**
+ * Main Application class for Filament
+ */
+export class Application {
+    constructor(defaultMeta) {
+        this.routes = [];
+        this.middlewares = [];
+        this.errorHandlers = [];
+        this.finalizers = [];
+        this.transformers = [];
+        this.defaultMeta = defaultMeta;
+    }
+    /**
+     * Register a route
+     */
+    route(method, path, meta, handler) {
+        const { pattern, paramNames } = pathToRegex(path);
+        const mergedMeta = this.mergeMeta(meta);
+        this.routes.push({
+            method,
+            path,
+            pattern,
+            paramNames,
+            meta: mergedMeta,
+            handler,
+        });
+    }
+    /**
+     * Merge partial meta with defaults
+     */
+    mergeMeta(partial) {
+        // Shallow merge - arrays replace
+        return {
+            ...this.defaultMeta,
+            ...partial,
+        };
+    }
+    // HTTP method helpers
+    get(path, meta, handler) {
+        this.route('GET', path, meta, handler);
+    }
+    post(path, meta, handler) {
+        this.route('POST', path, meta, handler);
+    }
+    put(path, meta, handler) {
+        this.route('PUT', path, meta, handler);
+    }
+    patch(path, meta, handler) {
+        this.route('PATCH', path, meta, handler);
+    }
+    delete(path, meta, handler) {
+        this.route('DELETE', path, meta, handler);
+    }
+    /**
+     * Register middleware
+     */
+    use(pathOrHandler, handler) {
+        if (typeof pathOrHandler === 'string' && handler) {
+            this.middlewares.push({ path: pathOrHandler, handler });
+        }
+        else if (typeof pathOrHandler === 'function') {
+            this.middlewares.push({ handler: pathOrHandler });
+        }
+    }
+    /**
+     * Register error handler
+     */
+    onError(handler) {
+        this.errorHandlers.push(handler);
+    }
+    /**
+     * Register finalizer
+     */
+    onFinalize(handler) {
+        this.finalizers.push(handler);
+    }
+    /**
+     * Register response transformer
+     */
+    onTransform(handler) {
+        this.transformers.push(handler);
+    }
+    /**
+     * Execute middleware chain
+     */
+    async executeMiddlewareChain(req, res, middlewares) {
+        let currentIndex = 0;
+        const next = async () => {
+            if (currentIndex >= middlewares.length) {
+                return;
+            }
+            const middleware = middlewares[currentIndex++];
+            await middleware(req, res, next);
+        };
+        await next();
+    }
+    /**
+     * Execute error handlers
+     */
+    async executeErrorHandlers(err, req, res) {
+        for (const handler of this.errorHandlers) {
+            try {
+                await handler(err, req, res, async () => { });
+            }
+            catch (handlerError) {
+                console.error('Error in error handler:', handlerError);
+            }
+        }
+        // If no error handler sent a response, send default error
+        if (!res.headersSent) {
+            res.status(500).json({ error: 'Internal Server Error' });
+        }
+    }
+    /**
+     * Execute response transformers
+     */
+    async executeTransformers(req, res) {
+        for (const transformer of this.transformers) {
+            try {
+                await transformer(req, res);
+            }
+            catch (err) {
+                console.error('Error in response transformer:', err);
+                throw err;
+            }
+        }
+    }
+    /**
+     * Execute finalizers
+     */
+    async executeFinalizers(req, res) {
+        for (const finalizer of this.finalizers) {
+            try {
+                await finalizer(req, res);
+            }
+            catch (err) {
+                console.error('Error in finalizer:', err);
+                // Finalizers should not block response
+            }
+        }
+    }
+    /**
+     * Handle incoming HTTP request
+     */
+    async handleRequest(nodeReq, nodeRes) {
+        const url = new URL(nodeReq.url || '/', `http://${nodeReq.headers.host || 'localhost'}`);
+        const method = (nodeReq.method || 'GET').toUpperCase();
+        const path = url.pathname;
+        // Find matching route
+        let matchedRoute;
+        let params = {};
+        for (const route of this.routes) {
+            if (route.method !== method)
+                continue;
+            const match = matchPath(path, route.pattern, route.paramNames);
+            if (match) {
+                matchedRoute = route;
+                params = match.params;
+                break;
+            }
+        }
+        if (!matchedRoute) {
+            nodeRes.statusCode = 404;
+            nodeRes.end(JSON.stringify({ error: 'Not Found' }));
+            return;
+        }
+        // Parse query parameters
+        const query = {};
+        url.searchParams.forEach((value, key) => {
+            const existing = query[key];
+            if (existing) {
+                query[key] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+            }
+            else {
+                query[key] = value;
+            }
+        });
+        // Parse headers
+        const headers = {};
+        Object.entries(nodeReq.headers).forEach(([key, value]) => {
+            headers[key] = value;
+        });
+        // Create request object
+        const req = {
+            method,
+            path,
+            params,
+            query,
+            headers,
+            endpointMeta: matchedRoute.meta,
+            _startTime: Date.now(),
+        };
+        // Read body for POST/PUT/PATCH
+        if (['POST', 'PUT', 'PATCH'].includes(method)) {
+            const chunks = [];
+            for await (const chunk of nodeReq) {
+                chunks.push(chunk);
+            }
+            const bodyStr = Buffer.concat(chunks).toString();
+            if (bodyStr) {
+                try {
+                    req.body = JSON.parse(bodyStr);
+                }
+                catch {
+                    req.body = bodyStr;
+                }
+            }
+        }
+        // Create response object
+        const res = new ResponseImpl((finalRes) => {
+            nodeRes.statusCode = finalRes.statusCode;
+            Object.entries(finalRes.headers).forEach(([key, value]) => {
+                nodeRes.setHeader(key, value);
+            });
+            if (finalRes.body) {
+                nodeRes.end(finalRes.body);
+            }
+            else {
+                nodeRes.end();
+            }
+        });
+        let hadError = false;
+        try {
+            // Filter applicable middleware (by path if specified)
+            const applicableMiddleware = this.middlewares
+                .filter((mw) => !mw.path || path.startsWith(mw.path))
+                .map((mw) => mw.handler);
+            // Execute middleware chain
+            await this.executeMiddlewareChain(req, res, applicableMiddleware);
+            // If response already sent by middleware, skip handler
+            if (!res.headersSent) {
+                // Execute route handler
+                await matchedRoute.handler(req, res, async () => { });
+                // Execute response transformers (only on success)
+                if (!res.headersSent) {
+                    await this.executeTransformers(req, res);
+                }
+            }
+        }
+        catch (err) {
+            hadError = true;
+            await this.executeErrorHandlers(err, req, res);
+        }
+        finally {
+            // Always execute finalizers
+            await this.executeFinalizers(req, res);
+            // Ensure response is sent
+            if (!res.headersSent) {
+                res.end();
+            }
+        }
+    }
+    /**
+     * Start the server
+     */
+    async listen(port) {
+        return new Promise((resolve, reject) => {
+            this.server = http.createServer((req, res) => {
+                this.handleRequest(req, res).catch((err) => {
+                    console.error('Unhandled error in request handler:', err);
+                    if (!res.headersSent) {
+                        res.statusCode = 500;
+                        res.end(JSON.stringify({ error: 'Internal Server Error' }));
+                    }
+                });
+            });
+            this.server.on('error', (err) => {
+                if (err.code === 'EADDRINUSE') {
+                    reject(new Error(`Port ${port} is already in use`));
+                }
+                else if (err.code === 'EACCES') {
+                    reject(new Error(`Permission denied: cannot listen on port ${port}`));
+                }
+                else {
+                    reject(new Error(`Failed to start server on port ${port}: ${err.message}`));
+                }
+            });
+            this.server.listen(port, () => {
+                console.log(`Server listening on port ${port}`);
+                resolve(port);
+            });
+        });
+    }
+    /**
+     * Stop the server
+     */
+    close() {
+        return new Promise((resolve, reject) => {
+            if (this.server) {
+                this.server.close((err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+}
+/**
+ * Factory function to create an application
+ */
+export function createApp(defaultMeta) {
+    return new Application(defaultMeta);
+}
+//# sourceMappingURL=application.js.map