@tamayrp14/fire-api 0.0.0-stage → 1.0.0

package/src/events/event-bus.ts

@@ -0,0 +1,61 @@
+export type EventListener<T = any> = (payload: T) => Promise<void> | void;
+
+export class EventBus {
+  private listeners = new Map<string, Array<EventListener>>();
+
+  public on<T = any>(event: string, listener: EventListener<T>): () => void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, []);
+    }
+    this.listeners.get(event)!.push(listener);
+
+    return () => this.off(event, listener);
+  }
+
+  public off(event: string, listener: EventListener): void {
+    const list = this.listeners.get(event);
+    if (!list) return;
+    const idx = list.indexOf(listener);
+    if (idx !== -1) list.splice(idx, 1);
+  }
+
+  public async emit<T = any>(event: string, payload: T): Promise<void> {
+    const promises: Promise<void>[] = [];
+
+    // 1. Exact match
+    const exactListeners = this.listeners.get(event) || [];
+    for (const fn of exactListeners) {
+      try {
+        const res = fn(payload);
+        if (res instanceof Promise) promises.push(res);
+      } catch (err) {
+        console.error(`[EventBus] Error in listener for event "${event}":`, err);
+      }
+    }
+
+    // 2. Wildcard match (e.g. "order.*" matches "order.paid")
+    for (const [pattern, fns] of this.listeners.entries()) {
+      if (pattern.includes('*') && this.matchWildcard(pattern, event)) {
+        for (const fn of fns) {
+          try {
+            const res = fn(payload);
+            if (res instanceof Promise) promises.push(res);
+          } catch (err) {
+            console.error(`[EventBus] Error in wildcard listener for pattern "${pattern}":`, err);
+          }
+        }
+      }
+    }
+
+    await Promise.allSettled(promises);
+  }
+
+  private matchWildcard(pattern: string, event: string): boolean {
+    const regexStr = '^' + pattern.replace(/\./g, '\\.').replace(/\*/g, '.*') + '$';
+    return new RegExp(regexStr).test(event);
+  }
+
+  public clear(): void {
+    this.listeners.clear();
+  }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+export { FireApp, createApp } from './core/app';
+export { Router, createRouter } from './core/router';
+export { createContext } from './core/context';
+export { HttpError } from './core/error';
+export { s, BaseSchema } from './schema/schema';
+export type { Infer } from './schema/schema';
+export { validate } from './schema/validator';
+export { generateMock } from './schema/mock';
+export { createClient } from './client';
+export { createMCPServer, MCPServer } from './ai/mcp';
+export { MemoryDatabase } from './db/memory-adapter';
+export { SQLiteDatabase } from './db/sqlite-adapter';
+export { FireMigrator } from './db/migrator';
+export type { Migration } from './db/migrator';
+export { MemoryCacheManager } from './cache/cache';
+export { createAuth, requireAuth } from './auth/auth';
+export { fromExpress } from './compat/express';
+export { enableStudio } from './studio/studio';
+export { createSSEResponse, formatSSEMessage } from './stream/sse';
+export { FireQueueManager } from './jobs/queue';
+export { FireCronScheduler } from './jobs/cron';
+export { WebSocketHub } from './ws/ws';
+export { EventBus } from './events/event-bus';
+export { createStorage, MemoryStorageAdapter, LocalDiskStorageAdapter } from './storage/storage';
+export { MetricsCollector } from './metrics/metrics';
+export { FireLogger } from './logging/logger';
+export { compressResponse } from './shield/compress';
+export { IdempotencyManager } from './shield/idempotency';
+export { computeHMAC, verifyHMAC, constantTimeEqual, WebhookVerifier } from './shield/webhook';
+export { runBenchmark, formatBenchmarkReport } from './cli/bench';
+export { generateDockerFiles } from './cli/docker';
+export { compileBinary } from './cli/compile';
+export { createAppProject } from './cli/create-app';
+export { formatRoutesTable } from './cli/routes';
+export { generatePostmanCollection } from './docs/collection';
+export { createStaticFileResponse } from './static/serve';
+export * from './types';

package/src/jobs/cron.ts

@@ -0,0 +1,77 @@
+export interface CronTask {
+  stop(): void;
+  isRunning: boolean;
+}
+
+export function parseInterval(expression: string): number {
+  const match = expression.trim().toLowerCase().match(/^(\d+)(ms|s|m|h|d)?$/);
+  if (match) {
+    const val = parseInt(match[1], 10);
+    const unit = match[2] || 's';
+    switch (unit) {
+      case 'ms': return val;
+      case 's': return val * 1000;
+      case 'm': return val * 60 * 1000;
+      case 'h': return val * 3600 * 1000;
+      case 'd': return val * 86400 * 1000;
+      default: return val * 1000;
+    }
+  }
+
+  // Common cron aliases
+  switch (expression.trim().toLowerCase()) {
+    case '@hourly': return 3600 * 1000;
+    case '@daily':
+    case '@midnight': return 86400 * 1000;
+    case '@weekly': return 7 * 86400 * 1000;
+    default:
+      // Default to 1 minute for unknown cron pattern in lightweight engine
+      return 60 * 1000;
+  }
+}
+
+export class FireCronScheduler {
+  private activeTimers: Set<any> = new Set();
+
+  public schedule(expression: string, task: () => Promise<void> | void): CronTask {
+    const intervalMs = parseInterval(expression);
+    let isRunning = true;
+
+    const timer = setInterval(() => {
+      if (!isRunning) return;
+      try {
+        Promise.resolve(task()).catch((e) => {
+          console.error('[FireCron Error]', e);
+        });
+      } catch (err) {
+        console.error('[FireCron Error]', err);
+      }
+    }, intervalMs);
+
+    // Don't keep Node process alive if only cron timers remain
+    if (timer && typeof (timer as any).unref === 'function') {
+      (timer as any).unref();
+    }
+
+    this.activeTimers.add(timer);
+
+    const cronTask: CronTask = {
+      isRunning: true,
+      stop: () => {
+        isRunning = false;
+        cronTask.isRunning = false;
+        clearInterval(timer);
+        this.activeTimers.delete(timer);
+      },
+    };
+
+    return cronTask;
+  }
+
+  public stopAll(): void {
+    for (const timer of this.activeTimers) {
+      clearInterval(timer);
+    }
+    this.activeTimers.clear();
+  }
+}

package/src/jobs/queue.ts

@@ -0,0 +1,108 @@
+import { FireQueue, FireQueueJob } from '../types';
+
+export class FireQueueManager implements FireQueue {
+  private jobs: Map<string, FireQueueJob> = new Map();
+  private handlers: Map<string, (data: any, job: FireQueueJob) => Promise<void> | void> = new Map();
+  private pendingQueue: string[] = [];
+  private isProcessing = false;
+  private concurrency: number;
+  private activeWorkers = 0;
+
+  constructor(options: { concurrency?: number } = {}) {
+    this.concurrency = options.concurrency || 5;
+  }
+
+  public handle<T = any>(
+    name: string,
+    worker: (data: T, job: FireQueueJob<T>) => Promise<void> | void
+  ): void {
+    this.handlers.set(name, worker);
+  }
+
+  public async dispatch<T = any>(
+    name: string,
+    data: T,
+    options: { maxAttempts?: number; delayMs?: number; retryDelayMs?: number } = {}
+  ): Promise<FireQueueJob<T>> {
+    const id = `job_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+    const job: FireQueueJob<T> = {
+      id,
+      name,
+      data,
+      attempts: 0,
+      maxAttempts: options.maxAttempts || 3,
+      createdAt: Date.now(),
+      status: 'pending',
+    };
+
+    (job as any).retryDelayMs = options.retryDelayMs ?? 50;
+
+    this.jobs.set(id, job);
+
+    if (options.delayMs && options.delayMs > 0) {
+      setTimeout(() => {
+        this.pendingQueue.push(id);
+        this.processQueue();
+      }, options.delayMs);
+    } else {
+      this.pendingQueue.push(id);
+      queueMicrotask(() => this.processQueue());
+    }
+
+    return job;
+  }
+
+  private async processQueue(): Promise<void> {
+    if (this.isProcessing) return;
+    this.isProcessing = true;
+
+    try {
+      while (this.pendingQueue.length > 0 && this.activeWorkers < this.concurrency) {
+        const jobId = this.pendingQueue.shift();
+        if (!jobId) break;
+
+        const job = this.jobs.get(jobId);
+        if (!job || job.status === 'completed' || job.status === 'failed') continue;
+
+        const handler = this.handlers.get(job.name);
+        if (!handler) {
+          // No handler registered yet; keep job pending or delay
+          this.pendingQueue.push(jobId);
+          break;
+        }
+
+        this.activeWorkers++;
+        job.status = 'processing';
+        job.attempts++;
+
+        Promise.resolve(handler(job.data, job))
+          .then(() => {
+            job.status = 'completed';
+          })
+          .catch((err) => {
+            if (job.attempts < job.maxAttempts) {
+              job.status = 'pending';
+              const baseDelay = (job as any).retryDelayMs || 50;
+              const backoffMs = Math.min(baseDelay * Math.pow(2, job.attempts - 1), 5000);
+              setTimeout(() => {
+                this.pendingQueue.push(jobId);
+                this.processQueue();
+              }, backoffMs);
+            } else {
+              job.status = 'failed';
+            }
+          })
+          .finally(() => {
+            this.activeWorkers--;
+            this.processQueue();
+          });
+      }
+    } finally {
+      this.isProcessing = false;
+    }
+  }
+
+  public getJob(id: string): FireQueueJob | undefined {
+    return this.jobs.get(id);
+  }
+}

package/src/logging/logger.ts

@@ -0,0 +1,66 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface LogRecord {
+  level: LogLevel;
+  time: number;
+  reqId?: string;
+  msg: string;
+  [key: string]: any;
+}
+
+export class FireLogger {
+  private customSink?: (record: LogRecord) => void;
+
+  constructor(private contextReqId?: string) {}
+
+  public setSink(sink: (record: LogRecord) => void): void {
+    this.customSink = sink;
+  }
+
+  private emitLog(level: LogLevel, msg: string, data?: Record<string, any>): LogRecord {
+    const record: LogRecord = {
+      level,
+      time: Date.now(),
+      ...(this.contextReqId ? { reqId: this.contextReqId } : {}),
+      msg,
+      ...(data || {}),
+    };
+
+    if (this.customSink) {
+      this.customSink(record);
+    } else {
+      const line = JSON.stringify(record);
+      if (level === 'error') {
+        console.error(line);
+      } else if (level === 'warn') {
+        console.warn(line);
+      } else {
+        console.log(line);
+      }
+    }
+
+    return record;
+  }
+
+  public debug(msg: string, data?: Record<string, any>): LogRecord {
+    return this.emitLog('debug', msg, data);
+  }
+
+  public info(msg: string, data?: Record<string, any>): LogRecord {
+    return this.emitLog('info', msg, data);
+  }
+
+  public warn(msg: string, data?: Record<string, any>): LogRecord {
+    return this.emitLog('warn', msg, data);
+  }
+
+  public error(msg: string, data?: Record<string, any>): LogRecord {
+    return this.emitLog('error', msg, data);
+  }
+
+  public child(reqId: string): FireLogger {
+    const logger = new FireLogger(reqId);
+    if (this.customSink) logger.setSink(this.customSink);
+    return logger;
+  }
+}

package/src/metrics/metrics.ts

@@ -0,0 +1,66 @@
+export class MetricsCollector {
+  private requestCounters: Map<string, number> = new Map();
+  private requestDurations: Map<string, { count: number; sum: number }> = new Map();
+  private dbQueriesCount = 0;
+  private startTime: number = Date.now();
+
+  public recordRequest(method: string, path: string, status: number, durationMs: number): void {
+    // 1. Counter: http_requests_total
+    const counterKey = `method="${method}",path="${path}",status="${status}"`;
+    const currentCount = this.requestCounters.get(counterKey) || 0;
+    this.requestCounters.set(counterKey, currentCount + 1);
+
+    // 2. Summary: http_request_duration_ms
+    const durationKey = `method="${method}",path="${path}"`;
+    const currentDuration = this.requestDurations.get(durationKey) || { count: 0, sum: 0 };
+    this.requestDurations.set(durationKey, {
+      count: currentDuration.count + 1,
+      sum: currentDuration.sum + durationMs,
+    });
+  }
+
+  public recordDbQuery(): void {
+    this.dbQueriesCount++;
+  }
+
+  public formatPrometheus(): string {
+    const lines: string[] = [];
+
+    // HTTP Requests Total
+    lines.push('# HELP http_requests_total Total number of HTTP requests processed');
+    lines.push('# TYPE http_requests_total counter');
+    for (const [labels, count] of this.requestCounters.entries()) {
+      lines.push(`http_requests_total{${labels}} ${count}`);
+    }
+
+    // HTTP Request Duration
+    lines.push('# HELP http_request_duration_ms Total request processing time in milliseconds');
+    lines.push('# TYPE http_request_duration_ms summary');
+    for (const [labels, stats] of this.requestDurations.entries()) {
+      lines.push(`http_request_duration_ms_sum{${labels}} ${stats.sum.toFixed(3)}`);
+      lines.push(`http_request_duration_ms_count{${labels}} ${stats.count}`);
+    }
+
+    // DB Queries Total
+    lines.push('# HELP fire_db_queries_total Total database queries executed');
+    lines.push('# TYPE fire_db_queries_total counter');
+    lines.push(`fire_db_queries_total ${this.dbQueriesCount}`);
+
+    // Process Memory
+    let memoryBytes = 0;
+    if (typeof process !== 'undefined' && process.memoryUsage) {
+      memoryBytes = process.memoryUsage().rss;
+    }
+    lines.push('# HELP process_resident_memory_bytes Resident memory size in bytes');
+    lines.push('# TYPE process_resident_memory_bytes gauge');
+    lines.push(`process_resident_memory_bytes ${memoryBytes}`);
+
+    // Process Uptime
+    const uptimeSeconds = Math.floor((Date.now() - this.startTime) / 1000);
+    lines.push('# HELP process_uptime_seconds Process uptime in seconds');
+    lines.push('# TYPE process_uptime_seconds gauge');
+    lines.push(`process_uptime_seconds ${uptimeSeconds}`);
+
+    return lines.join('\n') + '\n';
+  }
+}

package/src/modules/product/product.route.ts

@@ -0,0 +1,36 @@
+import { createRouter } from '../../index';
+import { CreateProductSchema, ProductIdSchema } from './product.schema';
+
+export const productRouter = createRouter('/products');
+
+// GET /products
+productRouter.get('/', {
+  cache: { ttl: 60, tags: ['products'] },
+  ai: { description: 'Fetch list of products', tags: ['Product'] },
+  handler: async (ctx) => {
+    const items = await ctx.db.table('products').find();
+    return ctx.ok(items);
+  },
+});
+
+// POST /products
+productRouter.post('/', {
+  schema: { body: CreateProductSchema },
+  ai: { description: 'Create a new product', tags: ['Product'] },
+  handler: async (ctx) => {
+    const created = await ctx.db.table('products').insert(ctx.body);
+    await ctx.cache.invalidate('products');
+    return ctx.created(created);
+  },
+});
+
+// GET /products/:id
+productRouter.get('/:id', {
+  schema: { params: ProductIdSchema },
+  ai: { description: 'Get a product by unique ID', tags: ['Product'] },
+  handler: async (ctx) => {
+    const item = await ctx.db.table('products').findById(ctx.params.id);
+    if (!item) return ctx.notFound('Product not found');
+    return ctx.ok(item);
+  },
+});

package/src/modules/product/product.schema.ts

@@ -0,0 +1,10 @@
+import { s } from '../../index';
+
+export const CreateProductSchema = s.object({
+  name: s.string().min(2).description('Product title or name'),
+  status: s.enum(['active', 'draft']).default('active'),
+});
+
+export const ProductIdSchema = s.object({
+  id: s.string().min(1),
+});

package/src/schema/mock.ts

@@ -0,0 +1,60 @@
+import {
+  ArraySchema,
+  BaseSchema,
+  BooleanSchema,
+  EnumSchema,
+  NumberSchema,
+  ObjectSchema,
+  StringSchema,
+} from './schema';
+
+export function generateMock(schema: BaseSchema): any {
+  if (schema.defaultValue !== undefined) {
+    return schema.defaultValue;
+  }
+
+  if (schema instanceof StringSchema) {
+    if (schema.isEmail) {
+      return `user_${Math.random().toString(36).slice(2, 6)}@example.com`;
+    }
+    const min = schema.minLength || 5;
+    const base = 'sample_text';
+    if (base.length < min) {
+      return base + '_'.repeat(min - base.length);
+    }
+    if (schema.maxLength && base.length > schema.maxLength) {
+      return base.slice(0, schema.maxLength);
+    }
+    return base;
+  }
+
+  if (schema instanceof NumberSchema) {
+    const min = schema.minVal !== undefined ? schema.minVal : 1;
+    const max = schema.maxVal !== undefined ? schema.maxVal : 100;
+    const val = min + (max - min) / 2;
+    return schema.isInteger ? Math.round(val) : Math.round(val * 100) / 100;
+  }
+
+  if (schema instanceof BooleanSchema) {
+    return true;
+  }
+
+  if (schema instanceof EnumSchema) {
+    return schema.values[0] || 'default';
+  }
+
+  if (schema instanceof ArraySchema) {
+    const count = schema.minItems || 2;
+    return Array.from({ length: count }, () => generateMock(schema.itemSchema));
+  }
+
+  if (schema instanceof ObjectSchema) {
+    const obj: Record<string, any> = {};
+    for (const [key, propSchema] of Object.entries(schema.shape)) {
+      obj[key] = generateMock(propSchema as BaseSchema);
+    }
+    return obj;
+  }
+
+  return 'mock_data';
+}

package/src/schema/openapi.ts

@@ -0,0 +1,101 @@
+import { Router } from '../core/router';
+import { BaseSchema } from './schema';
+
+export interface OpenAPIOptions {
+  title?: string;
+  version?: string;
+  description?: string;
+}
+
+export function generateOpenAPISpec(router: Router, options: OpenAPIOptions = {}): Record<string, any> {
+  const spec: Record<string, any> = {
+    openapi: '3.1.0',
+    info: {
+      title: options.title || 'FireAPI Documentation',
+      version: options.version || '1.0.0',
+      description: options.description || 'Auto-generated API documentation powered by FireAPI',
+    },
+    paths: {},
+  };
+
+  for (const route of router.routesList) {
+    // Convert :id to {id} for OpenAPI path specification
+    const openApiPath = route.path.replace(/:([a-zA-Z0-9_]+)/g, '{$1}');
+
+    if (!spec.paths[openApiPath]) {
+      spec.paths[openApiPath] = {};
+    }
+
+    const methodLower = route.method.toLowerCase();
+    const routeSchema = route.options.schema;
+    const ai = route.options.ai;
+
+    const operation: Record<string, any> = {
+      summary: ai?.description || `${route.method} ${openApiPath}`,
+      description: ai?.description,
+      parameters: [],
+      responses: {
+        '200': {
+          description: 'Successful Response',
+          content: {
+            'application/json': {
+              schema: routeSchema?.response && routeSchema.response instanceof BaseSchema
+                ? routeSchema.response.toOpenAPI()
+                : { type: 'object' },
+            },
+          },
+        },
+      },
+    };
+
+    if (ai?.tags) {
+      operation.tags = ai.tags;
+    }
+
+    // Path parameters
+    if (routeSchema?.params && routeSchema.params instanceof BaseSchema) {
+      const openApiParams = routeSchema.params.toOpenAPI();
+      if (openApiParams.properties) {
+        for (const [pKey, pSchema] of Object.entries(openApiParams.properties)) {
+          operation.parameters.push({
+            name: pKey,
+            in: 'path',
+            required: true,
+            schema: pSchema,
+          });
+        }
+      }
+    }
+
+    // Query parameters
+    if (routeSchema?.query && routeSchema.query instanceof BaseSchema) {
+      const openApiQuery = routeSchema.query.toOpenAPI();
+      if (openApiQuery.properties) {
+        for (const [qKey, qSchema] of Object.entries(openApiQuery.properties)) {
+          operation.parameters.push({
+            name: qKey,
+            in: 'query',
+            required: openApiQuery.required?.includes(qKey) ?? false,
+            schema: qSchema,
+          });
+        }
+      }
+    }
+
+    // Request body
+    if (routeSchema?.body && routeSchema.body instanceof BaseSchema) {
+      operation.requestBody = {
+        required: true,
+        content: {
+          'application/json': {
+            schema: routeSchema.body.toOpenAPI(),
+          },
+        },
+      };
+    }
+
+    spec.paths[openApiPath][methodLower] = operation;
+  }
+
+  return spec;
+}