jax-hono 1.0.15 → 1.0.17

package/build/generate-registry.ts

@@ -1,10 +1,12 @@
-import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
-import { cwd } from 'node:process'
-import { basename, join, parse, relative } from 'node:path'
-import { ensureGeneratedDir, generatedDir, packageDir, projectDir } from './generated-path'
-
-const srcDir = join(cwd(), 'src')
-const moduleExtensions = new Set(['.ts', '.js', '.mjs', '.cjs'])
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { cwd } from 'node:process'
+import { basename, dirname, isAbsolute, join, parse, relative, resolve } from 'node:path'
+import { ensureGeneratedDir, generatedDir, packageDir, projectDir } from './generated-path'
+
+const srcDir = join(cwd(), 'src')
+const projectRequire = createRequire(join(projectDir, 'package.json'))
+const moduleExtensions = new Set(['.ts', '.js', '.mjs', '.cjs'])
 const generatedHeader = `// This file is generated by jax-hono/build/generate-registry.ts.
 // Do not edit it directly.
 `
@@ -23,7 +25,13 @@ type PluginConfigItem =
       options?: unknown
     }
 
-type PluginConfig = Record<string, PluginConfigItem>
+type PluginConfig = Record<string, PluginConfigItem>
+
+type EnabledPlugin = {
+  name: string
+  packageName: string
+  rootDir: string
+}
 
 const controllerGroups: ControllerGroup[] = [
   { name: 'api', dirs: ['api', 'controllers/api', 'controller/api', 'modules'], suffix: '.api' },
@@ -83,18 +91,36 @@ function toImportPath(filePath: string) {
   return path
 }
 
-function toIdentifier(parts: string[]) {
-  const value = parts
-    .join('_')
+function toIdentifier(parts: string[]) {
+  const value = parts
+    .join('_')
     .replace(/[^a-zA-Z0-9_$]/g, '_')
     .replace(/^([^a-zA-Z_$])/, '_$1')
-
-  return value || 'module'
-}
-
-function toCamelCase(value: string) {
-  return value.replace(/[-_]+([a-zA-Z0-9])/g, (_match, char: string) => char.toUpperCase())
-}
+
+  return value || 'module'
+}
+
+function toLowerCamelIdentifier(parts: string[], suffix = '') {
+  const words = parts
+    .join('/')
+    .split(/[^a-zA-Z0-9_$]+/)
+    .filter(Boolean)
+  const value = words
+    .map((word, index) => {
+      const normalized = toCamelCase(word)
+
+      return index === 0
+        ? normalized.charAt(0).toLowerCase() + normalized.slice(1)
+        : toPascalCase(normalized)
+    })
+    .join('')
+
+  return toIdentifier([`${value}${suffix}`])
+}
+
+function toCamelCase(value: string) {
+  return value.replace(/[-_]+([a-zA-Z0-9])/g, (_match, char: string) => char.toUpperCase())
+}
 
 function toPascalCase(value: string) {
   const camel = toCamelCase(value)
@@ -146,8 +172,8 @@ function normalizeModulePath(modulePath: string) {
   return modulePath
 }
 
-function toModulePath(baseDir: string, filePath: string, suffixes: string[] = []) {
-  const modulePath = relative(join(srcDir, baseDir), filePath)
+function toModulePath(baseDir: string, filePath: string, suffixes: string[] = []) {
+  const modulePath = relative(join(srcDir, baseDir), filePath)
     .replace(parse(filePath).ext, '')
     .replaceAll('\\', '/')
   const withoutIndex = modulePath.endsWith('/index')
@@ -156,16 +182,36 @@ function toModulePath(baseDir: string, filePath: string, suffixes: string[] = []
 
   const stripped = stripKnownSuffix(withoutIndex, suffixes)
 
-  return baseDir === 'modules' ? normalizeModulePath(stripped) : stripped
-}
+  return baseDir === 'modules' ? normalizeModulePath(stripped) : stripped
+}
+
+function toPluginModulePath(pluginName: string, rootDir: string, filePath: string, suffixes: string[] = []) {
+  const modulePath = relative(rootDir, filePath)
+    .replace(parse(filePath).ext, '')
+    .replaceAll('\\', '/')
+  const withoutIndex = modulePath.endsWith('/index')
+    ? modulePath.slice(0, -'/index'.length)
+    : modulePath
+  const stripped = stripKnownSuffix(withoutIndex, suffixes)
+
+  return normalizeModulePath(stripped ? `${pluginName}/${stripped}` : pluginName)
+}
 
 function uniqueSorted(values: string[]) {
   return [...new Set(values)].sort((left, right) => left.localeCompare(right))
 }
 
-function getFilesFromDirs(dirs: string[]) {
-  return uniqueSorted(dirs.flatMap((dirName) => walkFiles(join(srcDir, dirName))))
-}
+function getFilesFromDirs(dirs: string[]) {
+  return uniqueSorted(dirs.flatMap((dirName) => walkFiles(join(srcDir, dirName))))
+}
+
+function getEnabledPluginFiles(suffix: string) {
+  return getEnabledPlugins().flatMap((plugin) => {
+    return walkFiles(plugin.rootDir)
+      .filter((filePath) => isSuffixedModuleFile(filePath, suffix))
+      .map((filePath) => ({ ...plugin, filePath }))
+  })
+}
 
 function isFileInDir(filePath: string, dirName: string) {
   const rel = relative(join(srcDir, dirName), filePath)
@@ -230,13 +276,14 @@ function buildNestedObject(entries: { path: string[]; value: string }[]): string
   return lines.join('\n')
 }
 
-function generateControllersRegistry() {
-  const used = new Set<string>()
-  const imports: string[] = []
-  const groupLines: string[] = []
-
-  for (const group of controllerGroups) {
-    const entries = getFilesFromDirs(group.dirs)
+function generateControllersRegistry() {
+  const used = new Set<string>()
+  const imports: string[] = []
+  const controllerExports: string[] = []
+  const groupLines: string[] = []
+
+  for (const group of controllerGroups) {
+    const projectEntries = getFilesFromDirs(group.dirs)
       .filter((filePath) => basename(filePath) !== 'index.ts')
       .filter((filePath) => !group.suffix || isModuleFeatureFile(filePath, group.suffix))
       .filter(hasDefaultExport)
@@ -246,12 +293,26 @@ function generateControllersRegistry() {
         }) ?? group.dirs[0]
         const modulePath = toModulePath(baseDir, filePath, group.suffix ? [group.suffix] : [])
         const importName = toIdentifier([group.name, modulePath, String(index), 'Controller'])
+        const exportName = toLowerCamelIdentifier(group.name === 'controller' ? [modulePath] : [group.name, modulePath], 'Controller')
 
-        return { modulePath, importName, filePath }
-      })
-      .filter((entry) => {
-        if (group.name !== 'controller') {
-          return true
+        return { modulePath, importName, exportName, filePath }
+      })
+    const pluginEntries = group.name === 'controller'
+      ? getEnabledPluginFiles('.controller')
+        .filter(({ filePath }) => basename(filePath) !== 'index.ts')
+        .filter(({ filePath }) => hasDefaultExport(filePath))
+        .map(({ name, rootDir, filePath }, index) => {
+          const modulePath = toPluginModulePath(name, rootDir, filePath, ['.controller'])
+          const importName = toIdentifier([group.name, 'plugin', modulePath, String(index), 'Controller'])
+          const exportName = toLowerCamelIdentifier([modulePath], 'Controller')
+
+          return { modulePath, importName, exportName, filePath }
+        })
+      : []
+    const entries = [...projectEntries, ...pluginEntries]
+      .filter((entry) => {
+        if (group.name !== 'controller') {
+          return true
         }
 
         const [scope] = entry.modulePath.split('/')
@@ -270,81 +331,106 @@ function generateControllersRegistry() {
         return true
       })
 
-    imports.push(...entries.map((entry) => `import ${entry.importName} from '${toImportPath(entry.filePath)}'`))
-
-    if (entries.length === 0) {
-      continue
+    imports.push(...entries.map((entry) => `import ${entry.importName} from '${toImportPath(entry.filePath)}'`))
+    controllerExports.push(...entries.map((entry) => `export const ${entry.exportName} = createController(${entry.importName})`))
+
+    if (entries.length === 0) {
+      continue
     }
 
-    const objectBody = indentObject(
-      buildNestedObject(entries.map((entry) => ({
-        path: entry.modulePath.split('/').map(toCamelCase),
-        value: `createController(${entry.importName})`,
-      }))),
-      4,
-    )
-
+    const objectBody = buildNestedObject(entries.map((entry) => ({
+      path: entry.modulePath.split('/').map(toCamelCase),
+      value: entry.exportName,
+    })))
+
     if (group.name === 'controller') {
-      groupLines.push(objectBody)
+      groupLines.push(indentObject(objectBody, 2))
     } else {
-      groupLines.push(`  ${group.name}: {\n${objectBody}\n  },`)
+      groupLines.push(`  ${group.name}: {\n${indentObject(objectBody, 4)}\n  },`)
     }
   }
 
   const helperImport = imports.length > 0
     ? `import { createController } from 'jax-hono/core/controller'\n`
     : ''
-  const content = `${generatedHeader}
-${helperImport}${imports.join('\n')}
-
-export const controllers = {
-${groupLines.join('\n')}
+  const content = `${generatedHeader}
+${helperImport}${imports.join('\n')}
+
+${controllerExports.join('\n')}
+
+export const controllers = {
+${groupLines.join('\n')}
 }
 `
 
   writeGeneratedFile('controllers.generated.ts', content)
 }
 
-function toObjectKey(value: string) {
-  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(value) ? value : JSON.stringify(value)
-}
-
-function generateMiddlewaresRegistry() {
-  const files = getFilesFromDirs(['middlewares', 'middleware', 'modules'])
-    .filter((filePath) => isModuleFeatureFile(filePath, '.middleware'))
-  const imports: string[] = []
-  const entries: string[] = []
-
-  files.forEach((filePath, index) => {
-    const source = readFileSync(filePath, 'utf8')
-    const exportNames = [...source.matchAll(/\bexport\s+(?:const|function)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g)]
-      .map((match) => match[1])
-      .sort((left, right) => left.localeCompare(right))
-
-    if (exportNames.length === 0) {
-      return
-    }
-
-    imports.push(`import { ${exportNames.join(', ')} } from '${toImportPath(filePath)}'`)
-    entries.push(...exportNames.map((name) => `  ${toMiddlewareKey(name)}: ${name},`))
-  })
-
-  const content = `${generatedHeader}
-${imports.join('\n')}
-
-export const middlewares = {
-${entries.join('\n')}
-}
-`
-
-  writeGeneratedFile('middlewares.generated.ts', content)
-}
+function toObjectKey(value: string) {
+  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(value) ? value : JSON.stringify(value)
+}
+
+function formatExportBlock(names: string[]) {
+  if (names.length === 0) {
+    return ''
+  }
+
+  return `export {\n${names.map((name) => `  ${name},`).join('\n')}\n}\n`
+}
+
+function createGeneratedContent(sections: string[]) {
+  return `${generatedHeader}\n${sections
+    .map((section) => section.trimEnd())
+    .filter((section) => section.trim())
+    .join('\n\n')}\n`
+}
+
+function generateMiddlewaresRegistry() {
+  const files = getFilesFromDirs(['middlewares', 'middleware', 'modules'])
+    .filter((filePath) => isModuleFeatureFile(filePath, '.middleware'))
+  const imports: string[] = []
+  const entries: string[] = []
+  const exportNames = new Set<string>()
+
+  files.forEach((filePath) => {
+    const source = readFileSync(filePath, 'utf8')
+    const middlewareNames = [...source.matchAll(/\bexport\s+(?:const|function)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g)]
+      .map((match) => match[1])
+      .sort((left, right) => left.localeCompare(right))
+
+    if (middlewareNames.length === 0) {
+      return
+    }
+
+    imports.push(`import { ${middlewareNames.join(', ')} } from '${toImportPath(filePath)}'`)
+    middlewareNames.forEach((name) => exportNames.add(name))
+    entries.push(...middlewareNames.map((name) => {
+      const key = toMiddlewareKey(name)
+
+      return key === name
+        ? `  ${name},`
+        : `  ${key}: ${name},`
+    }))
+  })
+
+  const exportBlock = formatExportBlock(Array.from(exportNames).sort((left, right) => left.localeCompare(right)))
+  const content = createGeneratedContent([
+    imports.join('\n'),
+    exportBlock,
+    `export const middlewares = {
+${entries.join('\n')}
+}`,
+  ])
+
+  writeGeneratedFile('middlewares.generated.ts', content)
+}
 
 function generateModelsRegistry() {
-  const files = getFilesFromDirs(['models', 'model', 'modules'])
-    .filter((filePath) => isModuleFeatureFile(filePath, '.model'))
-  const imports: string[] = []
-  const entries: string[] = []
+  const files = getFilesFromDirs(['models', 'model', 'modules'])
+    .filter((filePath) => isModuleFeatureFile(filePath, '.model'))
+  const imports: string[] = []
+  const entries: string[] = []
+  const exportNames = new Set<string>()
 
   files.forEach((filePath) => {
     const source = readFileSync(filePath, 'utf8')
@@ -362,25 +448,31 @@ function generateModelsRegistry() {
       filePath,
       ['.model'],
     ))
-
-    imports.push(`import { ${exportedModels.join(', ')} } from '${toImportPath(filePath)}'`)
-    entries.push(...exportedModels.map((name) => {
+
+    imports.push(`import { ${exportedModels.join(', ')} } from '${toImportPath(filePath)}'`)
+    exportedModels.forEach((name) => exportNames.add(name))
+    entries.push(...exportedModels.map((name) => {
       const key = exportedModels.length === 1 && modelKey
         ? modelKey
         : name === `${fileModelName}Model`
           ? fileModelName
           : name
 
-      return `  ${key}: ${name},`
-    }))
-  })
-
-  const content = `${generatedHeader}
-${imports.join('\n')}
-
-export const models = {
-${entries.join('\n')}
-}
+      return key === name
+        ? `  ${name},`
+        : `  ${key}: ${name},`
+    }))
+  })
+
+  const exportBlock = formatExportBlock(Array.from(exportNames).sort((left, right) => left.localeCompare(right)))
+
+  const content = `${generatedHeader}
+${imports.join('\n')}
+
+${exportBlock}
+export const models = {
+${entries.join('\n')}
+}
 
 export type Models = typeof models
 `
@@ -388,21 +480,30 @@ export type Models = typeof models
   writeGeneratedFile('models.generated.ts', content)
 }
 
-function generateServicesRegistry() {
-  const files = getFilesFromDirs(['services', 'service', 'modules'])
-    .filter((filePath) => isModuleFeatureFile(filePath, '.service'))
-  const imports: string[] = []
-  const entries: string[] = []
-
-  files.forEach((filePath) => {
-    const source = readFileSync(filePath, 'utf8')
-    const namedServiceClasses = [...source.matchAll(/\bexport\s+class\s+([a-zA-Z_$][a-zA-Z0-9_$]*Service)\b/g)]
-      .map((match) => match[1])
-      .sort((left, right) => left.localeCompare(right))
-    const defaultServiceClass = source.match(/\bexport\s+default\s+class(?:\s+([a-zA-Z_$][a-zA-Z0-9_$]*))?/)
-    const defaultServiceName = defaultServiceClass
-      ? defaultServiceClass[1] ?? `${toPascalCase(toModulePath('services', filePath))}Service`
-      : ''
+function generateServicesRegistry() {
+  const files = [
+    ...getFilesFromDirs(['services', 'service', 'modules'])
+      .filter((filePath) => isModuleFeatureFile(filePath, '.service'))
+      .map((filePath) => ({ filePath })),
+    ...getEnabledPluginFiles('.service'),
+  ]
+  const imports: string[] = []
+  const entries: string[] = []
+  const exportNames = new Set<string>()
+
+  files.forEach((item) => {
+    const { filePath } = item
+    const source = readFileSync(filePath, 'utf8')
+    const namedServiceClasses = [...source.matchAll(/\bexport\s+class\s+([a-zA-Z_$][a-zA-Z0-9_$]*Service)\b/g)]
+      .map((match) => match[1])
+      .sort((left, right) => left.localeCompare(right))
+    const defaultServiceClass = source.match(/\bexport\s+default\s+class(?:\s+([a-zA-Z_$][a-zA-Z0-9_$]*))?/)
+    const fallbackServicePath = 'name' in item
+      ? toPluginModulePath(item.name, item.rootDir, filePath, ['.service'])
+      : toModulePath('services', filePath)
+    const defaultServiceName = defaultServiceClass
+      ? defaultServiceClass[1] ?? `${toPascalCase(fallbackServicePath)}Service`
+      : ''
     const defaultImportName = defaultServiceName
       ? toIdentifier([defaultServiceName, 'Default'])
       : ''
@@ -411,31 +512,89 @@ function generateServicesRegistry() {
       return
     }
 
-    if (defaultServiceName) {
-      imports.push(`import ${defaultImportName} from '${toImportPath(filePath)}'`)
-      entries.push(`    ${toServiceKey(defaultServiceName)}: new ${defaultImportName}(deps),`)
-    }
-
-    if (namedServiceClasses.length > 0) {
-      imports.push(`import { ${namedServiceClasses.join(', ')} } from '${toImportPath(filePath)}'`)
-      entries.push(...namedServiceClasses.map((name) => `    ${toServiceKey(name)}: new ${name}(deps),`))
-    }
-  })
-
-  const content = `${generatedHeader}
-${imports.join('\n')}
-
-export function createServices(deps: any) {
-  return {
-${entries.join('\n')}
+    if (defaultServiceName) {
+      imports.push(`import ${defaultImportName} from '${toImportPath(filePath)}'`)
+      exportNames.add(`${defaultImportName} as ${defaultServiceName}`)
+      entries.push(`    ${toServiceKey(defaultServiceName)}: new ${defaultImportName}(deps),`)
+    }
+
+    if (namedServiceClasses.length > 0) {
+      imports.push(`import { ${namedServiceClasses.join(', ')} } from '${toImportPath(filePath)}'`)
+      namedServiceClasses.forEach((name) => exportNames.add(name))
+      entries.push(...namedServiceClasses.map((name) => `    ${toServiceKey(name)}: new ${name}(deps),`))
+    }
+  })
+
+  const exportBlock = formatExportBlock(Array.from(exportNames).sort((left, right) => left.localeCompare(right)))
+  const content = `${generatedHeader}
+${imports.join('\n')}
+
+${exportBlock}
+export function createServices(deps: any) {
+  return {
+${entries.join('\n')}
   }
 }
 
 export type Services = ReturnType<typeof createServices>
 `
 
-  writeGeneratedFile('services.generated.ts', content)
-}
+  writeGeneratedFile('services.generated.ts', content)
+}
+
+function generateCronsRegistry() {
+  const files = [
+    ...getFilesFromDirs(['cron', 'crons'])
+      .filter((filePath) => basename(filePath) !== 'index.ts')
+      .map((filePath) => ({
+        modulePath: toModulePath(filePath.includes(`${srcDir}/crons/`) ? 'crons' : 'cron', filePath, ['.cron']),
+        filePath,
+      })),
+    ...getFilesFromDirs(['modules'])
+      .filter((filePath) => isModuleFeatureFile(filePath, '.cron'))
+      .map((filePath) => ({
+        modulePath: toModulePath('modules', filePath, ['.cron']),
+        filePath,
+      })),
+    ...getEnabledPluginFiles('.cron')
+      .map(({ name, rootDir, filePath }) => ({
+        modulePath: toPluginModulePath(name, rootDir, filePath, ['.cron']),
+        filePath,
+      })),
+  ]
+    .filter(({ filePath }) => hasCronExport(filePath))
+    .filter((item, index, list) => {
+      return list.findIndex((row) => row.filePath === item.filePath) === index
+    })
+    .sort((left, right) => left.modulePath.localeCompare(right.modulePath))
+
+  const imports = files.map((item) => {
+    return `import * as ${toLowerCamelIdentifier([item.modulePath], 'Cron')} from '${toImportPath(item.filePath)}'`
+  })
+  const exportNames = files.map((item) => toLowerCamelIdentifier([item.modulePath], 'Cron'))
+  const entries = files.map((item) => {
+    const importName = toLowerCamelIdentifier([item.modulePath], 'Cron')
+
+    return `  { name: ${JSON.stringify(item.modulePath)}, module: ${importName} },`
+  })
+  const exportBlock = formatExportBlock(exportNames)
+  const content = createGeneratedContent([
+    imports.join('\n'),
+    exportBlock,
+    `export const cronModules = [
+${entries.join('\n')}
+] as const`,
+  ])
+
+  writeGeneratedFile('crons.generated.ts', content)
+}
+
+function hasCronExport(filePath: string) {
+  const source = readFileSync(filePath, 'utf8')
+
+  return /\bexport\s+default\b/.test(source)
+    || /\bexport\s+const\s+(?:cron|jobs)\b/.test(source)
+}
 
 function findBalancedObject(source: string, startIndex: number) {
   let depth = 0
@@ -560,7 +719,7 @@ function normalizePluginPackage(packageName: string, configFile: string) {
   return normalized
 }
 
-function mergePluginConfig(configs: { filePath: string; config: PluginConfig }[]) {
+function mergePluginConfig(configs: { filePath: string; config: PluginConfig }[]) {
   const merged = new Map<string, Exclude<PluginConfigItem, false>>()
 
   for (const { filePath, config } of configs) {
@@ -587,46 +746,104 @@ function mergePluginConfig(configs: { filePath: string; config: PluginConfig }[]
 
       return item.enable === true && typeof item.package === 'string' && item.package.length > 0
     })
-    .sort(([left], [right]) => left.localeCompare(right))
-}
+    .sort(([left], [right]) => left.localeCompare(right))
+}
+
+function getEnabledPluginConfigItems() {
+  return mergePluginConfig([
+    { filePath: join(packageDir, 'plugins/config.ts'), config: readPluginConfig(join(packageDir, 'plugins/config.ts')) },
+    { filePath: join(srcDir, 'config/plugin.ts'), config: readPluginConfig(join(srcDir, 'config/plugin.ts')) },
+  ])
+}
+
+function resolvePluginPackageDir(packageName: string) {
+  const resolved = resolvePluginPackage(packageName)
+
+  return statSync(resolved).isDirectory()
+    ? resolved
+    : dirname(resolved)
+}
+
+function resolvePluginPackage(packageName: string) {
+  if (isAbsolute(packageName)) {
+    return packageName
+  }
+
+  if (packageName.startsWith('./') || packageName.startsWith('../')) {
+    return resolve(projectDir, packageName)
+  }
+
+  if (packageName.startsWith('jax-hono/')) {
+    const packagePath = packageName.slice('jax-hono/'.length)
+    const directPath = join(packageDir, packagePath)
+
+    if (existsSync(directPath)) {
+      return directPath
+    }
+
+    const indexPath = join(directPath, 'index.ts')
+
+    if (existsSync(indexPath)) {
+      return indexPath
+    }
+  }
+
+  return projectRequire.resolve(packageName)
+}
+
+function getEnabledPlugins(): EnabledPlugin[] {
+  return getEnabledPluginConfigItems()
+    .map(([name, item]) => {
+      const rootDir = resolvePluginPackageDir(item.package)
+
+      return {
+        name,
+        packageName: item.package,
+        rootDir,
+      }
+    })
+    .filter((plugin) => existsSync(plugin.rootDir))
+}
 
 function serializePluginOptions(options: unknown) {
   return options === undefined ? '' : `, options: ${JSON.stringify(options)}`
 }
 
-function generatePluginContextRegistry() {
-  const enabledPlugins = mergePluginConfig([
-    { filePath: join(packageDir, 'plugins/config.ts'), config: readPluginConfig(join(packageDir, 'plugins/config.ts')) },
-    { filePath: join(srcDir, 'config/plugin.ts'), config: readPluginConfig(join(srcDir, 'config/plugin.ts')) },
-  ])
-  const imports = enabledPlugins.map(([name, item]) => {
-    return `import ${toIdentifier(['plugin', name])} from ${JSON.stringify(item.package)}`
-  })
-  const moduleEntries = enabledPlugins.map(
-    ([name, item]) =>
-      `  { name: ${JSON.stringify(name)}, module: ${toIdentifier(['plugin', name])}${serializePluginOptions(item.options)} },`,
-  )
-
-  const content = `${generatedHeader}${imports.length > 0 ? `${imports.join('\n')}\n\n` : ''}
-export const plugins = {} as Record<string, unknown>
-
-export type Plugins = typeof plugins
-
-export const pluginModules = [
-${moduleEntries.join('\n')}
-] as const
-`
-
-  writeGeneratedFile('plugins.generated.ts', content)
-}
+function generatePluginContextRegistry() {
+  const enabledPlugins = getEnabledPluginConfigItems()
+  const imports = enabledPlugins.map(([name, item]) => {
+    return `import ${toLowerCamelIdentifier([name], 'Plugin')} from ${JSON.stringify(item.package)}`
+  })
+  const exportNames = enabledPlugins.map(([name]) => toLowerCamelIdentifier([name], 'Plugin'))
+  const moduleEntries = enabledPlugins.map(
+    ([name, item]) =>
+      `  { name: ${JSON.stringify(name)}, module: ${toLowerCamelIdentifier([name], 'Plugin')}${serializePluginOptions(item.options)} },`,
+  )
+  const exportBlock = formatExportBlock(exportNames)
+
+  const content = createGeneratedContent([
+    imports.join('\n'),
+    exportBlock,
+    `export const plugins = {} as Record<string, unknown>
+
+export type Plugins = typeof plugins
+
+export const pluginModules = [
+${moduleEntries.join('\n')}
+] as const`,
+  ])
+
+  writeGeneratedFile('plugins.generated.ts', content)
+}
 
-export function generateRegistry() {
-  generateControllersRegistry()
-  generateMiddlewaresRegistry()
-  generateModelsRegistry()
-  generateServicesRegistry()
-  generatePluginContextRegistry()
-}
+export function generateRegistry() {
+  generateControllersRegistry()
+  generateMiddlewaresRegistry()
+  generateModelsRegistry()
+  generateServicesRegistry()
+  generateCronsRegistry()
+  generatePluginContextRegistry()
+}
 
 if (import.meta.main) {
   generateRegistry()

package/core/app.ts

@@ -2,10 +2,12 @@ import { createHono, createApi } from './hono';
 import { registerCrudRoutes } from '../helpers/crud';
 import config from '../config';
 import type { Config } from '../config';
-import { pluginModules } from '../generated/plugins.generated';
-import type { models as generatedModels } from '../generated/models.generated';
-import type { createServices as generatedCreateServices } from '../generated/services.generated';
-import { runWithJaxContext } from './controller';
+import { pluginModules } from '../generated/plugins.generated';
+import { cronModules } from '../generated/crons.generated';
+import type { models as generatedModels } from '../generated/models.generated';
+import type { createServices as generatedCreateServices } from '../generated/services.generated';
+import { runWithJaxContext } from './controller';
+import { startCronJobs, stopCronJobs } from './cron';
 import { requestLog } from '../middleware/request-log';
 import type { Hono } from 'hono';
 import type { JaxHono } from './hono';
@@ -65,7 +67,8 @@ export function createApp(deps: AppRuntimeDeps): JaxHono {
     service: undefined as unknown as Services,
     plugin: {} as Plugins
   };
-  const activePlugins: ActivePlugin[] = [];
+  const activePlugins: ActivePlugin[] = [];
+  let activeCrons: ReturnType<typeof startCronJobs> = [];
 
   ctx.service = deps.createServices(ctx);
   app.jax = ctx;
@@ -91,16 +94,19 @@ export function createApp(deps: AppRuntimeDeps): JaxHono {
   ).then(async (plugins) => {
     activePlugins.push(...plugins.filter((plugin): plugin is ActivePlugin => Boolean(plugin)));
 
-    printEnabledPlugins(activePlugins);
-
-    await Promise.all(activePlugins.map((plugin) => runPluginReadySafely(plugin, ctx)));
-  });
+    printEnabledPlugins(activePlugins);
+
+    await Promise.all(activePlugins.map((plugin) => runPluginReadySafely(plugin, ctx)));
+
+    activeCrons = startCronJobs(cronModules, ctx);
+  });
 
   app.ready = ready;
   app.close = async () => {
-    await ready.catch(() => undefined);
-    await closePluginsSafely(activePlugins, ctx);
-  };
+    await ready.catch(() => undefined);
+    stopCronJobs(activeCrons);
+    await closePluginsSafely(activePlugins, ctx);
+  };
 
   return app;
 }

package/core/cron.ts

@@ -0,0 +1,151 @@
+import type { AppContext } from './app';
+
+type MaybePromise<T> = T | Promise<T>;
+
+export type CronRunContext = AppContext & {
+  signal: AbortSignal;
+};
+
+export type CronSchedule = {
+  /**
+   * Cron expression supported by Bun.cron.
+   */
+  cron: string;
+  /**
+   * Run once immediately after the app is ready.
+   */
+  immediate?: boolean;
+};
+
+export type CronJob = CronSchedule & {
+  name?: string;
+  run: (ctx: CronRunContext) => MaybePromise<void>;
+};
+
+type CronModule =
+  | CronJob
+  | CronJob[]
+  | {
+      default?: CronJob | CronJob[];
+      cron?: CronJob | CronJob[];
+      jobs?: CronJob[];
+    };
+
+type CronModuleItem = {
+  name: string;
+  module: CronModule;
+};
+
+type ActiveCron = {
+  name: string;
+  cron: string;
+  nextRunAt?: Date;
+  stop: () => void;
+};
+
+export function defineCron(job: CronJob) {
+  return job;
+}
+
+export function startCronJobs(items: readonly CronModuleItem[], ctx: AppContext) {
+  const active: ActiveCron[] = [];
+
+  for (const item of items) {
+    for (const job of resolveCronJobs(item.module)) {
+      active.push(startCronJob(item.name, job, ctx));
+    }
+  }
+
+  printCronJobs(active);
+
+  return active;
+}
+
+export function stopCronJobs(items: readonly ActiveCron[]) {
+  for (const item of [...items].reverse()) {
+    item.stop();
+  }
+}
+
+function resolveCronJobs(module: CronModule): CronJob[] {
+  if (Array.isArray(module)) {
+    return module;
+  }
+
+  if (isCronJob(module)) {
+    return [module];
+  }
+
+  const jobs = module.default ?? module.cron ?? module.jobs ?? [];
+
+  return Array.isArray(jobs) ? jobs : [jobs];
+}
+
+function isCronJob(value: unknown): value is CronJob {
+  return Boolean(value && typeof value === 'object' && typeof (value as CronJob).run === 'function');
+}
+
+function startCronJob(moduleName: string, job: CronJob, appContext: AppContext): ActiveCron {
+  const name = job.name || moduleName;
+  const controller = new AbortController();
+  let running = false;
+
+  const run = async () => {
+    if (running || controller.signal.aborted) {
+      return;
+    }
+
+    running = true;
+
+    try {
+      await job.run({ ...appContext, signal: controller.signal });
+    } catch (error) {
+      console.error(`[cron] ${name} failed:`, error);
+    } finally {
+      running = false;
+    }
+  };
+  const cronJob = Bun.cron(job.cron, () => {
+    void run();
+  });
+
+  if (job.immediate) {
+    void run();
+  }
+
+  return {
+    name,
+    cron: job.cron,
+    nextRunAt: getNextRunAt(job.cron),
+    stop() {
+      controller.abort();
+      cronJob.stop();
+    },
+  };
+}
+
+function getNextRunAt(expression: string) {
+  try {
+    return Bun.cron.parse(expression) ?? undefined;
+  } catch (error) {
+    console.error(`[cron] invalid expression ${expression}:`, error);
+    return undefined;
+  }
+}
+
+function printCronJobs(items: readonly ActiveCron[]) {
+  if (items.length === 0) {
+    console.log('[cron] enabled: none');
+    return;
+  }
+
+  console.log('[cron] enabled:');
+
+  for (const item of items) {
+    const nextRunAt = item.nextRunAt
+      ? `${item.nextRunAt.toLocaleString()} (${item.nextRunAt.toISOString()})`
+      : 'unknown';
+
+    console.log(`  - ${item.name} (${item.cron}) next: ${nextRunAt}`);
+  }
+}

package/docs/agent.md

@@ -48,6 +48,51 @@ generated/plugins.generated.ts
 
 如果业务仓库里有多个工程都依赖 `jax-hono`，分别查看各工程的 `package.json`，运行它们自己的 setup/build 命令。
 
+## 插件生成约定
+
+生成器只扫描已启用插件。插件启用来源包括：
+
+- `jax-hono/plugins/config.ts`
+- 使用方工程的 `src/config/plugin.ts`
+
+未启用插件不应进入生成结果，避免构建解析未启用插件的运行时依赖。
+
+已启用插件中的约定文件会进入生成器：
+
+- `*.controller.ts` 注册到 `controllers` 根对象
+- `*.service.ts` 注册到 `services.generated.ts`
+- `*.cron.ts` 注册到 `crons.generated.ts`，由框架统一启动/停止
+
+例如启用插件 `foo` 后：
+
+```text
+plugins/foo/foo.controller.ts
+plugins/foo/foo-cache.service.ts
+plugins/foo/foo-cleanup.cron.ts
+```
+
+可生成：
+
+```ts
+controllers.foo
+service.fooCache
+```
+
+Cron 文件可以使用 `defineCron`：
+
+```ts
+import { defineCron } from 'jax-hono';
+
+export default defineCron({
+  name: 'foo-cleanup',
+  cron: '0 0 * * *',
+  immediate: true,
+  async run(ctx) {
+    // ctx.app / ctx.config / ctx.model / ctx.service / ctx.plugin / ctx.signal
+  }
+});
+```
+
 ## Controller 注册约定
 
 生成器需要保持不同命名空间的边界清晰：

package/docs/jax.md

@@ -91,9 +91,10 @@ export default definePlugin({
 - `generated/config.ts`
 - `generated/controllers.generated.ts`
 - `generated/middlewares.generated.ts`
-- `generated/models.generated.ts`
-- `generated/plugins.generated.ts`
-- `generated/services.generated.ts`
+- `generated/models.generated.ts`
+- `generated/plugins.generated.ts`
+- `generated/services.generated.ts`
+- `generated/crons.generated.ts`
 
 业务代码不要手动编辑 `generated` 目录。
 
@@ -259,7 +260,42 @@ Service 中推荐使用：
 
 新增文件后，如果业务侧需要使用，应优先在对应子入口导出，例如 `src/jax/utils/index.ts`、`src/jax/errors/index.ts`。只有框架核心 API 才放到 `src/jax/index.ts`。
 
-内置插件配置放在 `src/jax/plugins/config.ts`，内置插件实现放在 `src/jax/plugins/*`，项目级插件通过 `src/config/plugin.ts` 显式启用或覆盖。生成器只读取插件配置，不扫描插件目录。
+内置插件配置放在 `plugins/config.ts`，内置插件实现放在 `plugins/*`，项目级插件通过 `src/config/plugin.ts` 显式启用或覆盖。生成器只扫描已启用插件中的约定文件，不扫描未启用插件。
+
+已启用插件可以提供：
+
+- `*.controller.ts`：注册到 `controllers` 根对象
+- `*.service.ts`：注册到 `services.generated.ts`
+- `*.cron.ts`：注册到 `crons.generated.ts`，由框架统一启动/停止
+
+未启用插件不会进入生成结果，也不会让构建解析它的运行时依赖。
+
+### `cron`
+
+定时任务可以放在项目根级 `src/cron` / `src/crons` 目录，也可以放在模块或已启用插件中：
+
+```text
+src/cron/report.cron.ts
+src/modules/oss/oss-trash.cron.ts
+plugins/foo/foo-cleanup.cron.ts
+```
+
+Cron 文件导出 `defineCron()`、`cron` 或 `jobs` 即可被生成器识别：
+
+```ts
+import { defineCron } from 'jax-hono';
+
+export default defineCron({
+  name: 'daily-cleanup',
+  cron: '0 0 * * *',
+  immediate: true,
+  async run(ctx) {
+    // ctx.app / ctx.config / ctx.model / ctx.service / ctx.plugin / ctx.signal
+  }
+});
+```
+
+框架会在应用 ready 后统一启动定时任务，在 `app.close()` 时统一停止，不需要每个任务在入口文件手动声明。
 
 ## 常用命令
 

package/index.ts

@@ -61,9 +61,11 @@ export type { AppContext, AppPlugin } from './core/app';
 export type { Config, JaxConfig } from './config';
 export { ApiController } from './core/api-controller';
 export { Controller } from './core/controller';
-export { Service } from './core/service';
-export type { ServiceContext } from './core/service';
-export type { Services } from './generated/services.generated';
+export { Service } from './core/service';
+export type { ServiceContext } from './core/service';
+export { defineCron } from './core/cron';
+export type { CronJob, CronRunContext, CronSchedule } from './core/cron';
+export type { Services } from './generated/services.generated';
 export type { ApiFailResponse, ApiResponse, ApiSuccessResponse } from './middleware/api-response';
 
 export function createApp() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jax-hono",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "Lightweight framework layer on top of Hono, built for Bun",
   "type": "module",
   "main": "./index.ts",

package/utils/crypto.ts

@@ -4,6 +4,12 @@ export function md5(value: string) {
   return createHash('md5').update(value).digest('hex');
 }
 
-export function createToken(byteLength = 24) {
-  return randomBytes(byteLength).toString('hex');
-}
+export function createToken(byteLength = 24) {
+  return randomBytes(byteLength).toString('hex');
+}
+
+export function nonceStr(length: number) {
+  return randomBytes(Math.ceil(length / 2))
+    .toString('hex')
+    .slice(0, length);
+}

package/utils/index.ts

@@ -1,5 +1,7 @@
 export * from "./array";
 export * from "./async";
-export * from "./crypto";
-export * from "./regexp";
-export * from "./transform";
+export * from "./crypto";
+export * from "./order";
+export * from "./regexp";
+export * from "./transform";
+export * from "./validate";

package/utils/order.ts

@@ -0,0 +1,5 @@
+import dayjs from 'dayjs';
+
+export function getOrderNo(prefix = '') {
+  return `${prefix}${dayjs().format('YYYYMMDDHHmmssSSS')}${Math.floor(Math.random() * 9000 + 1000)}`;
+}

package/utils/regexp.ts

@@ -12,6 +12,14 @@
  * escapeRegex('price$')         // => 'price\\$'
  * escapeRegex(123)              // => '123'
  */
-export function escapeRegex(value: unknown) {
-  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
+export function escapeRegex(value: unknown) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function keywordRegex(keyword?: string) {
+  if (!keyword) {
+    return undefined;
+  }
+
+  return new RegExp(escapeRegex(keyword), 'i');
+}

package/utils/validate.ts

@@ -0,0 +1,7 @@
+export function requireFields(body: Record<string, unknown>, fields: string[]) {
+  for (const field of fields) {
+    if (body[field] === undefined || body[field] === null || body[field] === '') {
+      throw new Error(`缺少${field}`);
+    }
+  }
+}