@navios/adapter-xml 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Oleksandr Hanzha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,532 @@
+# @navios/adapter-xml
+
+A JSX-based XML adapter for Navios that enables building XML responses (RSS feeds, sitemaps, Atom feeds, etc.) using familiar JSX syntax with full TypeScript support.
+
+## Features
+
+- **JSX Syntax** - Write XML using JSX with TypeScript type checking
+- **Async Components** - Support for async components that fetch data during rendering
+- **Class Components** - `@Component` decorator with dependency injection support via `@navios/di`
+- **Type-Safe Tags** - Define custom XML tags with Zod schema validation
+- **Runtime Agnostic** - Works with both Fastify and Bun adapters
+- **CDATA Support** - Built-in `CData` component for safe text content
+- **Raw XML** - `DangerouslyInsertRawXml` for pre-rendered content
+- **XML Namespaces** - Full support for namespaced tags (e.g., `atom:link`)
+
+## Installation
+
+```bash
+npm install @navios/adapter-xml
+# or
+yarn add @navios/adapter-xml
+```
+
+## Configuration
+
+### TypeScript Setup
+
+Configure your `tsconfig.json` to use the JSX runtime:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@navios/adapter-xml"
+  }
+}
+```
+
+### Environment Setup
+
+Merge the XML environment with your base adapter (Fastify or Bun):
+
+```typescript
+import { defineFastifyEnvironment } from '@navios/adapter-fastify'
+import { defineXmlEnvironment } from '@navios/adapter-xml'
+import { NaviosFactory } from '@navios/core'
+
+import { AppModule } from './app.module.mjs'
+
+async function bootstrap() {
+  const fastifyEnv = defineFastifyEnvironment()
+  const xmlEnv = defineXmlEnvironment()
+
+  const mergedEnv = {
+    httpTokens: new Map([...fastifyEnv.httpTokens, ...xmlEnv.httpTokens]),
+  }
+
+  const app = await NaviosFactory.create(AppModule, {
+    adapter: mergedEnv,
+  })
+
+  await app.init()
+  await app.listen({ port: 3000 })
+}
+```
+
+## Usage
+
+### Basic Example - RSS Feed
+
+Define your XML tags:
+
+```typescript
+// tags.ts
+import { defineTag } from '@navios/adapter-xml'
+
+import { z } from 'zod/v4'
+
+export const rss = defineTag(
+  'rss',
+  z.object({
+    version: z.literal('2.0'),
+    'xmlns:atom': z.string().optional(),
+  }),
+)
+export const channel = defineTag('channel')
+export const title = defineTag('title')
+export const link = defineTag('link')
+export const description = defineTag('description')
+export const item = defineTag('item')
+export const pubDate = defineTag('pubDate')
+export const atomLink = defineTag(
+  'atom:link',
+  z.object({
+    href: z.string(),
+    rel: z.string(),
+    type: z.string().optional(),
+  }),
+)
+```
+
+Declare your endpoint:
+
+```typescript
+// api.ts
+import { declareXmlStream } from '@navios/adapter-xml'
+
+export const getRssFeed = declareXmlStream({
+  method: 'GET',
+  url: '/feed.xml',
+  contentType: 'application/rss+xml',
+})
+```
+
+Create the controller:
+
+```tsx
+// feed.controller.tsx
+import { Controller } from '@navios/core'
+import { XmlStream } from '@navios/adapter-xml'
+import { getRssFeed } from './api'
+import {
+  rss,
+  channel,
+  title,
+  link,
+  description,
+  item,
+  pubDate,
+  atomLink,
+} from './tags'
+
+@Controller('/api')
+export class FeedController {
+  @XmlStream(getRssFeed)
+  async getFeed() {
+    const posts = await this.fetchPosts()
+
+    return (
+      <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+        <channel>
+          <title>My Blog</title>
+          <link>https://example.com</link>
+          <description>Latest posts from my blog</description>
+          <atomLink
+            href="https://example.com/feed.xml"
+            rel="self"
+            type="application/rss+xml"
+          />
+          {posts.map((post) => (
+            <item>
+              <title>{post.title}</title>
+              <link>{post.url}</link>
+              <pubDate>{post.publishedAt.toUTCString()}</pubDate>
+              <description>{post.excerpt}</description>
+            </item>
+          ))}
+        </channel>
+      </rss>
+    )
+  }
+
+  private async fetchPosts() {
+    // Fetch posts from database
+    return []
+  }
+}
+```
+
+### Defining Tags
+
+Use `defineTag` to create type-safe XML tags:
+
+```typescript
+import { defineTag } from '@navios/adapter-xml'
+import { z } from 'zod/v4'
+
+// Simple tag without props validation
+const item = defineTag('item')
+
+// Tag with required props
+const link = defineTag('link', z.object({
+  href: z.string().url(),
+  rel: z.enum(['self', 'alternate', 'enclosure']),
+}))
+
+// Namespaced tag
+const atomLink = defineTag('atom:link', z.object({
+  href: z.string(),
+  rel: z.string(),
+  type: z.string().optional(),
+}))
+
+// Usage
+<link href="https://example.com" rel="self" />
+<atomLink href="https://example.com/feed" rel="alternate" />
+```
+
+### Async Components
+
+Components can be async functions that fetch data during rendering:
+
+```tsx
+interface PostItemProps {
+  postId: string
+}
+
+async function PostItem({ postId }: PostItemProps) {
+  const post = await fetchPostById(postId)
+
+  return (
+    <item>
+      <title>{post.title}</title>
+      <link>{post.url}</link>
+      <pubDate>{post.publishedAt.toUTCString()}</pubDate>
+    </item>
+  )
+}
+
+// Multiple async components are resolved in parallel
+async function LatestPosts() {
+  const postIds = await getLatestPostIds()
+
+  return (
+    <>
+      {postIds.map((id) => (
+        <PostItem postId={id} />
+      ))}
+    </>
+  )
+}
+```
+
+### Class Components
+
+Class components use the `@Component` decorator and implement the `XmlComponent` interface. They support dependency injection via `@navios/di`, making them ideal for components that need access to services.
+
+```tsx
+import { Component, XmlComponent } from '@navios/adapter-xml'
+import { inject, Injectable } from '@navios/di'
+
+// Define a service
+@Injectable()
+class PostService {
+  async getLatestPosts() {
+    // Fetch posts from database
+    return [{ title: 'Hello World', url: '/posts/hello' }]
+  }
+}
+
+// Basic class component without props
+@Component()
+class LatestPostsComponent implements XmlComponent {
+  private readonly postService = inject(PostService)
+
+  async render() {
+    const posts = await this.postService.getLatestPosts()
+
+    return (
+      <>
+        {posts.map((post) => (
+          <item>
+            <title>{post.title}</title>
+            <link>{post.url}</link>
+          </item>
+        ))}
+      </>
+    )
+  }
+}
+
+// Usage in JSX
+<channel>
+  <LatestPostsComponent />
+</channel>
+```
+
+#### Class Components with Props
+
+Use a Zod schema to define typed props for your component:
+
+```tsx
+import { Component, XmlComponent, CData } from '@navios/adapter-xml'
+import { z } from 'zod/v4'
+
+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() {
+    const { content, wrapInCData } = this.props
+
+    return (
+      <description>
+        {wrapInCData ? <CData>{content}</CData> : content}
+      </description>
+    )
+  }
+}
+
+// Usage with typed props
+<DescriptionComponent
+  content="<p>HTML content here</p>"
+  wrapInCData={true}
+/>
+```
+
+#### Rendering with Container
+
+When using class components, pass a DI container to `renderToXml`:
+
+```tsx
+import { renderToXml } from '@navios/adapter-xml'
+import { Container } from '@navios/di'
+
+const container = new Container()
+container.beginRequest('request-id')
+
+const xml = await renderToXml(<RssFeed />, { container })
+```
+
+### CDATA Sections
+
+Use `CData` for text content that may contain special characters:
+
+```tsx
+import { CData } from '@navios/adapter-xml'
+;<description>
+  <CData>{`This content has <special> characters & more`}</CData>
+</description>
+// Output: <description><![CDATA[This content has <special> characters & more]]></description>
+```
+
+### Raw XML Content
+
+Use `DangerouslyInsertRawXml` for pre-rendered HTML/XML content:
+
+```tsx
+import { DangerouslyInsertRawXml } from '@navios/adapter-xml'
+
+const contentEncoded = defineTag('content:encoded')
+
+const htmlContent = '<p>Hello <strong>World</strong></p>'
+
+<contentEncoded>
+  <DangerouslyInsertRawXml>{htmlContent}</DangerouslyInsertRawXml>
+</contentEncoded>
+// Output: <content:encoded><p>Hello <strong>World</strong></p></content:encoded>
+```
+
+**Warning:** `DangerouslyInsertRawXml` bypasses all XML escaping. Only use with trusted content.
+
+## API Reference
+
+### `defineTag(name, propsSchema?)`
+
+Creates a type-safe XML tag component.
+
+- `name` - Tag name (supports namespaces like `atom:link`)
+- `propsSchema` - Optional Zod schema for props validation
+
+### `declareXmlStream(config)`
+
+Declares an XML stream endpoint.
+
+```typescript
+interface BaseXmlStreamConfig {
+  method: HttpMethod
+  url: string
+  querySchema?: ZodType
+  requestSchema?: ZodType
+  contentType?:
+    | 'application/xml'
+    | 'text/xml'
+    | 'application/rss+xml'
+    | 'application/atom+xml'
+  xmlDeclaration?: boolean // Include <?xml?> declaration (default: true)
+  encoding?: string // XML encoding (default: 'UTF-8')
+}
+```
+
+### `@XmlStream(endpoint)`
+
+Decorator for controller methods that return XML.
+
+### `defineXmlEnvironment()`
+
+Returns environment configuration to merge with your base adapter.
+
+### `@Component(options?)`
+
+Decorator for class-based XML components with dependency injection support.
+
+```typescript
+// Without props
+@Component()
+class MyComponent implements XmlComponent { ... }
+
+// With props schema
+@Component({ schema: MyPropsSchema })
+class MyComponent implements XmlComponent { ... }
+
+// With custom registry
+@Component({ registry: customRegistry })
+class MyComponent implements XmlComponent { ... }
+```
+
+### `XmlComponent`
+
+Interface for class components. Must implement a `render()` method.
+
+```typescript
+interface XmlComponent {
+  render(): AnyXmlNode | Promise<AnyXmlNode>
+}
+```
+
+### `CData`
+
+Component for CDATA sections. Automatically handles content containing `]]>`.
+
+### `DangerouslyInsertRawXml`
+
+Component for inserting raw XML/HTML without escaping.
+
+### `renderToXml(node, options?)`
+
+Low-level function to render JSX to XML string.
+
+```typescript
+interface RenderOptions {
+  declaration?: boolean // Include XML declaration
+  encoding?: string // XML encoding
+  pretty?: boolean // Pretty print output
+  container?: Container // DI container for class components
+}
+```
+
+## Content Types
+
+The adapter supports these content types:
+
+- `application/xml` (default)
+- `text/xml`
+- `application/rss+xml`
+- `application/atom+xml`
+
+## Examples
+
+### Sitemap
+
+```tsx
+const urlset = defineTag('urlset', z.object({
+  xmlns: z.string(),
+}))
+const url = defineTag('url')
+const loc = defineTag('loc')
+const lastmod = defineTag('lastmod')
+const changefreq = defineTag('changefreq')
+const priority = defineTag('priority')
+
+@XmlStream(getSitemapDefinition)
+async getSitemap() {
+  const pages = await this.getPages()
+
+  return (
+    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+      {pages.map(page => (
+        <url>
+          <loc>{page.url}</loc>
+          <lastmod>{page.updatedAt.toISOString()}</lastmod>
+          <changefreq>weekly</changefreq>
+          <priority>{page.priority}</priority>
+        </url>
+      ))}
+    </urlset>
+  )
+}
+```
+
+### Atom Feed
+
+```tsx
+const feed = defineTag('feed', z.object({
+  xmlns: z.string(),
+}))
+const entry = defineTag('entry')
+const id = defineTag('id')
+const updated = defineTag('updated')
+const author = defineTag('author')
+const name = defineTag('name')
+const content = defineTag('content', z.object({
+  type: z.string().optional(),
+}))
+
+@XmlStream(getAtomFeedDefinition)
+async getAtomFeed() {
+  const posts = await this.getPosts()
+
+  return (
+    <feed xmlns="http://www.w3.org/2005/Atom">
+      <title>My Blog</title>
+      <link href="https://example.com" rel="alternate" />
+      <id>urn:uuid:blog-feed-id</id>
+      <updated>{new Date().toISOString()}</updated>
+      {posts.map(post => (
+        <entry>
+          <title>{post.title}</title>
+          <link href={post.url} rel="alternate" />
+          <id>{post.id}</id>
+          <updated>{post.updatedAt.toISOString()}</updated>
+          <author>
+            <name>{post.author}</name>
+          </author>
+          <content type="html">
+            <CData>{post.content}</CData>
+          </content>
+        </entry>
+      ))}
+    </feed>
+  )
+}
+```
+
+## License
+
+MIT

package/bun-plugin.mts

@@ -0,0 +1,129 @@
+import fs from 'fs'
+
+import * as babel from '@babel/core'
+import { plugin } from 'bun'
+import chalk from 'chalk'
+
+// 0. minor setup
+let totalTimeSpentTranspiling = 0
+const RELOAD_HACK_FILENAME = 'bunPlugin.reload.ts'
+
+const startSetup = Date.now()
+const log = (str: string): void => console.log(chalk.dim(`[bun] ${str}`))
+log(`evaluating plugin module`)
+
+plugin({
+  name: 'typescript-with-native-decorators-and-jsx',
+  setup(build): void {
+    // 1. watch files manually since --watch is broken when using bun plugin
+    const folderToWatch = import.meta.dir + '/src/'
+    log(`manually watching ${folderToWatch}`)
+    const watchFileSet = new Set<string | null>()
+    fs.watch(folderToWatch, { recursive: true }, (event, filename) => {
+      const needestart = watchFileSet.has(filename)
+      log(`file ${filename} changed (in set: ${watchFileSet.has(filename)})`)
+      if (needestart)
+        void Bun.file(`./${RELOAD_HACK_FILENAME}`).write(
+          `// '${Math.random()})\n`,
+        )
+    })
+
+    // 2. change how .ts and .tsx files are loaded
+    log(`setup took ${Date.now() - startSetup}ms`)
+    const filter = /.*\.m?(ts|tsx)$/
+    build.onLoad(
+      { filter },
+      async (args): Promise<{ loader: 'js'; contents: string }> => {
+        try {
+          watchFileSet.add(args.path.replace(folderToWatch, ''))
+          const codeTs = await Bun.file(args.path).text()
+          const startTranspiling = performance.now()
+          let codeJS = await transpileFile(args.path, codeTs)
+
+          totalTimeSpentTranspiling += performance.now() - startTranspiling
+          addToCache(codeTs, codeJS)
+          return { loader: 'js', contents: codeJS }
+        } catch (e) {
+          console.log(`[🔴] `, e)
+          return { contents: '', loader: 'js' }
+        }
+      },
+    )
+  },
+})
+
+// 4. cache system
+const oldCache: Map<string, string> = (await Bun.file(
+  './bunPlugin.cache',
+).exists())
+  ? new Map(JSON.parse((await Bun.file('./bunPlugin.cache').text()) || '[]'))
+  : new Map()
+
+const cache = new Map<string, string>()
+log(`restoring module with ${oldCache.size} entries`)
+
+export const getFromCache = (content: string): string | undefined => {
+  if (cache.has(content)) return cache.get(content)
+  if (oldCache.has(content)) {
+    const value = oldCache.get(content)
+    if (value) cache.set(content, value)
+    return value
+  }
+  return
+}
+export function debounce<F extends (...args: any[]) => void>(
+  func: F,
+  waitFor: number,
+) {
+  let timeout: ReturnType<typeof setTimeout> | null = null
+
+  const debounced = (...args: Parameters<F>) => {
+    if (timeout) {
+      clearTimeout(timeout)
+    }
+    timeout = setTimeout(() => func(...args), waitFor)
+  }
+
+  return debounced as (...args: Parameters<F>) => void
+}
+
+const saveCacheImpl = debounce(() => {
+  log(`saving cache with ${cache.size} entries (spent ${totalTimeSpentTranspiling.toFixed(2)}ms transpiling)`)
+  void Bun.file('./bunPlugin.cache').write(JSON.stringify([...cache.entries()]))
+}, 50)
+
+export const addToCache = (codeTS: string, codeJS: string): void => {
+  cache.set(codeTS, codeJS)
+  saveCacheImpl()
+}
+
+async function transpileFile(name: string, codeTs: string): Promise<string> {
+  // 1. try to return the cached version
+  const cache = getFromCache(codeTs)
+  if (cache) return cache
+
+  // or transpile a new
+  const codeJs = await transpileFileForReal(name, codeTs)
+  addToCache(codeTs, codeJs)
+  return codeJs
+}
+
+async function transpileFileForReal(
+  name: string,
+  codeTS: string,
+): Promise<string> {
+  // Use esbuild with JSX support
+  const esbuild = (await import('esbuild')).default
+
+  // Determine loader based on file extension and content
+  const hasJsx = codeTS.includes('<') && (codeTS.includes('/>') || codeTS.includes('</'))
+  const loader = hasJsx ? 'tsx' : 'ts'
+
+  const result = await esbuild.transform(codeTS, {
+    loader,
+    target: 'chrome110',
+    jsx: 'automatic',
+    jsxImportSource: '@navios/adapter-xml',
+  })
+  return result.code
+}