@syntay/fastay 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+import { Request as ExpressRequest, Response as ExpressResponse, NextFunction } from 'express';
+/**
+ * Request e Response do Express
+ * Podem ser usados nos handlers do usuário
+ */
+export type Request = ExpressRequest;
+export type Response = ExpressResponse;
+export type Next = NextFunction;

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/wrapMiddleware.d.ts

@@ -0,0 +1,6 @@
+import { Request, Response, NextFunction } from 'express';
+export type MiddlewareFn = (req: Request, res: Response, next: NextFunction) => any;
+/**
+ * Wrapper final
+ */
+export declare function wrapMiddleware(mw: MiddlewareFn): MiddlewareFn;

package/dist/utils/wrapMiddleware.js

@@ -0,0 +1,74 @@
+import { logger } from '../logger.js';
+const color = {
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    gray: (s) => `\x1b[90m${s}\x1b[0m`,
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    white: (s) => `\x1b[37m${s}\x1b[0m`,
+};
+/**
+ * Formata uma função para exibição bonitinha
+ */
+function formatFunction(fn) {
+    let code = fn.toString();
+    // deixa com quebras de linha
+    code = code.replace(/;/g, ';\n');
+    // tenta dar indentação
+    code = code
+        .replace(/{/g, '{\n  ')
+        .replace(/}/g, '\n}')
+        .replace(/\n\s*\n/g, '\n');
+    return code.trim();
+}
+/**
+ * Verifica se next() ou return existem
+ */
+function validateMiddlewareCode(mw) {
+    const raw = mw.toString();
+    const name = mw.name || 'anonymous';
+    const cleaned = raw
+        .replace(/\/\/.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\//gm, '');
+    const hasNext = /next\s*\(/.test(cleaned);
+    const hasReturn = /\breturn\b/.test(cleaned);
+    if (!hasNext && !hasReturn) {
+        const prettyCode = formatFunction(mw);
+        const message = [
+            `${color.red('⨯ Fastay Middleware Error')}`,
+            ``,
+            `The middleware ${color.yellow(`"${name}"`)} does not call next() or return any value.`,
+            `This will halt the middleware chain and block the request pipeline.`,
+            ``,
+            `▌ Middleware Source`,
+            color.gray(prettyCode),
+            ``,
+            `${color.cyan('▌ How to fix')}`,
+            `Ensure your middleware ends with either:`,
+            `  • ${color.green('next()')}`,
+            `  • ${color.green('return ...')}`,
+            ``,
+            `Fastay cannot continue until this middleware is fixed.`,
+        ].join('\n');
+        const err = new Error(message);
+        err.name = 'FastayMiddlewareError';
+        throw err;
+    }
+}
+/**
+ * Wrapper final
+ */
+export function wrapMiddleware(mw) {
+    const name = mw.name || 'anonymous';
+    validateMiddlewareCode(mw);
+    // retorna middleware "puro"
+    return async (req, res, next) => {
+        try {
+            await mw(req, res, next);
+        }
+        catch (err) {
+            logger.error(`[${name}] middleware error: ${err}`);
+            next(err);
+        }
+    };
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@syntay/fastay",
+  "version": "0.1.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "express": "^5.1.0",
+    "pino": "^10.1.0",
+    "pino-pretty": "^13.1.2"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.5",
+    "@types/node": "^20.19.25",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/app.ts

@@ -0,0 +1,233 @@
+import express from 'express';
+import path from 'path';
+import { loadApiRoutes } from './router.js';
+import {
+  MiddlewareMap,
+  loadFastayMiddlewares,
+  createMiddleware,
+} from './middleware.js';
+import { logger } from './logger.js';
+import { printBanner } from './banner.js';
+import type { ServeStaticOptions } from 'serve-static';
+import { Next, Request, Response } from './types/index.js';
+
+/**
+ * Express configuration options applied automatically by Fastay
+ * before internal middleware and route loading.
+ */
+export interface ExpressOptions {
+  /**
+   * Global middlewares applied to all routes.
+   * Example: [cors(), helmet()]
+   */
+  middlewares?: express.RequestHandler[];
+
+  /**
+   * Options passed to express.json().
+   * Useful for customizing JSON payload limits or behavior.
+   */
+  jsonOptions?: Parameters<typeof express.json>[0];
+
+  /**
+   * Options passed to express.urlencoded().
+   * Useful when handling form submissions or URL-encoded bodies.
+   */
+  urlencodedOptions?: Parameters<typeof express.urlencoded>[0];
+
+  /**
+   * Custom global error handler.
+   * If provided, Fastay will use this instead of the default one.
+   */
+  errorHandler?: express.ErrorRequestHandler;
+
+  /**
+   * Static file serving configuration.
+   * Example:
+   * {
+   *   path: "public",
+   *   options: { maxAge: "1d" }
+   * }
+   */
+  static?: {
+    path: string;
+    options?: ServeStaticOptions;
+  };
+
+  /**
+   * View engine configuration for Express.
+   * Example:
+   * {
+   *   engine: "pug",
+   *   dir: "views"
+   * }
+   */
+  views?: {
+    engine: string;
+    dir: string;
+  };
+
+  /**
+   * Enables or disables Express' "trust proxy" mode.
+   * Typically required when using reverse proxies (Nginx, Cloudflare, etc.).
+   */
+  trustProxy?: boolean;
+
+  /**
+   * Local variables available to all templates and responses.
+   * Fastay automatically injects them into `response.locals`.
+   */
+  locals?: Record<string, any>;
+}
+
+/**
+ * Options applied when creating a Fastay.js application.
+ */
+export type CreateAppOptions = {
+  /**
+   * Directory where API route modules are located.
+   * Default: "src/api"
+   */
+  apiDir?: string;
+
+  /**
+   * Base route where all API routes will be mounted.
+   * Default: "/api"
+   */
+  baseRoute?: string;
+
+  /**
+   * Port on which `.listen()` will run the server.
+   * Default: 3000
+   */
+  port?: number;
+
+  /**
+   * Express-level configuration such as middleware, body parsers,
+   * view engine, static assets, error handler, etc.
+   */
+  expressOptions?: ExpressOptions;
+
+  /**
+   * Internal Fastay middlewares applied after Express initialization
+   * but before route mounting.
+   */
+  middlewares?: MiddlewareMap;
+};
+
+/**
+ * Bootstraps and configures a Fastay application.
+ *
+ * Fastay automatically:
+ * - Discovers and registers routes defined in `apiDir`.
+ * - Applies both built-in and user-provided middlewares.
+ * - Exposes a health-check endpoint at `/_health`.
+ *
+ * @param opts - Configuration options for the Fastay application.
+ * @returns A Promise that resolves to an Express `Application` instance.
+ *
+ * @example
+ * ```ts
+ * import { createApp } from '@syntay/fastay';
+ * import cors from 'cors';
+ * import helmet from 'helmet';
+ *
+ * void (async () => {
+ *   await createApp({
+ *     apiDir: './src/api',
+ *     baseRoute: '/api',
+ *     port: 5555,
+ *     expressOptions: {
+ *       middlewares: [cors(), helmet()],
+ *     },
+ *   });
+ * })();
+ * ```
+ */
+export async function createApp(opts?: CreateAppOptions) {
+  const start = logger.timeStart();
+
+  printBanner();
+
+  // logger.group('Fastay');
+  logger.info('Initializing server...');
+
+  const apiDir = opts?.apiDir ?? path.resolve(process.cwd(), 'src', 'api');
+  const baseRoute = opts?.baseRoute ?? '/api';
+
+  logger.success(`API directory: ${apiDir}`);
+  logger.success(`Base route: ${baseRoute}`);
+
+  const app = express();
+
+  if (opts?.expressOptions) {
+    for (const [key, value] of Object.entries(opts.expressOptions)) {
+      // Se for array → assume middleware global
+      if (Array.isArray(value)) {
+        value.forEach((mw) => app.use(mw));
+      }
+      // Se o app tiver método com esse nome
+      else if (typeof (app as any)[key] === 'function') {
+        // TS-safe
+        ((app as any)[key] as Function)(value);
+      }
+      // special cases
+      else if (key === 'static' && value && typeof value === 'object') {
+        const v = value as { path: string; options?: any };
+        app.use(express.static(v.path, v.options));
+      } else if (key === 'jsonOptions') {
+        app.use(express.json(value as any));
+      } else if (key === 'urlencodedOptions') {
+        app.use(express.urlencoded(value as any));
+      }
+    }
+  }
+
+  app.use(express.json());
+
+  const defaltPort = opts?.port ? opts.port : 6000;
+
+  app.listen(defaltPort, () => {
+    logger.success(
+      `Server running at http://localhost:${defaltPort}${baseRoute}`
+    );
+  });
+
+  // external middlewares
+  if (opts?.expressOptions?.middlewares) {
+    logger.group('Express Middlewares');
+    for (const mw of opts.expressOptions.middlewares) {
+      logger.gear(`Loaded: ${mw.name || 'anonymous'}`);
+      app.use(mw);
+    }
+  }
+
+  // Fastay middlewares
+  if (opts?.middlewares) {
+    logger.group('Fastay Middlewares');
+    const apply = createMiddleware(opts.middlewares);
+    apply(app);
+  }
+
+  // automatic middlewares
+  // logger.group('Fastay Auto-Middlewares');
+  const isMiddleware = await loadFastayMiddlewares(app);
+
+  // health check
+  app.get('/_health', (_, res) => res.json({ ok: true }));
+  app.use((_req: Request, res: Response, next: Next) => {
+    res.setHeader('X-Powered-By', 'Syntay Engine');
+    next();
+  });
+
+  // load routes
+  // logger.group('Routes Loaded');
+  const totalRoutes = await loadApiRoutes(app, baseRoute, apiDir);
+  logger.success(`Total routes loaded: ${totalRoutes}`);
+
+  // app.use(errorHandler);
+
+  const time = logger.timeEnd(start);
+  logger.success(`Boot completed in ${time}ms`);
+
+  return app;
+}

package/src/banner.ts

@@ -0,0 +1,11 @@
+import { logger } from './logger.js';
+
+export function printBanner() {
+  const cyan = (s: string) => `\x1b[36m${s}\x1b[0m`;
+  const white = (s: string) => `\x1b[37m${s}\x1b[0m`;
+
+  logger.raw('');
+  logger.raw(`${cyan('⥨ Fastay.js')} ${white('1.0.0')}`);
+  logger.raw(`  ${white('- Runtime: Node.js\n')}`);
+  // logger.raw('\n');
+}

package/src/error-handler.ts

@@ -0,0 +1,48 @@
+import { Request, Response, NextFunction } from 'express';
+import { logger } from './logger';
+import fs from 'fs';
+
+export function errorHandler(
+  err: any,
+  req: Request,
+  res: Response,
+  next: NextFunction
+) {
+  const isSyntaxError =
+    err.name === 'SyntaxError' || err.message?.includes('Unexpected');
+  const route = `${req.method} ${req.originalUrl}`;
+
+  // Tenta extrair arquivo, linha e coluna (quando stack estiver presente)
+  let fileInfo = '';
+  if (err.stack) {
+    const stackLine = err.stack.split('\n')[1]; // pega primeira linha depois do erro
+    const match = stackLine.match(/\((.*):(\d+):(\d+)\)/);
+    if (match) {
+      const [_, file, line, col] = match;
+      fileInfo = `${file}:${line}:${col}`;
+
+      // Tenta mostrar o trecho da linha que deu erro
+      if (fs.existsSync(file)) {
+        const codeLines = fs.readFileSync(file, 'utf-8').split('\n');
+        const codeSnippet = codeLines[parseInt(line) - 1].trim();
+        fileInfo += ` → ${codeSnippet}`;
+      }
+    }
+  }
+
+  logger.group(`✗ Runtime Error in route [${route}]`);
+  logger.error(`${err.name}: ${err.message}`);
+  if (fileInfo) logger.error(`Location: ${fileInfo}`);
+
+  if (process.env.NODE_ENV === 'production') {
+    return res.status(500).json({
+      error: 'Internal server error',
+    });
+  }
+
+  return res.status(500).json({
+    error: err.message,
+    stack: err.stack,
+    file: fileInfo || undefined,
+  });
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { createApp } from './app.js';
+export { createMiddleware } from './middleware.js';
+export type { CreateAppOptions } from './app.js';
+export { Request, Response, Next } from './types';

package/src/logger.ts

@@ -0,0 +1,78 @@
+import pino, { LogDescriptor } from 'pino';
+import pretty, { PrettyOptions } from 'pino-pretty';
+
+// stream configurado para remover INFO:, timestamps e etc
+const stream = pretty({
+  colorize: true,
+  ignore: 'pid,hostname,time,level',
+  levelFirst: false,
+
+  // Remove "INFO: " antes da msg
+  messageKey: 'msg',
+
+  // Maneira correta TS-safe
+  messageFormat: (log: LogDescriptor, messageKey: string) => {
+    const msg = log[messageKey];
+    return typeof msg === 'string' ? msg : String(msg);
+  },
+} as PrettyOptions);
+
+const base = pino(
+  {
+    level: 'info',
+    timestamp: false, // remove [HH:mm:ss]
+    base: undefined, // remove pid, hostname
+  },
+  stream
+);
+
+// helpers para cores ANSI
+const colors = {
+  white: (s: string) => `\x1b[37m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
+  gray: (s: string) => `\x1b[90m${s}\x1b[0m`,
+};
+
+// emojis Fastay
+const ICONS = {
+  info: '○',
+  success: '✓',
+  error: '✗',
+  gear: '⚙️',
+};
+
+export const logger = {
+  info: (msg: string) =>
+    base.info(` ${colors.white(ICONS.info)} ${colors.white(msg)}`),
+  warn: (msg: string) => base.info(` ${colors.red('⚠')} ${colors.white(msg)}`),
+  error: (msg: string) =>
+    base.info(` ${colors.red(ICONS.error)} ${colors.white(msg)}`),
+  success: (msg: string) =>
+    base.info(` ${colors.green(ICONS.success)} ${colors.white(msg)}`),
+  gear: (msg: string) => base.info(` ${ICONS.gear}  ${colors.white(msg)}`),
+
+  space(lines: number = 1) {
+    for (let i = 0; i < lines; i++) base.info(' ');
+  },
+
+  group(title: string) {
+    this.space();
+    base.info('');
+    base.info(colors.cyan(title));
+    // this.space();
+  },
+
+  raw(msg: string) {
+    base.info(msg);
+  },
+
+  timeStart() {
+    return performance.now();
+  },
+
+  timeEnd(start: number) {
+    return (performance.now() - start).toFixed(1);
+  },
+};

package/src/middleware.ts

@@ -0,0 +1,107 @@
+import { Application, Request, Response, NextFunction } from 'express';
+import path from 'path';
+import fs from 'fs';
+import { pathToFileURL } from 'url';
+import { logger } from './logger.js';
+import { wrapMiddleware } from './utils/wrapMiddleware.js';
+
+type MiddlewareFn = (req: Request, res: Response, next: NextFunction) => any;
+
+/**
+ * Defines a map of routes and the middleware functions that Fastay
+ * will automatically load and attach during boot.
+ *
+ * Keys represent route prefixes (e.g. `/auth`, `/admin`), and
+ * values are arrays of Fastay middleware functions.
+ *
+ * Middleware functions use Fastay’s extended `Request`, `Response`,
+ * and `Next` types — not the raw Express versions.
+ *
+ * @example
+ * ```ts
+ * // src/middleware.ts
+ * import { createMiddleware } from '@syntay/fastay';
+ * import { authMiddleware } from './auth';
+ * import { auditLogger } from './audit';
+ *
+ * export const middleware = createMiddleware({
+ *   '/auth': [authMiddleware],
+ *   '/admin': [auditLogger]
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // src/auth.ts
+ * import { Request, Response, Next } from '@syntay/fastay';
+ *
+ * export async function authMiddleware(req: Request, _res: Response, next: Next) {
+ *   // Custom logic using extended Fastay types
+ *   req.user = { id: 1, role: "admin" };
+ *   next();
+ * }
+ * ```
+ */
+export type MiddlewareMap = Record<string, MiddlewareFn[]>;
+
+/**
+ * Creates a Fastay middleware loader.
+ *
+ * Fastay uses this internally to attach user-defined middleware to the
+ * Express application during boot. The framework automatically discovers
+ * and loads any `middleware` exported from the project's `src/` directory.
+ *
+ * Middleware functions are wrapped so both synchronous and asynchronous
+ * handlers behave consistently.
+ *
+ * @param map - A map of route prefixes and the middleware stack for each route.
+ * @returns A function that Fastay will call to register the mapped middleware.
+ *
+ * @example
+ * ```ts
+ * export const middleware = createMiddleware({
+ *   '/auth': [authMiddleware],
+ *   '/admin': [adminGuard, auditLogger]
+ * });
+ * ```
+ */
+export function createMiddleware(map: Record<string, MiddlewareFn[]>) {
+  return (app: Application) => {
+    for (const [route, middlewares] of Object.entries(map)) {
+      for (const mw of middlewares) {
+        const wrapped = wrapMiddleware(mw);
+
+        app.use(route, wrapped);
+      }
+    }
+  };
+}
+
+export async function loadFastayMiddlewares(app: Application) {
+  const isDev = process.env.NODE_ENV !== 'production';
+  const mwDir = path.resolve(
+    process.cwd(),
+    isDev ? 'src/middlewares' : 'dist/middlewares'
+  );
+
+  const file = path.join(mwDir, isDev ? 'middleware.ts' : 'middleware.js');
+  if (!fs.existsSync(file)) return;
+
+  const mod = await import(pathToFileURL(file).href);
+
+  if (!mod.middleware) return;
+
+  logger.group('Fastay Auto-Middlewares');
+
+  if (typeof mod.middleware === 'function') {
+    mod.middleware(app);
+    logger.info('Loading Fastay core middleware...');
+  } else {
+    const map = mod.middleware as Record<string, any[]>;
+    for (const [route, middlewares] of Object.entries(map)) {
+      for (const mw of middlewares) {
+        app.use(route, mw);
+      }
+    }
+  }
+}