@solid-stack/agnos

An agnostic, type-safe clean architecture application framework for TypeScript, powered by @solid-stack/di.

✨ Features

• 🏗️ Presentation-Agnostic Core: Decouple your business logic from presentation layers (CLI, HTTP, Next.js, WebSockets, background workers) via IPresentation and Program.
• 💉 Integrated Type-Safe DI: Seamless integration with @solid-stack/di supporting Stage 3 decorators (@MakeInjectable), multi-tokens, and compile-time dependency validation.
• 🪵 Pluggable Logging: Extensible logging subsystem using ILoggerTransport and LoggerTransportsToken multi-tokens with error isolation and SilentLogger support.
• 🎯 Standardized Use Cases: Clean UseCase<IRequest, IResponse> contracts for domain logic.
• 🛡️ Structured Error Hierarchy: Rich, domain- and lifecycle-tailored error types with HTTP status codes, machine-readable error codes, metadata context, and formatting (AgnosError, AppError, BootstrapError, FeatureLoadError, PresentationError, InputParsingError, InternalError, NotFoundError, ResourceConflictError, InvalidDependencyError, MissingDependencyError).
• ⚡ Dual ESM + CJS Output: Bundled via tsup with tree-shaking, sourcemaps, and full .d.ts declarations.

📦 Installation

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

🚀 Quick Start

1. Define Domain Use Case and Presentation

import { Container, MakeInjectable, type DepsType } from "@solid-stack/di";
import {
  IPresentation,
  ILogger,
  ILoggerTransport,
  LoggerTransportsToken,
  UseCase,
  start,
  type LogLevel,
} from "@solid-stack/agnos";

// 1. Define a Logger Transport
@MakeInjectable
class ConsoleTransport extends ILoggerTransport {
  public static deps = {};
  constructor(public deps: DepsType<typeof ConsoleTransport.deps>) {
    super();
  }

  push = (message: any[], level: LogLevel) => {
    console.log(`[${level.toUpperCase()}]`, ...message);
  };
}

// 2. Define a Use Case
interface GreetRequest {
  name: string;
}

interface GreetResponse {
  greeting: string;
}

@MakeInjectable
class GreetUseCase extends UseCase<GreetRequest, GreetResponse> {
  public static deps = {
    logger: ILogger,
  };

  constructor(public deps: DepsType<typeof GreetUseCase.deps>) {
    super();
  }

  async execute(request: GreetRequest): Promise<GreetResponse> {
    this.deps.logger.info(`Greeting user: ${request.name}`);
    return { greeting: `Hello, ${request.name}!` };
  }
}

// 3. Define Presentation Layer
@MakeInjectable
class AppPresentation extends IPresentation {
  public static deps = {
    greetUseCase: GreetUseCase,
    logger: ILogger,
  };

  constructor(public deps: DepsType<typeof AppPresentation.deps>) {
    super();
  }

  async init(): Promise<void> {
    this.deps.logger.info("Initializing presentation layer...");
  }

  async run(): Promise<void> {
    const res = await this.deps.greetUseCase.execute({ name: "Solid Stack Developer" });
    console.log(res.greeting);
  }

  async stop(): Promise<void> {
    this.deps.logger.info("Stopping presentation layer...");
  }
}

// 4. Bootstrap and Start Application
async function main() {
  const container = new Container();

  // Register logger transport and presentation
  container.provideMulti(LoggerTransportsToken, ConsoleTransport);
  container.provide(IPresentation, AppPresentation);

  // Start the application lifecycle (automatically loads infra and runs the presentation)
  await start(container);
}

main().catch(console.error);

🛠️ 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 | | pnpm prepublishOnly | Automatically runs tests, build, and dist validation before publishing |

🐳 Docker / Make Commands

make dev     # Start dev watcher container
make test    # Run test suite in container
make build   # Build package in container
make prod    # Verify production container
make clean   # Clean up containers and volumes

📄 License

MIT © Solid Stack Digital