@navios/core 1.0.0-alpha.4 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,59 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-01-15
+
+### Added
+
+- **Staged Plugin System**: New comprehensive plugin lifecycle with 10 stages for fine-grained control over application initialization
+  - `pre:modules-traverse` - Before module tree traversal (container only)
+  - `post:modules-traverse` - After module tree traversal (modules available)
+  - `pre:adapter-resolve` - Before adapter is resolved from container (ideal for DI modifications)
+  - `post:adapter-resolve` - After adapter is resolved
+  - `pre:adapter-setup` - Before adapter setup
+  - `post:adapter-setup` - After adapter setup
+  - `pre:modules-init` - Before route registration
+  - `post:modules-init` - After route registration (legacy plugin default)
+  - `pre:ready` - Before adapter signals ready
+  - `post:ready` - After adapter signals ready (app fully initialized)
+- **Stage-Specific Context Types**: Each stage provides appropriate context
+  - `ContainerOnlyContext` - Container access only (early stages)
+  - `ModulesLoadedContext` - Container + modules + moduleLoader (pre-adapter stages)
+  - `FullPluginContext<TAdapter>` - Full context with typed adapter (post-adapter stages)
+- **Plugin Factory Functions**: Convenient factory functions for creating staged plugins
+  - `definePreModulesTraversePlugin()` - Create pre:modules-traverse plugins
+  - `definePostModulesTraversePlugin()` - Create post:modules-traverse plugins
+  - `definePreAdapterResolvePlugin()` - Create pre:adapter-resolve plugins (ideal for instrumentation)
+  - `definePostAdapterResolvePlugin<TAdapter>()()` - Create post:adapter-resolve plugins
+  - `definePreAdapterSetupPlugin<TAdapter>()()` - Create pre:adapter-setup plugins
+  - `definePostAdapterSetupPlugin<TAdapter>()()` - Create post:adapter-setup plugins
+  - `definePreModulesInitPlugin<TAdapter>()()` - Create pre:modules-init plugins
+  - `definePostModulesInitPlugin<TAdapter>()()` - Create post:modules-init plugins
+  - `definePreReadyPlugin<TAdapter>()()` - Create pre:ready plugins
+  - `definePostReadyPlugin<TAdapter>()()` - Create post:ready plugins
+- **Plugin Stage Constants**: `PluginStages` object with all stage names as constants
+- **Stage Order Array**: `PLUGIN_STAGES_ORDER` array defining execution order
+
+### Changed
+
+- **Legacy Plugin Deprecation**: `NaviosPlugin` interface now deprecated in favor of staged plugins
+  - Legacy plugins automatically map to `post:modules-init` stage
+  - `PluginDefinition` type deprecated in favor of `StagedPluginDefinition`
+- **Plugin Context Types**: `PluginContext` type deprecated, use stage-specific context types instead
+
+### Dependencies
+
+- Updated internal plugin execution to support staged lifecycle
+
+## [1.0.0] - 2026-01-09
+
+### Added
+
+- **Stable Release**: First stable release of @navios/core
+  - Production-ready framework for building type-safe HTTP servers
+  - Comprehensive feature set with unified adapter architecture
+  - Full TypeScript support with end-to-end type safety
+
 ## [1.0.0-alpha.4] - 2026-01-09
 
 ### Added

package/README.md

@@ -169,14 +169,14 @@ Create your first Controller:
 ```ts
 import type { EndpointParams } from '@navios/core'
 
-import { Controller, Endpoint, syncInject } from '@navios/core'
+import { Controller, Endpoint, inject } from '@navios/core'
 
 import { AuthService } from './auth.service.mjs'
 
 @Controller()
 export class AuthController {
   // Inject the LoginService
-  loginService = syncInject(LoginService)
+  loginService = inject(LoginService)
 
   @Endpoint(login)
   async login(request: EndpointParams<typeof login>) {

package/docs/legacy-compat.md

@@ -21,7 +21,16 @@ No additional installation is required. The legacy-compat decorators are include
 To use legacy-compatible decorators, import them from the `legacy-compat` subpath:
 
 ```typescript
-import { Module, Controller, Endpoint, UseGuards, Header, HttpCode, Multipart, Stream } from '@navios/core/legacy-compat'
+import {
+  Controller,
+  Endpoint,
+  Header,
+  HttpCode,
+  Module,
+  Multipart,
+  Stream,
+  UseGuards,
+} from '@navios/core/legacy-compat'
 ```
 
 ## Available Decorators
@@ -65,12 +74,16 @@ export class UserController {
 Defines an HTTP endpoint with type-safe request/response schemas. Must be applied to methods.
 
 ```typescript
-import { Controller, Endpoint, type EndpointParams, type EndpointResult } from '@navios/core/legacy-compat'
+import type { EndpointParams, EndpointResult } from '@navios/core/legacy-compat'
+
+import { Controller, Endpoint } from '@navios/core/legacy-compat'
 
 @Controller()
 export class UserController {
   @Endpoint(getUserEndpoint)
-  async getUser(request: EndpointParams<typeof getUserEndpoint>): Promise<EndpointResult<typeof getUserEndpoint>> {
+  async getUser(
+    request: EndpointParams<typeof getUserEndpoint>,
+  ): Promise<EndpointResult<typeof getUserEndpoint>> {
     const { id } = request
     return { id, name: 'John Doe' }
   }
@@ -82,12 +95,19 @@ export class UserController {
 Defines a multipart/form-data endpoint for file uploads. Must be applied to methods.
 
 ```typescript
-import { Controller, Multipart, type MultipartParams, type MultipartResult } from '@navios/core/legacy-compat'
+import type {
+  MultipartParams,
+  MultipartResult,
+} from '@navios/core/legacy-compat'
+
+import { Controller, Multipart } from '@navios/core/legacy-compat'
 
 @Controller()
 export class FileController {
   @Multipart(uploadFileEndpoint)
-  async uploadFile(request: MultipartParams<typeof uploadFileEndpoint>): Promise<MultipartResult<typeof uploadFileEndpoint>> {
+  async uploadFile(
+    request: MultipartParams<typeof uploadFileEndpoint>,
+  ): Promise<MultipartResult<typeof uploadFileEndpoint>> {
     const { file } = request.data
     return { url: 'https://example.com/file.jpg' }
   }
@@ -99,12 +119,17 @@ export class FileController {
 Defines a streaming endpoint. Must be applied to methods.
 
 ```typescript
-import { Controller, Stream, type StreamParams } from '@navios/core/legacy-compat'
+import type { StreamParams } from '@navios/core/legacy-compat'
+
+import { Controller, Stream } from '@navios/core/legacy-compat'
 
 @Controller()
 export class FileController {
   @Stream(downloadFileEndpoint)
-  async downloadFile(request: StreamParams<typeof downloadFileEndpoint>, reply: any): Promise<void> {
+  async downloadFile(
+    request: StreamParams<typeof downloadFileEndpoint>,
+    reply: any,
+  ): Promise<void> {
     const { fileId } = request.urlParams
     // Stream file data to reply
   }
@@ -176,10 +201,10 @@ The legacy-compat module also exports type utilities for working with endpoints:
 
 ```typescript
 import type {
-  ModuleOptions,
   ControllerOptions,
   EndpointParams,
   EndpointResult,
+  ModuleOptions,
   MultipartParams,
   MultipartResult,
   StreamParams,
@@ -191,9 +216,18 @@ import type {
 Here's a complete example using legacy-compatible decorators:
 
 ```typescript
+import type { EndpointParams, EndpointResult } from '@navios/core/legacy-compat'
+
 import { builder } from '@navios/builder'
-import { Module, Controller, Endpoint, UseGuards, HttpCode, type EndpointParams, type EndpointResult } from '@navios/core/legacy-compat'
-import { Injectable, syncInject } from '@navios/core'
+import { inject, Injectable } from '@navios/core'
+import {
+  Controller,
+  Endpoint,
+  HttpCode,
+  Module,
+  UseGuards,
+} from '@navios/core/legacy-compat'
+
 import { z } from 'zod/v4'
 
 // Define API endpoints
@@ -239,17 +273,21 @@ export class UserService {
 @Controller()
 @UseGuards(AuthGuard)
 export class UserController {
-  userService = syncInject(UserService)
+  userService = inject(UserService)
 
   @Endpoint(getUserEndpoint)
-  async getUser(request: EndpointParams<typeof getUserEndpoint>): Promise<EndpointResult<typeof getUserEndpoint>> {
+  async getUser(
+    request: EndpointParams<typeof getUserEndpoint>,
+  ): Promise<EndpointResult<typeof getUserEndpoint>> {
     const { id } = request.urlParams
     return await this.userService.findById(id)
   }
 
   @Endpoint(createUserEndpoint)
   @HttpCode(201)
-  async createUser(request: EndpointParams<typeof createUserEndpoint>): Promise<EndpointResult<typeof createUserEndpoint>> {
+  async createUser(
+    request: EndpointParams<typeof createUserEndpoint>,
+  ): Promise<EndpointResult<typeof createUserEndpoint>> {
     const { name, email } = request.body
     return await this.userService.create({ name, email })
   }
@@ -270,10 +308,9 @@ If you're migrating from standard decorators to legacy-compatible decorators:
 
 ```typescript
 // Before
-import { Module, Controller, Endpoint } from '@navios/core'
-
+import { Controller, Endpoint, Module } from '@navios/core'
 // After
-import { Module, Controller, Endpoint } from '@navios/core/legacy-compat'
+import { Controller, Endpoint, Module } from '@navios/core/legacy-compat'
 ```
 
 2. Ensure your `tsconfig.json` has `experimentalDecorators` enabled:
@@ -317,4 +354,3 @@ The `emitDecoratorMetadata` option is optional but recommended for better runtim
 - Legacy-compatible decorators are fully compatible with all Navios features including guards, attributes, dependency injection, and adapters
 - You can mix legacy-compatible decorators with standard decorators in the same project, but it's recommended to use one approach consistently
 - The legacy-compat module is maintained alongside the standard decorators and receives the same updates and bug fixes
-

package/docs/quick-start.md

@@ -117,19 +117,14 @@ Create a user controller (`controllers/user.controller.ts`):
 ```ts
 import type { EndpointParams } from '@navios/core'
 
-import {
-  Controller,
-  Endpoint,
-  NotFoundException,
-  syncInject,
-} from '@navios/core'
+import { Controller, Endpoint, inject, NotFoundException } from '@navios/core'
 
 import { createUserEndpoint, getUserEndpoint } from '../api/index.js'
 import { UserService } from '../services/user.service.js'
 
 @Controller()
 export class UserController {
-  private userService = syncInject(UserService)
+  private userService = inject(UserService)
 
   @Endpoint(createUserEndpoint)
   async createUser(request: EndpointParams<typeof createUserEndpoint>) {