@expressots/core 3.0.0 → 4.0.0-preview.1

package/README.md

@@ -1,118 +1,66 @@
-<a name="readme-top"></a>
-
-<!-- PROJECT SHIELDS -->
-
-[![Codecov][codecov-shield]][codecov-url]
-[![NPM][npm-shield]][npm-url]
-![Build][build-shield]
-[![Contributors][contributors-shield]][contributors-url]
-[![Forks][forks-shield]][forks-url]
-[![Stargazers][stars-shield]][stars-url]
-[![Issues][issues-shield]][issues-url]
-[![MIT License][license-shield]][license-url]
-[![LinkedIn][linkedin-shield]][linkedin-url]
-
-<!-- PROJECT LOGO -->
-<br />
 <div align="center">
-  <a href="https://github.com/othneildrew/Best-README-Template">
-    <img src="https://github.com/expressots/expressots/blob/main/media/expressots.png" alt="Logo" width="120">
+  <a href="https://expresso-ts.com">
+    <img src="https://github.com/expressots/expressots/blob/main/media/expressots.png" alt="ExpressoTS" width="120">
   </a>
 
-  <h3 align="center">ExpressoTS Framework</h3>
-
-  <p align="center">
-    Everything you need to know to build applications with ExpressoTS
-    <br />
-    <a href="https://doc.expresso-ts.com/"><strong>Explore the docs »</strong></a>
-    <br />
-    <br />
-    <a href="https://github.com/expressots/expressots/discussions">Let's discuss</a>
-    ·
-    <a href="https://github.com/expressots/expressots/issues">Report Bug</a>
-    ·
-    <a href="https://github.com/expressots/expressots/issues">Request Feature</a>
+  <h1>@expressots/core</h1>
+
+  <p>A TypeScript framework for building server-side applications — fast to code, lean to run, simple to deploy.</p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/@expressots/core"><img src="https://img.shields.io/npm/v/@expressots/core?style=flat&color=0d0d0d" alt="npm"></a>
+    <a href="https://github.com/expressots/expressots/blob/main/LICENSE.md"><img src="https://img.shields.io/github/license/expressots/expressots?style=flat&color=0d0d0d" alt="License"></a>
+    <a href="https://discord.com/invite/PyPJfGK"><img src="https://img.shields.io/badge/Discord-join-0d0d0d?logo=discord&logoColor=white" alt="Discord"></a>
+  </p>
+
+  <p>
+    <a href="https://doc.expresso-ts.com">Documentation</a> ·
+    <a href="https://doc.expresso-ts.com/docs/core/first-steps">Getting Started</a> ·
+    <a href="https://discord.com/invite/PyPJfGK">Community</a>
   </p>
 </div>
 
-<!-- TABLE OF CONTENTS -->
-<details>
-  <summary>Table of Contents</summary>
-  <ol>
-    <li><a href="#about-the-project">About The Project</a></li>
-    <li><a href="#getting-started">Getting Started</a></li>
-    <li><a href="#contributing">Contributing</a></li>
-    <li><a href="#support-the-project">Support the project</a></li>
-    <li><a href="#license">License</a></li>
-  </ol>
-</details>
+---
 
-<!-- ABOUT THE PROJECT -->
+## Install
 
-# About The Project
+```bash
+npm i @expressots/core
+```
 
-ExpressoTS is a [Typescript](https://www.typescriptlang.org/) + [Node.js](https://nodejs.org/en/) lightweight framework for quick building scalable, easy to read and maintain, server-side applications 🐎
+## What This Package Does
 
-## Getting Started
+ExpressoTS Core is the foundation of the ExpressoTS framework. It provides dependency injection, routing, middleware orchestration, lifecycle hooks, interceptors, guards, error handling, and the application bootstrap — everything needed to structure and run a server-side TypeScript application with minimal boilerplate.
 
-- Here is our [Site](https://expresso-ts.com/)
-- You can find our [Documentation here](https://doc.expresso-ts.com/)
-- Checkout our [First Steps documentation](https://doc.expresso-ts.com/docs/overview/first-steps)
-- Our [CLI Documentation](https://doc.expresso-ts.com/docs/cli/overview)
+## Quick Look
 
-## Contributing
+```typescript
+// app.provider.ts
+import { AppFactory } from "@expressots/core";
+import { App } from "./app";
 
-Welcome to the ExpressoTS community, a place bustling with innovative minds just like yours. We're absolutely thrilled to have you here!
-ExpressoTS is more than just a TypeScript framework; it's a collective effort by developers who are passionate about creating a more efficient, secure, and robust web ecosystem. We firmly believe that the best ideas come from a diversity of perspectives, backgrounds, and skills.
+async function bootstrap() {
+  const app = await AppFactory.create(App);
+  await app.listen(3000, "development");
+}
 
-Why Contribute to Documentation?
+bootstrap();
+```
 
-- **Share Knowledge**: If you've figured out something cool, why keep it to yourself?
-- **Build Your Portfolio**: Contributing to an open-source project like ExpressoTS is a great way to showcase your skills.
-- **Join a Network**: Get to know a community of like-minded developers.
-- **Improve the Product**: Help us fill in the gaps, correct errors, or make complex topics easier to understand.
+## Documentation
 
-Ready to contribute?
+For guides, API reference, architecture patterns, and examples visit **[doc.expresso-ts.com](https://doc.expresso-ts.com)**.
 
-- [Contributing Guidelines](https://github.com/expressots/expressots/blob/main/CONTRIBUTING.md)
-- [How to Contribute](https://github.com/expressots/expressots/blob/main/CONTRIBUTING_HOWTO.md)
-- [Coding Guidelines](https://github.com/rsaz/TypescriptCodingGuidelines)
+## Contributing
 
-## Support the project
+See the [Contributing Guide](https://github.com/expressots/expressots/blob/main/CONTRIBUTING.md) for how to get involved.
 
-ExpressoTS is an independent open source project with ongoing development made possible thanks to your support. If you'd like to help, please consider:
+## Support
 
-- Become a **[sponsor on GitHub](https://github.com/sponsors/expressots)**
-- Follow the **[organization](https://github.com/expressots)** on GitHub and Star ⭐ the project
-- Subscribe to the Twitch channel: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)**
-- Join our **[Discord](https://discord.com/invite/PyPJfGK)**
-- Contribute submitting **[issues and pull requests](https://github.com/expressots/expressots/issues)**
-- Share the project with your friends and colleagues
+- [GitHub Sponsors](https://github.com/sponsors/expressots)
+- [Discord](https://discord.com/invite/PyPJfGK)
+- [Report an Issue](https://github.com/expressots/expressots/issues)
 
 ## License
 
-Distributed under the MIT License. See [`LICENSE.md`](https://github.com/expressots/expressots/blob/main/LICENSE.md) for more information.
-
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
-
-<!-- MARKDOWN LINKS & IMAGES -->
-<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
-
-[codecov-url]: https://codecov.io/gh/expressots/expressots
-[codecov-shield]: https://img.shields.io/codecov/c/gh/expressots/expressots/main?style=for-the-badge&logo=codecov&labelColor=FB9AD1
-[npm-url]: https://www.npmjs.com/package/@expressots/core
-[npm-shield]: https://img.shields.io/npm/v/%40expressots%2Fcore?style=for-the-badge&logo=npm&color=9B3922
-[build-shield]: https://img.shields.io/github/actions/workflow/status/expressots/expressots/build.yml?branch=main&style=for-the-badge&logo=github
-[contributors-shield]: https://img.shields.io/github/contributors/expressots/expressots?style=for-the-badge
-[contributors-url]: https://github.com/expressots/expressots/graphs/contributors
-[forks-shield]: https://img.shields.io/github/forks/expressots/expressots?style=for-the-badge
-[forks-url]: https://github.com/expressots/expressots/forks
-[stars-shield]: https://img.shields.io/github/stars/expressots/expressots?style=for-the-badge
-[stars-url]: https://github.com/expressots/expressots/stargazers
-[issues-shield]: https://img.shields.io/github/issues/expressots/expressots?style=for-the-badge
-[issues-url]: https://github.com/expressots/expressots/issues
-[license-shield]: https://img.shields.io/github/license/expressots/expressots?style=for-the-badge
-[license-url]: https://github.com/expressots/expressots/blob/main/LICENSE.md
-[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
-[linkedin-url]: https://www.linkedin.com/company/expresso-ts/
-[product-screenshot]: images/screenshot.png
+MIT — see [LICENSE](./LICENSE.md).

package/lib/CHANGELOG.md

@@ -1,3 +1,38 @@
+## [4.0.0](https://github.com/expressots/expressots/compare/3.0.0...4.0.0) (2026-05-12)
+
+Part of the ExpressoTS **v4.0.0 release bundle**. See the [v4.0.0 release notes](https://expresso-ts.com/docs/4.0.0/prologue/release) and the [upgrade guide](https://expresso-ts.com/docs/4.0.0/prologue/upgrade_guide) for the full picture.
+
+### Features
+
+* **interceptors:** new AOP system (`@Interceptor`, `IInterceptor`, `ExecutionContext`, `CallHandler`) with composition helpers `whenInterceptor`, `unlessInterceptor`, `pipeInterceptors`, `combineInterceptors`, and built-ins `LoggingInterceptor`, `PerformanceInterceptor`, `TimeoutInterceptor`. Companion `setupInterceptorsForExpress()` for one-line wiring.
+* **events:** type-safe event bus (`EventEmitter`, `@OnEvent`, `@OnEvents`, `@When`, `IEventHandler`) with auto-discovery, priority-based execution, `EventRecorder`, and `EventFlowTracker`. Companion `setupEventSystemForExpress()`.
+* **lazy loading:** `CreateLazyModule`, `withPreloadHint`, `withLazyConfig` and `setupLazyLoadingForExpress()` with `idle` / `immediate` / `manual` warmup strategies and zero-config route detection from `@controller()` decorators.
+* **configuration:** type-safe `defineConfig` + `Env.{string,number,boolean,enum,port,url,secret,array,json}` field builders with inline multi-environment defaults, `SecretValue` auto-redaction, helpful validation errors, and `when()` helper for environment-specific resolution.
+* **logging:** 11-phase production logger with `Logger.configure`, `withContext`, `child`, transports (`ConsoleTransport`, `FileTransport`, `HttpTransport`), redaction, suggestions, flow tracker, performance metrics, grouping, query/export API, and health monitor.
+* **content negotiation:** `@Accept`, `@Consumes`, `@Produces` decorators, built-in JSON / XML / CSV / YAML / Text formatters, `StreamResponse` for large payloads, quality-value support, custom formatter registration.
+* **authorization:** guard system with `@RequireAuthentication`, `@RequireRoles`, `@RequirePermissions`, built-in `AuthenticatedGuard` / `RoleGuard` / `PermissionGuard` / `ResourceOwnerGuard`, ABAC via `@RequirePolicy`, composition helpers `combineGuards` / `sequenceGuards` / `whenGuard`, permission hierarchy, multi-tenant support, request-scoped caching.
+* **middleware:** named registry (`getMiddlewareRegistry`, `use`, `compose`, `when`, `parallel`, `timeout`), preset API (`MIDDLEWARE_PRESETS`, `getPreset`, `createPreset`, `mergePresets`), `MiddlewareProfiler`, optional-package resolver.
+* **smart validation:** auto-detected `class-validator` integration with helpful errors and plugin support for Zod / Yup / Joi.
+* **error handling:** RFC 7807 compliant `AppError` with helpers (`badRequest`, `notFound`, `validationFailed`, etc.), auto-discovered exception filters via `@Catch`, route-level `@UseFilters`, and inherited filter matching.
+* **lifecycle hooks:** `IBootstrap`, `IShutdown`, `@postConstruct`, `@preDestroy` on DI-managed classes; `globalConfiguration`, `configureServices`, `postServerInitialization`, `serverShutdown` on `AppExpress`.
+* **DI scopes:** `Scope.Singleton` / `Transient` / `Request` plus custom scopes (`tenant`, `transaction`, `workflow`, `session`) via `provideInScope`.
+* **testing module:** `createTestApp`, `request` fluent API, `mockProvider`, `setupExpressoTSMatchers`, `expectStatus`, `expectBody` (with partial matching), snapshot testing, load testing, database fixtures.
+* **micro API:** new `micro()` fluent API for single-file apps and serverless deployments alongside the existing `createMicroAPI()` (kept for DI in a single file).
+* **route constraints + API versioning:** URL / header / query versioning, UUID / integer / pattern constraints with custom validators.
+
+### Breaking Changes
+
+* `.env` files are **opt-in** — `bootstrap()` now requires `envFileConfig` to load `.env`. Containerised deployments no longer trip "missing .env" alarms. See ADR-001.
+* `AppFactory.create()` replaced by `bootstrap()` from `@expressots/core`.
+* Node.js 20.18.0+ is now the minimum supported runtime.
+
+### Build System
+
+* dual ESM + CJS publication with subpath `exports` for both module systems.
+* migrated from Vitest to Jest 29.
+* embedded our customised DI implementation (replaces `inversify`).
+* embedded `reflect-metadata` so consumers don't have to install it explicitly.
+
 ## [3.0.0](https://github.com/expressots/expressots/compare/3.0.0-beta.3...3.0.0) (2024-12-04)
 
 ### Tests

package/lib/README.md

@@ -1,118 +1,66 @@
-<a name="readme-top"></a>
-
-<!-- PROJECT SHIELDS -->
-
-[![Codecov][codecov-shield]][codecov-url]
-[![NPM][npm-shield]][npm-url]
-![Build][build-shield]
-[![Contributors][contributors-shield]][contributors-url]
-[![Forks][forks-shield]][forks-url]
-[![Stargazers][stars-shield]][stars-url]
-[![Issues][issues-shield]][issues-url]
-[![MIT License][license-shield]][license-url]
-[![LinkedIn][linkedin-shield]][linkedin-url]
-
-<!-- PROJECT LOGO -->
-<br />
 <div align="center">
-  <a href="https://github.com/othneildrew/Best-README-Template">
-    <img src="https://github.com/expressots/expressots/blob/main/media/expressots.png" alt="Logo" width="120">
+  <a href="https://expresso-ts.com">
+    <img src="https://github.com/expressots/expressots/blob/main/media/expressots.png" alt="ExpressoTS" width="120">
   </a>
 
-  <h3 align="center">ExpressoTS Framework</h3>
-
-  <p align="center">
-    Everything you need to know to build applications with ExpressoTS
-    <br />
-    <a href="https://doc.expresso-ts.com/"><strong>Explore the docs »</strong></a>
-    <br />
-    <br />
-    <a href="https://github.com/expressots/expressots/discussions">Let's discuss</a>
-    ·
-    <a href="https://github.com/expressots/expressots/issues">Report Bug</a>
-    ·
-    <a href="https://github.com/expressots/expressots/issues">Request Feature</a>
+  <h1>@expressots/core</h1>
+
+  <p>A TypeScript framework for building server-side applications — fast to code, lean to run, simple to deploy.</p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/@expressots/core"><img src="https://img.shields.io/npm/v/@expressots/core?style=flat&color=0d0d0d" alt="npm"></a>
+    <a href="https://github.com/expressots/expressots/blob/main/LICENSE.md"><img src="https://img.shields.io/github/license/expressots/expressots?style=flat&color=0d0d0d" alt="License"></a>
+    <a href="https://discord.com/invite/PyPJfGK"><img src="https://img.shields.io/badge/Discord-join-0d0d0d?logo=discord&logoColor=white" alt="Discord"></a>
+  </p>
+
+  <p>
+    <a href="https://doc.expresso-ts.com">Documentation</a> ·
+    <a href="https://doc.expresso-ts.com/docs/core/first-steps">Getting Started</a> ·
+    <a href="https://discord.com/invite/PyPJfGK">Community</a>
   </p>
 </div>
 
-<!-- TABLE OF CONTENTS -->
-<details>
-  <summary>Table of Contents</summary>
-  <ol>
-    <li><a href="#about-the-project">About The Project</a></li>
-    <li><a href="#getting-started">Getting Started</a></li>
-    <li><a href="#contributing">Contributing</a></li>
-    <li><a href="#support-the-project">Support the project</a></li>
-    <li><a href="#license">License</a></li>
-  </ol>
-</details>
+---
 
-<!-- ABOUT THE PROJECT -->
+## Install
 
-# About The Project
+```bash
+npm i @expressots/core
+```
 
-ExpressoTS is a [Typescript](https://www.typescriptlang.org/) + [Node.js](https://nodejs.org/en/) lightweight framework for quick building scalable, easy to read and maintain, server-side applications 🐎
+## What This Package Does
 
-## Getting Started
+ExpressoTS Core is the foundation of the ExpressoTS framework. It provides dependency injection, routing, middleware orchestration, lifecycle hooks, interceptors, guards, error handling, and the application bootstrap — everything needed to structure and run a server-side TypeScript application with minimal boilerplate.
 
-- Here is our [Site](https://expresso-ts.com/)
-- You can find our [Documentation here](https://doc.expresso-ts.com/)
-- Checkout our [First Steps documentation](https://doc.expresso-ts.com/docs/overview/first-steps)
-- Our [CLI Documentation](https://doc.expresso-ts.com/docs/cli/overview)
+## Quick Look
 
-## Contributing
+```typescript
+// app.provider.ts
+import { AppFactory } from "@expressots/core";
+import { App } from "./app";
 
-Welcome to the ExpressoTS community, a place bustling with innovative minds just like yours. We're absolutely thrilled to have you here!
-ExpressoTS is more than just a TypeScript framework; it's a collective effort by developers who are passionate about creating a more efficient, secure, and robust web ecosystem. We firmly believe that the best ideas come from a diversity of perspectives, backgrounds, and skills.
+async function bootstrap() {
+  const app = await AppFactory.create(App);
+  await app.listen(3000, "development");
+}
 
-Why Contribute to Documentation?
+bootstrap();
+```
 
-- **Share Knowledge**: If you've figured out something cool, why keep it to yourself?
-- **Build Your Portfolio**: Contributing to an open-source project like ExpressoTS is a great way to showcase your skills.
-- **Join a Network**: Get to know a community of like-minded developers.
-- **Improve the Product**: Help us fill in the gaps, correct errors, or make complex topics easier to understand.
+## Documentation
 
-Ready to contribute?
+For guides, API reference, architecture patterns, and examples visit **[doc.expresso-ts.com](https://doc.expresso-ts.com)**.
 
-- [Contributing Guidelines](https://github.com/expressots/expressots/blob/main/CONTRIBUTING.md)
-- [How to Contribute](https://github.com/expressots/expressots/blob/main/CONTRIBUTING_HOWTO.md)
-- [Coding Guidelines](https://github.com/rsaz/TypescriptCodingGuidelines)
+## Contributing
 
-## Support the project
+See the [Contributing Guide](https://github.com/expressots/expressots/blob/main/CONTRIBUTING.md) for how to get involved.
 
-ExpressoTS is an independent open source project with ongoing development made possible thanks to your support. If you'd like to help, please consider:
+## Support
 
-- Become a **[sponsor on GitHub](https://github.com/sponsors/expressots)**
-- Follow the **[organization](https://github.com/expressots)** on GitHub and Star ⭐ the project
-- Subscribe to the Twitch channel: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)**
-- Join our **[Discord](https://discord.com/invite/PyPJfGK)**
-- Contribute submitting **[issues and pull requests](https://github.com/expressots/expressots/issues)**
-- Share the project with your friends and colleagues
+- [GitHub Sponsors](https://github.com/sponsors/expressots)
+- [Discord](https://discord.com/invite/PyPJfGK)
+- [Report an Issue](https://github.com/expressots/expressots/issues)
 
 ## License
 
-Distributed under the MIT License. See [`LICENSE.md`](https://github.com/expressots/expressots/blob/main/LICENSE.md) for more information.
-
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
-
-<!-- MARKDOWN LINKS & IMAGES -->
-<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
-
-[codecov-url]: https://codecov.io/gh/expressots/expressots
-[codecov-shield]: https://img.shields.io/codecov/c/gh/expressots/expressots/main?style=for-the-badge&logo=codecov&labelColor=FB9AD1
-[npm-url]: https://www.npmjs.com/package/@expressots/core
-[npm-shield]: https://img.shields.io/npm/v/%40expressots%2Fcore?style=for-the-badge&logo=npm&color=9B3922
-[build-shield]: https://img.shields.io/github/actions/workflow/status/expressots/expressots/build.yml?branch=main&style=for-the-badge&logo=github
-[contributors-shield]: https://img.shields.io/github/contributors/expressots/expressots?style=for-the-badge
-[contributors-url]: https://github.com/expressots/expressots/graphs/contributors
-[forks-shield]: https://img.shields.io/github/forks/expressots/expressots?style=for-the-badge
-[forks-url]: https://github.com/expressots/expressots/forks
-[stars-shield]: https://img.shields.io/github/stars/expressots/expressots?style=for-the-badge
-[stars-url]: https://github.com/expressots/expressots/stargazers
-[issues-shield]: https://img.shields.io/github/issues/expressots/expressots?style=for-the-badge
-[issues-url]: https://github.com/expressots/expressots/issues
-[license-shield]: https://img.shields.io/github/license/expressots/expressots?style=for-the-badge
-[license-url]: https://github.com/expressots/expressots/blob/main/LICENSE.md
-[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
-[linkedin-url]: https://www.linkedin.com/company/expresso-ts/
-[product-screenshot]: images/screenshot.png
+MIT — see [LICENSE](./LICENSE.md).