@navios/adapter-xml 0.1.0

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

@@ -0,0 +1,93 @@
+import type { EndpointFunctionArgs, HttpMethod, Util_FlatObject } from '@navios/builder'
+import type { ZodObject, ZodType } from 'zod/v4'
+
+import { getEndpointMetadata, XmlStreamAdapterToken } from '@navios/core'
+
+import type { BaseXmlStreamConfig } from '../types/config.mjs'
+
+export type XmlStreamParams<
+  EndpointDeclaration extends {
+    config: BaseXmlStreamConfig<any, any, any, any>
+  },
+  Url extends string = EndpointDeclaration['config']['url'],
+  QuerySchema = EndpointDeclaration['config']['querySchema'],
+> = QuerySchema extends ZodObject
+  ? EndpointDeclaration['config']['requestSchema'] extends ZodType
+    ? Util_FlatObject<EndpointFunctionArgs<Url, QuerySchema, EndpointDeclaration['config']['requestSchema'], true>>
+    : Util_FlatObject<EndpointFunctionArgs<Url, QuerySchema, undefined, true>>
+  : EndpointDeclaration['config']['requestSchema'] extends ZodType
+    ? Util_FlatObject<EndpointFunctionArgs<Url, undefined, EndpointDeclaration['config']['requestSchema'], true>>
+    : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>
+
+/**
+ * Decorator for XML Stream endpoints that return JSX-based XML responses.
+ *
+ * @example
+ * ```typescript
+ * import { XmlStream } 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',
+ * })
+ *
+ * @Controller('/api')
+ * class FeedController {
+ *   @XmlStream(getRssFeed)
+ *   async getFeed() {
+ *     return (
+ *       <rss version="2.0">
+ *         <channel>
+ *           <title>My Feed</title>
+ *         </channel>
+ *       </rss>
+ *     )
+ *   }
+ * }
+ * ```
+ */
+export function XmlStream<
+  Method extends HttpMethod = HttpMethod,
+  Url extends string = string,
+  QuerySchema = undefined,
+  RequestSchema = ZodType,
+>(endpoint: { config: BaseXmlStreamConfig<Method, Url, QuerySchema, RequestSchema> }) {
+  return (
+    target: (
+      params: QuerySchema extends ZodObject
+        ? RequestSchema extends ZodType
+          ? Util_FlatObject<EndpointFunctionArgs<Url, QuerySchema, RequestSchema, true>>
+          : Util_FlatObject<EndpointFunctionArgs<Url, QuerySchema, undefined, true>>
+        : RequestSchema extends ZodType
+          ? Util_FlatObject<EndpointFunctionArgs<Url, undefined, RequestSchema, true>>
+          : Util_FlatObject<EndpointFunctionArgs<Url, undefined, undefined, true>>,
+    ) => Promise<any>, // Returns XmlNode
+    context: ClassMethodDecoratorContext,
+  ) => {
+    if (typeof target !== 'function') {
+      throw new Error('[Navios] XmlStream decorator can only be used on functions.')
+    }
+    if (context.kind !== 'method') {
+      throw new Error('[Navios] XmlStream decorator can only be used on methods.')
+    }
+
+    const config = endpoint.config
+    if (context.metadata) {
+      const endpointMetadata = getEndpointMetadata<BaseXmlStreamConfig>(target, context)
+      if (endpointMetadata.config && endpointMetadata.config.url) {
+        throw new Error(`[Navios] Endpoint ${config.method} ${config.url} already exists.`)
+      }
+      // @ts-expect-error We don't need to set correctly in the metadata
+      endpointMetadata.config = config
+      endpointMetadata.adapterToken = XmlStreamAdapterToken
+      endpointMetadata.classMethod = target.name
+      endpointMetadata.httpMethod = config.method
+      endpointMetadata.url = config.url
+    }
+    return target
+  }
+}

package/src/define-environment.mts

@@ -0,0 +1,40 @@
+import type { AnyInjectableType } from '@navios/di'
+
+import { XmlStreamAdapterToken } from '@navios/core'
+import { InjectionToken } from '@navios/di'
+
+import { XmlStreamAdapterService } from './adapters/index.mjs'
+
+/**
+ * Creates the XML environment configuration to be merged with base adapter (Fastify/Bun).
+ *
+ * @example
+ * ```typescript
+ * import { defineFastifyEnvironment } from '@navios/adapter-fastify'
+ * import { defineXmlEnvironment } from '@navios/adapter-xml'
+ * import { NaviosFactory } from '@navios/core'
+ *
+ * const fastifyEnv = defineFastifyEnvironment()
+ * const xmlEnv = defineXmlEnvironment()
+ *
+ * // Merge environments
+ * const mergedEnv = {
+ *   httpTokens: new Map([
+ *     ...fastifyEnv.httpTokens,
+ *     ...xmlEnv.httpTokens,
+ *   ]),
+ * }
+ *
+ * const app = await NaviosFactory.create(AppModule, {
+ *   adapter: mergedEnv,
+ * })
+ * ```
+ */
+export function defineXmlEnvironment() {
+  const httpTokens = new Map<InjectionToken<any, undefined>, AnyInjectableType>([
+    [XmlStreamAdapterToken, XmlStreamAdapterService],
+  ])
+  return {
+    httpTokens,
+  }
+}

package/src/handlers/index.mts

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

package/src/handlers/xml-stream.mts

@@ -0,0 +1,31 @@
+import type { HttpMethod } from '@navios/builder'
+
+import type { BaseXmlStreamConfig } from '../types/config.mjs'
+
+/**
+ * Declares an XML Stream endpoint configuration for use with @XmlStream decorator.
+ *
+ * @example
+ * ```typescript
+ * import { declareXmlStream } from '@navios/adapter-xml'
+ *
+ * export const getRssFeed = declareXmlStream({
+ *   method: 'GET',
+ *   url: '/feed.xml',
+ *   querySchema: undefined,
+ *   requestSchema: undefined,
+ *   contentType: 'application/rss+xml',
+ *   xmlDeclaration: true,
+ * })
+ * ```
+ */
+export function declareXmlStream<
+  Method extends HttpMethod,
+  Url extends string,
+  QuerySchema = undefined,
+  RequestSchema = undefined,
+>(
+  config: BaseXmlStreamConfig<Method, Url, QuerySchema, RequestSchema>,
+): { config: BaseXmlStreamConfig<Method, Url, QuerySchema, RequestSchema> } {
+  return { config }
+}

package/src/index.mts

@@ -0,0 +1,41 @@
+// Types
+export type {
+  XmlNode,
+  AsyncXmlNode,
+  CDataNode,
+  RawXmlNode,
+  ClassComponentNode,
+  AnyXmlNode,
+  BaseXmlStreamConfig,
+  XmlComponent,
+  ComponentClass,
+} from './types/index.mjs'
+
+export {
+  Fragment,
+  AsyncComponent,
+  CDataSymbol,
+  RawXmlSymbol,
+  ClassComponent,
+} from './types/index.mjs'
+
+// Runtime
+export { createElement, CData, DangerouslyInsertRawXml, renderToXml, MissingContainerError } from './runtime/index.mjs'
+export type { RenderOptions } from './runtime/index.mjs'
+
+// Tags
+export { defineTag } from './tags/index.mjs'
+export type { TagComponent } from './tags/index.mjs'
+
+// Decorators
+export { XmlStream, Component, isComponentClass } from './decorators/index.mjs'
+export type { XmlStreamParams } from './decorators/index.mjs'
+
+// Handlers
+export { declareXmlStream } from './handlers/index.mjs'
+
+// Adapters
+export { XmlStreamAdapterService } from './adapters/index.mjs'
+
+// Environment
+export { defineXmlEnvironment } from './define-environment.mjs'

package/src/jsx-dev-runtime.mts

@@ -0,0 +1,8 @@
+// Dev runtime is the same as the production runtime for XML
+export { jsx, jsxs } from './runtime/create-element.mjs'
+export { Fragment } from './types/xml-node.mjs'
+
+// jsxDEV is called by development builds of React/JSX transformers
+// It has additional debugging parameters that we ignore for XML
+import { jsx } from './runtime/create-element.mjs'
+export const jsxDEV = jsx

package/src/jsx-runtime.mts

@@ -0,0 +1,2 @@
+export { jsx, jsxs } from './runtime/create-element.mjs'
+export { Fragment } from './types/xml-node.mjs'

package/src/jsx.mts

@@ -0,0 +1,25 @@
+// JSX type definitions
+// This file serves as an entry point for TypeScript to include JSX types
+// Users can add "@navios/adapter-xml/jsx" to their tsconfig.json "types" array
+import type { AnyXmlNode, XmlNode } from './types/xml-node.mjs'
+
+declare global {
+  namespace JSX {
+    type Element = XmlNode
+
+    interface ElementChildrenAttribute {
+      children: {}
+    }
+
+    interface IntrinsicElements {
+      // Allow any XML tag name with any props
+      [tagName: string]: {
+        [prop: string]: string | number | boolean | null | undefined
+      } & {
+        children?: AnyXmlNode | AnyXmlNode[]
+      }
+    }
+  }
+}
+
+export {}

package/src/runtime/create-element.mts

@@ -0,0 +1,113 @@
+import type { AnyXmlNode, AsyncXmlNode, ClassComponentNode, XmlNode } from '../types/xml-node.mjs'
+import type { ComponentClass } from '../types/component.mjs'
+
+import { isComponentClass } from '../decorators/component.decorator.mjs'
+import { AsyncComponent, ClassComponent, Fragment } from '../types/xml-node.mjs'
+
+type SyncComponent = (props: any) => XmlNode | AsyncXmlNode | ClassComponentNode
+type AsyncComponentFn = (props: any) => Promise<XmlNode | AsyncXmlNode | ClassComponentNode>
+type FunctionalComponent = SyncComponent | AsyncComponentFn
+type ComponentType = FunctionalComponent | ComponentClass
+
+function flattenChildren(children: any): AnyXmlNode[] {
+  if (children == null || children === false) {
+    return []
+  }
+  if (Array.isArray(children)) {
+    return children.flat(Infinity).filter((c) => c != null && c !== false)
+  }
+  return [children]
+}
+
+/**
+ * JSX automatic runtime function.
+ * Used by the JSX transformer when jsxImportSource is set.
+ * Children are passed as part of props.children.
+ */
+export function jsx(
+  type: string | typeof Fragment | ComponentType,
+  props: Record<string, unknown> | null,
+): XmlNode | AsyncXmlNode | ClassComponentNode {
+  const { children, ...restProps } = props ?? {}
+  const flatChildren = flattenChildren(children)
+
+  // Handle class components - create ClassComponentNode for later resolution
+  if (isComponentClass(type)) {
+    return {
+      type: ClassComponent,
+      componentClass: type,
+      props: { ...restProps, children: flatChildren },
+    }
+  }
+
+  // Handle function components (sync or async)
+  if (typeof type === 'function') {
+    const result = type({ ...restProps, children: flatChildren })
+
+    // If component returns a Promise, wrap it in AsyncXmlNode
+    if (result instanceof Promise) {
+      return {
+        type: AsyncComponent,
+        promise: result,
+      }
+    }
+
+    return result
+  }
+
+  return {
+    type,
+    props: restProps,
+    children: flatChildren,
+  }
+}
+
+/**
+ * JSX automatic runtime function for static children.
+ * Identical to jsx() for XML - React uses this for optimization hints.
+ */
+export const jsxs = jsx
+
+/**
+ * Classic createElement for manual usage.
+ * Children are passed as rest arguments.
+ */
+export function createElement(
+  type: string | typeof Fragment | ComponentType,
+  props: Record<string, unknown> | null,
+  ...children: any[]
+): XmlNode | AsyncXmlNode | ClassComponentNode {
+  const flatChildren = flattenChildren(children)
+
+  // Handle class components - create ClassComponentNode for later resolution
+  if (isComponentClass(type)) {
+    return {
+      type: ClassComponent,
+      componentClass: type,
+      props: { ...props, children: flatChildren },
+    }
+  }
+
+  // Handle function components (sync or async)
+  if (typeof type === 'function') {
+    const result = type({ ...props, children: flatChildren })
+
+    // If component returns a Promise, wrap it in AsyncXmlNode
+    if (result instanceof Promise) {
+      return {
+        type: AsyncComponent,
+        promise: result,
+      }
+    }
+
+    return result
+  }
+
+  return {
+    type,
+    props: props ?? {},
+    children: flatChildren,
+  }
+}
+
+export { Fragment }

package/src/runtime/fragment.mts

@@ -0,0 +1 @@
+export { Fragment } from '../types/xml-node.mjs'

package/src/runtime/index.mts

@@ -0,0 +1,4 @@
+export { createElement, Fragment } from './create-element.mjs'
+export { CData, DangerouslyInsertRawXml } from './special-nodes.mjs'
+export { renderToXml, MissingContainerError } from './render-to-xml.mjs'
+export type { RenderOptions } from './render-to-xml.mjs'

package/src/runtime/render-to-xml.mts

@@ -0,0 +1,214 @@
+import type { Container } from '@navios/di'
+
+import type {
+  AnyXmlNode,
+  AsyncXmlNode,
+  CDataNode,
+  ClassComponentNode,
+  RawXmlNode,
+} from '../types/xml-node.mjs'
+import type { XmlComponent } from '../types/component.mjs'
+
+import {
+  AsyncComponent,
+  CDataSymbol,
+  ClassComponent,
+  Fragment,
+  RawXmlSymbol,
+} from '../types/xml-node.mjs'
+
+export interface RenderOptions {
+  /** Include XML declaration (<?xml version="1.0"?>) - defaults to true */
+  declaration?: boolean
+  /** XML encoding, defaults to 'UTF-8' */
+  encoding?: string
+  /** Pretty print with indentation */
+  pretty?: boolean
+  /**
+   * DI container for resolving class components.
+   * Required if the tree contains any class components.
+   */
+  container?: Container
+}
+
+export class MissingContainerError extends Error {
+  constructor(componentName: string) {
+    super(
+      `[@navios/adapter-xml] Cannot render class component "${componentName}" without a container. ` +
+        `Pass a container to renderToXml options: renderToXml(node, { container })`,
+    )
+    this.name = 'MissingContainerError'
+  }
+}
+
+export async function renderToXml(
+  node: AnyXmlNode,
+  options: RenderOptions = {},
+): Promise<string> {
+  const {
+    declaration = true,
+    encoding = 'UTF-8',
+    pretty = false,
+    container,
+  } = options
+
+  let xml = ''
+  if (declaration) {
+    xml += `<?xml version="1.0" encoding="${encoding}"?>`
+    if (pretty) xml += '\n'
+  }
+
+  xml += await renderNode(node, pretty ? 0 : -1, container)
+  return xml
+}
+
+async function renderNode(
+  node: AnyXmlNode,
+  indent: number,
+  container: Container | undefined,
+): Promise<string> {
+  if (node == null) return ''
+  if (typeof node === 'string') return escapeXml(node)
+  if (typeof node === 'number') return String(node)
+
+  // Handle class components - resolve via DI container
+  if (isClassComponentNode(node)) {
+    if (!container) {
+      throw new MissingContainerError(node.componentClass.name)
+    }
+
+    // Resolve the component instance from the container, passing props as schema args
+    // This validates props via Zod schema if defined on the component
+    const instance = (await container.get(
+      node.componentClass as any,
+      node.props,
+    )) as XmlComponent
+
+    // Call render() - no arguments, props are already in the instance
+    const result = instance.render()
+
+    // Handle async render methods
+    const resolved = result instanceof Promise ? await result : result
+
+    // Recursively render the result
+    return renderNode(resolved, indent, container)
+  }
+
+  // Handle async components - resolve the promise first
+  if (isAsyncNode(node)) {
+    const resolved = await node.promise
+    return renderNode(resolved, indent, container)
+  }
+
+  // Handle CDATA nodes
+  if (isCDataNode(node)) {
+    return renderCData(node.content)
+  }
+
+  // Handle Raw XML nodes - no escaping
+  if (isRawXmlNode(node)) {
+    return node.content
+  }
+
+  const { type, props, children } = node
+
+  if (type === Fragment) {
+    const renderedChildren = await Promise.all(
+      children
+        .filter((c) => c != null)
+        .map((c) => renderNode(c, indent, container)),
+    )
+    return renderedChildren.join('')
+  }
+
+  const prefix = indent >= 0 ? '  '.repeat(indent) : ''
+  const newline = indent >= 0 ? '\n' : ''
+
+  const attrs = Object.entries(props)
+    .filter(([_, v]) => v != null)
+    .map(([k, v]) => ` ${k}="${escapeAttr(String(v))}"`)
+    .join('')
+
+  if (children.length === 0) {
+    return `${prefix}<${type}${attrs}/>${newline}`
+  }
+
+  const childIndent = indent >= 0 ? indent + 1 : -1
+
+  // Resolve all children (including async and class components) in parallel
+  const resolvedChildren = await Promise.all(
+    children
+      .filter((c) => c != null)
+      .map((c) => renderNode(c, childIndent, container)),
+  )
+  const childContent = resolvedChildren.join('')
+
+  // Check if children are simple (text, numbers, CDATA, or raw XML)
+  const hasOnlySimpleContent = children.every(
+    (c) =>
+      typeof c === 'string' ||
+      typeof c === 'number' ||
+      isCDataNode(c) ||
+      isRawXmlNode(c),
+  )
+  if (hasOnlySimpleContent) {
+    return `${prefix}<${type}${attrs}>${childContent}</${type}>${newline}`
+  }
+
+  return `${prefix}<${type}${attrs}>${newline}${childContent}${prefix}</${type}>${newline}`
+}
+
+function isClassComponentNode(node: unknown): node is ClassComponentNode {
+  return (
+    node !== null &&
+    typeof node === 'object' &&
+    'type' in node &&
+    node.type === ClassComponent
+  )
+}
+
+function isAsyncNode(node: unknown): node is AsyncXmlNode {
+  return (
+    node !== null &&
+    typeof node === 'object' &&
+    'type' in node &&
+    node.type === AsyncComponent
+  )
+}
+
+function isCDataNode(node: any): node is CDataNode {
+  return node && typeof node === 'object' && node.type === CDataSymbol
+}
+
+function isRawXmlNode(node: any): node is RawXmlNode {
+  return node && typeof node === 'object' && node.type === RawXmlSymbol
+}
+
+/**
+ * Renders content as CDATA section.
+ * If content contains "]]>", splits into multiple CDATA sections.
+ * The technique is to end the CDATA section before ]]>, then start a new one.
+ */
+function renderCData(content: string): string {
+  // Handle the edge case where content contains "]]>"
+  // We split on "]]>" and join with "]]]]><![CDATA[>" which effectively
+  // ends the CDATA section after "]]" and starts a new one for ">"
+  if (content.includes(']]>')) {
+    // Replace ]]> with ]]]]><![CDATA[> which closes CDATA before > and reopens it
+    const escaped = content.replace(/]]>/g, ']]]]><![CDATA[>')
+    return `<![CDATA[${escaped}]]>`
+  }
+  return `<![CDATA[${content}]]>`
+}
+
+function escapeXml(str: string): string {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+function escapeAttr(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}