express-file-cluster 0.1.0

package/dist/tasks/index.d.ts

@@ -0,0 +1,16 @@
+import { T as TaskDefinition, a as TaskOptions } from '../types-DNdkDUPX.js';
+import 'express';
+
+declare const taskRegistry: Map<string, TaskDefinition<unknown>>;
+type HandlerFn<T> = (payload: T) => Promise<void>;
+type DefineTaskOverload = {
+    <T>(handler: HandlerFn<T>): TaskDefinition<T>;
+    <T>(options: TaskOptions, handler: HandlerFn<T>): TaskDefinition<T>;
+};
+declare const defineTask: DefineTaskOverload;
+type EnqueueImpl = (name: string, payload: unknown) => Promise<void>;
+declare function setEnqueueImpl(impl: EnqueueImpl): void;
+declare function enqueue<T>(name: string, payload: T): Promise<void>;
+declare function registerTask(name: string, def: TaskDefinition): void;
+
+export { defineTask, enqueue, registerTask, setEnqueueImpl, taskRegistry };

package/dist/tasks/index.js

@@ -0,0 +1,41 @@
+// src/tasks/index.ts
+var taskRegistry = /* @__PURE__ */ new Map();
+var defineTask = (handlerOrOptions, maybeHandler) => {
+  let options = {};
+  let handler;
+  if (typeof handlerOrOptions === "function") {
+    handler = handlerOrOptions;
+  } else {
+    options = handlerOrOptions;
+    if (!maybeHandler) throw new Error("[EFC] defineTask: handler function is required");
+    handler = maybeHandler;
+  }
+  return {
+    handler,
+    options,
+    name: ""
+  };
+};
+var _impl = null;
+function setEnqueueImpl(impl) {
+  _impl = impl;
+}
+async function enqueue(name, payload) {
+  if (!_impl) {
+    throw new Error(
+      `[EFC] Task queue not initialised. Set tasks.backend in ignite() config.`
+    );
+  }
+  return _impl(name, payload);
+}
+function registerTask(name, def) {
+  taskRegistry.set(name, { ...def, name });
+}
+export {
+  defineTask,
+  enqueue,
+  registerTask,
+  setEnqueueImpl,
+  taskRegistry
+};
+//# sourceMappingURL=index.js.map

package/dist/tasks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tasks/index.ts"],"sourcesContent":["import type { TaskDefinition, TaskOptions } from '../types.js';\n\nexport const taskRegistry = new Map<string, TaskDefinition>();\n\ntype HandlerFn<T> = (payload: T) => Promise<void>;\ntype DefineTaskOverload = {\n  <T>(handler: HandlerFn<T>): TaskDefinition<T>;\n  <T>(options: TaskOptions, handler: HandlerFn<T>): TaskDefinition<T>;\n};\n\nexport const defineTask: DefineTaskOverload = <T>(\n  handlerOrOptions: HandlerFn<T> | TaskOptions,\n  maybeHandler?: HandlerFn<T>,\n): TaskDefinition<T> => {\n  let options: TaskOptions = {};\n  let handler: HandlerFn<T>;\n\n  if (typeof handlerOrOptions === 'function') {\n    handler = handlerOrOptions;\n  } else {\n    options = handlerOrOptions;\n    if (!maybeHandler) throw new Error('[EFC] defineTask: handler function is required');\n    handler = maybeHandler;\n  }\n\n  return {\n    handler: handler as (payload: unknown) => Promise<void>,\n    options,\n    name: '',\n  };\n};\n\ntype EnqueueImpl = (name: string, payload: unknown) => Promise<void>;\nlet _impl: EnqueueImpl | null = null;\n\nexport function setEnqueueImpl(impl: EnqueueImpl): void {\n  _impl = impl;\n}\n\nexport async function enqueue<T>(name: string, payload: T): Promise<void> {\n  if (!_impl) {\n    throw new Error(\n      `[EFC] Task queue not initialised. Set tasks.backend in ignite() config.`,\n    );\n  }\n  return _impl(name, payload as unknown);\n}\n\nexport function registerTask(name: string, def: TaskDefinition): void {\n  taskRegistry.set(name, { ...def, name });\n}\n"],"mappings":";AAEO,IAAM,eAAe,oBAAI,IAA4B;AAQrD,IAAM,aAAiC,CAC5C,kBACA,iBACsB;AACtB,MAAI,UAAuB,CAAC;AAC5B,MAAI;AAEJ,MAAI,OAAO,qBAAqB,YAAY;AAC1C,cAAU;AAAA,EACZ,OAAO;AACL,cAAU;AACV,QAAI,CAAC,aAAc,OAAM,IAAI,MAAM,gDAAgD;AACnF,cAAU;AAAA,EACZ;AAEA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,MAAM;AAAA,EACR;AACF;AAGA,IAAI,QAA4B;AAEzB,SAAS,eAAe,MAAyB;AACtD,UAAQ;AACV;AAEA,eAAsB,QAAW,MAAc,SAA2B;AACxE,MAAI,CAAC,OAAO;AACV,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,SAAO,MAAM,MAAM,OAAkB;AACvC;AAEO,SAAS,aAAa,MAAc,KAA2B;AACpE,eAAa,IAAI,MAAM,EAAE,GAAG,KAAK,KAAK,CAAC;AACzC;","names":[]}

package/dist/types-DNdkDUPX.d.cts

@@ -0,0 +1,70 @@
+import { RequestHandler, ErrorRequestHandler } from 'express';
+
+type DatabaseEngine = 'mongodb' | 'postgresql';
+type AuthStrategy = 'http-only' | 'localStorage';
+type TaskBackend = 'bullmq' | 'pg-boss';
+interface TaskConfig {
+    backend: TaskBackend;
+    redisUrl?: string;
+    concurrency?: number;
+}
+interface EFCConfig {
+    port?: number;
+    apiDir: string;
+    tasksDir?: string;
+    database?: DatabaseEngine;
+    databaseUrl?: string;
+    authStrategy?: AuthStrategy;
+    jwtSecret?: string;
+    cluster?: boolean;
+    workers?: number;
+    tasks?: TaskConfig | false;
+    globalMiddlewares?: RequestHandler[];
+    onWorkerReady?: (id: number) => void;
+    onWorkerCrash?: (id: number, code: number) => void;
+    onError?: ErrorRequestHandler;
+}
+interface RouteEntry {
+    urlPath: string;
+    filePath: string;
+    params: string[];
+}
+interface TaskOptions {
+    thread?: boolean;
+    retries?: number;
+    backoff?: 'fixed' | 'exponential';
+    concurrency?: number;
+    schedule?: string;
+}
+interface TaskDefinition<TPayload = unknown> {
+    handler: (payload: TPayload) => Promise<void>;
+    options: TaskOptions;
+    name: string;
+    filePath?: string;
+}
+interface FieldDefinition {
+    type: 'string' | 'number' | 'boolean' | 'date' | 'object' | 'array';
+    required?: boolean;
+    unique?: boolean;
+    default?: unknown;
+}
+type ModelSchema = Record<string, FieldDefinition>;
+interface ModelCRUD<T extends Record<string, unknown>> {
+    find(filter?: Partial<T>): Promise<T[]>;
+    findById(id: string): Promise<(T & {
+        id: string;
+    }) | null>;
+    findOne(filter: Partial<T>): Promise<(T & {
+        id: string;
+    }) | null>;
+    create(data: Partial<T>): Promise<T & {
+        id: string;
+    }>;
+    update(id: string, data: Partial<T>): Promise<(T & {
+        id: string;
+    }) | null>;
+    delete(id: string): Promise<void>;
+    count(filter?: Partial<T>): Promise<number>;
+}
+
+export type { AuthStrategy as A, DatabaseEngine as D, EFCConfig as E, ModelSchema as M, RouteEntry as R, TaskDefinition as T, TaskOptions as a, ModelCRUD as b };

package/dist/types-DNdkDUPX.d.ts

@@ -0,0 +1,70 @@
+import { RequestHandler, ErrorRequestHandler } from 'express';
+
+type DatabaseEngine = 'mongodb' | 'postgresql';
+type AuthStrategy = 'http-only' | 'localStorage';
+type TaskBackend = 'bullmq' | 'pg-boss';
+interface TaskConfig {
+    backend: TaskBackend;
+    redisUrl?: string;
+    concurrency?: number;
+}
+interface EFCConfig {
+    port?: number;
+    apiDir: string;
+    tasksDir?: string;
+    database?: DatabaseEngine;
+    databaseUrl?: string;
+    authStrategy?: AuthStrategy;
+    jwtSecret?: string;
+    cluster?: boolean;
+    workers?: number;
+    tasks?: TaskConfig | false;
+    globalMiddlewares?: RequestHandler[];
+    onWorkerReady?: (id: number) => void;
+    onWorkerCrash?: (id: number, code: number) => void;
+    onError?: ErrorRequestHandler;
+}
+interface RouteEntry {
+    urlPath: string;
+    filePath: string;
+    params: string[];
+}
+interface TaskOptions {
+    thread?: boolean;
+    retries?: number;
+    backoff?: 'fixed' | 'exponential';
+    concurrency?: number;
+    schedule?: string;
+}
+interface TaskDefinition<TPayload = unknown> {
+    handler: (payload: TPayload) => Promise<void>;
+    options: TaskOptions;
+    name: string;
+    filePath?: string;
+}
+interface FieldDefinition {
+    type: 'string' | 'number' | 'boolean' | 'date' | 'object' | 'array';
+    required?: boolean;
+    unique?: boolean;
+    default?: unknown;
+}
+type ModelSchema = Record<string, FieldDefinition>;
+interface ModelCRUD<T extends Record<string, unknown>> {
+    find(filter?: Partial<T>): Promise<T[]>;
+    findById(id: string): Promise<(T & {
+        id: string;
+    }) | null>;
+    findOne(filter: Partial<T>): Promise<(T & {
+        id: string;
+    }) | null>;
+    create(data: Partial<T>): Promise<T & {
+        id: string;
+    }>;
+    update(id: string, data: Partial<T>): Promise<(T & {
+        id: string;
+    }) | null>;
+    delete(id: string): Promise<void>;
+    count(filter?: Partial<T>): Promise<number>;
+}
+
+export type { AuthStrategy as A, DatabaseEngine as D, EFCConfig as E, ModelSchema as M, RouteEntry as R, TaskDefinition as T, TaskOptions as a, ModelCRUD as b };

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "express-file-cluster",
+  "version": "0.1.0",
+  "description": "Enterprise-grade, zero-boilerplate backend framework with file-based routing and multi-core clustering",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "efc": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./auth": {
+      "import": "./dist/auth/index.js",
+      "require": "./dist/auth/index.cjs",
+      "types": "./dist/auth/index.d.ts"
+    },
+    "./tasks": {
+      "import": "./dist/tasks/index.js",
+      "require": "./dist/tasks/index.cjs",
+      "types": "./dist/tasks/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "chokidar": "^4.0.0",
+    "commander": "^12.0.0",
+    "cookie-parser": "^1.4.6",
+    "express": "^4.19.0",
+    "jsonwebtoken": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/cookie-parser": "^1.4.7",
+    "@types/express": "^4.17.21",
+    "@types/jsonwebtoken": "^9.0.6",
+    "@types/node": "^22.0.0",
+    "bullmq": "^5.79.1",
+    "mongoose": "^9.7.2",
+    "tsup": "^8.2.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "peerDependencies": {
+    "bullmq": ">=5.0.0",
+    "mongoose": ">=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "bullmq": {
+      "optional": true
+    },
+    "mongoose": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,71 @@
+import type { RequestHandler, Response } from 'express';
+import jwt from 'jsonwebtoken';
+import type { AuthStrategy } from '../types.js';
+
+interface AuthConfig {
+  secret: string;
+  strategy: AuthStrategy;
+  expiresIn: string;
+  cookieDomain?: string | undefined;
+}
+
+let _config: AuthConfig | null = null;
+
+export function configureAuth(config: AuthConfig): void {
+  _config = config;
+}
+
+function getConfig(): AuthConfig {
+  if (!_config) throw new Error('[EFC] Auth not configured — pass jwtSecret to ignite()');
+  return _config;
+}
+
+export function issueToken(res: Response, payload: Record<string, unknown>): void {
+  const { secret, expiresIn, cookieDomain } = getConfig();
+  // expiresIn is a plain string (e.g. '7d'); cast satisfies jwt's branded StringValue
+  const token = jwt.sign(payload, secret, { expiresIn: expiresIn as jwt.SignOptions['expiresIn'] & string });
+  res.cookie('efc_token', token, {
+    httpOnly: true,
+    secure: process.env['NODE_ENV'] === 'production',
+    sameSite: 'strict',
+    ...(cookieDomain !== undefined && { domain: cookieDomain }),
+  });
+}
+
+export function revokeToken(res: Response): void {
+  res.clearCookie('efc_token');
+}
+
+export function signToken(payload: Record<string, unknown>): string {
+  const { secret, expiresIn } = getConfig();
+  return jwt.sign(payload, secret, { expiresIn: expiresIn as jwt.SignOptions['expiresIn'] & string });
+}
+
+export const requireAuth: RequestHandler = (req, res, next) => {
+  const { secret, strategy } = getConfig();
+
+  try {
+    let token: string | undefined;
+
+    if (strategy === 'http-only') {
+      const cookies = (req as typeof req & { cookies: Record<string, string> }).cookies;
+      token = cookies['efc_token'];
+    } else {
+      const auth = req.headers['authorization'];
+      if (typeof auth === 'string' && auth.startsWith('Bearer ')) {
+        token = auth.slice(7);
+      }
+    }
+
+    if (!token) {
+      res.status(401).json({ error: 'Unauthorized' });
+      return;
+    }
+
+    const decoded = jwt.verify(token, secret);
+    (req as typeof req & { user: unknown }).user = decoded;
+    next();
+  } catch {
+    res.status(401).json({ error: 'Unauthorized' });
+  }
+};

package/src/cli/commands/build.ts

@@ -0,0 +1,43 @@
+import { Command } from 'commander';
+import { spawn } from 'node:child_process';
+import chalk from 'chalk';
+
+export function buildCommand(): Command {
+  const cmd = new Command('build');
+
+  cmd
+    .argument('<mode>', 'prod')
+    .description('Build the application for production')
+    .action((mode: string) => {
+      if (mode !== 'prod') {
+        console.error(chalk.red(`Unknown build mode: ${mode}. Use 'prod'.`));
+        process.exit(1);
+      }
+      buildProd();
+    });
+
+  return cmd;
+}
+
+function buildProd(): void {
+  console.log(chalk.cyan('[EFC] Building for production…'));
+
+  // Type-check first
+  const tsc = spawn('npx', ['tsc', '--noEmit'], { stdio: 'inherit' });
+
+  tsc.on('exit', (code) => {
+    if (code !== 0) {
+      console.error(chalk.red('[EFC] TypeScript errors found. Fix them before building.'));
+      process.exit(1);
+    }
+
+    const tsup = spawn('npx', ['tsup'], { stdio: 'inherit' });
+    tsup.on('exit', (tsupCode) => {
+      if (tsupCode === 0) {
+        console.log(chalk.green('[EFC] Build complete → dist/'));
+      } else {
+        process.exit(tsupCode ?? 1);
+      }
+    });
+  });
+}

package/src/cli/commands/diagnostics.ts

@@ -0,0 +1,124 @@
+import { Command } from 'commander';
+import { scanDir } from '../../router/scan.js';
+import path from 'node:path';
+import fs from 'node:fs';
+import chalk from 'chalk';
+
+export function diagnosticsCommands(): Command[] {
+  return [routesCommand(), tasksCommand(), doctorCommand()];
+}
+
+function routesCommand(): Command {
+  return new Command('routes')
+    .description('Print the resolved route table')
+    .action(() => {
+      const apiDir = resolveApiDir();
+      if (!apiDir) {
+        console.error(chalk.red('[EFC] Could not find apiDir (expected src/api)'));
+        process.exit(1);
+      }
+
+      const routes = scanDir(apiDir);
+      if (routes.length === 0) {
+        console.log(chalk.yellow('No routes found.'));
+        return;
+      }
+
+      console.log(chalk.bold('\n  Route Table\n'));
+      console.log(chalk.dim('  ' + '─'.repeat(60)));
+      for (const route of routes) {
+        const rel = path.relative(process.cwd(), route.filePath);
+        console.log(`  ${chalk.cyan(route.urlPath.padEnd(35))} ${chalk.dim(rel)}`);
+      }
+      console.log(chalk.dim('  ' + '─'.repeat(60)));
+      console.log(chalk.dim(`\n  ${routes.length} route(s) found\n`));
+    });
+}
+
+function tasksCommand(): Command {
+  return new Command('tasks')
+    .description('List registered background tasks')
+    .action(() => {
+      const tasksDir = resolveTasksDir();
+      if (!tasksDir || !fs.existsSync(tasksDir)) {
+        console.log(chalk.yellow('No tasks directory found.'));
+        return;
+      }
+
+      const files = fs.readdirSync(tasksDir).filter((f) => /\.(ts|js)$/.test(f));
+      if (files.length === 0) {
+        console.log(chalk.yellow('No tasks found.'));
+        return;
+      }
+
+      console.log(chalk.bold('\n  Background Tasks\n'));
+      for (const file of files) {
+        console.log(`  ${chalk.cyan(path.basename(file, path.extname(file)))}`);
+      }
+      console.log();
+    });
+}
+
+function doctorCommand(): Command {
+  return new Command('doctor')
+    .description('Validate config, env vars, and project setup')
+    .action(() => {
+      const cwd = process.cwd();
+      const checks: { label: string; ok: boolean; hint?: string }[] = [
+        {
+          label: 'package.json exists',
+          ok: fs.existsSync(path.join(cwd, 'package.json')),
+        },
+        {
+          label: 'tsconfig.json exists',
+          ok: fs.existsSync(path.join(cwd, 'tsconfig.json')),
+          hint: 'Run `tsc --init` to create one',
+        },
+        {
+          label: 'src/api directory exists',
+          ok: fs.existsSync(path.join(cwd, 'src', 'api')),
+          hint: 'Create src/api/ and add route files',
+        },
+        {
+          label: 'DATABASE_URL set',
+          ok: Boolean(process.env['DATABASE_URL']),
+          hint: 'Add DATABASE_URL to .env',
+        },
+        {
+          label: 'JWT_SECRET set',
+          ok: Boolean(process.env['JWT_SECRET']),
+          hint: 'Add JWT_SECRET to .env (generate: openssl rand -hex 64)',
+        },
+      ];
+
+      console.log(chalk.bold('\n  EFC Doctor\n'));
+      let allOk = true;
+      for (const check of checks) {
+        const icon = check.ok ? chalk.green('✓') : chalk.red('✗');
+        console.log(`  ${icon}  ${check.label}`);
+        if (!check.ok) {
+          allOk = false;
+          if (check.hint) console.log(chalk.dim(`       → ${check.hint}`));
+        }
+      }
+      console.log();
+      if (allOk) {
+        console.log(chalk.green('  All checks passed!\n'));
+      } else {
+        console.log(chalk.yellow('  Some checks failed. Fix the issues above.\n'));
+        process.exit(1);
+      }
+    });
+}
+
+function resolveApiDir(): string | null {
+  const cwd = process.cwd();
+  const candidates = [path.join(cwd, 'src', 'api'), path.join(cwd, 'api')];
+  return candidates.find((d) => fs.existsSync(d)) ?? null;
+}
+
+function resolveTasksDir(): string | null {
+  const cwd = process.cwd();
+  const candidates = [path.join(cwd, 'src', 'tasks'), path.join(cwd, 'tasks')];
+  return candidates.find((d) => fs.existsSync(d)) ?? null;
+}

package/src/cli/commands/generate.ts

@@ -0,0 +1,91 @@
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+
+export function generateCommand(): Command {
+  const cmd = new Command('generate').alias('g').description('Scaffold EFC modules');
+
+  cmd
+    .command('route <routePath>')
+    .description('Scaffold a route module, e.g. users/[id]')
+    .action((routePath: string) => generateRoute(routePath));
+
+  cmd
+    .command('task <name>')
+    .description('Scaffold a background task module')
+    .action((name: string) => generateTask(name));
+
+  cmd
+    .command('middleware <name>')
+    .description('Scaffold a middleware module')
+    .action((name: string) => generateMiddleware(name));
+
+  return cmd;
+}
+
+function writeFile(filePath: string, content: string): void {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  if (fs.existsSync(filePath)) {
+    console.error(chalk.red(`File already exists: ${filePath}`));
+    process.exit(1);
+  }
+  fs.writeFileSync(filePath, content, 'utf8');
+  console.log(chalk.green(`  created  ${path.relative(process.cwd(), filePath)}`));
+}
+
+function generateRoute(routePath: string): void {
+  const cwd = process.cwd();
+  const filePath = path.join(cwd, 'src', 'api', `${routePath}.ts`);
+
+  const content = `import type { Request, Response } from 'express';
+
+export const GET = async (req: Request, res: Response) => {
+  res.json({ message: 'OK' });
+};
+
+export const POST = async (req: Request, res: Response) => {
+  res.status(201).json({ message: 'Created' });
+};
+`;
+
+  writeFile(filePath, content);
+  console.log(chalk.cyan(`[EFC] Route scaffolded`));
+}
+
+function generateTask(name: string): void {
+  const cwd = process.cwd();
+  const filePath = path.join(cwd, 'src', 'tasks', `${name}.ts`);
+
+  const content = `import { defineTask } from 'express-file-cluster/tasks';
+
+interface ${name}Payload {
+  // TODO: define payload fields
+}
+
+export default defineTask<${name}Payload>(async (payload) => {
+  // TODO: implement task logic
+  console.log('[Task:${name}]', payload);
+});
+`;
+
+  writeFile(filePath, content);
+  console.log(chalk.cyan(`[EFC] Task scaffolded`));
+}
+
+function generateMiddleware(name: string): void {
+  const cwd = process.cwd();
+  const filePath = path.join(cwd, 'src', 'middlewares', `${name}.ts`);
+
+  const content = `import type { Request, Response, NextFunction } from 'express';
+
+export function ${name}(req: Request, res: Response, next: NextFunction): void {
+  // TODO: implement middleware logic
+  next();
+}
+`;
+
+  writeFile(filePath, content);
+  console.log(chalk.cyan(`[EFC] Middleware scaffolded`));
+}

package/src/cli/commands/run.ts

@@ -0,0 +1,28 @@
+import { Command } from 'commander';
+import { spawn } from 'node:child_process';
+import chalk from 'chalk';
+
+export function runCommand(): Command {
+  const cmd = new Command('run');
+
+  cmd
+    .argument('<runner>', 'tests')
+    .description('Run EFC sub-commands (tests)')
+    .allowUnknownOption()
+    .action((runner: string) => {
+      if (runner === 'tests') {
+        runTests(cmd.args.slice(1));
+      } else {
+        console.error(chalk.red(`Unknown runner: ${runner}. Use 'tests'.`));
+        process.exit(1);
+      }
+    });
+
+  return cmd;
+}
+
+function runTests(extraArgs: string[]): void {
+  console.log(chalk.cyan('[EFC] Running tests via Vitest…'));
+  const child = spawn('npx', ['vitest', 'run', ...extraArgs], { stdio: 'inherit' });
+  child.on('exit', (code) => process.exit(code ?? 0));
+}