express-file-cluster 0.1.0

package/src/cli/commands/start.ts

@@ -0,0 +1,74 @@
+import { Command } from 'commander';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import chalk from 'chalk';
+
+export function startCommand(): Command {
+  const cmd = new Command('start');
+
+  cmd
+    .argument('<mode>', 'dev | prod')
+    .description('Start the EFC server')
+    .action((mode: string) => {
+      if (mode === 'dev') {
+        startDev();
+      } else if (mode === 'prod') {
+        startProd();
+      } else {
+        console.error(chalk.red(`Unknown mode: ${mode}. Use 'dev' or 'prod'.`));
+        process.exit(1);
+      }
+    });
+
+  return cmd;
+}
+
+function startDev(): void {
+  const entry = resolveEntry();
+  if (!entry) {
+    console.error(chalk.red('[EFC] Could not find entry point. Expected src/index.ts or index.ts'));
+    process.exit(1);
+  }
+
+  console.log(chalk.cyan('[EFC] Starting development server…'));
+  console.log(chalk.dim(`  Entry: ${entry}`));
+
+  const child = spawn(
+    'node',
+    ['--import', 'tsx/esm', '--watch', entry],
+    { stdio: 'inherit', env: { ...process.env, NODE_ENV: 'development' } },
+  );
+
+  child.on('exit', (code) => process.exit(code ?? 0));
+}
+
+function startProd(): void {
+  const cwd = process.cwd();
+  const distEntry = path.join(cwd, 'dist', 'index.js');
+
+  if (!fs.existsSync(distEntry)) {
+    console.error(chalk.red('[EFC] dist/index.js not found. Run `efc build prod` first.'));
+    process.exit(1);
+  }
+
+  console.log(chalk.cyan('[EFC] Starting production server…'));
+
+  const child = spawn('node', [distEntry], {
+    stdio: 'inherit',
+    env: { ...process.env, NODE_ENV: 'production' },
+  });
+
+  child.on('exit', (code) => process.exit(code ?? 0));
+}
+
+function resolveEntry(): string | null {
+  const cwd = process.cwd();
+  const candidates = [
+    path.join(cwd, 'src', 'index.ts'),
+    path.join(cwd, 'index.ts'),
+    path.join(cwd, 'src', 'index.js'),
+    path.join(cwd, 'index.js'),
+  ];
+  return candidates.find((f) => fs.existsSync(f)) ?? null;
+}

package/src/cli/index.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { startCommand } from './commands/start.js';
+import { buildCommand } from './commands/build.js';
+import { runCommand } from './commands/run.js';
+import { generateCommand } from './commands/generate.js';
+import { diagnosticsCommands } from './commands/diagnostics.js';
+
+const program = new Command('efc')
+  .description('Express File Cluster CLI')
+  .version('0.1.0');
+
+program.addCommand(startCommand());
+program.addCommand(buildCommand());
+program.addCommand(runCommand());
+program.addCommand(generateCommand());
+
+for (const cmd of diagnosticsCommands()) {
+  program.addCommand(cmd);
+}
+
+program.parse(process.argv);

package/src/cluster/index.ts

@@ -0,0 +1,31 @@
+import cluster from 'node:cluster';
+import os from 'node:os';
+
+interface ClusterOptions {
+  workers?: number;
+  onWorkerReady?: ((id: number) => void) | undefined;
+  onWorkerCrash?: ((id: number, code: number) => void) | undefined;
+}
+
+export function runMaster(options: ClusterOptions = {}): void {
+  const count = options.workers ?? os.cpus().length;
+
+  console.log(`[EFC] Primary ${process.pid} starting ${count} workers`);
+
+  for (let i = 0; i < count; i++) {
+    cluster.fork();
+  }
+
+  cluster.on('online', (worker) => {
+    options.onWorkerReady?.(worker.id);
+  });
+
+  cluster.on('exit', (worker, code, signal) => {
+    const exitCode = code ?? (signal ? -1 : 0);
+    console.warn(`[EFC] Worker ${worker.id} exited (code=${exitCode}), respawning…`);
+    options.onWorkerCrash?.(worker.id, exitCode);
+    cluster.fork();
+  });
+}
+
+export { cluster };

package/src/compose.ts

@@ -0,0 +1,26 @@
+import type { RequestHandler } from 'express';
+
+export function compose(...handlers: RequestHandler[]): RequestHandler {
+  return (req, res, next) => {
+    let index = 0;
+
+    function dispatch(i: number): void {
+      if (i >= handlers.length) {
+        next();
+        return;
+      }
+      const handler = handlers[i];
+      if (!handler) {
+        next();
+        return;
+      }
+      try {
+        Promise.resolve(handler(req, res, () => dispatch(i + 1))).catch(next);
+      } catch (err) {
+        next(err);
+      }
+    }
+
+    dispatch(index);
+  };
+}

package/src/db/index.ts

@@ -0,0 +1,31 @@
+// Thread-local DB client populated during Pre-Flight.
+// The Proxy ensures callers import `db` once and never null-check it —
+// it throws with a helpful message if accessed before Pre-Flight completes.
+
+type AnyClient = Record<string, unknown>;
+
+let _client: AnyClient | null = null;
+
+export function setDbClient(client: AnyClient): void {
+  _client = client;
+}
+
+export function getDbClient(): AnyClient {
+  if (!_client) {
+    throw new Error('[EFC] db not ready — accessed before Pre-Flight completed');
+  }
+  return _client;
+}
+
+export const db: AnyClient = new Proxy({} as AnyClient, {
+  get(_target, prop: string) {
+    return getDbClient()[prop];
+  },
+  set(_target, prop: string, value: unknown) {
+    getDbClient()[prop] = value;
+    return true;
+  },
+});
+
+export { connectMongo } from './mongo.js';
+export { defineModel } from './model.js';

package/src/db/model.ts

@@ -0,0 +1,95 @@
+import type { ModelSchema, ModelCRUD } from '../types.js';
+
+type AnyRecord = Record<string, unknown> & { id: string };
+
+function normalise(doc: Record<string, unknown>): AnyRecord {
+  const id = doc['_id'] ? String(doc['_id']) : '';
+  return { ...doc, id } as AnyRecord;
+}
+
+async function getModel(name: string, schemaObj: Record<string, unknown>): Promise<import('mongoose').Model<Record<string, unknown>>> {
+  let mg: typeof import('mongoose');
+  try {
+    mg = await import('mongoose');
+  } catch {
+    throw new Error('[EFC] mongoose is not installed. Run: npm install mongoose');
+  }
+
+  if (mg.models[name]) return mg.models[name] as import('mongoose').Model<Record<string, unknown>>;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const schema = new mg.Schema(schemaObj as any, { timestamps: true });
+  return mg.model<Record<string, unknown>>(name, schema);
+}
+
+function buildMongooseSchema(schema: ModelSchema): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, def] of Object.entries(schema)) {
+    const entry: Record<string, unknown> = {};
+    switch (def.type) {
+      case 'string':   entry['type'] = String; break;
+      case 'number':   entry['type'] = Number; break;
+      case 'boolean':  entry['type'] = Boolean; break;
+      case 'date':     entry['type'] = Date; break;
+      case 'object':   entry['type'] = Object; break;
+      case 'array':    entry['type'] = Array; break;
+    }
+    if (def.required !== undefined) entry['required'] = def.required;
+    if (def.unique !== undefined)   entry['unique'] = def.unique;
+    if (def.default !== undefined)  entry['default'] = def.default;
+    out[key] = entry;
+  }
+  return out;
+}
+
+export function defineModel<T extends Record<string, unknown>>(
+  name: string,
+  schema: ModelSchema,
+): ModelCRUD<T> {
+  const mongooseSchema = buildMongooseSchema(schema);
+
+  return {
+    async find(filter = {}) {
+      const M = await getModel(name, mongooseSchema);
+      const docs = await M.find(filter as Record<string, unknown>).lean();
+      return (docs as Record<string, unknown>[]).map(normalise) as (T & { id: string })[];
+    },
+
+    async findById(id) {
+      const M = await getModel(name, mongooseSchema);
+      const doc = await M.findById(id).lean();
+      if (!doc) return null;
+      return normalise(doc as Record<string, unknown>) as T & { id: string };
+    },
+
+    async findOne(filter) {
+      const M = await getModel(name, mongooseSchema);
+      const doc = await M.findOne(filter as Record<string, unknown>).lean();
+      if (!doc) return null;
+      return normalise(doc as Record<string, unknown>) as T & { id: string };
+    },
+
+    async create(data) {
+      const M = await getModel(name, mongooseSchema);
+      const doc = await M.create(data);
+      return normalise(doc.toObject() as Record<string, unknown>) as T & { id: string };
+    },
+
+    async update(id, data) {
+      const M = await getModel(name, mongooseSchema);
+      const doc = await M.findByIdAndUpdate(id, data, { new: true }).lean();
+      if (!doc) return null;
+      return normalise(doc as Record<string, unknown>) as T & { id: string };
+    },
+
+    async delete(id) {
+      const M = await getModel(name, mongooseSchema);
+      await M.findByIdAndDelete(id);
+    },
+
+    async count(filter = {}) {
+      const M = await getModel(name, mongooseSchema);
+      return M.countDocuments(filter as Record<string, unknown>);
+    },
+  };
+}

package/src/db/mongo.ts

@@ -0,0 +1,22 @@
+// Wraps mongoose connection for Pre-Flight. Throws clearly if mongoose isn't installed.
+
+let mongoose: typeof import('mongoose');
+
+async function loadMongoose(): Promise<typeof import('mongoose')> {
+  if (mongoose) return mongoose;
+  try {
+    mongoose = await import('mongoose');
+    return mongoose;
+  } catch {
+    throw new Error(
+      '[EFC] mongoose is not installed. Run: npm install mongoose',
+    );
+  }
+}
+
+export async function connectMongo(url: string): Promise<import('mongoose').Connection> {
+  const mg = await loadMongoose();
+  await mg.connect(url);
+  console.log('[EFC] MongoDB connected');
+  return mg.connection;
+}

package/src/errors.ts

@@ -0,0 +1,10 @@
+export class HttpError extends Error {
+  readonly statusCode: number;
+
+  constructor(statusCode: number, message: string) {
+    super(message);
+    this.name = 'HttpError';
+    this.statusCode = statusCode;
+    Error.captureStackTrace(this, HttpError);
+  }
+}

package/src/index.ts

@@ -0,0 +1,127 @@
+import express from 'express';
+import cookieParser from 'cookie-parser';
+import cluster from 'node:cluster';
+import os from 'node:os';
+import type { EFCConfig } from './types.js';
+import { scanDir } from './router/scan.js';
+import { mountRoutes } from './router/mount.js';
+import { runMaster } from './cluster/index.js';
+import { configureAuth } from './auth/index.js';
+import { HttpError } from './errors.js';
+import { connectMongo } from './db/mongo.js';
+import { setDbClient } from './db/index.js';
+import { scanTasks } from './tasks/scanner.js';
+import { initBullMQ } from './tasks/bullmq-backend.js';
+
+export async function ignite(config: EFCConfig): Promise<void> {
+  const {
+    port = 3000,
+    cluster: clusterEnabled = true,
+    workers,
+    apiDir,
+    jwtSecret,
+    authStrategy = 'http-only',
+    globalMiddlewares = [],
+    onWorkerReady,
+    onWorkerCrash,
+    onError,
+  } = config;
+
+  if (clusterEnabled && cluster.isPrimary) {
+    runMaster({
+      workers: workers ?? os.cpus().length,
+      ...(onWorkerReady !== undefined && { onWorkerReady }),
+      ...(onWorkerCrash !== undefined && { onWorkerCrash }),
+    });
+    return;
+  }
+
+  const app = express();
+
+  app.use(express.json());
+  app.use(express.urlencoded({ extended: true }));
+  app.use(cookieParser());
+
+  for (const mw of globalMiddlewares) {
+    app.use(mw);
+  }
+
+  // Pre-Flight step 1: Connect database
+  if (config.database === 'mongodb' && config.databaseUrl) {
+    const conn = await connectMongo(config.databaseUrl);
+    setDbClient(conn as unknown as Record<string, unknown>);
+  }
+
+  // Pre-Flight step 2: Configure auth
+  if (jwtSecret) {
+    const cookieDomain = process.env['COOKIE_DOMAIN'];
+    configureAuth({
+      secret: jwtSecret,
+      strategy: authStrategy,
+      expiresIn: process.env['JWT_EXPIRES_IN'] ?? '7d',
+      ...(cookieDomain !== undefined && { cookieDomain }),
+    });
+  }
+
+  // Pre-Flight step 3: Scan and register tasks
+  if (config.tasksDir) {
+    await scanTasks(config.tasksDir);
+  }
+
+  // Pre-Flight step 4: Start task queue backend
+  if (config.tasks) {
+    if (config.tasks.backend === 'bullmq') {
+      await initBullMQ({
+        redisUrl: config.tasks.redisUrl ?? 'redis://localhost:6379',
+        concurrency: config.tasks.concurrency ?? 5,
+      });
+    }
+  }
+
+  // Pre-Flight step 5: Scan routes and mount
+  const routes = scanDir(apiDir);
+  await mountRoutes(app, routes);
+
+  if (onError) {
+    app.use(onError);
+  } else {
+    app.use(
+      (
+        err: unknown,
+        _req: express.Request,
+        res: express.Response,
+        _next: express.NextFunction,
+      ) => {
+        if (err instanceof HttpError) {
+          res.status(err.statusCode).json({ error: err.message, statusCode: err.statusCode });
+        } else {
+          console.error('[EFC] Unhandled error:', err);
+          res.status(500).json({ error: 'Internal Server Error', statusCode: 500 });
+        }
+      },
+    );
+  }
+
+  await new Promise<void>((resolve) => {
+    app.listen(port, () => {
+      const wid = (cluster.worker as { id: number } | undefined)?.id ?? 'primary';
+      console.log(`[EFC] Worker ${wid} listening on :${port}`);
+      resolve();
+    });
+  });
+}
+
+export { HttpError } from './errors.js';
+export { compose } from './compose.js';
+export { db, setDbClient, getDbClient, defineModel } from './db/index.js';
+export { scanDir } from './router/scan.js';
+export type {
+  EFCConfig,
+  RouteEntry,
+  TaskOptions,
+  TaskDefinition,
+  DatabaseEngine,
+  AuthStrategy,
+  ModelSchema,
+  ModelCRUD,
+} from './types.js';

package/src/router/mount.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import express from 'express';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { mountRoutes } from './mount.js';
+import type { RouteEntry } from '../types.js';
+
+function makeApp() {
+  return express();
+}
+
+describe('mountRoutes', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'efc-mount-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('mounts a GET handler from a route module', async () => {
+    const file = path.join(tmpDir, 'health.js');
+    fs.writeFileSync(
+      file,
+      `export const GET = async (req, res) => res.json({ ok: true });`,
+    );
+
+    const app = makeApp();
+    const routes: RouteEntry[] = [{ urlPath: '/health', filePath: file, params: [] }];
+
+    await mountRoutes(app, routes);
+
+    const stack = app._router?.stack ?? [];
+    const hasRoute = stack.some(
+      (layer: { route?: { path: string; methods: Record<string, boolean> } }) =>
+        layer.route?.path === '/health' && layer.route?.methods?.get,
+    );
+    expect(hasRoute).toBe(true);
+  });
+
+  it('mounts multiple methods from a single route file', async () => {
+    const file = path.join(tmpDir, 'users.js');
+    fs.writeFileSync(
+      file,
+      `export const GET = async (req, res) => res.json([]);
+       export const POST = async (req, res) => res.status(201).json({});`,
+    );
+
+    const app = makeApp();
+    const routes: RouteEntry[] = [{ urlPath: '/users', filePath: file, params: [] }];
+
+    await mountRoutes(app, routes);
+
+    // Express registers one layer per method; collect all /users layers
+    type Layer = { route?: { path: string; methods: Record<string, boolean> } };
+    const stack: Layer[] = app._router?.stack ?? [];
+    const layers = stack.filter((l) => l.route?.path === '/users');
+    const methods = layers.flatMap((l) => Object.keys(l.route?.methods ?? {}));
+    expect(methods).toContain('get');
+    expect(methods).toContain('post');
+  });
+
+  it('skips non-function exports silently', async () => {
+    const file = path.join(tmpDir, 'noop.js');
+    fs.writeFileSync(file, `export const middlewares = [];`);
+
+    const app = makeApp();
+    const routes: RouteEntry[] = [{ urlPath: '/noop', filePath: file, params: [] }];
+
+    await expect(mountRoutes(app, routes)).resolves.toBeUndefined();
+  });
+});

package/src/router/mount.ts

@@ -0,0 +1,49 @@
+import type { Application, RequestHandler } from 'express';
+import type { RouteEntry } from '../types.js';
+
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'] as const;
+type HttpMethod = (typeof HTTP_METHODS)[number];
+
+function asyncWrap(handler: RequestHandler): RequestHandler {
+  return (req, res, next) => {
+    Promise.resolve(handler(req, res, next)).catch(next);
+  };
+}
+
+export async function mountRoutes(app: Application, routes: RouteEntry[]): Promise<void> {
+  for (const route of routes) {
+    const mod = (await import(route.filePath)) as Record<string, unknown>;
+    const routeMiddlewares: RequestHandler[] = Array.isArray(mod['middlewares'])
+      ? (mod['middlewares'] as RequestHandler[])
+      : [];
+
+    const implemented: HttpMethod[] = [];
+    const unimplemented: HttpMethod[] = [];
+
+    for (const method of HTTP_METHODS) {
+      if (typeof mod[method] === 'function') {
+        implemented.push(method);
+        app[method.toLowerCase() as Lowercase<HttpMethod>](
+          route.urlPath,
+          ...routeMiddlewares,
+          asyncWrap(mod[method] as RequestHandler),
+        );
+      } else {
+        unimplemented.push(method);
+      }
+    }
+
+    if (implemented.length > 0 && unimplemented.length > 0) {
+      const allowHeader = implemented.join(', ');
+      app.all(route.urlPath, (req, res, next) => {
+        if ((unimplemented as string[]).includes(req.method)) {
+          res.set('Allow', allowHeader).status(405).json({ error: 'Method Not Allowed' });
+        } else {
+          next();
+        }
+      });
+    }
+  }
+}
+
+export { asyncWrap };

package/src/router/scan.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { filePathToUrlPath } from './scan.js';
+
+describe('filePathToUrlPath', () => {
+  it('maps static files to their path', () => {
+    expect(filePathToUrlPath('/health.ts')).toBe('/health');
+    expect(filePathToUrlPath('/users/profile.ts')).toBe('/users/profile');
+  });
+
+  it('maps index files to parent path', () => {
+    expect(filePathToUrlPath('/index.ts')).toBe('/');
+    expect(filePathToUrlPath('/users/index.ts')).toBe('/users');
+  });
+
+  it('maps dynamic segments', () => {
+    expect(filePathToUrlPath('/users/[id].ts')).toBe('/users/:id');
+    expect(filePathToUrlPath('/posts/[slug]/comments.ts')).toBe('/posts/:slug/comments');
+  });
+
+  it('handles nested dynamic', () => {
+    expect(filePathToUrlPath('/a/[b]/c/[d].ts')).toBe('/a/:b/c/:d');
+  });
+});

package/src/router/scan.ts

@@ -0,0 +1,55 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { RouteEntry } from '../types.js';
+
+const ROUTE_FILE_RE = /\.(ts|js|mts|mjs|cts|cjs)$/;
+const DYNAMIC_SEGMENT_RE = /\[([^\]]+)\]/g;
+
+function filePathToUrlPath(relativePath: string): string {
+  let p = relativePath.replace(ROUTE_FILE_RE, '');
+  // index files map to parent path
+  p = p.replace(/\/index$/, '');
+  // [param] → :param
+  p = p.replace(DYNAMIC_SEGMENT_RE, ':$1');
+  return p === '' ? '/' : p.startsWith('/') ? p : `/${p}`;
+}
+
+function extractParams(relativePath: string): string[] {
+  const params: string[] = [];
+  let match: RegExpExecArray | null;
+  const re = new RegExp(DYNAMIC_SEGMENT_RE.source, 'g');
+  while ((match = re.exec(relativePath)) !== null) {
+    if (match[1]) params.push(match[1]);
+  }
+  return params;
+}
+
+export function scanDir(dir: string, base: string = dir): RouteEntry[] {
+  if (!fs.existsSync(dir)) return [];
+
+  const entries: RouteEntry[] = [];
+  const items = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const item of items) {
+    const fullPath = path.join(dir, item.name);
+    if (item.isDirectory()) {
+      entries.push(...scanDir(fullPath, base));
+    } else if (ROUTE_FILE_RE.test(item.name)) {
+      const relative = '/' + path.relative(base, fullPath).replace(/\\/g, '/');
+      entries.push({
+        urlPath: filePathToUrlPath(relative),
+        filePath: fullPath,
+        params: extractParams(relative),
+      });
+    }
+  }
+
+  // Sort: static routes before dynamic ones at each segment level
+  return entries.sort((a, b) => {
+    const aDynamic = a.urlPath.includes(':') ? 1 : 0;
+    const bDynamic = b.urlPath.includes(':') ? 1 : 0;
+    return aDynamic - bDynamic || a.urlPath.localeCompare(b.urlPath);
+  });
+}
+
+export { filePathToUrlPath };