jax-hono 1.0.1 → 1.0.3

package/README.md

@@ -13,5 +13,5 @@ helpers/    框架辅助函数
 utils/      纯工具函数
 errors/     统一错误类型
 types/      框架公共类型
-generated/  自动生成的注册表
+generated/  调用项目中自动生成的注册表，包内同名目录会链接到这里
 ```

package/bin/jax.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const cliPath = path.join(__dirname, "jax.ts");
+
+function getBunCommand() {
+  const candidates = [];
+
+  if (process.env.BUN_INSTALL) {
+    candidates.push(
+      path.join(
+        process.env.BUN_INSTALL,
+        "bin",
+        process.platform === "win32" ? "bun.exe" : "bun",
+      ),
+    );
+  }
+
+  if (process.platform === "win32") {
+    const nodeDir = path.dirname(process.execPath);
+    candidates.push(
+      path.join(nodeDir, "bun.exe"),
+      path.join(nodeDir, "node_modules", "bun", "bin", "bun.exe"),
+    );
+  }
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return "bun";
+}
+
+const child = spawn(getBunCommand(), [cliPath, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  windowsHide: true,
+});
+
+child.on("error", (error) => {
+  if (error.code === "ENOENT") {
+    console.error(
+      "未找到 Bun。请从 https://bun.sh 安装 Bun，或确认 bun 已加入 PATH。",
+    );
+    process.exit(1);
+  }
+
+  console.error(error.message);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code ?? 0);
+});

package/bin/jax.ts

@@ -4,18 +4,40 @@ import { cac } from "cac";
 import { $ } from "bun";
 import path from "node:path";
 import { existsSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
+import { lstat, mkdir, rm } from "node:fs/promises";
 
 const cli = cac("jax");
 
+async function removeExistingTarget(
+  targetDir: string,
+  allowRegularDirectory: boolean,
+) {
+  if (!existsSync(targetDir)) {
+    return;
+  }
+
+  const stats = await lstat(targetDir);
+  if (stats.isSymbolicLink() || allowRegularDirectory) {
+    await rm(targetDir, { recursive: true, force: true });
+    return;
+  }
+
+  console.error(
+    `目标已存在且不是符号链接：${targetDir}\n请手动删除后再执行 jax link。`,
+  );
+  process.exit(1);
+}
+
 cli
-  .command(
-    "link",
-    "Create a symlink to the jax-hono installation directory",
-  )
+  .command("link", "创建指向 jax-hono 安装目录的链接")
   .action(async () => {
     const cwd = process.cwd();
     const sourceDir = path.resolve(import.meta.dir, "..");
+    if (path.resolve(cwd) === sourceDir) {
+      console.error("不能在 jax-hono 安装目录内执行 jax link。");
+      process.exit(1);
+    }
+
     const shouldUseNodeModules =
       existsSync(path.join(cwd, "package.json")) ||
       existsSync(path.join(cwd, "node_modules"));
@@ -29,54 +51,90 @@ cli
       await mkdir(targetRoot, { recursive: true });
     }
 
+    await removeExistingTarget(targetDir, shouldUseNodeModules);
+
     if (process.platform === "win32") {
       const result =
-        await $`cmd /c mklink /D ${targetDir} ${sourceDir}`.nothrow();
+        await $`cmd /c mklink /J ${targetDir} ${sourceDir}`.nothrow().quiet();
       if (result.exitCode !== 0) {
         console.error(
-          "Failed to create symlink. Make sure you run as Administrator.",
+          `创建目录联接失败：${result.stderr.toString()}`,
         );
         process.exit(1);
       }
-      console.log(`Symlink created: ${targetDir} <<===>> ${sourceDir}`);
+      console.log(`目录联接已创建：${targetDir} <<===>> ${sourceDir}`);
     } else {
       const relativeSource = path.relative(path.dirname(targetDir), sourceDir);
-      const result = await $`ln -sf ${relativeSource} ${targetDir}`.nothrow();
+      const result = await $`ln -sf ${relativeSource} ${targetDir}`.nothrow().quiet();
       if (result.exitCode !== 0) {
-        console.error(`Failed to create symlink: ${result.stderr.toString()}`);
+        console.error(`创建符号链接失败：${result.stderr.toString()}`);
         process.exit(1);
       }
-      console.log(`Symlink created: ${targetDir} -> ${relativeSource}`);
+      console.log(`符号链接已创建：${targetDir} -> ${relativeSource}`);
     }
   });
 
 cli
-  .command("open", "Open jax-hono installation directory in file manager")
+  .command("open", "在文件管理器中打开 jax-hono 安装目录")
   .action(async () => {
     const sourceDir = path.resolve(import.meta.dir, "..");
 
-    let command: string[];
-    if (process.platform === "darwin") {
-      command = ["open", sourceDir];
-    } else if (process.platform === "win32") {
-      command = ["explorer", sourceDir];
-    } else {
-      command = ["xdg-open", sourceDir];
+    if (process.platform === "win32") {
+      const escapedSourceDir = sourceDir.replace(/'/g, "''");
+      const proc = Bun.spawn([
+        "powershell",
+        "-NoProfile",
+        "-Command",
+        `Start-Process -FilePath explorer.exe -ArgumentList '${escapedSourceDir}'`,
+      ], {
+        stdout: "pipe",
+        stderr: "pipe",
+        windowsHide: true,
+      });
+      const exitCode = await proc.exited;
+      const stderr = await new Response(proc.stderr).text();
+
+      if (exitCode !== 0) {
+        console.error(`打开目录失败：${stderr || "未知错误"}`);
+        process.exit(1);
+      }
+
+      console.log(`已打开：${sourceDir}`);
+      return;
     }
 
+    const command =
+      process.platform === "darwin" ? ["open", sourceDir] : ["xdg-open", sourceDir];
     const [cmd, ...args] = command;
-    const result = await $`${cmd} ${args}`.nothrow();
+    const result = await $`${cmd} ${args}`.nothrow().quiet();
     if (result.exitCode !== 0) {
-      console.error(`Failed to open directory: ${result.stderr.toString()}`);
+      console.error(`打开目录失败：${result.stderr.toString() || "未知错误"}`);
       process.exit(1);
     }
-    console.log(`Opened: ${sourceDir}`);
+    console.log(`已打开：${sourceDir}`);
   });
 
-cli.help();
+cli.help((sections) =>
+  sections.map((section) => {
+    const titleMap: Record<string, string> = {
+      Usage: "用法",
+      Commands: "命令",
+      "For more info, run any command with the `--help` flag":
+        "查看更多信息，请在任意命令后添加 `--help`",
+      Options: "选项",
+      Examples: "示例",
+    };
+
+    return {
+      ...section,
+      title: section.title ? (titleMap[section.title] ?? section.title) : section.title,
+      body: section.body.replace("Display this message", "显示帮助信息"),
+    };
+  }),
+);
 const parsed = cli.parse();
 
-// Show help when no command is matched (e.g. bare `jax` or unknown command)
+// 未匹配到命令时显示帮助，例如直接执行 `jax` 或输入未知命令。
 if (!cli.matchedCommand && !parsed.options.help) {
   cli.outputHelp();
 }

package/build/generate-config.ts

@@ -1,12 +1,11 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
 import { cwd } from 'node:process'
 import { join, parse, relative } from 'node:path'
+import { ensureGeneratedDir, generatedDir, projectDir } from './generated-path'
 
-const packageDir = join(import.meta.dir, '..')
 const srcDir = join(cwd(), 'src')
 const configDir = join(srcDir, 'config')
 const typesFile = join(srcDir, 'types/index.ts')
-const generatedDir = join(packageDir, 'generated')
 const outputFile = join(generatedDir, 'config.ts')
 const envStages = new Set([
   'default',
@@ -102,14 +101,14 @@ ${projectConfigType}
 export default configModules
 `
 
-  mkdirSync(generatedDir, { recursive: true })
+  ensureGeneratedDir()
 
   if (existsSync(outputFile) && readFileSync(outputFile, 'utf8') === content) {
     return
   }
 
   writeFileSync(outputFile, content)
-  console.log(`Generated ${relative(srcDir, outputFile)} with ${files.length} config file(s).`)
+  console.log(`Generated ${relative(projectDir, outputFile)} with ${files.length} config file(s).`)
 }
 
 if (import.meta.main) {

package/build/generate-registry.ts

@@ -1,10 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
 import { cwd } from 'node:process'
 import { basename, join, parse, relative } from 'node:path'
+import { ensureGeneratedDir, generatedDir, projectDir } from './generated-path'
 
-const packageDir = join(import.meta.dir, '..')
 const srcDir = join(cwd(), 'src')
-const generatedDir = join(packageDir, 'generated')
 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.
@@ -66,14 +65,14 @@ function walkFiles(dir: string): string[] {
 function writeGeneratedFile(fileName: string, content: string) {
   const outputFile = join(generatedDir, fileName)
 
-  mkdirSync(generatedDir, { recursive: true })
+  ensureGeneratedDir()
 
   if (existsSync(outputFile) && readFileSync(outputFile, 'utf8') === content) {
     return
   }
 
   writeFileSync(outputFile, content)
-  console.log(`Generated ${relative(srcDir, outputFile)}.`)
+  console.log(`Generated ${relative(projectDir, outputFile)}.`)
 }
 
 function toImportPath(filePath: string) {

package/build/generated-path.ts

@@ -0,0 +1,57 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+} from 'node:fs'
+import { cwd } from 'node:process'
+import { join, resolve } from 'node:path'
+
+export const packageDir = join(import.meta.dir, '..')
+export const projectDir = cwd()
+
+export function getGeneratedDir() {
+  const configuredDir = Bun.env.JAX_HONO_GENERATED_DIR
+
+  return configuredDir
+    ? resolve(projectDir, configuredDir)
+    : join(projectDir, 'generated')
+}
+
+export const generatedDir = getGeneratedDir()
+
+export function ensureGeneratedDir() {
+  mkdirSync(generatedDir, { recursive: true })
+  ensurePackageGeneratedLink()
+}
+
+function ensurePackageGeneratedLink() {
+  const packageGeneratedDir = join(packageDir, 'generated')
+
+  if (resolve(packageGeneratedDir) === resolve(generatedDir)) {
+    if (existsSync(packageGeneratedDir) && lstatSync(packageGeneratedDir).isSymbolicLink()) {
+      rmSync(packageGeneratedDir, { recursive: true, force: true })
+      mkdirSync(generatedDir, { recursive: true })
+    }
+
+    return
+  }
+
+  if (existsSync(packageGeneratedDir)) {
+    const stats = lstatSync(packageGeneratedDir)
+
+    if (stats.isSymbolicLink()) {
+      const currentTarget = realpathSync(packageGeneratedDir)
+
+      if (resolve(currentTarget) === resolve(generatedDir)) {
+        return
+      }
+    }
+
+    rmSync(packageGeneratedDir, { recursive: true, force: true })
+  }
+
+  symlinkSync(generatedDir, packageGeneratedDir, 'junction')
+}

package/docs/jax.md

@@ -80,7 +80,7 @@ export default definePlugin({
 });
 ```
 
-未启用的插件不会写入 `src/jax/generated/plugins.generated.ts`，因此 `bun build` 不会解析它的运行时依赖。
+未启用的插件不会写入调用项目的 `generated/plugins.generated.ts`，因此 `bun build` 不会解析它的运行时依赖。
 
 ### `build`
 
@@ -88,12 +88,12 @@ export default definePlugin({
 
 当前 `bun run setup` 会生成：
 
-- `src/jax/generated/config.ts`
-- `src/jax/generated/controllers.generated.ts`
-- `src/jax/generated/middlewares.generated.ts`
-- `src/jax/generated/models.generated.ts`
-- `src/jax/generated/plugins.generated.ts`
-- `src/jax/generated/services.generated.ts`
+- `generated/config.ts`
+- `generated/controllers.generated.ts`
+- `generated/middlewares.generated.ts`
+- `generated/models.generated.ts`
+- `generated/plugins.generated.ts`
+- `generated/services.generated.ts`
 
 业务代码不要手动编辑 `generated` 目录。
 

package/index.ts

@@ -1,4 +1,6 @@
 import { Hono } from 'hono';
+import './core/hono';
+import './middleware/api-response';
 import { createHono, createApi } from './core/hono';
 import { registerCrudRoutes } from './helpers/crud';
 import type { Config } from './config';

package/middleware/jwt.ts

@@ -1,62 +1,67 @@
-import config from '../config';
-import jwt from 'jsonwebtoken';
-import type { Context, MiddlewareHandler, Next } from 'hono';
+import config from "../config";
+import jwt from "jsonwebtoken";
+import type { Context, MiddlewareHandler, Next } from "hono";
 
-type JwtAuthOptions<TPayload extends Record<string, any> = Record<string, any>> = {
+type JwtAuthOptions<
+  TPayload extends Record<string, any> = Record<string, any>,
+> = {
   secretSuffix: string;
   stateKey: string;
   validate?: (payload: TPayload, c: Context) => boolean | Promise<boolean>;
   resolveState?: (payload: TPayload, c: Context) => unknown | Promise<unknown>;
 };
 
-function createJwtAuth<TPayload extends Record<string, any> = Record<string, any>>(
-  options: JwtAuthOptions<TPayload>
-): MiddlewareHandler {
+function createJwtAuth<
+  TPayload extends Record<string, any> = Record<string, any>,
+>(options: JwtAuthOptions<TPayload>): MiddlewareHandler {
   return async (c, next) => {
-    const session = c.get('session');
-    const sessionData = session.get(options.stateKey);
+    // const session = c.get('session');
+    // const sessionData = session.get(options.stateKey);
 
-    if (sessionData) {
-      console.log('sessionData', sessionData);
-      c.state[options.stateKey] = sessionData;
-      await next();
-    }
+    // if (sessionData) {
+    //   c.state[options.stateKey] = sessionData;
+    //   await next();
+    // }
 
     const token = getAuthorizationToken(c);
 
     if (!token) {
-      return c.json({ code: 401, msg: '请先登录' });
+      return c.json({ code: 401, msg: "请先登录" });
     }
 
     try {
       const payload = jwt.verify(
         token,
-        (config as any).jwt.secret + options.secretSuffix
+        (config as any).jwt.secret + options.secretSuffix,
       ) as TPayload;
-      const valid = options.validate ? await options.validate(payload, c) : true;
+      const valid = options.validate
+        ? await options.validate(payload, c)
+        : true;
 
       if (!valid) {
-        return c.json({ code: 401, msg: '请重新登录' });
+        return c.json({ code: 401, msg: "请重新登录" });
       }
 
-      const stateValue = options.resolveState ? await options.resolveState(payload, c) : payload;
+      const stateValue = options.resolveState
+        ? await options.resolveState(payload, c)
+        : payload;
 
       if (!stateValue) {
-        return c.json({ code: 401, msg: '请重新登录' });
+        return c.json({ code: 401, msg: "请重新登录" });
       }
 
       c.state[options.stateKey] = stateValue;
 
       await next();
     } catch {
-      return c.json({ code: 401, msg: '请重新登录' });
+      return c.json({ code: 401, msg: "请重新登录" });
     }
   };
 }
 
 function createOptionalAuth(auth: MiddlewareHandler): MiddlewareHandler {
   return async (c, next) => {
-    if (!c.req.header('authorization')) {
+    if (!c.req.header("authorization")) {
       await next();
       return;
     }
@@ -66,10 +71,10 @@ function createOptionalAuth(auth: MiddlewareHandler): MiddlewareHandler {
 }
 
 function getAuthorizationToken(c: Context) {
-  const authorization = c.req.header('authorization') ?? '';
+  const authorization = c.req.header("authorization") ?? "";
 
-  return authorization.startsWith('Bearer ')
-    ? authorization.slice('Bearer '.length)
+  return authorization.startsWith("Bearer ")
+    ? authorization.slice("Bearer ".length)
     : authorization;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jax-hono",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Lightweight framework layer on top of Hono, built for Bun",
   "type": "module",
   "main": "./index.ts",
@@ -60,7 +60,7 @@
     }
   },
   "bin": {
-    "jax": "./bin/jax.ts"
+    "jax": "./bin/jax.js"
   },
   "files": [
     "index.ts",
@@ -82,10 +82,10 @@
   },
   "dependencies": {
     "@hono/session": "^0.2.1",
-    "cac": "^7.0.0",
-    "hono": "^4.12.27"
+    "cac": "^7.0.0"
   },
   "peerDependencies": {
+    "hono": "^4.12.27",
     "dayjs": "*",
     "deepmerge": "^4.3.1",
     "dotenv": "^17.4.2",
@@ -94,9 +94,11 @@
     "mongoose": "*"
   },
   "devDependencies": {
+    "@types/bun": "^1.3.14",
     "dayjs": "^1.11.21",
     "deepmerge": "^4.3.1",
     "dotenv": "^17.4.2",
+    "hono": "^4.12.27",
     "jsonwebtoken": "^9.0.3",
     "minimist": "^1.2.8",
     "mongoose": "^8.24.1"
@@ -116,4 +118,4 @@
     "bun": ">=1.0.0"
   },
   "license": "MIT"
-}
+}

package/plugins/mongoose/model.ts

@@ -6,7 +6,7 @@ import mongoose, {
   type Model,
   type SchemaOptions,
 } from "mongoose";
-import config from "@/config";
+import config from "../../config";
 import { rankSetter } from "./schema";
 import dayjs from "dayjs";
 

package/plugins/session/index.ts

@@ -1,20 +1,86 @@
-import { useSession, useSessionStorage } from '@hono/session'
-import type { SessionEnv } from '@hono/session'
-import { Hono } from 'hono'
-import { definePlugin } from '../define'
+import { useSession, useSessionStorage } from '@hono/session';
+import type { Session, SessionData, SessionOptions, Storage } from '@hono/session';
+import type { Context } from 'hono';
+import { definePlugin } from '../define';
+
+export type JaxSessionData = SessionData;
+
+export type SessionStorageFactory<Data extends SessionData = JaxSessionData> = (
+  c: Context
+) => Storage<Data>;
+
+export type SessionPluginOptions<Data extends SessionData = JaxSessionData> =
+  SessionOptions<Data> & {
+    /**
+     * Optional backing storage. When omitted, @hono/session keeps session data
+     * inside the encrypted cookie.
+     */
+    storage?: Storage<Data> | SessionStorageFactory<Data>;
+  };
+
+declare module 'hono' {
+  interface ContextVariableMap {
+    session: Session<JaxSessionData>;
+    sessionStorage?: Storage<JaxSessionData>;
+  }
+}
+
+const DEFAULT_SESSION_DURATION = {
+  // 会话的有效时间以秒为单位。超过该时间后，会话将失效，需要重新认证才能继续使用。
+  absolute: 60 * 60 * 24 * 7 // 7天
+};
+
+const DEFAULT_SESSION_OPTIONS: SessionPluginOptions = {
+  secret: 'jax-session',
+  duration: DEFAULT_SESSION_DURATION
+};
+
+function isSessionPluginOptions(options: unknown): options is SessionPluginOptions {
+  return Boolean(options && typeof options === 'object' && !Array.isArray(options));
+}
+
+function resolveSessionOptions(config: unknown, options: unknown): SessionPluginOptions {
+  const configOptions = readConfigSessionOptions(config);
+  const pluginOptions = isSessionPluginOptions(options) ? options : {};
+  const duration: NonNullable<SessionPluginOptions['duration']> = {
+    absolute: DEFAULT_SESSION_DURATION.absolute,
+    ...configOptions.duration,
+    ...pluginOptions.duration
+  };
+  const { storage, ...sessionOptions } = {
+    ...DEFAULT_SESSION_OPTIONS,
+    ...configOptions,
+    ...pluginOptions,
+    duration
+  };
+
+  return {
+    ...sessionOptions,
+    storage
+  };
+}
+
+function readConfigSessionOptions(config: unknown): SessionPluginOptions {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    return {};
+  }
+
+  const session = (config as { session?: unknown }).session;
+
+  return isSessionPluginOptions(session) ? session : {};
+}
 
 export default definePlugin({
-  setup(ctx) {
-    ctx.app.use(
-      useSession({
-        secret: ctx.config?.session?.secret || 'jax-session',
-        duration: {
-          // 会话的有效时间以秒为单位。超过该时间后，会话将失效，需要重新认证才能继续使用。
-          absolute: 60 * 60 * 24 * 7, // 7天
-          // 会话被视为活跃的时间长度，以秒为单位。在这一时间内，会话的最大年龄可以延长。
-          // inactivity: 60 * 5,
-        },
-      }),
-    )
-  },
-})
+  setup(ctx, options) {
+    const { storage, ...sessionOptions } = resolveSessionOptions(ctx.config, options);
+
+    if (storage) {
+      ctx.app.use(useSessionStorage(storage));
+    }
+
+    ctx.app.use(useSession(sessionOptions));
+  }
+});
+
+export type { Session, SessionData, SessionOptions, Storage };
+export { useSession, useSessionStorage };

package/types/config.ts

@@ -1,13 +1,9 @@
+import type { SessionPluginOptions } from '../plugins/session';
+
 export type JaxConfig = {
   rootDir: string;
   port: number;
   env: string;
 
-  session?: {
-    secret?: string;
-    duration?: {
-      absolute: number;
-      inactivity?: number;
-    };
-  };
+  session?: SessionPluginOptions;
 };