@tamayrp14/fire-api 0.0.0-stage → 1.0.1

package/src/cache/cache.ts

@@ -0,0 +1,72 @@
+import { FireCacheManager } from '../types';
+
+interface CacheEntry {
+  value: any;
+  expiresAt: number;
+  tags: Set<string>;
+}
+
+export class MemoryCacheManager implements FireCacheManager {
+  private cache: Map<string, CacheEntry> = new Map();
+  private tagIndex: Map<string, Set<string>> = new Map(); // tag -> Set of keys
+
+  public async get<T = any>(key: string): Promise<T | null> {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+
+    if (Date.now() > entry.expiresAt) {
+      this.deleteKey(key);
+      return null;
+    }
+
+    return entry.value as T;
+  }
+
+  public async set(key: string, value: any, ttlSeconds = 60, tags: string[] = []): Promise<void> {
+    const expiresAt = Date.now() + ttlSeconds * 1000;
+    const tagSet = new Set(tags);
+
+    // If key already existed with other tags, clean up old index
+    this.deleteKey(key);
+
+    this.cache.set(key, { value, expiresAt, tags: tagSet });
+
+    for (const tag of tags) {
+      if (!this.tagIndex.has(tag)) {
+        this.tagIndex.set(tag, new Set());
+      }
+      this.tagIndex.get(tag)!.add(key);
+    }
+  }
+
+  public async invalidate(tag: string): Promise<void> {
+    const keys = this.tagIndex.get(tag);
+    if (!keys) return;
+
+    for (const key of Array.from(keys)) {
+      this.deleteKey(key);
+    }
+    this.tagIndex.delete(tag);
+  }
+
+  public async clear(): Promise<void> {
+    this.cache.clear();
+    this.tagIndex.clear();
+  }
+
+  private deleteKey(key: string): void {
+    const entry = this.cache.get(key);
+    if (entry) {
+      for (const tag of entry.tags) {
+        const tagSet = this.tagIndex.get(tag);
+        if (tagSet) {
+          tagSet.delete(key);
+          if (tagSet.size === 0) {
+            this.tagIndex.delete(tag);
+          }
+        }
+      }
+      this.cache.delete(key);
+    }
+  }
+}

package/src/cli/bench.ts

@@ -0,0 +1,118 @@
+export interface BenchmarkOptions {
+  concurrency?: number;
+  totalRequests?: number;
+  durationSec?: number;
+  customFetch?: (url: string) => Promise<Response>;
+}
+
+export interface BenchmarkStats {
+  url: string;
+  totalRequests: number;
+  successfulRequests: number;
+  failedRequests: number;
+  durationMs: number;
+  rps: number;
+  latency: {
+    min: number;
+    max: number;
+    avg: number;
+    p50: number;
+    p90: number;
+    p95: number;
+    p99: number;
+  };
+}
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const index = Math.ceil((p / 100) * sorted.length) - 1;
+  return sorted[Math.max(0, Math.min(index, sorted.length - 1))];
+}
+
+export async function runBenchmark(url: string, options: BenchmarkOptions = {}): Promise<BenchmarkStats> {
+  const concurrency = options.concurrency || 10;
+  const total = options.totalRequests || 200;
+  const fetchFn = options.customFetch || globalThis.fetch;
+
+  const latencies: number[] = [];
+  let successfulRequests = 0;
+  let failedRequests = 0;
+  let sent = 0;
+
+  const startTime = performance.now();
+
+  async function worker() {
+    while (sent < total) {
+      sent++;
+      const reqStart = performance.now();
+      try {
+        const res = await fetchFn(url);
+        const reqDuration = performance.now() - reqStart;
+        latencies.push(reqDuration);
+        if (res.ok) {
+          successfulRequests++;
+        } else {
+          failedRequests++;
+        }
+      } catch {
+        const reqDuration = performance.now() - reqStart;
+        latencies.push(reqDuration);
+        failedRequests++;
+      }
+    }
+  }
+
+  const workers = Array.from({ length: concurrency }, () => worker());
+  await Promise.all(workers);
+
+  const durationMs = performance.now() - startTime;
+  const rps = Math.round((latencies.length / (durationMs / 1000)) * 100) / 100;
+
+  latencies.sort((a, b) => a - b);
+  const sum = latencies.reduce((acc, val) => acc + val, 0);
+
+  return {
+    url,
+    totalRequests: latencies.length,
+    successfulRequests,
+    failedRequests,
+    durationMs: Math.round(durationMs),
+    rps,
+    latency: {
+      min: Math.round((latencies[0] || 0) * 100) / 100,
+      max: Math.round((latencies[latencies.length - 1] || 0) * 100) / 100,
+      avg: Math.round((sum / (latencies.length || 1)) * 100) / 100,
+      p50: Math.round(percentile(latencies, 50) * 100) / 100,
+      p90: Math.round(percentile(latencies, 90) * 100) / 100,
+      p95: Math.round(percentile(latencies, 95) * 100) / 100,
+      p99: Math.round(percentile(latencies, 99) * 100) / 100,
+    },
+  };
+}
+
+export function formatBenchmarkReport(stats: BenchmarkStats): string {
+  const successRate = stats.totalRequests > 0
+    ? ((stats.successfulRequests / stats.totalRequests) * 100).toFixed(1)
+    : '0';
+
+  return `
+==================================================
+🔥 FireAPI Benchmark Engine
+==================================================
+Target:        ${stats.url}
+Duration:      ${stats.durationMs} ms
+Total Reqs:    ${stats.totalRequests}
+Success Rate:  ${successRate}% (${stats.successfulRequests} ok / ${stats.failedRequests} fail)
+
+🚀 Requests/sec: ${stats.rps.toLocaleString()} req/s
+
+Latency (ms):
+  Min:  ${stats.latency.min} ms
+  P50:  ${stats.latency.p50} ms
+  P90:  ${stats.latency.p90} ms
+  P95:  ${stats.latency.p95} ms
+  P99:  ${stats.latency.p99} ms
+  Max:  ${stats.latency.max} ms
+==================================================
+`;
+}

package/src/cli/compile.ts

@@ -0,0 +1,29 @@
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface CompileOptions {
+  entry?: string;
+  output?: string;
+  minify?: boolean;
+}
+
+export function compileBinary(options: CompileOptions = {}): { command: string; success: boolean; output: string } {
+  const entry = options.entry || (fs.existsSync('./src/index.ts') ? './src/index.ts' : './index.ts');
+  const output = options.output || './dist/server';
+  const minifyFlag = options.minify !== false ? '--minify' : '';
+
+  const outDir = path.dirname(output);
+  if (!fs.existsSync(outDir)) {
+    fs.mkdirSync(outDir, { recursive: true });
+  }
+
+  const command = `bun build ${entry} --compile ${minifyFlag} --outfile ${output}`.trim();
+
+  try {
+    const stdout = execSync(command, { encoding: 'utf-8', stdio: 'pipe' });
+    return { command, success: true, output: stdout };
+  } catch (err: any) {
+    return { command, success: false, output: err.message };
+  }
+}

package/src/cli/create-app.ts

@@ -0,0 +1,284 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface CreateAppOptions {
+  name: string;
+  template?: 'standard' | 'minimal';
+  targetDir?: string;
+}
+
+export function createAppProject(options: CreateAppOptions): { projectDir: string; filesCreated: string[] } {
+  const projectName = options.name || 'my-fire-api';
+  const baseDir = options.targetDir || path.resolve(process.cwd(), projectName);
+
+  if (!fs.existsSync(baseDir)) {
+    fs.mkdirSync(baseDir, { recursive: true });
+  }
+
+  const filesCreated: string[] = [];
+
+  const writeFile = (relPath: string, content: string) => {
+    const fullPath = path.join(baseDir, relPath);
+    const dir = path.dirname(fullPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(fullPath, content.trim() + '\n', 'utf-8');
+    filesCreated.push(relPath);
+  };
+
+  // 1. package.json
+  writeFile('package.json', JSON.stringify({
+    name: projectName,
+    version: '1.0.0',
+    description: 'High-performance API built with FireAPI',
+    type: 'module',
+    main: 'src/index.ts',
+    scripts: {
+      dev: 'bun --watch src/index.ts',
+      start: 'bun src/index.ts',
+      test: 'bun test',
+      compile: 'fire compile ./dist/server',
+      docker: 'fire docker',
+      routes: 'fire routes',
+    },
+    dependencies: {
+      'fire-api': '^1.0.0',
+    },
+    devDependencies: {
+      '@types/node': '^20.0.0',
+      typescript: '^5.0.0',
+    },
+  }, null, 2));
+
+  // 2. tsconfig.json
+  writeFile('tsconfig.json', JSON.stringify({
+    compilerOptions: {
+      target: 'ESNext',
+      module: 'ESNext',
+      moduleResolution: 'bundler',
+      strict: true,
+      skipLibCheck: true,
+      esModuleInterop: true,
+      allowSyntheticDefaultImports: true,
+      forceConsistentCasingInFileNames: true,
+      outDir: './dist',
+    },
+    include: ['src/**/*', 'test/**/*'],
+  }, null, 2));
+
+  // 3. .env.example & .env
+  const envContent = `PORT=3000
+NODE_ENV=development
+JWT_SECRET=super_secret_jwt_key_change_me_in_prod
+DB_DRIVER=sqlite
+DB_URL=./data.db
+CORS_ORIGIN=*
+`;
+  writeFile('.env.example', envContent);
+  writeFile('.env', envContent);
+
+  // 4. .gitignore
+  writeFile('.gitignore', `node_modules/
+dist/
+data.db
+*.log
+.env
+.DS_Store
+`);
+
+  // 5. README.md
+  writeFile('README.md', `# 🔥 ${projectName}
+
+High-performance, modern Web Standard API built with **FireAPI**.
+
+## 🚀 Quick Start
+
+\`\`\`bash
+# 1. Install dependencies
+bun install
+# or
+pnpm install
+
+# 2. Run development server (with auto-reload)
+bun dev
+
+# 3. View Interactive API Docs
+http://localhost:3000/docs
+
+# 4. View Dev Dashboard (FireStudio)
+http://localhost:3000/studio
+
+# 5. Run Tests
+bun test
+\`\`\`
+`);
+
+  // 6. src/index.ts
+  writeFile('src/index.ts', `import { createApp, enableStudio } from 'fire-api';
+import { userRouter } from './modules/users/users.router';
+import { authRouter } from './modules/auth/auth.router';
+
+const port = Number(process.env.PORT) || 3000;
+
+const app = createApp({
+  port,
+  database: {
+    driver: (process.env.DB_DRIVER as any) || 'sqlite',
+    url: process.env.DB_URL || ':memory:',
+  },
+  security: {
+    cors: true,
+    rateLimit: { max: 500, window: '1m' },
+  },
+  health: true, // Auto /healthz & /readyz
+  docs: '/docs', // Scalar Docs at /docs & OpenAPI at /openapi.json
+});
+
+// Enable Embedded Dev Studio at /studio
+enableStudio(app, { path: '/studio' });
+
+// Mount Domain Modules
+app.use(authRouter);
+app.use(userRouter);
+
+// Start Server
+app.listen(port, () => {
+  console.log(\`🔥 \${projectName} running at http://localhost:\${port}\`);
+  console.log(\`📖 Interactive Docs:   http://localhost:\${port}/docs\`);
+  console.log(\`🖥️ FireStudio:         http://localhost:\${port}/studio\`);
+  console.log(\`🩺 Health Probes:      http://localhost:\${port}/healthz\`);
+});
+
+export type AppRouter = typeof app;
+export default app;
+`);
+
+  // 7. src/modules/users/users.schema.ts
+  writeFile('src/modules/users/users.schema.ts', `import { s, type Infer } from 'fire-api';
+
+export const UserSchema = s.object({
+  id: s.string().optional(),
+  name: s.string().min(2).description('Full name of the user'),
+  email: s.string().email().description('Unique email address'),
+  role: s.enum(['admin', 'user', 'moderator']).default('user'),
+  createdAt: s.string().optional(),
+});
+
+export const CreateUserSchema = s.object({
+  name: s.string().min(2),
+  email: s.string().email(),
+  role: s.enum(['admin', 'user', 'moderator']).default('user'),
+});
+
+export type User = Infer<typeof UserSchema>;
+export type CreateUserInput = Infer<typeof CreateUserSchema>;
+`);
+
+  // 8. src/modules/users/users.router.ts
+  writeFile('src/modules/users/users.router.ts', `import { createRouter } from 'fire-api';
+import { CreateUserSchema } from './users.schema';
+
+export const userRouter = createRouter('/users');
+
+// GET /users - List all users
+userRouter.get('/', {
+  ai: { description: 'Retrieve all users', tags: ['Users'] },
+  handler: async (ctx) => {
+    const users = await ctx.db.users.find();
+    return ctx.ok(users);
+  },
+});
+
+// GET /users/:id - Get user by id with relational posts
+userRouter.get('/:id', {
+  ai: { description: 'Get a user by ID', tags: ['Users'] },
+  handler: async (ctx) => {
+    const user = await ctx.db.users.include('posts').findById(ctx.params.id);
+    if (!user) return ctx.notFound('User not found');
+    return ctx.ok(user);
+  },
+});
+
+// POST /users - Create user with validation & idempotency shield
+userRouter.post('/', {
+  schema: { body: CreateUserSchema },
+  idempotent: true,
+  ai: { description: 'Create a new user', tags: ['Users'] },
+  handler: async (ctx) => {
+    const existing = await ctx.db.users.findOne({ email: ctx.body.email });
+    if (existing) {
+      return ctx.badRequest('Email is already registered');
+    }
+
+    const newUser = await ctx.db.users.insert(ctx.body);
+    await ctx.emit('user.created', newUser);
+
+    return ctx.created(newUser);
+  },
+});
+
+// DELETE /users/:id - Delete user cleanly
+userRouter.delete('/:id', {
+  ai: { description: 'Delete a user by ID', tags: ['Users'] },
+  handler: async (ctx) => {
+    await ctx.db.users.delete(ctx.params.id);
+    return ctx.ok({ deleted: true });
+  },
+});
+`);
+
+  // 9. src/modules/auth/auth.router.ts
+  writeFile('src/modules/auth/auth.router.ts', `import { createAuth } from 'fire-api';
+
+// Turnkey Web Crypto PBKDF2 + JWT Authentication Sub-Router
+export const authRouter = createAuth({
+  jwtSecret: process.env.JWT_SECRET || 'dev_secret_key_123',
+  tokenExpiresIn: '7d',
+});
+`);
+
+  // 10. test/app.test.ts
+  writeFile('test/app.test.ts', `import { describe, expect, it } from 'bun:test';
+import app from '../src/index';
+
+describe('${projectName} API E2E Suite', () => {
+  it('responds with 200 on /healthz probe', async () => {
+    const res = await app.handle(new Request('http://localhost:3000/healthz'));
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe('ok');
+  });
+
+  it('creates and retrieves a user seamlessly', async () => {
+    // 1. Create User
+    const createRes = await app.handle(
+      new Request('http://localhost:3000/users', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Idempotency-Key': 'key-initial-admin',
+        },
+        body: JSON.stringify({
+          name: 'Super Admin',
+          email: 'admin@fireapi.dev',
+          role: 'admin',
+        }),
+      })
+    );
+
+    expect(createRes.status).toBe(201);
+    const createdUser = await createRes.json();
+    expect(createdUser.name).toBe('Super Admin');
+
+    // 2. Query Users
+    const listRes = await app.handle(new Request('http://localhost:3000/users'));
+    expect(listRes.status).toBe(200);
+    const users = await listRes.json();
+    expect(users.length).toBeGreaterThanOrEqual(1);
+  });
+});
+`);
+
+  return { projectDir: baseDir, filesCreated };
+}

package/src/cli/docker.ts

@@ -0,0 +1,51 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export function generateDockerFiles(baseDir = process.cwd()): { dockerfilePath: string; dockerignorePath: string } {
+  const dockerfilePath = path.join(baseDir, 'Dockerfile');
+  const dockerignorePath = path.join(baseDir, '.dockerignore');
+
+  const dockerfileContent = `# ==============================================
+# 🔥 FireAPI Ultra-Lightweight Production Container (< 25MB)
+# ==============================================
+
+# Stage 1: Build & Dependencies
+FROM oven/bun:alpine AS base
+WORKDIR /app
+
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+
+COPY package.json bun.lock* ./
+RUN bun install --production
+
+COPY . .
+RUN chown -R appuser:appgroup /app
+
+# Stage 2: Distroless Production Runner
+FROM oven/bun:alpine AS runner
+WORKDIR /app
+
+COPY --from=base /app /app
+
+USER appuser
+EXPOSE 3000
+
+ENV NODE_ENV=production
+ENV PORT=3000
+
+CMD ["bun", "run", "src/index.ts"]
+`;
+
+  const dockerignoreContent = `node_modules
+dist
+.git
+.env*
+*.log
+uploads
+`;
+
+  fs.writeFileSync(dockerfilePath, dockerfileContent, 'utf-8');
+  fs.writeFileSync(dockerignorePath, dockerignoreContent, 'utf-8');
+
+  return { dockerfilePath, dockerignorePath };
+}

package/src/cli/generator.ts

@@ -0,0 +1,75 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export function generateResource(resourceName: string, baseDir = process.cwd()): { routeFile: string; schemaFile: string } {
+  const cleanName = resourceName.toLowerCase().replace(/[^a-z0-9_-]/g, '');
+  const capitalized = cleanName.charAt(0).toUpperCase() + cleanName.slice(1);
+  const targetDir = path.join(baseDir, 'src', 'modules', cleanName);
+
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  const schemaPath = path.join(targetDir, `${cleanName}.schema.ts`);
+  const routePath = path.join(targetDir, `${cleanName}.route.ts`);
+
+  const schemaContent = `import { s } from 'fire-api';
+
+export const Create${capitalized}Schema = s.object({
+  name: s.string().min(2).description('${capitalized} title or name'),
+  status: s.enum(['active', 'draft']).default('active'),
+});
+
+export const ${capitalized}IdSchema = s.object({
+  id: s.string().min(1),
+});
+`;
+
+  const routeContent = `import { createRouter } from 'fire-api';
+import { Create${capitalized}Schema, ${capitalized}IdSchema } from './${cleanName}.schema';
+
+export const ${cleanName}Router = createRouter('/${cleanName}s');
+
+// GET /${cleanName}s
+${cleanName}Router.get('/', {
+  cache: { ttl: 60, tags: ['${cleanName}s'] },
+  ai: { description: 'Fetch list of ${cleanName}s', tags: ['${capitalized}'] },
+  handler: async (ctx) => {
+    return ctx.db.${cleanName}s.find();
+  },
+});
+
+// POST /${cleanName}s
+${cleanName}Router.post('/', {
+  schema: { body: Create${capitalized}Schema },
+  ai: { description: 'Create a new ${cleanName}', tags: ['${capitalized}'] },
+  handler: async (ctx) => {
+    const created = await ctx.db.${cleanName}s.insert(ctx.body);
+    await ctx.cache.invalidate('${cleanName}s');
+    return ctx.created(created);
+  },
+});
+
+// GET /${cleanName}s/:id
+${cleanName}Router.get('/:id', {
+  schema: { params: ${capitalized}IdSchema },
+  ai: { description: 'Get a ${cleanName} by unique ID', tags: ['${capitalized}'] },
+  handler: async (ctx) => {
+    const item = await ctx.db.${cleanName}s.findById(ctx.params.id);
+    if (!item) return ctx.notFound('${capitalized} not found');
+    return ctx.ok(item);
+  },
+});
+
+// DELETE /${cleanName}s/:id
+${cleanName}Router.delete('/:id', async (ctx) => {
+  await ctx.db.${cleanName}s.delete(ctx.params.id);
+  return { deleted: true };
+});
+`;
+
+  fs.writeFileSync(schemaPath, schemaContent, 'utf-8');
+  fs.writeFileSync(routePath, routeContent, 'utf-8');
+
+  return { routeFile: routePath, schemaFile: schemaPath };
+}