rajt 0.0.75 → 0.0.76

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rajt",
   "description": "A serverless bundler layer, fully typed for AWS Lambda (Node.js and LLRT) and Cloudflare Workers.",
-  "version": "0.0.75",
+  "version": "0.0.76",
   "type": "module",
   "main": "./src/index.ts",
   "bin": {
@@ -42,18 +42,21 @@
     "forj": "^0.0.6",
     "t0n": "^0.1",
     "@hono/node-server": "^1.19.9",
-    "@hono/zod-validator": "^0.7.6",
+    "@hono/standard-validator": "^0.2.2",
     "@iarna/toml": "^2.2.5",
+    "@scalar/hono-api-reference": "^0.9.40",
     "chokidar-cli": "^3.0.0",
     "citty": "^0.1.6",
     "dotenv": "^16.5.0",
     "esbuild": "^0.25.2",
     "hono": "^4.11.7",
+    "hono-openapi": "^1.2.0",
     "miniflare": "^4.20251217.0",
     "tiny-glob": "^0.2",
     "tsx": "^4.19.3",
     "ua-parser-js": "^2.0.8",
-    "wrangler": "^4.61.0"
+    "wrangler": "^4.61.0",
+    "zod-openapi": "4"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20251230.0",

package/src/create-app.ts

@@ -1,11 +1,15 @@
 import { Hono } from 'hono'
 import { logger } from 'hono/logger'
 import { matchedRoutes } from 'hono/route'
+import { basicAuth } from 'hono/basic-auth'
+import { openAPIRouteHandler, describeRoute, resolver } from 'hono-openapi'
+import { Scalar } from '@scalar/hono-api-reference'
 import { Envir, Datte } from 't0n'
 import type {
   Env, Context, Next,
   HTTPResponseError,
   ServerOptions,
+  DescribeRouteOptions,
 } from './types'
 import { resolve, resolveMiddleware } from './utils/resolve'
 import { getMiddlewares, getHandler } from './register'
@@ -13,6 +17,7 @@ import request, { GET_REQUEST } from './request'
 import response from './response'
 import { isDev } from './utils/environment'
 import { gray } from './utils/colors'
+import packageJson from '../../../package.json'
 
 const NFHandler = () => response.notFound()
 const EHandler = async (e: Error | HTTPResponseError) => {
@@ -60,7 +65,7 @@ const EHandler = async (e: Error | HTTPResponseError) => {
   // stack: isDev (? e.stack : undefined
 }
 
-export const createApp = <E extends Env>(options?: ServerOptions<E>) => {
+export const createApp = <E extends Env>(options?: ServerOptions<E> & { configs: any }) => {
   // const root = options?.root ?? '/'
   const app = options?.app ?? new Hono<E>()
 
@@ -110,12 +115,102 @@ export const createApp = <E extends Env>(options?: ServerOptions<E>) => {
   const routes = options?.routes || []
   for (const route of routes) {
     if (Array.isArray(route)) { // @ts-ignore
-      app[route[0]](route[1], ...mw(route[2], route[3]), ...resolve(getHandler(route[3]), route[3]))
+      app[route[0]](route[1], describeRoute(route[4]), ...mw(route[2], route[3]), ...resolve(getHandler(route[3]), route[3]))
     } else { // @ts-ignore
-      app[route.method](route.path, ...mw(route.middlewares, route.name), ...resolve(route.handle, route.name))
+      app[route.method](route.path, describeRoute(route.desc), ...mw(route.middlewares, route.name), ...resolve(route.handle, route.name))
     }
   }
 
+  const _docs = options?.configs?.docs ?? {}
+  const docs = {
+    ..._docs,
+    disable: !!_docs?.disable,
+    path: _docs?.path || '/docs',
+    auth: _docs?.auth || {},
+  }
+
+  if (docs.disable) return app
+
+  if (docs?.auth?.username && docs?.auth?.password) {
+    app.use(docs.path +'/*', async (c, next) => {
+      const realm = docs.auth?.realm || 'Docs'
+      const unauthorized = response.unauthorized(
+        null,
+        {'WWW-Authenticate': `Basic realm="${realm.replace(/"/g, '\\"')}", charset="UTF-8"`}
+      )
+      if (!c.req.raw.headers.get('Authorization')) return unauthorized
+      const auth = basicAuth({ username: docs.auth.username, password: docs.auth.password, realm })
+
+      try {
+        await auth(c, next)
+      } catch {
+        return unauthorized
+      }
+    })
+  }
+
+  const appName = Envir.get('APP_NAME', packageJson?.name || 'API Docs')
+  const appVersion = Envir.get('APP_VERSION', packageJson?.version || '1.0.0')
+
+  app.get(
+    docs.path +'/openapi',
+    openAPIRouteHandler(app, {
+      documentation: {
+        info: {
+          title: appName,
+          version: appVersion,
+          description: Envir.get('APP_DESCRIPTION', packageJson?.description || ''),
+        },
+        components: {
+          securitySchemes: {
+            JWT: {
+              type: 'http',
+              scheme: 'bearer',
+              bearerFormat: 'JWT',
+            },
+          },
+          responses: {
+            500: {
+              description: 'Internal Server Error',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      m: {
+                        type: 'array',
+                        items: { type: 'string' },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+            ...docs?.responses,
+          },
+        },
+      },
+    })
+  )
+
+  app.get(
+    docs.path,
+    Scalar({
+      theme: 'saturn',
+      url: docs.path +'/openapi',
+      showDeveloperTools: 'never',
+      telemetry: false,
+      documentDownloadType: 'json', //'direct',
+      isLoading: true,
+      persistAuth: true,
+      hideClientButton: true,
+      slug: appName.toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/[^\w\s_-]/g, '').replace(/[\s_-]+/g, '_').replace(/[^\x00-\x7F]/g, '') +'_'+ appVersion,
+      // hideDownloadButton: true,
+      // onLoaded: () => document?.querySelectorAll('[href="https://www.scalar.com"]')?.forEach(el => el.remove()),
+      customCss: `[href="https://www.scalar.com"]{display:none}`,
+    })
+  )
+
   return app
 }
 

package/src/dev.ts

@@ -25,6 +25,6 @@ middlewares.forEach(mw => registerMiddleware(mw.handle))
 Ability.fromRoutes(routes)
 Ability.roles = Config.get('roles', {})
 
-const app = createApp({ routes })
+const app = createApp({ routes, configs: Config.get('rajt', {}) })
 
 export default app

package/src/http.ts

@@ -5,7 +5,8 @@ import { Ability } from './auth'
 import mergeMiddleware from './utils/merge-middleware'
 import type {
   Context, Next,
-  IRequest
+  IRequest,
+  DescribeRouteOptions,
 } from './types'
 
 function method(method: string, ...args: any[]): void | ClassDecorator {
@@ -104,6 +105,13 @@ export function Auth(...args: any[]): void | ClassDecorator {
 }
 
 function _auth(target: Function | any) {
+  if (!target?.d) target.d = {}
+  if (!target.d?.security) target.d.security = []
+  target.d.security.push({JWT: []})
+
+  if (!target.d?.responses) target.d.responses = {}
+  target.d.responses[401] = {description: 'Unauthorized'}
+
   mergeMiddleware(target, async (c: Context, next: Next) => {
     const req = c.get(GET_REQUEST as unknown as string) as IRequest
     const ability = Ability.fromAction(target)
@@ -114,3 +122,13 @@ function _auth(target: Function | any) {
     await next()
   })
 }
+
+function _describe(spec: DescribeRouteOptions): ClassDecorator{
+  return (target: any) => {
+    target.d = spec
+  }
+}
+
+export const OpenApi = _describe
+export const Describe = _describe
+export const Desc = _describe

package/src/prod.ts

@@ -12,4 +12,4 @@ Ability.fromRoutes(routes)
 Ability.roles = Config.get('roles', {})
 
 // @ts-ignore
-export const app = createApp({ routes })
+export const app = createApp({ routes, configs: Config.get('rajt', {}) })

package/src/response.ts

@@ -28,13 +28,13 @@ export default class $Response {
     return new Response(body ?? null, b)
   }
 
-  static text(data?: string, status?: StatusCode) {
-    return this.raw(status, data, 'text/plain; charset=UTF-8' as BaseMime)
+  static text(str?: string, status?: StatusCode, headers?: HeaderRecord) {
+    return this.raw(status, str, 'text/plain; charset=UTF-8' as BaseMime, headers)
   }
 
   static json<T>(data?: T, status?: StatusCode, headers?: HeaderRecord) {
     if (data == null)
-      return this.raw(status)
+      return this.raw(status, null, undefined, headers)
 
     return this.raw(status, JSON.stringify(data), 'application/json', headers)
   }
@@ -64,70 +64,70 @@ export default class $Response {
   }
 
   static ok(): Response
-  static ok<T>(data: T): Response
-  static ok<T>(data?: T) {
-    return this.json(data, 200)
+  static ok<T>(data: T, headers?: HeaderRecord): Response
+  static ok<T>(data?: T, headers?: HeaderRecord) {
+    return this.json(data, 200, headers)
   }
 
   static created(): Response
-  static created<T>(data: T): Response
-  static created<T>(data?: T) {
-    return this.json(data, 201)
+  static created<T>(data: T, headers?: HeaderRecord): Response
+  static created<T>(data?: T, headers?: HeaderRecord) {
+    return this.json(data, 201, headers)
   }
 
   static accepted(): Response
-  static accepted<T>(data: T): Response
-  static accepted<T>(data?: T) {
-    return this.json(data, 202)
+  static accepted<T>(data: T, headers?: HeaderRecord): Response
+  static accepted<T>(data?: T, headers?: HeaderRecord) {
+    return this.json(data, 202, headers)
   }
 
-  static deleted() {
-    return this.noContent()
+  static deleted(headers?: HeaderRecord) {
+    return this.noContent(headers)
   }
 
-  static noContent() {
-    return this.raw(204)
+  static noContent(headers?: HeaderRecord) {
+    return this.json(null, 204, headers)
   }
 
   static badRequest(): Response
-  static badRequest(errors?: Errors, msg?: string) {
-    return this.error(errors, msg, 400)
+  static badRequest(errors?: Errors, msg?: string, headers?: HeaderRecord) {
+    return this.error(errors, msg, 400, headers)
   }
 
   static unauthorized(): Response
-  static unauthorized<T>(data: T): Response
-  static unauthorized<T>(data?: T) {
-    return this.json(data, 401)
+  static unauthorized<T>(data: T, headers?: HeaderRecord): Response
+  static unauthorized<T>(data?: T, headers?: HeaderRecord) {
+    return this.json(data, 401, headers)
   }
 
   static forbidden(): Response
-  static forbidden<T>(data: T): Response
-  static forbidden<T>(data?: T) {
-    return this.json(data, 403)
+  static forbidden<T>(data: T, headers?: HeaderRecord): Response
+  static forbidden<T>(data?: T, headers?: HeaderRecord) {
+    return this.json(data, 403, headers)
   }
 
   static notFound(): Response
-  static notFound(msg: string): Response
-  static notFound(msg?: string) {
-    return this.raw(404, msg)
+  static notFound<T>(msg: T, headers?: HeaderRecord): Response
+  static notFound<T>(msg?: T, headers?: HeaderRecord) {
+    return this.json(msg, 404, headers)
   }
 
   static conflict(): Response
-  static conflict(errors?: Errors, msg?: string) {
-    return this.error(errors, msg, 409)
+  static conflict(errors?: Errors, msg?: string, headers?: HeaderRecord) {
+    return this.error(errors, msg, 409, headers)
   }
 
   static unsupportedMediaType(): Response
-  static unsupportedMediaType(errors?: Errors, msg?: string) {
-    return this.error(errors, msg, 415)
+  static unsupportedMediaType(errors?: Errors, msg?: string, headers?: HeaderRecord) {
+    return this.error(errors, msg, 415, headers)
   }
 
   static internalError(): Response
-  static internalError(errors?: Errors, msg?: string) {
-    return this.error(errors, msg, 500)
+  static internalError(errors?: Errors, msg?: string, headers?: HeaderRecord) {
+    return this.error(errors, msg, 500, headers)
   }
 
-  static error(errors?: Errors, msg?: string, status?: ContentfulStatusCode) {
+  static error(errors?: Errors, msg?: string, status?: ContentfulStatusCode, headers?: HeaderRecord) {
     status ??= 500
     if (!errors && !msg)
       return this.raw(status, msg)
@@ -136,6 +136,6 @@ export default class $Response {
     if (msg) resp.m = msg
     if (errors) resp.e = errors
 
-    return this.json(resp, status)
+    return this.json(resp, status, headers)
   }
 }

package/src/routes.ts

@@ -64,6 +64,15 @@ export async function getRoutes(
 
       const m = handle?.m?.toLowerCase()
       const [method, uri] = m ? [m, handle?.p] : [extractHttpVerb(path), extractHttpPath(path)]
+      const d = handle?.d || {}
+      const desc = {
+        summary: handle?.d?.summary || name,
+        ...d,
+        responses: {
+          500: {$ref: '#/components/responses/500'},
+          ...d?.responses,
+        }
+      }
       routes.push({
         method, path: uri,
         name,
@@ -71,6 +80,7 @@ export async function getRoutes(
         // @ts-ignore
         middlewares,
         handle,
+        desc,
       })
 
       if (!keys.has(name)) {
@@ -290,6 +300,7 @@ try {
     route.path,
     route.middlewares,
     route.name,
+    route.desc,
   ])))
 }
 

package/src/types.ts

@@ -7,6 +7,7 @@ import type {
 import type { ResponseHeader } from 'hono/utils/headers'
 // import type { StatusCode } from 'hono/utils/http-status'
 import type { BaseMime } from 'hono/utils/mime'
+import type { DescribeRouteOptions } from 'hono-openapi'
 import z from 'zod'
 import Action from './action'
 import request from './request'
@@ -28,7 +29,7 @@ export type {
   RedirectStatusCode,
   StatusCode,
 } from 'hono/utils/http-status'
-export type { BaseMime }
+export type { BaseMime, DescribeRouteOptions }
 
 type PublicMethods<T> = {
   [K in keyof T]: K extends `#${string}` | `$${string}` | symbol | 'prototype' ? never : K
@@ -52,6 +53,7 @@ export type Route = {
   file: string,
   middlewares: Function[],
   handle: Handlers,
+  desc: DescribeRouteOptions,
 }
 
 // export type ActionType = Function | Handler | Action | (new () => Action)

package/src/validator.ts

@@ -1,5 +1,5 @@
 import { ZodObject } from 'zod'
-import { zValidator } from '@hono/zod-validator'
+import { validator } from 'hono-openapi'
 import response from './response'
 import type {
   Rule, Rules,
@@ -29,16 +29,16 @@ export default class $Validator {
     return fn
   }
 
-  static readonly json = $Validator.fn('json')
-  static readonly form = $Validator.fn('form')
-  static readonly query = $Validator.fn('query')
-  static readonly param = $Validator.fn('param')
-  static readonly header = $Validator.fn('header')
-  static readonly cookie = $Validator.fn('cookie')
+  static readonly json = $Validator.fn('json')!
+  static readonly form = $Validator.fn('form')!
+  static readonly query = $Validator.fn('query')!
+  static readonly param = $Validator.fn('param')!
+  static readonly header = $Validator.fn('header')!
+  static readonly cookie = $Validator.fn('cookie')!
 
   static parse(rules: Rules): Function[] {
     return (Array.isArray(rules) ? rules : [rules]) // @ts-ignore
-      .flatMap(rule => zValidator(rule.target, rule.schema, (result, c) => {
+      .flatMap(rule => validator(rule.target, rule.schema, (result, c) => {
         if (!result.success) // @ts-ignore
           return response.badRequest({ ...result.error.flatten()[rule.eTarget] })
       }))