@solid-stack/agnos-express

Express presentation adapter for the Agnos clean application architecture framework.

✨ Features

• ⚡ Seamless Agnos Integration: Implements the IPresentation lifecycle interface (init, run, stop).
• 🧩 Dependency Injection: Fully integrated with @solid-stack/di using ValueToken and MultiToken patterns.
• 🚀 Auto-Discovery: Automatic feature route discovery from pxExpress directories and global middleware loading.
• 🛡️ Clean Encapsulation: Minimal public API surface — all internals are abstracted.
• 📦 Dual ESM & CommonJS Output: Bundled via tsup with complete TypeScript type declarations.

📦 Installation

pnpm add @solid-stack/agnos-express @solid-stack/agnos @solid-stack/di express

🚀 Quick Start

1. Define a Route

Create a route handler extending ExpressRoute:

import { ExpressRoute } from "@solid-stack/agnos-express";
import type { Request, Response } from "express";

export default class GetUsersRoute extends ExpressRoute {
  method = "get" as const;
  path = "/";

  handler = async (req: Request, res: Response) => {
    res.json({ users: [{ id: 1, name: "Alice" }] });
  };
}

2. Bootstrap Application

import { Container } from "@solid-stack/di";
import { start } from "@solid-stack/agnos";
import { loadExpressPresentation } from "@solid-stack/agnos-express";

async function main() {
  const container = new Container();

  // Load Express presentation layer with optional lifecycle hooks
  await loadExpressPresentation(container, {
    port: 3000,
    featuresDir: "./src/features",
    mainDir: "./src/presentation",
    onBeforeMiddlewares: (app) => {
      // Direct access to Express app before global middlewares load
    },
    onAfterRouters: (app) => {
      // Direct access to Express app after feature routers load
    },
  });

  // Start Agnos application lifecycle
  await start(container, {
    featuresDir: "./src/features",
  });
}

main().catch(console.error);

📁 Directory Architecture

my-app/
├── src/
│   ├── features/
│   │   └── users/
│   │       ├── pxExpress/
│   │       │   ├── index.ts          # export const path = '/users';
│   │       │   └── handlers/
│   │       │       └── getUsers.ts   # export default class GetUsersRoute extends ExpressRoute
│   │       └── DepsProvider.ts
│   └── presentation/
│       └── index.ts                  # export const middlewares = [...]; export const errorHandlers = [...];

🛠️ Available Scripts

| Command | Description | | --- | --- | | pnpm dev | Starts tsup in watch mode for development | | pnpm build | Bundles ESM/CJS outputs and generates TypeScript type declarations | | pnpm test | Runs tests using Vitest | | pnpm test:watch | Runs Vitest in interactive watch mode | | pnpm test:coverage | Runs tests with code coverage reporting | | pnpm typecheck | Typechecks the project using TypeScript (tsc --noEmit) | | pnpm check | Runs typecheck, tests, and build in sequence |

📄 License

MIT © Solid Stack Digital