fusion-framework 1.2.2 → 1.2.4

package/index.js

@@ -134,7 +134,7 @@ header.fingerprint = () =>
     : {
         'X-Powered-By': 'Fusion Framework',
         'X-Framework': 'Fusion',
-        ['X-Fusion-Version']: '1.2.2',
+        ['X-Fusion-Version']: '1.2.4',
       }
 
 function isThenable(value) {
@@ -219,6 +219,121 @@ function resolveRoutePath(routePath, ApiClass) {
   return native.resolveRoutePathJs(routePath, ApiClass.name)
 }
 
+function apiActionName(methodName) {
+  if (typeof native.apiActionNameJs === 'function') {
+    return native.apiActionNameJs(methodName)
+  }
+  let stem = methodName
+  if (methodName.endsWith('Action') && methodName.length > 6) stem = methodName.slice(0, -6)
+  else if (methodName.endsWith('ACTION') && methodName.length > 6) stem = methodName.slice(0, -6)
+  return stem.toLowerCase()
+}
+
+function resolveMethodRoutePath(template, className, methodName) {
+  if (typeof native.resolveMethodRoutePathJs === 'function') {
+    return native.resolveMethodRoutePathJs(template, className, methodName)
+  }
+  return resolveRoutePath(template, { name: className }).replace(
+    /\[action\]/g,
+    apiActionName(methodName),
+  )
+}
+
+function joinRoutePaths(base, segment) {
+  const left = String(base || '').replace(/\/+$/, '')
+  const right = String(segment || '').replace(/^\/+|\/+$/g, '')
+  if (!right) return left || '/'
+  if (!left) return `/${right}`
+  return `${left}/${right}`
+}
+
+function resolveHandlerRoute(classBasePath, template, className, methodName) {
+  if (typeof native.resolveHandlerRouteJs === 'function') {
+    return native.resolveHandlerRouteJs(classBasePath, template, className, methodName)
+  }
+  const resolved = resolveMethodRoutePath(template, className, methodName)
+  if (String(template).startsWith('/')) {
+    return joinRoutePaths('', resolved.replace(/^\/+/, ''))
+  }
+  return joinRoutePaths(classBasePath, resolved)
+}
+
+function httpRoute(method, route, options = {}) {
+  const meta = {
+    method: String(method).toLowerCase(),
+    template: route,
+    tags: Array.isArray(options.tags) ? options.tags : [],
+    desc: options.desc ?? null,
+    title: options.title ?? null,
+    deprecated: !!options.deprecated,
+  }
+  function wrap(fn) {
+    fn.__fusionHttpRoute = meta
+    return fn
+  }
+  return wrap
+}
+
+function httpGet(route, options = {}) {
+  return httpRoute('get', route, options)
+}
+function httpPost(route, options = {}) {
+  return httpRoute('post', route, options)
+}
+function httpPut(route, options = {}) {
+  return httpRoute('put', route, options)
+}
+function httpPatch(route, options = {}) {
+  return httpRoute('patch', route, options)
+}
+function httpDelete(route, options = {}) {
+  return httpRoute('delete', route, options)
+}
+function httpHead(route, options = {}) {
+  return httpRoute('head', route, options)
+}
+function httpOptions(route, options = {}) {
+  return httpRoute('options', route, options)
+}
+
+function collectRouteSlots(ApiClass, classBasePath, classSwagger) {
+  const slots = []
+  const custom = new Set()
+  const className = ApiClass.name
+
+  for (const key of Object.getOwnPropertyNames(ApiClass.prototype)) {
+    if (key === 'constructor' || key.startsWith('_')) continue
+    const fn = ApiClass.prototype[key]
+    if (typeof fn !== 'function' || !fn.__fusionHttpRoute) continue
+    custom.add(key)
+    const meta = fn.__fusionHttpRoute
+    slots.push({
+      path: resolveHandlerRoute(classBasePath, meta.template, className, key),
+      httpMethod: meta.method,
+      handlerMethod: key,
+      swagger: {
+        tags: meta.tags,
+        description: meta.desc,
+        title: meta.title,
+        deprecated: meta.deprecated,
+      },
+    })
+  }
+
+  for (const methodName of HTTP_METHODS) {
+    if (custom.has(methodName)) continue
+    if (!definesMethod(ApiClass, methodName)) continue
+    slots.push({
+      path: classBasePath,
+      httpMethod: methodName,
+      handlerMethod: methodName,
+      swagger: classSwagger,
+    })
+  }
+
+  return slots
+}
+
 function emptyRequest() {
   return {
     method: '',
@@ -372,17 +487,21 @@ function router(routePath, options = {}) {
       )
     }
 
+    const classSwagger = {
+      tags: Array.isArray(options.tags) ? options.tags : [],
+      description: options.desc ?? null,
+      title: options.title ?? null,
+      deprecated: !!options.deprecated,
+    }
+
     registry.push({
       path: resolved,
+      classBasePath: resolved,
       ApiClass,
       middleware: routeMiddleware,
-      swagger: {
-        tags: Array.isArray(options.tags) ? options.tags : [],
-        description: options.desc ?? null,
-        title: options.title ?? null,
-        deprecated: !!options.deprecated,
-      },
+      swagger: classSwagger,
       version_prefix: v,
+      slots: collectRouteSlots(ApiClass, resolved, classSwagger),
     })
     return ApiClass
   }
@@ -487,7 +606,9 @@ function readSwaggerSettings() {
   const navbar = {
     enabled: truthyEnabled(navbarRaw.enabled, true),
     showUrlInput: truthyEnabled(navbarRaw.showUrlInput, true),
+    showUrlInputSet: Object.prototype.hasOwnProperty.call(navbarRaw, 'showUrlInput'),
     urls: Array.isArray(navbarRaw.urls) ? navbarRaw.urls : null,
+    urlsSet: Array.isArray(navbarRaw.urls),
   }
 
   const ui = {
@@ -532,6 +653,60 @@ function readSwaggerSettings() {
   }
 }
 
+const UNVERSIONED_SWAGGER_NAME = 'default'
+
+function normalizeVersionLabel(value) {
+  return String(value || '')
+    .trim()
+    .replace(/^\/+|\/+$/g, '')
+}
+
+function collectRouteVersions() {
+  const versions = []
+  let hasUnversioned = false
+  for (const item of registry) {
+    const version = normalizeVersionLabel(item.version_prefix)
+    if (!version) {
+      hasUnversioned = true
+      continue
+    }
+    if (!versions.includes(version)) versions.push(version)
+  }
+  return { versions, hasUnversioned }
+}
+
+function swaggerVersionUrls(prefix) {
+  const { versions, hasUnversioned } = collectRouteVersions()
+  const urls = versions.map((label) => ({
+    url: `${prefix}/${label}/openapi.json`,
+    name: label,
+  }))
+  if (hasUnversioned && urls.length) {
+    urls.push({
+      url: `${prefix}/${UNVERSIONED_SWAGGER_NAME}/openapi.json`,
+      name: UNVERSIONED_SWAGGER_NAME,
+    })
+  }
+  return urls
+}
+
+function applyVersionNavbar(swagger) {
+  const autoUrls = swaggerVersionUrls(swagger.path)
+  if (!swagger.navbar.urlsSet && autoUrls.length) {
+    swagger.navbar.urls = autoUrls
+    if (!swagger.navbar.showUrlInputSet) swagger.navbar.showUrlInput = false
+  }
+  return autoUrls.map((item) => item.name)
+}
+
+function routeMatchesVersion(item, filter) {
+  const version = normalizeVersionLabel(item.version_prefix)
+  if (filter == null) return true
+  const label = normalizeVersionLabel(filter)
+  if (!label || label.toLowerCase() === UNVERSIONED_SWAGGER_NAME) return !version
+  return version.toLowerCase() === label.toLowerCase()
+}
+
 function applySwaggerOpenApi(openapi, swagger) {
   openapi.info = { ...asObject(openapi.info), ...swagger.info }
   if (swagger.servers?.length) openapi.servers = swagger.servers
@@ -546,7 +721,66 @@ function applySwaggerOpenApi(openapi, swagger) {
   return openapi
 }
 
-function swaggerUiHtml(swagger, openapiUrl) {
+function fillOpenApiPaths(openapi, versionFilter = null) {
+  const parsePathParams = (pattern) => {
+    return String(pattern)
+      .split('/')
+      .filter((seg) => (seg.startsWith('{') && seg.endsWith('}')) || (seg.startsWith('[') && seg.endsWith(']')))
+      .map((seg) => seg.slice(1, -1))
+  }
+
+  for (const item of registry) {
+    if (!routeMatchesVersion(item, versionFilter)) continue
+    const { ApiClass, swagger: routeSwagger } = item
+    const slots = item.slots || []
+
+    for (const slot of slots) {
+      const pathParams = parsePathParams(slot.path)
+      const resolvedPath = slot.path.startsWith('/') ? slot.path : `/${slot.path}`
+      const routeSwaggerEntry = slot.swagger || routeSwagger
+
+      if (!openapi.paths[resolvedPath]) openapi.paths[resolvedPath] = {}
+
+      const methodLower = String(slot.httpMethod).toLowerCase()
+      const methodUpper = methodLower.toUpperCase()
+      const params = pathParams.map((name) => ({
+        name,
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      }))
+
+      openapi.paths[resolvedPath][methodLower] = {
+        tags: routeSwaggerEntry?.tags?.length ? routeSwaggerEntry.tags : [],
+        summary: routeSwaggerEntry?.title ?? `${ApiClass.name}.${slot.handlerMethod}`,
+        description: routeSwaggerEntry?.description ?? '',
+        deprecated: !!routeSwaggerEntry?.deprecated,
+        operationId: `${ApiClass.name}_${slot.handlerMethod}`,
+        parameters: params,
+        responses: { 200: { description: 'OK' } },
+      }
+    }
+  }
+  return openapi
+}
+
+function buildOpenApi(swagger, version = null) {
+  const openapi = applySwaggerOpenApi(
+    {
+      openapi: '3.0.3',
+      info: { ...swagger.info },
+      paths: {},
+    },
+    swagger,
+  )
+  const label = normalizeVersionLabel(version)
+  if (label && label !== UNVERSIONED_SWAGGER_NAME) {
+    openapi.info = { ...openapi.info, version: label }
+  }
+  return fillOpenApiPaths(openapi, version)
+}
+
+function swaggerUiHtml(swagger, openapiUrl, primaryName = null) {
   const uiOpts = { ...swagger.ui }
   delete uiOpts.presets
   delete uiOpts.plugins
@@ -555,9 +789,12 @@ function swaggerUiHtml(swagger, openapiUrl) {
   if (swagger.navbar?.urls?.length) {
     delete uiOpts.url
     uiOpts.urls = swagger.navbar.urls
+    const name = primaryName || swagger.navbar.urls[0]?.name
+    if (name) uiOpts['urls.primaryName'] = name
   } else {
     uiOpts.url = openapiUrl
     delete uiOpts.urls
+    delete uiOpts['urls.primaryName']
   }
   uiOpts.dom_id = '#swagger-ui'
 
@@ -573,7 +810,7 @@ function swaggerUiHtml(swagger, openapiUrl) {
   const showUrlInput = swagger.navbar?.showUrlInput !== false
   const hideUrlCss =
     navbarEnabled && !showUrlInput
-      ? `<style>.topbar .download-url-wrapper { display: none !important; }</style>`
+      ? `<style>.topbar form { display: none !important; }</style>`
       : ''
   const standaloneScript = navbarEnabled
     ? `<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-standalone-preset.js"></script>`
@@ -633,16 +870,16 @@ class FusionApp {
     if (this.mounted) return
     activeGlobalMiddleware = [...this._middleware]
 
-    for (const { path: routePath, ApiClass, middleware: routeMiddleware = [] } of registry) {
-      for (const methodName of HTTP_METHODS) {
-        if (!definesMethod(ApiClass, methodName)) continue
-        this.engine.route(methodName.toUpperCase(), routePath, (errOrRequest, maybeRequest) => {
+    for (const { ApiClass, middleware: routeMiddleware = [], slots = [] } of registry) {
+      for (const slot of slots) {
+        const handlerMethod = slot.handlerMethod
+        this.engine.route(String(slot.httpMethod).toUpperCase(), slot.path, (errOrRequest, maybeRequest) => {
           const request = nativeRequestArg(errOrRequest, maybeRequest)
           const chain = [...activeGlobalMiddleware, ...routeMiddleware]
           const handler = async (req) => {
             try {
               const instance = new ApiClass(req || emptyRequest())
-              const fn = instance[methodName]
+              const fn = instance[handlerMethod]
               return await Promise.resolve(fn.call(instance))
             } catch (err) {
               if (err instanceof HTTPException) return err.toResponse()
@@ -657,64 +894,26 @@ class FusionApp {
     const swagger = readSwaggerSettings()
     if (swagger.enabled) {
       const prefix = swagger.path
+      const labels = applyVersionNavbar(swagger)
+      const combined = buildOpenApi(swagger)
 
-      const openapi = applySwaggerOpenApi(
-        {
-          openapi: '3.0.3',
-          info: { ...swagger.info },
-          paths: {},
-        },
-        swagger,
-      )
-
-      const parsePathParams = (pattern) => {
-        return String(pattern)
-          .split('/')
-          .filter((seg) => (seg.startsWith('{') && seg.endsWith('}')) || (seg.startsWith('[') && seg.endsWith(']')))
-          .map((seg) => seg.slice(1, -1))
-      }
-
-      for (const item of registry) {
-        const { path: p, ApiClass, swagger: routeSwagger } = item
-        const pathParams = parsePathParams(p)
-        const resolvedPath = p.startsWith('/') ? p : `/${p}`
-
-        if (!openapi.paths[resolvedPath]) openapi.paths[resolvedPath] = {}
-
-        for (const methodName of HTTP_METHODS) {
-          if (!definesMethod(ApiClass, methodName)) continue
-
-          const methodUpper = String(methodName).toUpperCase()
-          const methodLower = String(methodName).toLowerCase()
-
-          const params = pathParams.map((name) => ({
-            name,
-            in: 'path',
-            required: true,
-            schema: { type: 'string' },
-          }))
-
-          openapi.paths[resolvedPath][methodLower] = {
-            tags: routeSwagger?.tags?.length ? routeSwagger.tags : [],
-            summary: routeSwagger?.title ?? `${ApiClass.name}.${methodUpper}`,
-            description: routeSwagger?.description ?? '',
-            deprecated: !!routeSwagger?.deprecated,
-            operationId: `${ApiClass.name}_${methodLower}`,
-            parameters: params,
-            responses: { '200': { description: 'OK' } },
-          }
-        }
-      }
-
-      const uiEnvelope = () => ({
+      const htmlEnvelope = (primaryName = null) => ({
         status: 200,
-        body: swaggerUiHtml(swagger, `${prefix}/openapi.json`),
+        body: swaggerUiHtml(swagger, `${prefix}/openapi.json`, primaryName),
         headers: { 'content-type': 'text/html' },
       })
-      this.engine.route('GET', `${prefix}/openapi.json`, () => openapi)
-      this.engine.route('GET', prefix, uiEnvelope)
+
+      this.engine.route('GET', `${prefix}/openapi.json`, () => combined)
+      this.engine.route('GET', prefix, () => htmlEnvelope())
       if (prefix !== '/') {
-        this.engine.route('GET', `${prefix}/`, uiEnvelope)
+        this.engine.route('GET', `${prefix}/`, () => htmlEnvelope())
+      }
+
+      for (const label of labels) {
+        const spec = buildOpenApi(swagger, label)
+        this.engine.route('GET', `${prefix}/${label}/openapi.json`, () => spec)
+        this.engine.route('GET', `${prefix}/${label}`, () => htmlEnvelope(label))
+        this.engine.route('GET', `${prefix}/${label}/`, () => htmlEnvelope(label))
       }
     }
 
@@ -772,8 +971,17 @@ module.exports = {
   HTTPException,
   router,
   route,
+  httpGet,
+  httpPost,
+  httpPut,
+  httpPatch,
+  httpDelete,
+  httpHead,
+  httpOptions,
   apiResourceName,
   resolveRoutePath,
+  resolveHandlerRoute,
+  apiActionName,
   configure,
   getSettings,
   settings,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fusion-framework",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Class-based HTTP framework for Node.js, powered by a shared Rust core via N-API",
   "keywords": [
     "http",