@ahmedbaset/adminjs-hono 0.1.0

package/src/buildRouter.ts

@@ -0,0 +1,224 @@
+import AdminJS, { Router as AdminRouter } from 'adminjs'
+import type { Hono, Handler, Context } from 'hono'
+import { WrongArgumentError, INVALID_ADMINJS_INSTANCE } from './errors.js'
+import { log } from './logger.js'
+import { convertToHonoRoute } from './convertRoutes.js'
+import type { HonoVariables } from './types.js'
+
+/**
+ * Validates and initializes an AdminJS instance
+ * @param admin - The AdminJS instance to initialize
+ * @throws {WrongArgumentError} If the admin parameter is not a valid AdminJS instance
+ */
+export function initializeAdmin(admin: AdminJS): void {
+  if (admin?.constructor?.name !== 'AdminJS') {
+    throw new WrongArgumentError(INVALID_ADMINJS_INSTANCE)
+  }
+
+  admin.initialize().then(() => {
+    log.debug('AdminJS: bundle ready')
+  })
+}
+
+/**
+ * Creates a Hono route handler from an AdminJS route
+ * Extracts request data and invokes the AdminJS controller
+ * 
+ * @param admin - The AdminJS instance
+ * @param route - The AdminJS route definition
+ * @returns Hono handler function
+ */
+export function routeHandler(
+  admin: AdminJS,
+  route: (typeof AdminRouter)['routes'][0]
+): Handler<{ Variables: HonoVariables }> {
+  return async (c: Context<{ Variables: HonoVariables }>) => {
+    // Get session from context (may be undefined for non-authenticated routes)
+    const session = c.get('session')
+    const adminUser = session?.adminUser
+    
+    // Instantiate the AdminJS controller
+    const controller = new route.Controller({ admin }, adminUser)
+    
+    // Extract request data
+    const params = c.req.param()
+    const query = c.req.query()
+    const method = c.req.method.toLowerCase()
+    
+    // Get parsed form data from context (set by form parser middleware)
+    const fields = c.get('fields') || {}
+    const files = c.get('files') || {}
+    const payload = {
+      ...fields,
+      ...files,
+    }
+    
+    // Execute the controller action
+    const html = await controller[route.action](
+      {
+        ...c.req,
+        params,
+        query,
+        payload,
+        method,
+      },
+      c.res
+    )
+    
+    // Set Content-Type header if specified
+    if (route.contentType) {
+      c.header('Content-Type', route.contentType)
+    }
+    
+    // Return response
+    if (html) {
+      return c.body(html)
+    }
+    
+    // If no response body, return empty response
+    return c.body(null)
+  }
+}
+
+/**
+ * Registers a single AdminJS route with the Hono app
+ * @param route - The AdminJS route to register
+ * @param app - The Hono app instance
+ * @param admin - The AdminJS instance
+ */
+export function buildRoute(
+  route: (typeof AdminRouter)['routes'][number],
+  app: Hono,
+  admin: AdminJS
+): void {
+  // Convert AdminJS route path to Hono format
+  const honoPath = convertToHonoRoute(route.path)
+  
+  // Register handler based on HTTP method
+  if (route.method === 'GET') {
+    app.get(honoPath, routeHandler(admin, route))
+  } else if (route.method === 'POST') {
+    app.post(honoPath, routeHandler(admin, route))
+  }
+}
+
+/**
+ * Registers all AdminJS routes with the Hono app
+ * @param routes - Array of AdminJS routes
+ * @param app - The Hono app instance
+ * @param admin - The AdminJS instance
+ */
+export function buildRoutes(
+  routes: (typeof AdminRouter)['routes'],
+  app: Hono,
+  admin: AdminJS
+): void {
+  routes.forEach((route) => buildRoute(route, app, admin))
+}
+
+/**
+ * Determines Content-Type header based on file extension
+ * @param path - File path
+ * @returns Content-Type string
+ */
+function getContentType(path: string): string {
+  if (path.endsWith('.js')) {
+    return 'application/javascript'
+  } else if (path.endsWith('.css')) {
+    return 'text/css'
+  } else if (path.endsWith('.html')) {
+    return 'text/html'
+  } else if (path.endsWith('.json')) {
+    return 'application/json'
+  } else if (path.endsWith('.png')) {
+    return 'image/png'
+  } else if (path.endsWith('.jpg') || path.endsWith('.jpeg')) {
+    return 'image/jpeg'
+  } else if (path.endsWith('.svg')) {
+    return 'image/svg+xml'
+  }
+  return 'application/octet-stream'
+}
+
+/**
+ * Registers AdminJS asset routes with the Hono app
+ * @param assets - Array of AdminJS assets
+ * @param routes - Array of AdminJS routes (to find component bundler route)
+ * @param app - The Hono app instance
+ * @param admin - The AdminJS instance
+ */
+export function buildAssets(
+  assets: (typeof AdminRouter)['assets'],
+  routes: (typeof AdminRouter)['routes'],
+  app: Hono,
+  admin: AdminJS
+): void {
+  // Register component bundler route if it exists
+  const componentBundlerRoute = routes.find(
+    (r) => r.action === 'bundleComponents'
+  )
+  if (componentBundlerRoute) {
+    buildRoute(componentBundlerRoute, app, admin)
+  }
+  
+  // Register static asset routes
+  assets.forEach((asset) => {
+    app.get(asset.path, async (c) => {
+      try {
+        // Read file using Node.js fs (for Node runtime)
+        // For other runtimes, this would need runtime detection
+        const fs = await import('fs/promises')
+        const path = await import('path')
+        
+        const filePath = path.resolve(asset.src)
+        const fileContent = await fs.readFile(filePath)
+        
+        // Set appropriate Content-Type header
+        const contentType = getContentType(asset.path)
+        c.header('Content-Type', contentType)
+        
+        return c.body(fileContent)
+      } catch (error) {
+        console.error(`Error serving asset ${asset.path}:`, error)
+        return c.text('Asset not found', 404)
+      }
+    })
+  })
+}
+
+import type { UploadOptions } from './types.js'
+import { createFormParserMiddleware } from './formParser.js'
+
+/**
+ * Builds a Hono app with AdminJS routes (without authentication)
+ * 
+ * @param admin - The AdminJS instance
+ * @param predefinedApp - Optional existing Hono app to use
+ * @param uploadOptions - Optional upload configuration
+ * @returns Configured Hono app
+ */
+export function buildRouter(
+  admin: AdminJS,
+  predefinedApp?: Hono,
+  uploadOptions?: UploadOptions
+): Hono {
+  // Initialize AdminJS
+  initializeAdmin(admin)
+  
+  // Use provided app or create new Hono instance
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const { Hono: HonoClass } = require('hono')
+  const app = predefinedApp ?? new HonoClass()
+  
+  // Get routes and assets from AdminJS
+  const { routes, assets } = AdminRouter
+  
+  // Register form parsing middleware
+  app.use('*', createFormParserMiddleware(uploadOptions))
+  
+  // Build assets and routes
+  buildAssets(assets, routes, app, admin)
+  buildRoutes(routes, app, admin)
+  
+  return app
+}

package/src/convertRoutes.ts

@@ -0,0 +1,10 @@
+/**
+ * Converts AdminJS route path format to Hono route path format
+ * AdminJS uses {param} notation while Hono uses :param notation
+ * 
+ * @param path - AdminJS route path (e.g., "/resources/{resourceId}/actions/{action}")
+ * @returns Hono route path (e.g., "/resources/:resourceId/actions/:action")
+ */
+export function convertToHonoRoute(path: string): string {
+  return path.replace(/\{([^}]+)\}/g, ':$1')
+}

package/src/errors.ts

@@ -0,0 +1,24 @@
+export class WrongArgumentError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'WrongArgumentError'
+  }
+}
+
+export const INVALID_ADMINJS_INSTANCE =
+  'You have to pass an instance of AdminJS to the buildRouter() function'
+
+export const MISSING_AUTH_CONFIG_ERROR =
+  'You must provide either "authenticate" function or "provider" in authentication options'
+
+export const INVALID_AUTH_CONFIG_ERROR =
+  'You cannot provide both "authenticate" function and "provider" in authentication options'
+
+export class OldBodyParserUsedError extends Error {
+  constructor() {
+    super(
+      'You are using old body-parser middleware which is not compatible with AdminJS. Please remove it.'
+    )
+    this.name = 'OldBodyParserUsedError'
+  }
+}

package/src/formParser.ts

@@ -0,0 +1,73 @@
+import type { MiddlewareHandler, Context } from 'hono'
+import type { UploadOptions, HonoVariables } from './types.js'
+
+/**
+ * Creates middleware to parse form data (multipart/form-data and application/x-www-form-urlencoded)
+ * Extracts fields and files from the request and stores them in context variables
+ * 
+ * @param options - Upload configuration options
+ * @returns Hono middleware handler
+ */
+export function createFormParserMiddleware(
+  options?: UploadOptions
+): MiddlewareHandler<{ Variables: HonoVariables }> {
+  return async (c: Context<{ Variables: HonoVariables }>, next) => {
+    const contentType = c.req.header('content-type')
+    
+    if (
+      contentType?.includes('multipart/form-data') ||
+      contentType?.includes('application/x-www-form-urlencoded')
+    ) {
+      try {
+        const formData = await c.req.formData()
+        const fields: Record<string, any> = {}
+        const files: Record<string, File> = {}
+        
+        for (const [key, value] of formData.entries()) {
+          if (value instanceof File) {
+            // Check file size if maxFileSize is specified
+            if (options?.maxFileSize && value.size > options.maxFileSize) {
+              throw new Error(
+                `File ${value.name} exceeds maximum size of ${options.maxFileSize} bytes`
+              )
+            }
+            files[key] = value
+          } else {
+            fields[key] = value
+          }
+        }
+        
+        // Check total fields size if maxFieldsSize is specified
+        if (options?.maxFieldsSize) {
+          const totalFieldsSize = Object.values(fields).reduce(
+            (sum, val) => sum + String(val).length,
+            0
+          )
+          if (totalFieldsSize > options.maxFieldsSize) {
+            throw new Error(
+              `Total fields size exceeds maximum of ${options.maxFieldsSize} bytes`
+            )
+          }
+        }
+        
+        // Check number of fields if maxFields is specified
+        if (options?.maxFields && Object.keys(fields).length > options.maxFields) {
+          throw new Error(
+            `Number of fields exceeds maximum of ${options.maxFields}`
+          )
+        }
+        
+        c.set('fields', fields)
+        c.set('files', files)
+      } catch (error) {
+        // Handle parsing errors gracefully
+        console.error('Form parsing error:', error)
+        c.set('fields', {})
+        c.set('files', {})
+        throw error
+      }
+    }
+    
+    await next()
+  }
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+import { buildAuthenticatedRouter } from './buildAuthenticatedRouter.js'
+import { buildRouter } from './buildRouter.js'
+
+/**
+ * @module @ahmedbaset/adminjs-hono
+ * 
+ * AdminJS adapter for Hono web framework
+ * 
+ * Provides two main functions:
+ * - buildRouter: Creates a Hono app with AdminJS routes (no authentication)
+ * - buildAuthenticatedRouter: Creates a Hono app with AdminJS routes protected by session authentication
+ * 
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono'
+ * import AdminJS from 'adminjs'
+ * import { buildRouter } from '@ahmedbaset/adminjs-hono'
+ * 
+ * const admin = new AdminJS({
+ *   databases: [],
+ *   rootPath: '/admin',
+ * })
+ * 
+ * const app = new Hono()
+ * const adminRouter = buildRouter(admin)
+ * app.route('/admin', adminRouter)
+ * ```
+ */
+
+/**
+ * Plugin name
+ */
+export const name = 'AdminJSHono'
+
+/**
+ * Plugin interface
+ */
+export type HonoPlugin = {
+  name: string
+  buildAuthenticatedRouter: typeof buildAuthenticatedRouter
+  buildRouter: typeof buildRouter
+}
+
+/**
+ * Default plugin export
+ */
+const plugin: HonoPlugin = { name, buildAuthenticatedRouter, buildRouter }
+
+export default plugin
+
+// Export main functions
+export { buildRouter } from './buildRouter.js'
+export { buildAuthenticatedRouter } from './buildAuthenticatedRouter.js'
+
+// Export types
+export type {
+  AuthenticationOptions,
+  UploadOptions,
+  AuthenticationMaxRetriesOptions,
+  AuthenticationContext,
+  SessionOptions,
+  SessionData,
+} from './types.js'
+
+// Export utilities
+export { convertToHonoRoute } from './convertRoutes.js'
+export * from './errors.js'
+export { log } from './logger.js'
+
+// Export authentication handlers (for advanced usage)
+export { withLogin } from './authentication/login.handler.js'
+export { withLogout } from './authentication/logout.handler.js'
+export { withProtectedRoutesHandler } from './authentication/protected-routes.handler.js'
+export { withRefresh } from './authentication/refresh.handler.js'

package/src/logger.ts

@@ -0,0 +1,18 @@
+const DEBUG = process.env.ADMINJS_HONO_DEBUG === 'true'
+
+export const log = {
+  debug: (...args: unknown[]) => {
+    if (DEBUG) {
+      console.log('[AdminJS Hono]', ...args)
+    }
+  },
+  info: (...args: unknown[]) => {
+    console.log('[AdminJS Hono]', ...args)
+  },
+  warn: (...args: unknown[]) => {
+    console.warn('[AdminJS Hono]', ...args)
+  },
+  error: (...args: unknown[]) => {
+    console.error('[AdminJS Hono]', ...args)
+  },
+}

package/src/session.ts

@@ -0,0 +1,71 @@
+import { getCookie, setCookie } from 'hono/cookie'
+import type { MiddlewareHandler, Context } from 'hono'
+import type { SessionData, SessionOptions, HonoVariables } from './types.js'
+
+// In-memory session store (not suitable for production with multiple instances)
+const sessions = new Map<string, SessionData>()
+
+/**
+ * Generates a unique session ID using Web Crypto API
+ * @returns A unique session identifier
+ */
+function generateSessionId(): string {
+  return crypto.randomUUID()
+}
+
+/**
+ * Creates session middleware for Hono
+ * Manages cookie-based sessions with in-memory storage
+ * 
+ * @param secret - Secret key for session (currently unused, for future HMAC signing)
+ * @param cookieName - Name of the session cookie
+ * @param options - Session cookie options
+ * @returns Hono middleware handler
+ */
+export function createSessionMiddleware(
+  secret: string,
+  cookieName: string,
+  options?: SessionOptions
+): MiddlewareHandler<{ Variables: HonoVariables }> {
+  return async (c: Context<{ Variables: HonoVariables }>, next) => {
+    let sessionId = getCookie(c, cookieName)
+    
+    // Create new session if none exists or session not found
+    if (!sessionId || !sessions.has(sessionId)) {
+      sessionId = generateSessionId()
+      sessions.set(sessionId, {})
+    }
+    
+    // Get session data and store in context
+    const session = sessions.get(sessionId)!
+    c.set('session', session)
+    
+    await next()
+    
+    // Save session cookie after request processing
+    setCookie(c, cookieName, sessionId, {
+      httpOnly: options?.httpOnly ?? true,
+      secure: options?.secure ?? false,
+      sameSite: options?.sameSite ?? 'Lax',
+      maxAge: options?.maxAge ?? 86400, // 24 hours default
+      path: options?.path ?? '/',
+      domain: options?.domain,
+    })
+  }
+}
+
+/**
+ * Destroys a session by removing it from the store
+ * @param sessionId - The session ID to destroy
+ */
+export function destroySession(sessionId: string): void {
+  sessions.delete(sessionId)
+}
+
+/**
+ * Gets the session store (for testing purposes)
+ * @returns The session store Map
+ */
+export function getSessionStore(): Map<string, SessionData> {
+  return sessions
+}

package/src/types.ts

@@ -0,0 +1,53 @@
+import type { BaseAuthProvider, CurrentAdmin } from 'adminjs'
+import type { Context } from 'hono'
+
+export type UploadOptions = {
+  uploadDir?: string
+  maxFileSize?: number
+  maxFieldsSize?: number
+  maxFields?: number
+  keepExtensions?: boolean
+}
+
+// Hono context variables
+export type HonoVariables = {
+  session: SessionData
+  fields: Record<string, any>
+  files: Record<string, File>
+}
+
+export type AuthenticationContext = {
+  req: Context<{ Variables: HonoVariables }>
+  res: Context<{ Variables: HonoVariables }>
+}
+
+export type AuthenticationMaxRetriesOptions = {
+  count: number
+  duration: number // in seconds
+}
+
+export type AuthenticationOptions = {
+  cookiePassword: string
+  cookieName?: string
+  authenticate?: (
+    email: string,
+    password: string,
+    context?: AuthenticationContext
+  ) => Promise<CurrentAdmin | null> | CurrentAdmin | null
+  maxRetries?: number | AuthenticationMaxRetriesOptions
+  provider?: BaseAuthProvider
+}
+
+export type SessionOptions = {
+  maxAge?: number
+  httpOnly?: boolean
+  secure?: boolean
+  sameSite?: 'Strict' | 'Lax' | 'None'
+  domain?: string
+  path?: string
+}
+
+export type SessionData = {
+  adminUser?: CurrentAdmin
+  redirectTo?: string
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./lib",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "lib", "test", "examples"]
+}

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+})