@navios/adapter-xml 0.1.0 → 0.7.0

package/src/adapters/xml-stream-adapter.service.mts

@@ -1,33 +1,74 @@
 import type {
   AbstractHttpHandlerAdapterInterface,
+  ClassType,
   HandlerMetadata,
+  ScopedContainer,
 } from '@navios/core'
-import type { ClassType, RequestContextHolder } from '@navios/di'
 
-import { StreamAdapterToken, XmlStreamAdapterToken } from '@navios/core'
-import { Container, inject, Injectable } from '@navios/di'
+import {
+  inject,
+  Injectable,
+  StreamAdapterToken,
+  XmlStreamAdapterToken,
+} from '@navios/core'
 
 import type { BaseXmlStreamConfig } from '../types/config.mjs'
 import type { AnyXmlNode } from '../types/xml-node.mjs'
 
 import { renderToXml } from '../runtime/render-to-xml.mjs'
 
+/**
+ * Adapter service for handling XML Stream endpoints in Navios.
+ *
+ * This service integrates with the base stream adapter (Fastify or Bun) to handle
+ * XML endpoints that return JSX-based XML responses. It automatically renders JSX
+ * nodes to XML strings and sends them with the appropriate Content-Type headers.
+ *
+ * The service supports:
+ * - Async components (resolved in parallel)
+ * - Class components (resolved via DI container)
+ * - Regular JSX elements
+ * - CDATA sections
+ * - Raw XML content
+ *
+ * @implements {AbstractHttpHandlerAdapterInterface}
+ *
+ * @example
+ * ```ts
+ * // This service is automatically registered when using defineXmlEnvironment()
+ * // and is used by endpoints decorated with @XmlStream()
+ * ```
+ */
 @Injectable({
   token: XmlStreamAdapterToken,
 })
 export class XmlStreamAdapterService implements AbstractHttpHandlerAdapterInterface {
-  protected container = inject(Container)
   /** Base stream adapter - we proxy hasSchema, prepareArguments, provideSchema to it */
   protected streamAdapter = inject(StreamAdapterToken)
 
   /**
-   * Proxy to base StreamAdapter - reuses existing argument preparation logic
-   * (handles querySchema, requestSchema, URL params for both Fastify and Bun)
+   * Prepares argument getters for parsing request data.
+   *
+   * Proxies to the base stream adapter to reuse existing argument preparation logic
+   * that handles query parameters, request body, and URL parameters for both
+   * Fastify and Bun adapters.
+   *
+   * @param handlerMetadata - The handler metadata with schemas and configuration.
+   * @returns An array of getter functions that populate request arguments.
    */
   prepareArguments(handlerMetadata: HandlerMetadata<BaseXmlStreamConfig>) {
     return this.streamAdapter.prepareArguments?.(handlerMetadata) ?? []
   }
 
+  /**
+   * Provides schema information for the handler.
+   *
+   * Proxies to the base stream adapter to reuse existing schema generation logic.
+   * For Fastify, this enables built-in validation. For Bun, this returns an empty object.
+   *
+   * @param handlerMetadata - The handler metadata containing configuration and schemas.
+   * @returns Schema information (Fastify route schema or empty object for Bun).
+   */
   provideSchema(
     handlerMetadata: HandlerMetadata<BaseXmlStreamConfig>,
   ): Record<string, any> {
@@ -40,6 +81,14 @@ export class XmlStreamAdapterService implements AbstractHttpHandlerAdapterInterf
     return {}
   }
 
+  /**
+   * Checks if the handler has any validation schemas defined.
+   *
+   * Proxies to the base stream adapter to check for query or request schemas.
+   *
+   * @param handlerMetadata - The handler metadata containing configuration.
+   * @returns `true` if the handler has any schemas (query or request).
+   */
   hasSchema(handlerMetadata: HandlerMetadata<any>): boolean {
     if (
       'hasSchema' in this.streamAdapter &&
@@ -51,12 +100,25 @@ export class XmlStreamAdapterService implements AbstractHttpHandlerAdapterInterf
   }
 
   /**
-   * Custom handler - renders JSX to XML and handles response for both Fastify and Bun
+   * Creates a request handler function for XML Stream endpoints.
+   *
+   * This method generates a handler that:
+   * 1. Parses and validates request data (body, query, URL params) using the base adapter
+   * 2. Invokes the controller method with validated arguments (returns JSX)
+   * 3. Renders the JSX tree to XML string (resolves async and class components)
+   * 4. Sends the XML response with appropriate Content-Type header
+   *
+   * The handler automatically detects the environment (Fastify vs Bun) and uses the
+   * appropriate response mechanism (reply object vs Response object).
+   *
+   * @param controller - The controller class containing the handler method.
+   * @param handlerMetadata - The handler metadata with configuration and schemas.
+   * @returns A function that handles incoming requests and sends XML responses.
    */
   provideHandler(
     controller: ClassType,
     handlerMetadata: HandlerMetadata<BaseXmlStreamConfig>,
-  ): (context: RequestContextHolder, request: any, reply: any) => Promise<any> {
+  ): (context: ScopedContainer, request: any, reply: any) => Promise<any> {
     const getters = this.prepareArguments(handlerMetadata)
     const config = handlerMetadata.config
 
@@ -74,14 +136,9 @@ export class XmlStreamAdapterService implements AbstractHttpHandlerAdapterInterf
     }
 
     const contentType = config.contentType ?? 'application/xml'
-    const renderOptions = {
-      declaration: config.xmlDeclaration ?? true,
-      encoding: config.encoding ?? 'UTF-8',
-      container: this.container,
-    }
 
-    return async (context: RequestContextHolder, request: any, reply: any) => {
-      const controllerInstance = await this.container.get(controller)
+    return async (context: ScopedContainer, request: any, reply: any) => {
+      const controllerInstance = await context.get(controller)
       const argument = await formatArguments(request)
 
       // Call controller method - returns XmlNode (JSX), may contain async/class components
@@ -89,7 +146,11 @@ export class XmlStreamAdapterService implements AbstractHttpHandlerAdapterInterf
         await controllerInstance[handlerMetadata.classMethod](argument)
 
       // Render JSX to XML string (async - resolves all async and class components)
-      const xml = await renderToXml(xmlNode, renderOptions)
+      const xml = await renderToXml(xmlNode, {
+        declaration: config.xmlDeclaration ?? true,
+        encoding: config.encoding ?? 'UTF-8',
+        container: context,
+      })
 
       // Environment detection: Bun doesn't have reply
       const isHttpStandardEnvironment = reply === undefined

package/src/decorators/component.decorator.mts

@@ -1,19 +1,70 @@
+import type { Registry } from '@navios/core'
 import type { z, ZodObject, ZodRawShape } from 'zod/v4'
 
-import type { Registry } from '@navios/di'
-
 import {
+  globalRegistry,
   InjectableScope,
-  InjectableType,
   InjectableTokenMeta,
+  InjectableType,
   InjectionToken,
-  globalRegistry,
-} from '@navios/di'
+} from '@navios/core'
 
 import type { ComponentClass, XmlComponent } from '../types/component.mjs'
 
 export const ComponentMeta = Symbol.for('xml.component.meta')
 
+/**
+ * Decorator for class-based XML components with dependency injection support.
+ *
+ * Class components must implement the `XmlComponent` interface with a `render()` method.
+ * They can optionally accept props via constructor, validated with a Zod schema.
+ *
+ * @overload
+ * Component without props (no schema).
+ *
+ * @example
+ * ```tsx
+ * @Component()
+ * class LatestPostsComponent implements XmlComponent {
+ *   private readonly postService = inject(PostService)
+ *
+ *   async render() {
+ *     const posts = await this.postService.getLatestPosts()
+ *     return <>{posts.map(post => <item>...</item>)}</>
+ *   }
+ * }
+ * ```
+ *
+ * @overload
+ * Component with props schema for type-safe props.
+ *
+ * @param options - Configuration object with schema and optional registry.
+ * @param options.schema - Zod schema for validating and typing component props.
+ * @param options.registry - Optional custom DI registry (defaults to global registry).
+ *
+ * @example
+ * ```tsx
+ * const DescriptionSchema = z.object({
+ *   content: z.string(),
+ *   wrapInCData: z.boolean().optional(),
+ * })
+ *
+ * @Component({ schema: DescriptionSchema })
+ * class DescriptionComponent implements XmlComponent {
+ *   constructor(private props: z.output<typeof DescriptionSchema>) {}
+ *
+ *   async render() {
+ *     return <description>{this.props.wrapInCData ? <CData>{this.props.content}</CData> : this.props.content}</description>
+ *   }
+ * }
+ * ```
+ *
+ * @overload
+ * Component with custom registry only (no props).
+ *
+ * @param options - Configuration object with registry.
+ * @param options.registry - Custom DI registry to use for this component.
+ */
 // #1 Component without props (no schema)
 export function Component(): <T extends ComponentClass>(
   target: T,
@@ -32,10 +83,7 @@ export function Component<Schema extends ZodObject<ZodRawShape>>(options: {
 // #3 Component with custom registry only
 export function Component(options: {
   registry: Registry
-}): <T extends ComponentClass>(
-  target: T,
-  context?: ClassDecoratorContext,
-) => T
+}): <T extends ComponentClass>(target: T, context?: ClassDecoratorContext) => T
 
 export function Component(
   options: {
@@ -91,7 +139,21 @@ export function Component(
 }
 
 /**
- * Type guard to check if a class is a component
+ * Type guard to check if a value is a component class.
+ *
+ * Component classes are classes decorated with `@Component` that implement
+ * the `XmlComponent` interface.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a component class, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * if (isComponentClass(MyClass)) {
+ *   // MyClass is a component class
+ *   const instance = await container.get(MyClass)
+ * }
+ * ```
  */
 export function isComponentClass(value: unknown): value is ComponentClass {
   return (

package/src/decorators/component.decorator.spec.mts

@@ -1,4 +1,4 @@
-import { Container, Registry } from '@navios/di'
+import { Container, Registry } from '@navios/core'
 
 import { describe, expect, it } from 'vitest'
 import { z } from 'zod/v4'
@@ -152,13 +152,16 @@ describe('class component rendering', () => {
     }
 
     const container = new Container()
-    container.beginRequest('test-request')
+    const requestContainer = container.beginRequest('test-request')
     try {
       const node = createElement(SimpleComponent, null)
-      const xml = await renderToXml(node, { declaration: false, container })
+      const xml = await renderToXml(node, {
+        declaration: false,
+        container: requestContainer,
+      })
       expect(xml).toBe('<simple>content</simple>')
     } finally {
-      await container.endRequest('test-request')
+      await requestContainer.endRequest()
     }
   })
 
@@ -177,13 +180,16 @@ describe('class component rendering', () => {
     }
 
     const container = new Container()
-    container.beginRequest('test-request')
+    const requestContainer = container.beginRequest('test-request')
     try {
       const node = createElement(Greeting, { name: 'World' })
-      const xml = await renderToXml(node, { declaration: false, container })
+      const xml = await renderToXml(node, {
+        declaration: false,
+        container: requestContainer,
+      })
       expect(xml).toBe('<greeting>Hello, World!</greeting>')
     } finally {
-      await container.endRequest('test-request')
+      await requestContainer.endRequest()
     }
   })
 
@@ -203,13 +209,16 @@ describe('class component rendering', () => {
     }
 
     const container = new Container()
-    container.beginRequest('test-request')
+    const requestContainer = container.beginRequest('test-request')
     try {
       const node = createElement(Outer, null)
-      const xml = await renderToXml(node, { declaration: false, container })
+      const xml = await renderToXml(node, {
+        declaration: false,
+        container: requestContainer,
+      })
       expect(xml).toBe('<outer><inner>nested</inner></outer>')
     } finally {
-      await container.endRequest('test-request')
+      await requestContainer.endRequest()
     }
   })
 
@@ -223,13 +232,16 @@ describe('class component rendering', () => {
     }
 
     const container = new Container()
-    container.beginRequest('test-request')
+    const requestContainer = container.beginRequest('test-request')
     try {
       const node = createElement(AsyncComponent, null)
-      const xml = await renderToXml(node, { declaration: false, container })
+      const xml = await renderToXml(node, {
+        declaration: false,
+        container: requestContainer,
+      })
       expect(xml).toBe('<async>loaded</async>')
     } finally {
-      await container.endRequest('test-request')
+      await requestContainer.endRequest()
     }
   })
 
@@ -263,13 +275,13 @@ describe('class component rendering', () => {
     }
 
     const container = new Container()
-    container.beginRequest('test-request')
+    const requestContainer = container.beginRequest('test-request')
     try {
       // Valid props
       const validNode = createElement(StrictComponent, { count: 5 })
       const xml = await renderToXml(validNode, {
         declaration: false,
-        container,
+        container: requestContainer,
       })
       expect(xml).toBe('<count>5</count>')
 
@@ -279,7 +291,7 @@ describe('class component rendering', () => {
         renderToXml(invalidNode, { declaration: false, container }),
       ).rejects.toThrow()
     } finally {
-      await container.endRequest('test-request')
+      await requestContainer.endRequest()
     }
   })
 
@@ -296,7 +308,7 @@ describe('class component rendering', () => {
     }
 
     const container = new Container()
-    container.beginRequest('test-request')
+    const requestContainer = container.beginRequest('test-request')
     try {
       const node = createElement(
         'page',
@@ -304,12 +316,15 @@ describe('class component rendering', () => {
         createElement(Header, { title: 'Welcome' }),
         createElement(Footer, null),
       )
-      const xml = await renderToXml(node, { declaration: false, container })
+      const xml = await renderToXml(node, {
+        declaration: false,
+        container: requestContainer,
+      })
       expect(xml).toBe(
         '<page><header>Welcome</header><footer>Copyright 2025</footer></page>',
       )
     } finally {
-      await container.endRequest('test-request')
+      await requestContainer.endRequest()
     }
   })
 
@@ -328,7 +343,7 @@ describe('class component rendering', () => {
     }
 
     const container = new Container()
-    container.beginRequest('test-request')
+    const requestContainer = container.beginRequest('test-request')
     try {
       const node = createElement(
         Wrapper,
@@ -336,10 +351,13 @@ describe('class component rendering', () => {
         createElement('child1', null),
         createElement('child2', null),
       )
-      const xml = await renderToXml(node, { declaration: false, container })
+      const xml = await renderToXml(node, {
+        declaration: false,
+        container: requestContainer,
+      })
       expect(xml).toBe('<wrapper><child1/><child2/></wrapper>')
     } finally {
-      await container.endRequest('test-request')
+      await requestContainer.endRequest()
     }
   })
 })

package/src/decorators/xml-stream.decorator.mts

@@ -5,6 +5,28 @@ import { getEndpointMetadata, XmlStreamAdapterToken } from '@navios/core'
 
 import type { BaseXmlStreamConfig } from '../types/config.mjs'
 
+/**
+ * Type helper that extracts the parameter types for an XML Stream endpoint handler.
+ *
+ * This type automatically infers the correct parameter types based on the endpoint
+ * configuration, including URL parameters, query parameters, and request body.
+ *
+ * @template EndpointDeclaration - The endpoint declaration type from `declareXmlStream`.
+ * @template Url - The URL path pattern.
+ * @template QuerySchema - The query parameter schema type.
+ *
+ * @example
+ * ```typescript
+ * const getFeed = declareXmlStream({
+ *   method: 'GET',
+ *   url: '/feed/:category',
+ *   querySchema: z.object({ page: z.string() }),
+ * })
+ *
+ * // XmlStreamParams<typeof getFeed> resolves to:
+ * // { urlParams: { category: string }, query: { page: string } }
+ * ```
+ */
 export type XmlStreamParams<
   EndpointDeclaration extends {
     config: BaseXmlStreamConfig<any, any, any, any>
@@ -22,16 +44,30 @@ export type XmlStreamParams<
 /**
  * Decorator for XML Stream endpoints that return JSX-based XML responses.
  *
+ * This decorator marks controller methods that return JSX elements, which will be
+ * automatically rendered to XML and sent with the appropriate Content-Type header.
+ * The method can be async and can contain async components, class components, and
+ * regular JSX elements.
+ *
+ * @template Method - The HTTP method (GET, POST, etc.).
+ * @template Url - The URL path pattern (supports parameters like `/posts/:id`).
+ * @template QuerySchema - Optional Zod schema for query parameter validation.
+ * @template RequestSchema - Optional Zod schema for request body validation.
+ *
+ * @param endpoint - The endpoint declaration created with `declareXmlStream`.
+ * @returns A method decorator function.
+ *
+ * @throws {Error} If used on a non-function or non-method.
+ * @throws {Error} If the endpoint URL already exists.
+ *
  * @example
  * ```typescript
- * import { XmlStream } from '@navios/adapter-xml'
+ * import { XmlStream, declareXmlStream } from '@navios/adapter-xml'
  * import { Controller } from '@navios/core'
  *
  * const getRssFeed = declareXmlStream({
  *   method: 'GET',
  *   url: '/feed.xml',
- *   querySchema: undefined,
- *   requestSchema: undefined,
  *   contentType: 'application/rss+xml',
  * })
  *
@@ -49,6 +85,25 @@ export type XmlStreamParams<
  *   }
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * // With query parameters
+ * const getSitemap = declareXmlStream({
+ *   method: 'GET',
+ *   url: '/sitemap.xml',
+ *   querySchema: z.object({ page: z.string().optional() }),
+ * })
+ *
+ * @Controller()
+ * class SitemapController {
+ *   @XmlStream(getSitemap)
+ *   async getSitemap(params: { query?: { page?: string } }) {
+ *     const page = params.query?.page
+ *     return <urlset>...</urlset>
+ *   }
+ * }
+ * ```
  */
 export function XmlStream<
   Method extends HttpMethod = HttpMethod,

package/src/define-environment.mts

@@ -1,7 +1,6 @@
-import type { AnyInjectableType } from '@navios/di'
+import type { AnyInjectableType } from '@navios/core'
 
-import { XmlStreamAdapterToken } from '@navios/core'
-import { InjectionToken } from '@navios/di'
+import { InjectionToken, XmlStreamAdapterToken } from '@navios/core'
 
 import { XmlStreamAdapterService } from './adapters/index.mjs'
 
@@ -31,9 +30,9 @@ import { XmlStreamAdapterService } from './adapters/index.mjs'
  * ```
  */
 export function defineXmlEnvironment() {
-  const httpTokens = new Map<InjectionToken<any, undefined>, AnyInjectableType>([
-    [XmlStreamAdapterToken, XmlStreamAdapterService],
-  ])
+  const httpTokens = new Map<InjectionToken<any, undefined>, AnyInjectableType>(
+    [[XmlStreamAdapterToken, XmlStreamAdapterService]],
+  )
   return {
     httpTokens,
   }

package/src/handlers/xml-stream.mts

@@ -3,19 +3,41 @@ import type { HttpMethod } from '@navios/builder'
 import type { BaseXmlStreamConfig } from '../types/config.mjs'
 
 /**
- * Declares an XML Stream endpoint configuration for use with @XmlStream decorator.
+ * Declares an XML Stream endpoint configuration for use with `@XmlStream` decorator.
+ *
+ * This function creates an endpoint declaration that can be used with the `@XmlStream`
+ * decorator to mark controller methods that return JSX-based XML responses.
+ *
+ * @template Method - The HTTP method (GET, POST, etc.).
+ * @template Url - The URL path pattern (supports parameters like `/posts/:id`).
+ * @template QuerySchema - Optional Zod schema for query parameter validation.
+ * @template RequestSchema - Optional Zod schema for request body validation.
+ *
+ * @param config - The endpoint configuration including method, URL, schemas, and XML options.
+ * @returns An endpoint declaration object to be used with `@XmlStream` decorator.
  *
  * @example
  * ```typescript
  * import { declareXmlStream } from '@navios/adapter-xml'
+ * import { z } from 'zod/v4'
  *
+ * // Simple endpoint
  * export const getRssFeed = declareXmlStream({
  *   method: 'GET',
  *   url: '/feed.xml',
- *   querySchema: undefined,
- *   requestSchema: undefined,
  *   contentType: 'application/rss+xml',
+ * })
+ *
+ * // With query parameters
+ * export const getSitemap = declareXmlStream({
+ *   method: 'GET',
+ *   url: '/sitemap.xml',
+ *   querySchema: z.object({
+ *     page: z.string().optional(),
+ *   }),
+ *   contentType: 'application/xml',
  *   xmlDeclaration: true,
+ *   encoding: 'UTF-8',
  * })
  * ```
  */