@navios/openapi-bun 0.7.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@navios/openapi-bun",
+  "version": "0.7.0",
+  "author": {
+    "name": "Oleksandr Hanzha",
+    "email": "alex@granted.name"
+  },
+  "repository": {
+    "directory": "packages/openapi-bun",
+    "type": "git",
+    "url": "https://github.com/Arilas/navios.git"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@navios/adapter-bun": "^0.7.1",
+    "@navios/builder": "^0.5.1",
+    "@navios/core": "^0.7.1",
+    "@navios/openapi": "^0.7.0",
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "typings": "./lib/index.d.mts",
+  "main": "./lib/index.cjs",
+  "module": "./lib/index.mjs",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/index.d.mts",
+        "default": "./lib/index.mjs"
+      },
+      "require": {
+        "types": "./lib/index.d.cts",
+        "default": "./lib/index.cjs"
+      }
+    }
+  },
+  "devDependencies": {
+    "@navios/adapter-bun": "^0.7.1",
+    "@navios/builder": "^0.5.1",
+    "@navios/core": "^0.7.1",
+    "@navios/openapi": "^0.7.0",
+    "typescript": "^5.9.3",
+    "zod": "^4.2.1"
+  },
+  "dependencies": {
+    "@scalar/core": "^0.3.28",
+    "yaml": "^2.8.2"
+  }
+}

package/project.json

@@ -0,0 +1,66 @@
+{
+  "name": "@navios/openapi-bun",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/openapi-bun/src",
+  "prefix": "openapi-bun",
+  "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/openapi-bun"
+      }
+    },
+    "lint": {
+      "executor": "nx:run-commands",
+      "inputs": ["^projectSources", "project"],
+      "options": {
+        "command": "oxlint --fix",
+        "cwd": "packages/openapi-bun"
+      }
+    },
+    "test:ci": {
+      "executor": "nx:run-commands",
+      "inputs": ["^projectSources", "project"],
+      "options": {
+        "command": "vitest run",
+        "cwd": "packages/openapi-bun"
+      }
+    },
+    "build": {
+      "executor": "nx:run-commands",
+      "inputs": ["projectSources", "{projectRoot}/tsdown.config.mts"],
+      "outputs": ["{projectRoot}/lib"],
+      "dependsOn": ["check", "lint"],
+      "options": {
+        "command": "tsdown",
+        "cwd": "packages/openapi-bun"
+      }
+    },
+    "publish": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "command": "yarn npm publish --access public",
+        "cwd": "packages/openapi-bun"
+      }
+    },
+    "publish:next": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "command": "yarn npm publish --access public --tag next",
+        "cwd": "packages/openapi-bun"
+      }
+    }
+  }
+}

package/src/controllers/index.mts

@@ -0,0 +1,3 @@
+export { createOpenApiJsonController } from './openapi-json.controller.mjs'
+export { createOpenApiYamlController } from './openapi-yaml.controller.mjs'
+export { createOpenApiUiController } from './openapi-ui.controller.mjs'

package/src/controllers/openapi-json.controller.mts

@@ -0,0 +1,51 @@
+import type { EndpointParams, EndpointResult } from '@navios/core'
+import type { ClassType } from '@navios/di'
+
+import { builder } from '@navios/builder'
+import { Controller, Endpoint, inject } from '@navios/core'
+import { ApiExclude } from '@navios/openapi'
+
+import { z } from 'zod'
+
+import { OpenApiDocumentServiceToken } from '../services/openapi-document.service.mjs'
+
+/**
+ * Schema for OpenAPI document response.
+ * Uses z.record(z.unknown()) since OpenAPI documents have complex structure.
+ */
+const openApiDocumentSchema = z.record(z.string(), z.unknown())
+
+/**
+ * Creates a customized JSON controller with the correct path.
+ * Called by the plugin to create a controller with the configured jsonPath.
+ *
+ * @param jsonPath - The path to serve the OpenAPI JSON (e.g., '/openapi.json')
+ * @returns A controller class that serves the OpenAPI document as JSON
+ */
+export function createOpenApiJsonController(jsonPath: string): ClassType {
+  const API = builder()
+
+  const endpoint = API.declareEndpoint({
+    method: 'GET',
+    url: jsonPath,
+    responseSchema: openApiDocumentSchema,
+  })
+
+  @ApiExclude()
+  @Controller()
+  class OpenApiJsonController {
+    private documentService = inject(OpenApiDocumentServiceToken)
+
+    @Endpoint(endpoint)
+    async getJson(
+      _params: EndpointParams<typeof endpoint>,
+    ): EndpointResult<typeof endpoint> {
+      return this.documentService.getDocument() as unknown as Record<
+        string,
+        unknown
+      >
+    }
+  }
+
+  return OpenApiJsonController
+}

package/src/controllers/openapi-ui.controller.mts

@@ -0,0 +1,72 @@
+import type { StreamParams } from '@navios/core'
+import type { ClassType } from '@navios/di'
+
+import { builder } from '@navios/builder'
+import { Controller, inject, Stream } from '@navios/core'
+import { ApiExclude, ApiStream } from '@navios/openapi'
+
+import { getHtmlDocument } from '@scalar/core/libs/html-rendering'
+
+import type { ScalarOptions } from '../schemas/index.mjs'
+
+import { OpenApiOptionsToken } from '../tokens/openapi-options.token.mjs'
+
+/**
+ * Creates a customized Scalar UI controller with the correct path.
+ *
+ * @param docsPath - The path to serve the Scalar UI (e.g., '/docs')
+ * @param jsonPath - The path to the OpenAPI JSON spec (used by Scalar to load the spec)
+ * @returns A controller class that serves the Scalar API Reference UI
+ */
+export function createOpenApiUiController(
+  docsPath: string,
+  jsonPath: string,
+): ClassType {
+  const API = builder()
+
+  const endpoint = API.declareStream({
+    method: 'GET',
+    url: docsPath,
+  })
+
+  @ApiExclude()
+  @Controller()
+  class OpenApiUiController {
+    private options = inject(OpenApiOptionsToken)
+    private html: string | null = null
+
+    // @ts-expect-error - Stream decorator is not typed correctly
+    @Stream(endpoint)
+    @ApiStream({ contentType: 'text/html' })
+    async getUi(_params: StreamParams<typeof endpoint>) {
+      // Generate HTML on first request (lazy initialization)
+      if (!this.html) {
+        this.html = this.generateHtml()
+      }
+
+      return new Response(this.html, {
+        headers: {
+          'Content-Type': 'text/html; charset=utf-8',
+        },
+      })
+    }
+
+    private generateHtml(): string {
+      const scalarOptions: ScalarOptions = this.options.scalar ?? {}
+
+      return getHtmlDocument({
+        url: jsonPath,
+        theme: scalarOptions.theme ?? 'default',
+        favicon: scalarOptions.favicon,
+        customCss: scalarOptions.customCss,
+        hideDownloadButton: scalarOptions.hideDownloadButton,
+        hideSearch: scalarOptions.hideSearch,
+        metaData: scalarOptions.metaData,
+        cdn: scalarOptions.cdn,
+        pageTitle: scalarOptions.metaData?.title ?? 'API Reference',
+      })
+    }
+  }
+
+  return OpenApiUiController
+}

package/src/controllers/openapi-yaml.controller.mts

@@ -0,0 +1,46 @@
+import type { StreamParams } from '@navios/core'
+import type { ClassType } from '@navios/di'
+
+import { builder } from '@navios/builder'
+import { Controller, inject, Stream } from '@navios/core'
+import { ApiExclude, ApiStream } from '@navios/openapi'
+
+import { OpenApiDocumentServiceToken } from '../services/openapi-document.service.mjs'
+
+/**
+ * Creates a customized YAML controller with the correct path.
+ * Uses Stream endpoint to set content-type header properly.
+ *
+ * @param yamlPath - The path to serve the OpenAPI YAML (e.g., '/openapi.yaml')
+ * @returns A controller class that serves the OpenAPI document as YAML
+ */
+export function createOpenApiYamlController(yamlPath: string): ClassType {
+  const API = builder()
+
+  const endpoint = API.declareStream({
+    method: 'GET',
+    url: yamlPath,
+  })
+
+  @ApiExclude()
+  @Controller()
+  class OpenApiYamlController {
+    private documentService = inject(OpenApiDocumentServiceToken)
+
+    // @ts-expect-error - Stream decorator is not typed correctly
+    @Stream(endpoint)
+    @ApiStream({ contentType: 'text/yaml' })
+    async getYaml(_params: StreamParams<typeof endpoint>) {
+      const yaml = this.documentService.getYamlDocument()
+
+      // Return a Response with proper content-type
+      return new Response(yaml, {
+        headers: {
+          'Content-Type': 'text/yaml; charset=utf-8',
+        },
+      })
+    }
+  }
+
+  return OpenApiYamlController
+}

package/src/index.mts

@@ -0,0 +1,30 @@
+// Plugin
+export {
+  OpenApiBunPlugin,
+  defineOpenApiPlugin,
+  type BunOpenApiPluginOptions,
+  type ScalarOptions,
+  type ScalarTheme,
+} from './openapi-bun.plugin.mjs'
+
+// Schemas (for advanced use cases)
+export {
+  bunOpenApiPluginOptionsSchema,
+  scalarOptionsSchema,
+  scalarThemeSchema,
+  type BunOpenApiPluginOptionsBase,
+} from './schemas/index.mjs'
+
+// Tokens (for advanced use cases)
+export { OpenApiOptionsToken } from './tokens/index.mjs'
+
+// Services (for advanced use cases)
+export {
+  OpenApiDocumentService,
+  OpenApiDocumentServiceToken,
+} from './services/index.mjs'
+
+// Controller factories (for custom setups)
+export { createOpenApiJsonController } from './controllers/openapi-json.controller.mjs'
+export { createOpenApiYamlController } from './controllers/openapi-yaml.controller.mjs'
+export { createOpenApiUiController } from './controllers/openapi-ui.controller.mjs'

package/src/openapi-bun.plugin.mts

@@ -0,0 +1,167 @@
+import type {
+  NaviosPlugin,
+  PluginContext,
+  PluginDefinition,
+} from '@navios/core'
+import type { ClassType } from '@navios/di'
+
+import { InjectableScope, InjectableType } from '@navios/di'
+
+import type { ScalarOptions, ScalarTheme } from './schemas/index.mjs'
+import type { BunOpenApiPluginOptions } from './tokens/openapi-options.token.mjs'
+
+import { createOpenApiJsonController } from './controllers/openapi-json.controller.mjs'
+import { createOpenApiUiController } from './controllers/openapi-ui.controller.mjs'
+import { createOpenApiYamlController } from './controllers/openapi-yaml.controller.mjs'
+import { bunOpenApiPluginOptionsSchema } from './schemas/index.mjs'
+import { OpenApiDocumentService } from './services/openapi-document.service.mjs'
+import { OpenApiOptionsToken } from './tokens/openapi-options.token.mjs'
+
+/**
+ * OpenAPI plugin for Bun adapter.
+ *
+ * This plugin:
+ * - Scans all registered modules for endpoints
+ * - Generates an OpenAPI 3.1 document
+ * - Injects controllers for JSON, YAML, and Scalar UI endpoints
+ *
+ * Unlike the Fastify plugin which registers routes directly,
+ * this plugin uses the standard Navios controller pattern via
+ * ModuleLoaderService.extendModules().
+ */
+export class OpenApiBunPlugin implements NaviosPlugin<BunOpenApiPluginOptions> {
+  readonly name = 'openapi-bun'
+
+  async register(
+    context: PluginContext,
+    options: BunOpenApiPluginOptions,
+  ): Promise<void> {
+    // Parse and validate options with defaults
+    const parsedOptions = bunOpenApiPluginOptionsSchema.parse(options)
+    const fullOptions = { ...options, ...parsedOptions }
+
+    // Step 1: Register options in DI container
+    this.registerOptions(context, fullOptions)
+
+    // Step 2: Register document service and initialize it
+    await this.initializeDocumentService(context, fullOptions)
+
+    // Step 3: Create and register controllers based on options
+    const controllers = this.createControllers(parsedOptions)
+
+    // Step 4: Extend modules with our controllers
+    if (controllers.length > 0) {
+      await context.moduleLoader.extendModules([
+        {
+          controllers,
+          moduleName: 'OpenApiBunModule',
+        },
+      ])
+    }
+  }
+
+  /**
+   * Registers the plugin options in the DI container.
+   */
+  private registerOptions(
+    context: PluginContext,
+    options: BunOpenApiPluginOptions,
+  ): void {
+    const locator = context.container.getServiceLocator()
+    const instanceName = locator.getInstanceIdentifier(OpenApiOptionsToken)
+
+    locator
+      .getManager()
+      .storeCreatedHolder(
+        instanceName,
+        options,
+        InjectableType.Class,
+        InjectableScope.Singleton,
+      )
+  }
+
+  /**
+   * Registers and initializes the document service.
+   */
+  private async initializeDocumentService(
+    context: PluginContext,
+    _options: BunOpenApiPluginOptions,
+  ): Promise<void> {
+    // Get the document service from container (triggers DI registration)
+    const documentService = await context.container.get(OpenApiDocumentService)
+
+    // Initialize with modules and global prefix
+    documentService.initialize(context.modules, context.globalPrefix)
+  }
+
+  /**
+   * Creates controller classes based on options.
+   */
+  private createControllers(
+    options: ReturnType<typeof bunOpenApiPluginOptionsSchema.parse>,
+  ): ClassType[] {
+    const controllers: ClassType[] = []
+
+    if (!options.disableJson) {
+      controllers.push(createOpenApiJsonController(options.jsonPath))
+    }
+
+    if (!options.disableYaml) {
+      controllers.push(createOpenApiYamlController(options.yamlPath))
+    }
+
+    if (!options.disableScalar) {
+      controllers.push(
+        createOpenApiUiController(options.docsPath, options.jsonPath),
+      )
+    }
+
+    return controllers
+  }
+}
+
+/**
+ * Creates a plugin definition for the OpenAPI Bun plugin.
+ *
+ * @param options - Plugin configuration options
+ * @returns Plugin definition to pass to `app.usePlugin()`
+ *
+ * @example
+ * ```typescript
+ * import { NaviosFactory } from '@navios/core'
+ * import { defineBunEnvironment } from '@navios/adapter-bun'
+ * import { defineOpenApiPlugin } from '@navios/openapi-bun'
+ *
+ * const app = await NaviosFactory.create(AppModule, {
+ *   adapter: defineBunEnvironment(),
+ * })
+ *
+ * app.usePlugin(defineOpenApiPlugin({
+ *   info: {
+ *     title: 'My API',
+ *     version: '1.0.0',
+ *     description: 'API documentation',
+ *   },
+ *   servers: [
+ *     { url: 'http://localhost:3000', description: 'Development' },
+ *   ],
+ *   scalar: {
+ *     theme: 'purple',
+ *   },
+ * }))
+ *
+ * await app.listen({ port: 3000 })
+ * // API docs available at http://localhost:3000/docs
+ * ```
+ */
+export function defineOpenApiPlugin(
+  options: BunOpenApiPluginOptions,
+): PluginDefinition<BunOpenApiPluginOptions> {
+  return {
+    plugin: new OpenApiBunPlugin(),
+    options,
+  }
+}
+
+// Re-export types for convenience
+export type { ScalarOptions, ScalarTheme, BunOpenApiPluginOptions }

package/src/schemas/index.mts

@@ -0,0 +1,10 @@
+export {
+  bunOpenApiPluginOptionsSchema,
+  scalarMetaDataSchema,
+  scalarOptionsSchema,
+  scalarThemeSchema,
+  type BunOpenApiPluginOptionsBase,
+  type ScalarMetaData,
+  type ScalarOptions,
+  type ScalarTheme,
+} from './openapi-bun-options.schema.mjs'

package/src/schemas/openapi-bun-options.schema.mts

@@ -0,0 +1,135 @@
+import { z } from 'zod'
+
+/**
+ * Zod schema for Scalar UI theme options
+ */
+export const scalarThemeSchema = z.enum([
+  'default',
+  'alternate',
+  'moon',
+  'purple',
+  'solarized',
+  'bluePlanet',
+  'saturn',
+  'kepler',
+  'mars',
+  'deepSpace',
+  'laserwave',
+  'elysiajs',
+  'fastify',
+  'none',
+])
+
+/**
+ * Zod schema for Scalar UI metadata
+ */
+export const scalarMetaDataSchema = z
+  .object({
+    title: z.string().optional(),
+    description: z.string().optional(),
+    ogDescription: z.string().optional(),
+    ogTitle: z.string().optional(),
+    ogImage: z.string().optional(),
+    twitterCard: z.string().optional(),
+  })
+  .optional()
+
+/**
+ * Zod schema for Scalar UI configuration options
+ */
+export const scalarOptionsSchema = z.object({
+  /**
+   * Theme for Scalar UI
+   * @default 'default'
+   */
+  theme: scalarThemeSchema.optional(),
+
+  /**
+   * Custom favicon URL
+   */
+  favicon: z.string().optional(),
+
+  /**
+   * Custom logo URL
+   */
+  logo: z.string().optional(),
+
+  /**
+   * Hide the "Download OpenAPI Spec" button
+   * @default false
+   */
+  hideDownloadButton: z.boolean().optional(),
+
+  /**
+   * Hide the "Search" input
+   * @default false
+   */
+  hideSearch: z.boolean().optional(),
+
+  /**
+   * Custom CSS to inject
+   */
+  customCss: z.string().optional(),
+
+  /**
+   * Meta data for the HTML page
+   */
+  metaData: scalarMetaDataSchema,
+
+  /**
+   * CDN URL for Scalar API Reference
+   * @default 'https://cdn.jsdelivr.net/npm/@scalar/api-reference'
+   */
+  cdn: z.string().optional(),
+})
+
+/**
+ * Zod schema for Bun OpenAPI plugin options
+ */
+export const bunOpenApiPluginOptionsSchema = z.object({
+  /**
+   * Path to serve OpenAPI JSON
+   * @default '/openapi.json'
+   */
+  jsonPath: z.string().optional().default('/openapi.json'),
+
+  /**
+   * Path to serve OpenAPI YAML
+   * @default '/openapi.yaml'
+   */
+  yamlPath: z.string().optional().default('/openapi.yaml'),
+
+  /**
+   * Path to serve Scalar UI
+   * @default '/docs'
+   */
+  docsPath: z.string().optional().default('/docs'),
+
+  /**
+   * Scalar UI configuration
+   */
+  scalar: scalarOptionsSchema.optional(),
+
+  /**
+   * Disable JSON endpoint
+   * @default false
+   */
+  disableJson: z.boolean().optional().default(false),
+
+  /**
+   * Disable Scalar UI (only serve JSON/YAML)
+   * @default false
+   */
+  disableScalar: z.boolean().optional().default(false),
+
+  /**
+   * Disable YAML endpoint
+   * @default true
+   */
+  disableYaml: z.boolean().optional().default(true),
+})
+
+export type ScalarTheme = z.infer<typeof scalarThemeSchema>
+export type ScalarMetaData = z.infer<typeof scalarMetaDataSchema>
+export type ScalarOptions = z.infer<typeof scalarOptionsSchema>
+export type BunOpenApiPluginOptionsBase = z.infer<typeof bunOpenApiPluginOptionsSchema>

package/src/services/index.mts

@@ -0,0 +1,4 @@
+export {
+  OpenApiDocumentService,
+  OpenApiDocumentServiceToken,
+} from './openapi-document.service.mjs'