@tamayrp14/fire-api 0.0.0-stage → 1.0.0

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 };
+}

package/src/cli/routes.ts

@@ -0,0 +1,76 @@
+import { Router } from '../core/router';
+
+export interface RouteTableRow {
+  method: string;
+  path: string;
+  auth: string;
+  roles: string;
+  cache: string;
+  idempotent: string;
+  description: string;
+}
+
+export function formatRoutesTable(router: Router): string {
+  const routes = router.getRoutes();
+
+  if (routes.length === 0) {
+    return 'No routes registered in application.';
+  }
+
+  const rows: RouteTableRow[] = routes.map((r) => {
+    const roles = r.options.roles && r.options.roles.length > 0 ? r.options.roles.join(', ') : '-';
+    const cache = r.options.cache ? `${r.options.cache.ttl}s` : '-';
+    const idempotent = r.options.idempotent ? '✓' : '-';
+    const auth = r.options.security ? 'Required' : (r.options.roles ? 'Role-Guarded' : 'Public');
+    const description = r.options.ai?.description || '-';
+
+    return {
+      method: r.method,
+      path: r.path,
+      auth,
+      roles,
+      cache,
+      idempotent,
+      description,
+    };
+  });
+
+  // Calculate column widths
+  const headers = {
+    method: 'METHOD',
+    path: 'ROUTE PATH',
+    auth: 'AUTH',
+    roles: 'ROLES',
+    cache: 'CACHE',
+    idempotent: 'IDEMPOTENT',
+    description: 'DESCRIPTION',
+  };
+
+  const colWidths = {
+    method: Math.max(headers.method.length, ...rows.map((r) => r.method.length)),
+    path: Math.max(headers.path.length, ...rows.map((r) => r.path.length)),
+    auth: Math.max(headers.auth.length, ...rows.map((r) => r.auth.length)),
+    roles: Math.max(headers.roles.length, ...rows.map((r) => r.roles.length)),
+    cache: Math.max(headers.cache.length, ...rows.map((r) => r.cache.length)),
+    idempotent: Math.max(headers.idempotent.length, ...rows.map((r) => r.idempotent.length)),
+    description: Math.max(headers.description.length, ...rows.map((r) => r.description.length)),
+  };
+
+  const pad = (str: string, len: number) => str.padEnd(len, ' ');
+
+  const headerLine = `| ${pad(headers.method, colWidths.method)} | ${pad(headers.path, colWidths.path)} | ${pad(headers.auth, colWidths.auth)} | ${pad(headers.roles, colWidths.roles)} | ${pad(headers.cache, colWidths.cache)} | ${pad(headers.idempotent, colWidths.idempotent)} | ${pad(headers.description, colWidths.description)} |`;
+  const sepLine = `|-${'-'.repeat(colWidths.method)}-|-${'-'.repeat(colWidths.path)}-|-${'-'.repeat(colWidths.auth)}-|-${'-'.repeat(colWidths.roles)}-|-${'-'.repeat(colWidths.cache)}-|-${'-'.repeat(colWidths.idempotent)}-|-${'-'.repeat(colWidths.description)}-|`;
+
+  const bodyLines = rows.map((r) =>
+    `| ${pad(r.method, colWidths.method)} | ${pad(r.path, colWidths.path)} | ${pad(r.auth, colWidths.auth)} | ${pad(r.roles, colWidths.roles)} | ${pad(r.cache, colWidths.cache)} | ${pad(r.idempotent, colWidths.idempotent)} | ${pad(r.description, colWidths.description)} |`
+  );
+
+  return [
+    `🔥 FireAPI Route Manifest (${routes.length} total endpoints):`,
+    sepLine,
+    headerLine,
+    sepLine,
+    ...bodyLines,
+    sepLine,
+  ].join('\n');
+}

package/src/client.ts

@@ -0,0 +1,120 @@
+export interface ClientRequestOptions {
+  params?: Record<string, string | number>;
+  query?: Record<string, any>;
+  body?: any;
+  headers?: HeadersInit;
+}
+
+export interface ClientResponse<T = any> {
+  ok: boolean;
+  status: number;
+  data: T;
+  error?: any;
+  headers: Headers;
+}
+
+export interface ClientOptions {
+  fetch?: typeof fetch;
+  headers?: HeadersInit;
+}
+
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head']);
+
+function buildUrl(baseUrl: string, segments: string[], options?: ClientRequestOptions): string {
+  let path = segments.join('/');
+
+  // Substitute path params if any segment is :param or contains :param
+  if (options?.params) {
+    for (const [key, val] of Object.entries(options.params)) {
+      path = path.replace(new RegExp(`:${key}\\b`, 'g'), encodeURIComponent(String(val)));
+    }
+  }
+
+  // Remove any remaining raw :param if not replaced
+  const cleanBase = baseUrl.replace(/\/+$/, '');
+  const cleanPath = path.startsWith('/') ? path : '/' + path;
+  let fullUrl = `${cleanBase}${cleanPath}`;
+
+  if (options?.query) {
+    const searchParams = new URLSearchParams();
+    for (const [k, v] of Object.entries(options.query)) {
+      if (v !== undefined && v !== null) {
+        if (Array.isArray(v)) {
+          v.forEach((item) => searchParams.append(k, String(item)));
+        } else {
+          searchParams.append(k, String(v));
+        }
+      }
+    }
+    const queryStr = searchParams.toString();
+    if (queryStr) {
+      fullUrl += (fullUrl.includes('?') ? '&' : '?') + queryStr;
+    }
+  }
+
+  return fullUrl;
+}
+
+export function createClient<TApp = any>(baseUrl = '', clientOptions: ClientOptions = {}): any {
+  const fetchFn = clientOptions.fetch || globalThis.fetch;
+
+  function createProxy(pathSegments: string[]): any {
+    return new Proxy(() => {}, {
+      get(_target, prop: string) {
+        const lowerProp = prop.toLowerCase();
+        if (HTTP_METHODS.has(lowerProp)) {
+          // This is the terminal HTTP method call, e.g. .get({ params, query, body })
+          return async (reqOptions?: ClientRequestOptions): Promise<ClientResponse> => {
+            const url = buildUrl(baseUrl, pathSegments, reqOptions);
+            const headers = new Headers(clientOptions.headers);
+            if (reqOptions?.headers) {
+              const extraHeaders = new Headers(reqOptions.headers);
+              extraHeaders.forEach((v, k) => headers.set(k, v));
+            }
+
+            let bodyContent: BodyInit | undefined;
+            if (reqOptions?.body !== undefined && lowerProp !== 'get' && lowerProp !== 'head') {
+              if (!headers.has('Content-Type')) {
+                headers.set('Content-Type', 'application/json');
+              }
+              bodyContent = typeof reqOptions.body === 'string'
+                ? reqOptions.body
+                : JSON.stringify(reqOptions.body);
+            }
+
+            const response = await fetchFn(url, {
+              method: lowerProp.toUpperCase(),
+              headers,
+              body: bodyContent,
+            });
+
+            let responseData: any = null;
+            const contentType = response.headers.get('content-type') || '';
+            if (contentType.includes('application/json')) {
+              try {
+                responseData = await response.json();
+              } catch {
+                responseData = null;
+              }
+            } else {
+              responseData = await response.text();
+            }
+
+            return {
+              ok: response.ok,
+              status: response.status,
+              data: responseData,
+              error: response.ok ? undefined : responseData,
+              headers: response.headers,
+            };
+          };
+        }
+
+        // Sub-path traversal
+        return createProxy([...pathSegments, prop]);
+      },
+    });
+  }
+
+  return createProxy([]);
+}