@navios/adapter-xml 0.1.0

package/project.json

@@ -0,0 +1,91 @@
+{
+  "name": "@navios/adapter-xml",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/adapter-xml/src",
+  "prefix": "adapter-xml",
+  "tags": [],
+  "projectType": "library",
+  "targets": {
+    "check": {
+      "executor": "nx:run-commands",
+      "outputs": ["{projectRoot}/dist"],
+      "inputs": [
+        "^projectSources",
+        "projectSources",
+        "{projectRoot}/tsconfig.json",
+        "{projectRoot}/tsconfig.lib.json"
+      ],
+      "options": {
+        "command": ["tsc -b"],
+        "cwd": "packages/adapter-xml"
+      }
+    },
+    "lint": {
+      "executor": "nx:run-commands",
+      "inputs": ["^projectSources", "project"],
+      "options": {
+        "command": "oxlint --fix",
+        "cwd": "packages/adapter-xml"
+      }
+    },
+    "test:ci": {
+      "executor": "nx:run-commands",
+      "inputs": ["^projectSources", "project"],
+      "dependsOn": ["test:ci:unit", "test:ci:fastify", "test:ci:bun"],
+      "options": {
+        "command": "echo 'All tests passed'",
+        "cwd": "packages/adapter-xml"
+      }
+    },
+    "test:ci:unit": {
+      "executor": "nx:run-commands",
+      "inputs": ["^projectSources", "project"],
+      "options": {
+        "command": "vitest run --config vitest.config.mts src/",
+        "cwd": "packages/adapter-xml"
+      }
+    },
+    "test:ci:fastify": {
+      "executor": "nx:run-commands",
+      "inputs": ["^projectSources", "project"],
+      "options": {
+        "command": "vitest run --config vitest.e2e.fastify.config.mts",
+        "cwd": "packages/adapter-xml"
+      }
+    },
+    "test:ci:bun": {
+      "executor": "nx:run-commands",
+      "inputs": ["^projectSources", "project"],
+      "options": {
+        "command": "bun test e2e/bun/",
+        "cwd": "packages/adapter-xml"
+      }
+    },
+    "build": {
+      "executor": "nx:run-commands",
+      "inputs": ["projectSources", "{projectRoot}/tsup.config.mts"],
+      "outputs": ["{projectRoot}/lib"],
+      "dependsOn": ["check", "test:ci", "lint"],
+      "options": {
+        "command": "tsup",
+        "cwd": "packages/adapter-xml"
+      }
+    },
+    "publish": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "command": "yarn npm publish --access public",
+        "cwd": "packages/adapter-xml"
+      }
+    },
+    "publish:next": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "command": "yarn npm publish --access public --tag next",
+        "cwd": "packages/adapter-xml"
+      }
+    }
+  }
+}

package/src/adapters/index.mts

@@ -0,0 +1 @@
+export { XmlStreamAdapterService } from './xml-stream-adapter.service.mjs'

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

@@ -0,0 +1,121 @@
+import type {
+  AbstractHttpHandlerAdapterInterface,
+  HandlerMetadata,
+} from '@navios/core'
+import type { ClassType, RequestContextHolder } from '@navios/di'
+
+import { StreamAdapterToken, XmlStreamAdapterToken } from '@navios/core'
+import { Container, inject, Injectable } from '@navios/di'
+
+import type { BaseXmlStreamConfig } from '../types/config.mjs'
+import type { AnyXmlNode } from '../types/xml-node.mjs'
+
+import { renderToXml } from '../runtime/render-to-xml.mjs'
+
+@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)
+   */
+  prepareArguments(handlerMetadata: HandlerMetadata<BaseXmlStreamConfig>) {
+    return this.streamAdapter.prepareArguments?.(handlerMetadata) ?? []
+  }
+
+  provideSchema(
+    handlerMetadata: HandlerMetadata<BaseXmlStreamConfig>,
+  ): Record<string, any> {
+    if (
+      'provideSchema' in this.streamAdapter &&
+      typeof this.streamAdapter.provideSchema === 'function'
+    ) {
+      return this.streamAdapter.provideSchema(handlerMetadata)
+    }
+    return {}
+  }
+
+  hasSchema(handlerMetadata: HandlerMetadata<any>): boolean {
+    if (
+      'hasSchema' in this.streamAdapter &&
+      typeof this.streamAdapter.hasSchema === 'function'
+    ) {
+      return this.streamAdapter.hasSchema(handlerMetadata)
+    }
+    return false
+  }
+
+  /**
+   * Custom handler - renders JSX to XML and handles response for both Fastify and Bun
+   */
+  provideHandler(
+    controller: ClassType,
+    handlerMetadata: HandlerMetadata<BaseXmlStreamConfig>,
+  ): (context: RequestContextHolder, request: any, reply: any) => Promise<any> {
+    const getters = this.prepareArguments(handlerMetadata)
+    const config = handlerMetadata.config
+
+    const formatArguments = async (request: any) => {
+      const argument: Record<string, any> = {}
+      const promises: Promise<void>[] = []
+      for (const getter of getters) {
+        const res = getter(argument, request)
+        if (res instanceof Promise) {
+          promises.push(res)
+        }
+      }
+      await Promise.all(promises)
+      return argument
+    }
+
+    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)
+      const argument = await formatArguments(request)
+
+      // Call controller method - returns XmlNode (JSX), may contain async/class components
+      const xmlNode: AnyXmlNode =
+        await controllerInstance[handlerMetadata.classMethod](argument)
+
+      // Render JSX to XML string (async - resolves all async and class components)
+      const xml = await renderToXml(xmlNode, renderOptions)
+
+      // Environment detection: Bun doesn't have reply
+      const isHttpStandardEnvironment = reply === undefined
+
+      if (isHttpStandardEnvironment) {
+        // Bun: return Response object
+        const headers: Record<string, string> = {
+          'Content-Type': contentType,
+        }
+        for (const [key, value] of Object.entries(handlerMetadata.headers)) {
+          if (value != null) {
+            headers[key] = String(value)
+          }
+        }
+        return new Response(xml, {
+          status: handlerMetadata.successStatusCode,
+          headers,
+        })
+      } else {
+        // Fastify: use reply object
+        reply
+          .status(handlerMetadata.successStatusCode)
+          .header('Content-Type', contentType)
+          .headers(handlerMetadata.headers)
+          .send(xml)
+      }
+    }
+  }
+}

package/src/decorators/component.decorator.mts

@@ -0,0 +1,102 @@
+import type { z, ZodObject, ZodRawShape } from 'zod/v4'
+
+import type { Registry } from '@navios/di'
+
+import {
+  InjectableScope,
+  InjectableType,
+  InjectableTokenMeta,
+  InjectionToken,
+  globalRegistry,
+} from '@navios/di'
+
+import type { ComponentClass, XmlComponent } from '../types/component.mjs'
+
+export const ComponentMeta = Symbol.for('xml.component.meta')
+
+// #1 Component without props (no schema)
+export function Component(): <T extends ComponentClass>(
+  target: T,
+  context?: ClassDecoratorContext,
+) => T
+
+// #2 Component with props schema
+export function Component<Schema extends ZodObject<ZodRawShape>>(options: {
+  schema: Schema
+  registry?: Registry
+}): <T extends new (props: z.output<Schema>, ...args: any[]) => XmlComponent>(
+  target: T,
+  context?: ClassDecoratorContext,
+) => T
+
+// #3 Component with custom registry only
+export function Component(options: {
+  registry: Registry
+}): <T extends ComponentClass>(
+  target: T,
+  context?: ClassDecoratorContext,
+) => T
+
+export function Component(
+  options: {
+    schema?: ZodObject<ZodRawShape>
+    registry?: Registry
+  } = {},
+) {
+  const { schema, registry = globalRegistry } = options
+
+  return <T extends ComponentClass>(
+    target: T,
+    context?: ClassDecoratorContext,
+  ): T => {
+    if (
+      (context && context.kind !== 'class') ||
+      (target instanceof Function && !context)
+    ) {
+      throw new Error(
+        '[@navios/adapter-xml] @Component decorator can only be used on classes.',
+      )
+    }
+
+    // Verify the class has a render method
+    if (typeof target.prototype.render !== 'function') {
+      throw new Error(
+        `[@navios/adapter-xml] @Component class "${target.name}" must implement render() method.`,
+      )
+    }
+
+    // Create token with schema if provided
+    const injectableToken = schema
+      ? InjectionToken.create(target, schema)
+      : InjectionToken.create(target)
+
+    // Register with Request scope - each render gets fresh instances
+    registry.set(
+      injectableToken,
+      InjectableScope.Request,
+      target,
+      InjectableType.Class,
+    )
+
+    // Store token metadata on the class (same pattern as @Injectable)
+    // @ts-expect-error - Adding metadata to class
+    target[InjectableTokenMeta] = injectableToken
+
+    // Mark as component for JSX runtime detection
+    // @ts-expect-error - Adding metadata to class
+    target[ComponentMeta] = true
+
+    return target
+  }
+}
+
+/**
+ * Type guard to check if a class is a component
+ */
+export function isComponentClass(value: unknown): value is ComponentClass {
+  return (
+    typeof value === 'function' &&
+    // @ts-expect-error - Checking metadata
+    value[ComponentMeta] === true
+  )
+}

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

@@ -0,0 +1,345 @@
+import { Container, Registry } from '@navios/di'
+
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod/v4'
+
+import type { XmlComponent } from '../types/component.mjs'
+
+import { createElement } from '../runtime/create-element.mjs'
+import { renderToXml } from '../runtime/render-to-xml.mjs'
+import { ClassComponent } from '../types/xml-node.mjs'
+import {
+  Component,
+  ComponentMeta,
+  isComponentClass,
+} from './component.decorator.mjs'
+
+describe('@Component decorator', () => {
+  it('should mark class as a component', () => {
+    @Component()
+    class TestComponent implements XmlComponent {
+      render() {
+        return createElement('test', null)
+      }
+    }
+
+    expect(isComponentClass(TestComponent)).toBe(true)
+    // @ts-expect-error - Checking metadata
+    expect(TestComponent[ComponentMeta]).toBe(true)
+  })
+
+  it('should throw if class does not have render method', () => {
+    expect(() => {
+      // @ts-expect-error - Testing invalid class
+      @Component()
+      class InvalidComponent {
+        notRender() {
+          return null
+        }
+      }
+      // Force evaluation
+      return InvalidComponent
+    }).toThrow('must implement render() method')
+  })
+
+  it('should create ClassComponentNode when used in createElement', () => {
+    @Component()
+    class MyComponent implements XmlComponent {
+      render() {
+        return createElement('content', null, 'Hello')
+      }
+    }
+
+    const node = createElement(MyComponent, null)
+
+    expect(node).toEqual({
+      type: ClassComponent,
+      componentClass: MyComponent,
+      props: { children: [] },
+    })
+  })
+
+  it('should pass props to ClassComponentNode', () => {
+    const PropsSchema = z.object({
+      name: z.string(),
+      age: z.number().optional(),
+    })
+
+    @Component({ schema: PropsSchema })
+    class PropsComponent implements XmlComponent {
+      constructor(private props: z.output<typeof PropsSchema>) {}
+
+      render() {
+        return createElement('user', null, this.props.name)
+      }
+    }
+
+    const node = createElement(PropsComponent, { name: 'John', age: 30 })
+
+    expect(node).toEqual({
+      type: ClassComponent,
+      componentClass: PropsComponent,
+      props: { name: 'John', age: 30, children: [] },
+    })
+  })
+
+  it('should allow custom registry', () => {
+    const customRegistry = new Registry()
+
+    @Component({ registry: customRegistry })
+    class RegistryComponent implements XmlComponent {
+      render() {
+        return createElement('custom', null)
+      }
+    }
+
+    expect(isComponentClass(RegistryComponent)).toBe(true)
+    // The component should have a token stored
+    // @ts-expect-error - Checking InjectableTokenMeta
+    const token = RegistryComponent[Symbol.for('InjectableTokenMeta')]
+    expect(token).toBeDefined()
+    // And that token should be registered in the custom registry
+    expect(customRegistry.has(token)).toBe(true)
+  })
+})
+
+describe('isComponentClass', () => {
+  it('should return true for decorated classes', () => {
+    @Component()
+    class DecoratedComponent implements XmlComponent {
+      render() {
+        return createElement('test', null)
+      }
+    }
+
+    expect(isComponentClass(DecoratedComponent)).toBe(true)
+  })
+
+  it('should return false for regular functions', () => {
+    function regularFunction() {
+      return createElement('test', null)
+    }
+
+    expect(isComponentClass(regularFunction)).toBe(false)
+  })
+
+  it('should return false for regular classes', () => {
+    class RegularClass {
+      render() {
+        return createElement('test', null)
+      }
+    }
+
+    expect(isComponentClass(RegularClass)).toBe(false)
+  })
+
+  it('should return false for non-functions', () => {
+    expect(isComponentClass('string')).toBe(false)
+    expect(isComponentClass(123)).toBe(false)
+    expect(isComponentClass(null)).toBe(false)
+    expect(isComponentClass(undefined)).toBe(false)
+    expect(isComponentClass({})).toBe(false)
+  })
+})
+
+describe('class component rendering', () => {
+  it('should render basic class component', async () => {
+    @Component()
+    class SimpleComponent implements XmlComponent {
+      render() {
+        return createElement('simple', null, 'content')
+      }
+    }
+
+    const container = new Container()
+    container.beginRequest('test-request')
+    try {
+      const node = createElement(SimpleComponent, null)
+      const xml = await renderToXml(node, { declaration: false, container })
+      expect(xml).toBe('<simple>content</simple>')
+    } finally {
+      await container.endRequest('test-request')
+    }
+  })
+
+  it('should render class component with props', async () => {
+    const GreetingSchema = z.object({
+      name: z.string(),
+    })
+
+    @Component({ schema: GreetingSchema })
+    class Greeting implements XmlComponent {
+      constructor(private props: z.output<typeof GreetingSchema>) {}
+
+      render() {
+        return createElement('greeting', null, `Hello, ${this.props.name}!`)
+      }
+    }
+
+    const container = new Container()
+    container.beginRequest('test-request')
+    try {
+      const node = createElement(Greeting, { name: 'World' })
+      const xml = await renderToXml(node, { declaration: false, container })
+      expect(xml).toBe('<greeting>Hello, World!</greeting>')
+    } finally {
+      await container.endRequest('test-request')
+    }
+  })
+
+  it('should render nested class components', async () => {
+    @Component()
+    class Inner implements XmlComponent {
+      render() {
+        return createElement('inner', null, 'nested')
+      }
+    }
+
+    @Component()
+    class Outer implements XmlComponent {
+      render() {
+        return createElement('outer', null, createElement(Inner, null))
+      }
+    }
+
+    const container = new Container()
+    container.beginRequest('test-request')
+    try {
+      const node = createElement(Outer, null)
+      const xml = await renderToXml(node, { declaration: false, container })
+      expect(xml).toBe('<outer><inner>nested</inner></outer>')
+    } finally {
+      await container.endRequest('test-request')
+    }
+  })
+
+  it('should render async class component', async () => {
+    @Component()
+    class AsyncComponent implements XmlComponent {
+      async render() {
+        await new Promise((resolve) => setTimeout(resolve, 10))
+        return createElement('async', null, 'loaded')
+      }
+    }
+
+    const container = new Container()
+    container.beginRequest('test-request')
+    try {
+      const node = createElement(AsyncComponent, null)
+      const xml = await renderToXml(node, { declaration: false, container })
+      expect(xml).toBe('<async>loaded</async>')
+    } finally {
+      await container.endRequest('test-request')
+    }
+  })
+
+  it('should throw MissingContainerError when container not provided', async () => {
+    @Component()
+    class RequiresContainer implements XmlComponent {
+      render() {
+        return createElement('test', null)
+      }
+    }
+
+    const node = createElement(RequiresContainer, null)
+
+    await expect(renderToXml(node, { declaration: false })).rejects.toThrow(
+      'Cannot render class component "RequiresContainer" without a container',
+    )
+  })
+
+  it('should validate props with Zod schema', async () => {
+    const StrictSchema = z.object({
+      count: z.number().min(0),
+    })
+
+    @Component({ schema: StrictSchema })
+    class StrictComponent implements XmlComponent {
+      constructor(private props: z.output<typeof StrictSchema>) {}
+
+      render() {
+        return createElement('count', null, String(this.props.count))
+      }
+    }
+
+    const container = new Container()
+    container.beginRequest('test-request')
+    try {
+      // Valid props
+      const validNode = createElement(StrictComponent, { count: 5 })
+      const xml = await renderToXml(validNode, {
+        declaration: false,
+        container,
+      })
+      expect(xml).toBe('<count>5</count>')
+
+      // Invalid props - negative number
+      const invalidNode = createElement(StrictComponent, { count: -1 })
+      await expect(
+        renderToXml(invalidNode, { declaration: false, container }),
+      ).rejects.toThrow()
+    } finally {
+      await container.endRequest('test-request')
+    }
+  })
+
+  it('should mix functional and class components', async () => {
+    function Header({ title }: { title: string }) {
+      return createElement('header', null, title)
+    }
+
+    @Component()
+    class Footer implements XmlComponent {
+      render() {
+        return createElement('footer', null, 'Copyright 2025')
+      }
+    }
+
+    const container = new Container()
+    container.beginRequest('test-request')
+    try {
+      const node = createElement(
+        'page',
+        null,
+        createElement(Header, { title: 'Welcome' }),
+        createElement(Footer, null),
+      )
+      const xml = await renderToXml(node, { declaration: false, container })
+      expect(xml).toBe(
+        '<page><header>Welcome</header><footer>Copyright 2025</footer></page>',
+      )
+    } finally {
+      await container.endRequest('test-request')
+    }
+  })
+
+  it('should handle children in class components', async () => {
+    const WrapperSchema = z.object({
+      children: z.array(z.any()).optional(),
+    })
+
+    @Component({ schema: WrapperSchema })
+    class Wrapper implements XmlComponent {
+      constructor(private props: z.output<typeof WrapperSchema>) {}
+
+      render() {
+        return createElement('wrapper', null, ...(this.props.children ?? []))
+      }
+    }
+
+    const container = new Container()
+    container.beginRequest('test-request')
+    try {
+      const node = createElement(
+        Wrapper,
+        null,
+        createElement('child1', null),
+        createElement('child2', null),
+      )
+      const xml = await renderToXml(node, { declaration: false, container })
+      expect(xml).toBe('<wrapper><child1/><child2/></wrapper>')
+    } finally {
+      await container.endRequest('test-request')
+    }
+  })
+})

package/src/decorators/index.mts

@@ -0,0 +1,4 @@
+export { XmlStream } from './xml-stream.decorator.mjs'
+export type { XmlStreamParams } from './xml-stream.decorator.mjs'
+
+export { Component, ComponentMeta, isComponentClass } from './component.decorator.mjs'