@tamayrp14/fire-api 0.0.0-stage → 1.0.0

package/test/file-upload.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'bun:test';
+import { createApp, createRouter, s } from '../src/index';
+
+describe('FireAPI Native Multipart & File Upload Shield (s.file, ctx.files)', () => {
+  it('parses multipart/form-data and stores uploaded files via ctx.files.*.store()', async () => {
+    const app = createApp({
+      storage: { driver: 'memory' },
+    });
+    const router = createRouter();
+
+    const UploadSchema = s.object({
+      title: s.string().min(2),
+      avatar: s.file({
+        maxSize: '2MB',
+        types: ['image/png', 'image/jpeg'],
+      }),
+    });
+
+    router.post('/upload', {
+      schema: { body: UploadSchema },
+      handler: async (ctx) => {
+        const stored = await ctx.files.avatar.store('avatars');
+        return ctx.created({
+          title: ctx.body.title,
+          fileName: ctx.files.avatar.name,
+          fileSize: ctx.files.avatar.size,
+          url: stored.url,
+        });
+      },
+    });
+
+    app.use(router);
+
+    // Create a real FormData
+    const formData = new FormData();
+    formData.append('title', 'My Profile Photo');
+    const fakeFile = new File(['fake-png-binary-content-12345'], 'profile.png', { type: 'image/png' });
+    formData.append('avatar', fakeFile);
+
+    const res = await app.handle(
+      new Request('http://localhost:3000/upload', {
+        method: 'POST',
+        body: formData,
+      })
+    );
+
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.title).toBe('My Profile Photo');
+    expect(body.fileName).toBe('profile.png');
+    expect(body.fileSize).toBeGreaterThan(0);
+    expect(body.url).toContain('/uploads/avatars/');
+  });
+
+  it('rejects files exceeding maxSize with 400 validation error', async () => {
+    const app = createApp();
+    const router = createRouter();
+
+    router.post('/upload-strict', {
+      schema: {
+        body: s.object({
+          doc: s.file({ maxSize: '10B' }), // Tiny limit: 10 bytes!
+        }),
+      },
+      handler: async (ctx) => ctx.ok({ success: true }),
+    });
+
+    app.use(router);
+
+    const formData = new FormData();
+    const largeFile = new File(['This file is definitely longer than 10 bytes'], 'big.txt', { type: 'text/plain' });
+    formData.append('doc', largeFile);
+
+    const res = await app.handle(
+      new Request('http://localhost:3000/upload-strict', {
+        method: 'POST',
+        body: formData,
+      })
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.message).toBe('Validation Error');
+  });
+
+  it('rejects forbidden file types with 400 validation error', async () => {
+    const app = createApp();
+    const router = createRouter();
+
+    router.post('/upload-images-only', {
+      schema: {
+        body: s.object({
+          image: s.file({ types: ['image/png', 'image/jpeg'] }),
+        }),
+      },
+      handler: async (ctx) => ctx.ok({ success: true }),
+    });
+
+    app.use(router);
+
+    const formData = new FormData();
+    const exeFile = new File(['malicious-binary'], 'malware.exe', { type: 'application/x-msdownload' });
+    formData.append('image', exeFile);
+
+    const res = await app.handle(
+      new Request('http://localhost:3000/upload-images-only', {
+        method: 'POST',
+        body: formData,
+      })
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.message).toBe('Validation Error');
+  });
+});

package/test/hooks.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'bun:test';
+import { createApp, createRouter } from '../src/index';
+
+describe('FireAPI Lifecycle Interceptors & Hooks (app.hook)', () => {
+  it('intercepts request early via onRequest hook', async () => {
+    const app = createApp();
+    const router = createRouter();
+
+    let hookExecuted = false;
+
+    // Reject IP if blacklisted
+    app.hook('onRequest', async (ctx) => {
+      hookExecuted = true;
+      if (ctx.req.headers.get('x-blocked-client') === 'true') {
+        return ctx.forbidden('Access blocked by security hook');
+      }
+    });
+
+    router.get('/data', (ctx) => ctx.ok({ secret: 'safe' }));
+    app.use(router);
+
+    // 1. Blocked request
+    const resBlocked = await app.handle(
+      new Request('http://localhost:3000/data', {
+        headers: { 'x-blocked-client': 'true' },
+      })
+    );
+    expect(resBlocked.status).toBe(403);
+    expect(hookExecuted).toBe(true);
+
+    // 2. Normal request
+    const resNormal = await app.handle(new Request('http://localhost:3000/data'));
+    expect(resNormal.status).toBe(200);
+  });
+
+  it('modifies response via afterHandle hook', async () => {
+    const app = createApp();
+    const router = createRouter();
+
+    app.hook('afterHandle', async (ctx, response) => {
+      const headers = new Headers(response.headers);
+      headers.set('X-Global-Audit', 'verified');
+      return new Response(response.body, {
+        status: response.status,
+        headers,
+      });
+    });
+
+    router.get('/items', (ctx) => ctx.ok(['item1', 'item2']));
+    app.use(router);
+
+    const res = await app.handle(new Request('http://localhost:3000/items'));
+    expect(res.status).toBe(200);
+    expect(res.headers.get('X-Global-Audit')).toBe('verified');
+  });
+
+  it('captures uncaught errors via onError hook', async () => {
+    const app = createApp();
+    const router = createRouter();
+
+    let capturedError: any = null;
+
+    app.hook('onError', async (err) => {
+      capturedError = err;
+    });
+
+    router.get('/crash', () => {
+      throw new Error('Database connection explosion');
+    });
+    app.use(router);
+
+    const res = await app.handle(new Request('http://localhost:3000/crash'));
+    expect(res.status).toBe(500);
+    expect(capturedError).not.toBeNull();
+    expect(capturedError.message).toBe('Database connection explosion');
+  });
+});

package/test/idempotency.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'bun:test';
+import { createApp, createRouter } from '../src/index';
+
+describe('FireAPI Idempotency Shield (X-Idempotency-Key)', () => {
+  it('deduplicates requests and returns identical cached response without re-executing handler', async () => {
+    const app = createApp({ database: { driver: 'memory' } });
+    let executionCount = 0;
+
+    const orderRouter = createRouter('/orders');
+    orderRouter.post('/checkout', {
+      idempotent: true,
+      handler: async (ctx) => {
+        executionCount++;
+        const order = await ctx.db.orders.insert({
+          total: ctx.body.total,
+          orderNumber: `ORD-${Date.now()}-${executionCount}`,
+        });
+        return ctx.created(order);
+      },
+    });
+
+    app.use(orderRouter);
+
+    const idempotencyKey = 'unique-key-xyz-777';
+
+    // 1. First Request
+    const res1 = await app.handle(
+      new Request('http://localhost:3000/orders/checkout', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Idempotency-Key': idempotencyKey,
+        },
+        body: JSON.stringify({ total: 100 }),
+      })
+    );
+
+    expect(res1.status).toBe(201);
+    const data1 = await res1.json();
+    expect(executionCount).toBe(1);
+    expect(data1.total).toBe(100);
+
+    // 2. Second Request (Identical X-Idempotency-Key) - Must NOT re-execute handler!
+    const res2 = await app.handle(
+      new Request('http://localhost:3000/orders/checkout', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Idempotency-Key': idempotencyKey,
+        },
+        body: JSON.stringify({ total: 100 }),
+      })
+    );
+
+    expect(res2.status).toBe(201);
+    const data2 = await res2.json();
+    expect(executionCount).toBe(1); // Handler was NOT run again!
+    expect(data2.orderNumber).toBe(data1.orderNumber); // Identical response payload!
+    expect(res2.headers.get('X-Idempotent-Replay')).toBe('true');
+
+    // Verify only 1 order exists in database
+    const ordersInDb = await app.db.orders.find();
+    expect(ordersInDb.length).toBe(1);
+  });
+});

package/test/integration.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'bun:test';
+import { createApp, createRouter, s, createClient } from '../src/index';
+
+describe('FireAPI End-to-End Integration Suite', () => {
+  it('powers a complete production API lifecycle with DB, Security, Validation, and Client', async () => {
+    const app = createApp({
+      database: { driver: 'memory' },
+      security: {
+        rateLimit: { max: 100, window: '1m' },
+        cors: true,
+      },
+      docs: '/docs',
+      openapiPath: '/openapi.json',
+    });
+
+    const UserSchema = s.object({
+      name: s.string().min(2),
+      email: s.string().email(),
+      role: s.enum(['admin', 'member']).default('member'),
+    });
+
+    const userRouter = createRouter('/users');
+
+    userRouter.post('/', {
+      schema: { body: UserSchema },
+      ai: { description: 'Register a new user' },
+      handler: async (ctx) => {
+        const created = await ctx.db.table('users').insert(ctx.body);
+        return ctx.created(created);
+      },
+    });
+
+    userRouter.get('/:id', {
+      schema: { params: s.object({ id: s.string().min(1) }) },
+      cache: { ttl: 30, tags: ['users'] },
+      ai: { description: 'Get user by unique ID' },
+      handler: async (ctx) => {
+        const user = await ctx.db.table('users').findById(ctx.params.id);
+        if (!user) return ctx.notFound('User not found');
+        return ctx.ok(user);
+      },
+    });
+
+    app.use(userRouter);
+    app.enableMCP({ name: 'IntegrationMCP' });
+
+    // 1. Create client bound to app.handle directly
+    const client = createClient('http://localhost:3000', {
+      fetch: (url, init) => {
+        const req = new Request(url, init);
+        return app.handle(req);
+      },
+    });
+
+    // 2. Test POST /users (Success)
+    const postRes = await client.users.post({
+      body: { name: 'Yoga Developer', email: 'yoga@fire.dev' },
+    });
+    expect(postRes.status).toBe(201);
+    expect(postRes.data.id).toBeDefined();
+    expect(postRes.data.name).toBe('Yoga Developer');
+    expect(postRes.data.role).toBe('member');
+    expect(postRes.headers.get('x-response-time')).toBeDefined();
+    expect(postRes.headers.get('x-content-type-options')).toBe('nosniff');
+
+    const createdId = postRes.data.id;
+
+    // 3. Test POST /users (Validation failure)
+    const badRes = await client.users.post({
+      body: { name: 'Y', email: 'invalid-email' },
+    });
+    expect(badRes.status).toBe(400);
+    expect(badRes.data.error).toBe('Bad Request');
+
+    // 4. Test GET /users/:id (Success)
+    const getRes = await client.users[':id'].get({ params: { id: createdId } });
+    expect(getRes.status).toBe(200);
+    expect(getRes.data.email).toBe('yoga@fire.dev');
+
+    // 5. Test OpenAPI Spec generation
+    const specReq = new Request('http://localhost:3000/openapi.json');
+    const specRes = await app.handle(specReq);
+    expect(specRes.status).toBe(200);
+    const specJson = await specRes.json();
+    expect(specJson.openapi).toBe('3.1.0');
+    expect(specJson.paths['/users'].post).toBeDefined();
+
+    // 6. Test Scalar Interactive Docs HTML
+    const docsReq = new Request('http://localhost:3000/docs');
+    const docsRes = await app.handle(docsReq);
+    expect(docsRes.status).toBe(200);
+    expect(docsRes.headers.get('content-type')).toContain('text/html');
+    const htmlText = await docsRes.text();
+    expect(htmlText).toContain('@scalar/api-reference');
+
+    // 7. Test AI / MCP Tool execution endpoint
+    const mcpReq = new Request('http://localhost:3000/mcp', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: '1',
+        method: 'tools/list',
+      }),
+    });
+    const mcpRes = await app.handle(mcpReq);
+    expect(mcpRes.status).toBe(200);
+    const mcpData = await mcpRes.json();
+    expect(mcpData.result.tools.length).toBeGreaterThanOrEqual(2);
+  });
+});

package/test/jobs.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'bun:test';
+import { FireQueueManager } from '../src/jobs/queue';
+import { FireCronScheduler } from '../src/jobs/cron';
+
+describe('FireAPI Zero-Redis Background Jobs & Cron Scheduler', () => {
+  it('dispatches and processes background jobs asynchronously', async () => {
+    const queue = new FireQueueManager();
+    let processedData: any = null;
+
+    queue.handle('send-welcome', async (data) => {
+      processedData = data;
+    });
+
+    const job = await queue.dispatch('send-welcome', { to: 'yoga@fire.dev', name: 'Yoga' });
+    expect(job.id).toBeDefined();
+    expect(job.name).toBe('send-welcome');
+
+    // Wait briefly for in-process worker to consume
+    await new Promise((r) => setTimeout(r, 30));
+
+    expect(processedData).toEqual({ to: 'yoga@fire.dev', name: 'Yoga' });
+    expect(job.status).toBe('completed');
+  });
+
+  it('retries failed jobs up to maxAttempts', async () => {
+    const queue = new FireQueueManager();
+    let attemptCount = 0;
+
+    queue.handle('unstable-task', async () => {
+      attemptCount++;
+      if (attemptCount < 2) {
+        throw new Error('Temporary glitch');
+      }
+    });
+
+    const job = await queue.dispatch('unstable-task', {}, { maxAttempts: 3 });
+
+    await new Promise((r) => setTimeout(r, 60));
+
+    expect(attemptCount).toBe(2);
+    expect(job.status).toBe('completed');
+  });
+
+  it('executes scheduled cron tasks periodically and supports stopping', async () => {
+    const cron = new FireCronScheduler();
+    let ticks = 0;
+
+    const task = cron.schedule('20ms', () => {
+      ticks++;
+    });
+
+    await new Promise((r) => setTimeout(r, 55));
+    expect(ticks).toBeGreaterThanOrEqual(2);
+
+    task.stop();
+    const recordedTicks = ticks;
+    await new Promise((r) => setTimeout(r, 40));
+    expect(ticks).toBe(recordedTicks); // stopped, ticks didn't increase
+  });
+});

package/test/metrics.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'bun:test';
+import { MetricsCollector } from '../src/metrics/metrics';
+import { createApp } from '../src/core/app';
+
+describe('FireAPI Prometheus Metrics & APM Engine (fire-api/metrics)', () => {
+  it('records requests and formats standard Prometheus output', () => {
+    const collector = new MetricsCollector();
+
+    collector.recordRequest('GET', '/api/users', 200, 1.45);
+    collector.recordRequest('GET', '/api/users', 200, 2.10);
+    collector.recordRequest('POST', '/api/users', 201, 5.20);
+    collector.recordRequest('GET', '/api/secret', 403, 0.80);
+
+    const output = collector.formatPrometheus();
+
+    expect(output).toContain('# HELP http_requests_total');
+    expect(output).toContain('# TYPE http_requests_total counter');
+    expect(output).toContain('http_requests_total{method="GET",path="/api/users",status="200"} 2');
+    expect(output).toContain('http_requests_total{method="POST",path="/api/users",status="201"} 1');
+    expect(output).toContain('http_requests_total{method="GET",path="/api/secret",status="403"} 1');
+    expect(output).toContain('http_request_duration_ms_count');
+    expect(output).toContain('process_resident_memory_bytes');
+    expect(output).toContain('process_uptime_seconds');
+  });
+
+  it('serves Prometheus metrics at /metrics automatically from FireApp', async () => {
+    const app = createApp();
+
+    // Trigger one request to record
+    await app.handle(new Request('http://localhost:3000/docs'));
+
+    const metricsRes = await app.handle(new Request('http://localhost:3000/metrics'));
+    expect(metricsRes.status).toBe(200);
+    expect(metricsRes.headers.get('Content-Type')).toContain('text/plain');
+
+    const text = await metricsRes.text();
+    expect(text).toContain('http_requests_total');
+    expect(text).toContain('method="GET"');
+  });
+});

package/test/mock.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'bun:test';
+import { s } from '../src/schema/schema';
+import { generateMock } from '../src/schema/mock';
+
+describe('FireAPI Schema-Driven Auto-Mocking Engine', () => {
+  it('generates schema-compliant mock data that passes schema validation 100%', () => {
+    const ProductSchema = s.object({
+      id: s.string().min(3),
+      title: s.string().min(2),
+      email: s.string().email(),
+      price: s.number().min(10).max(500),
+      isAvailable: s.boolean(),
+      category: s.enum(['electronics', 'books', 'fashion']),
+      tags: s.array(s.string().min(1)).min(1),
+    });
+
+    const mockData = generateMock(ProductSchema);
+
+    expect(mockData).toBeDefined();
+    expect(typeof mockData.title).toBe('string');
+    expect(mockData.email).toContain('@');
+    expect(mockData.price).toBeGreaterThanOrEqual(10);
+    expect(mockData.price).toBeLessThanOrEqual(500);
+    expect(typeof mockData.isAvailable).toBe('boolean');
+    expect(['electronics', 'books', 'fashion']).toContain(mockData.category);
+    expect(Array.isArray(mockData.tags)).toBe(true);
+    expect(mockData.tags.length).toBeGreaterThanOrEqual(1);
+
+    // Verify it passes validation
+    const validation = ProductSchema.validate(mockData);
+    expect(validation.success).toBe(true);
+  });
+});

package/test/multi-tenant.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'bun:test';
+import { createApp, createRouter } from '../src/index';
+
+describe('FireAPI Zero-Ceremony Multi-Tenant SaaS Scoping (ctx.tenant)', () => {
+  it('automatically isolates database records per tenant using X-Tenant-ID header', async () => {
+    const app = createApp({
+      database: { driver: 'memory' },
+      multiTenant: {
+        header: 'X-Tenant-ID',
+        autoScopeDB: true,
+      },
+    });
+
+    const router = createRouter('/products');
+
+    router.post('/', async (ctx) => {
+      const product = await ctx.db.products.insert({ name: ctx.body.name, price: ctx.body.price });
+      return ctx.created(product);
+    });
+
+    router.get('/', async (ctx) => {
+      const products = await ctx.db.products.find();
+      return ctx.ok({ tenantId: ctx.tenant?.id, products });
+    });
+
+    app.use(router);
+
+    // 1. Tenant Acme inserts a product
+    const resAcmeInsert = await app.handle(
+      new Request('http://localhost:3000/products', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Tenant-ID': 'org_acme',
+        },
+        body: JSON.stringify({ name: 'Acme Anvil', price: 99 }),
+      })
+    );
+    expect(resAcmeInsert.status).toBe(201);
+
+    // 2. Tenant Stark inserts a product
+    const resStarkInsert = await app.handle(
+      new Request('http://localhost:3000/products', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Tenant-ID': 'org_stark',
+        },
+        body: JSON.stringify({ name: 'Arc Reactor', price: 99999 }),
+      })
+    );
+    expect(resStarkInsert.status).toBe(201);
+
+    // 3. Acme queries products -> MUST ONLY see Acme's products!
+    const resAcmeGet = await app.handle(
+      new Request('http://localhost:3000/products', {
+        headers: { 'X-Tenant-ID': 'org_acme' },
+      })
+    );
+    expect(resAcmeGet.status).toBe(200);
+    const acmeData = await resAcmeGet.json();
+    expect(acmeData.tenantId).toBe('org_acme');
+    expect(acmeData.products.length).toBe(1);
+    expect(acmeData.products[0].name).toBe('Acme Anvil');
+    expect(acmeData.products[0].tenantId).toBe('org_acme');
+
+    // 4. Stark queries products -> MUST ONLY see Stark's products!
+    const resStarkGet = await app.handle(
+      new Request('http://localhost:3000/products', {
+        headers: { 'X-Tenant-ID': 'org_stark' },
+      })
+    );
+    expect(resStarkGet.status).toBe(200);
+    const starkData = await resStarkGet.json();
+    expect(starkData.tenantId).toBe('org_stark');
+    expect(starkData.products.length).toBe(1);
+    expect(starkData.products[0].name).toBe('Arc Reactor');
+    expect(starkData.products[0].tenantId).toBe('org_stark');
+  });
+});

package/test/observability.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'bun:test';
+import { createApp, createRouter } from '../src/index';
+
+describe('FireAPI Cloud-Native Observability, Health & Structured Logging', () => {
+  it('automatically sets and propagates X-Request-ID across context and headers', async () => {
+    const app = createApp();
+    const router = createRouter();
+
+    let capturedReqId = '';
+
+    router.get('/trace', (ctx) => {
+      capturedReqId = ctx.requestId;
+      return ctx.ok({ traceId: ctx.requestId });
+    });
+
+    app.use(router);
+
+    // 1. Client provides custom X-Request-ID
+    const res1 = await app.handle(
+      new Request('http://localhost:3000/trace', {
+        headers: { 'X-Request-ID': 'custom-req-123' },
+      })
+    );
+
+    expect(res1.status).toBe(200);
+    expect(res1.headers.get('X-Request-ID')).toBe('custom-req-123');
+    expect(capturedReqId).toBe('custom-req-123');
+
+    // 2. Client does not provide header -> auto-generated unique ID
+    const res2 = await app.handle(new Request('http://localhost:3000/trace'));
+    expect(res2.status).toBe(200);
+    const generatedId = res2.headers.get('X-Request-ID');
+    expect(generatedId).not.toBeNull();
+    expect(generatedId?.startsWith('req_')).toBe(true);
+    expect(capturedReqId).toBe(generatedId!);
+  });
+
+  it('provides structured JSON logging via ctx.log with automatic reqId context', async () => {
+    const app = createApp();
+    const router = createRouter();
+
+    const capturedLogs: any[] = [];
+
+    router.get('/log-test', (ctx) => {
+      ctx.log.setSink((record: any) => capturedLogs.push(record));
+      ctx.log.info('Processing order', { amount: 250, currency: 'USD' });
+      ctx.log.warn('Inventory low', { sku: 'SKU-001' });
+      return ctx.ok({ logged: true });
+    });
+
+    app.use(router);
+
+    const res = await app.handle(
+      new Request('http://localhost:3000/log-test', {
+        headers: { 'X-Request-ID': 'req-logger-99' },
+      })
+    );
+
+    expect(res.status).toBe(200);
+    expect(capturedLogs.length).toBe(2);
+
+    expect(capturedLogs[0].level).toBe('info');
+    expect(capturedLogs[0].msg).toBe('Processing order');
+    expect(capturedLogs[0].reqId).toBe('req-logger-99');
+    expect(capturedLogs[0].amount).toBe(250);
+
+    expect(capturedLogs[1].level).toBe('warn');
+    expect(capturedLogs[1].msg).toBe('Inventory low');
+  });
+
+  it('serves liveness (/healthz) and readiness (/readyz) probes automatically', async () => {
+    const app = createApp({
+      database: { driver: 'memory' },
+      health: {
+        livenessPath: '/healthz',
+        readinessPath: '/readyz',
+        checkDatabase: true,
+      },
+    });
+
+    // 1. Test /healthz
+    const livenessRes = await app.handle(new Request('http://localhost:3000/healthz'));
+    expect(livenessRes.status).toBe(200);
+    const livenessBody = await livenessRes.json();
+    expect(livenessBody.status).toBe('ok');
+    expect(typeof livenessBody.timestamp).toBe('number');
+
+    // 2. Test /readyz
+    const readinessRes = await app.handle(new Request('http://localhost:3000/readyz'));
+    expect(readinessRes.status).toBe(200);
+    const readinessBody = await readinessRes.json();
+    expect(readinessBody.status).toBe('ok');
+    expect(readinessBody.checks.database).toBe('ok');
+  });
+});