jax-hono 1.0.0

package/core/api-controller.ts

@@ -0,0 +1,244 @@
+import { Controller } from './controller';
+import { arrayFrom } from '../utils/array';
+import { escapeRegex } from '../utils/regexp';
+import type { Context } from 'hono';
+
+const bodyCache = new WeakMap<Context, unknown>();
+
+export abstract class ApiController extends Controller {
+  protected get Model(): any {
+    return undefined;
+  }
+
+  protected get key() {
+    return '_id';
+  }
+
+  protected get sort() {
+    return { [this.key]: -1 };
+  }
+
+  protected get isPage() {
+    return true;
+  }
+
+  protected get batchAction() {
+    return true;
+  }
+
+  protected get admin(): any {
+    return this.state.admin;
+  }
+
+  protected get user(): any {
+    return this.state.user;
+  }
+
+  protected get query() {
+    return this.context.req.query();
+  }
+
+  protected get params() {
+    return this.context.req.param();
+  }
+
+  protected async body<T = Record<string, any>>() {
+    if (bodyCache.has(this.context)) {
+      return bodyCache.get(this.context) as T;
+    }
+
+    try {
+      const body = await this.context.req.json<T>();
+      bodyCache.set(this.context, body);
+
+      return body;
+    } catch {
+      const body = {} as T;
+      bodyCache.set(this.context, body);
+
+      return body;
+    }
+  }
+
+  async index(c: Context) {
+    const Model = this.requireModel();
+    const query = c.req.query();
+    let options: Record<string, any> = { sort: this.sort };
+
+    if (typeof (this as any).beforeIndex === 'function') {
+      options = { ...options, ...(await (this as any).beforeIndex()) };
+    }
+
+    const filter = await this.getFilter(options.filter);
+    let data: any;
+
+    if (this.isPage) {
+      data = await Model.findPage(filter, {
+        ...options,
+        page: query.page,
+        pageSize: query.pageSize
+      });
+      data.list = await this.formatList(data.list);
+    } else {
+      data = await Model.find(filter).sort(options.sort ?? this.sort);
+      data = await this.formatList(data);
+    }
+
+    return c.ok(data);
+  }
+
+  async show(c: Context) {
+    const Model = this.requireModel();
+    const doc = await Model.findOne({ [this.key]: c.req.param('id') });
+
+    if (!doc) {
+      return c.fail('数据获取失败');
+    }
+
+    return c.ok(await this.formatItem(doc));
+  }
+
+  async create(c: Context) {
+    const Model = this.requireModel();
+    const body = await this.body();
+
+    (this as any).isNew = true;
+
+    if (typeof (this as any).beforeCreate === 'function') {
+      await (this as any).beforeCreate();
+    }
+
+    if (typeof (this as any).beforeSave === 'function') {
+      await (this as any).beforeSave();
+    }
+
+    const doc = await Model.create(body);
+
+    if (typeof (this as any).afterSave === 'function') {
+      await (this as any).afterSave(doc);
+    }
+
+    return c.ok(undefined, '操作成功');
+  }
+
+  async update(c: Context) {
+    const Model = this.requireModel();
+    const body = await this.body();
+    const ids = (c.req.param('id') ?? '').split(',').filter(Boolean);
+
+    (this as any).isUpdate = true;
+    (this as any).isBatch = ids.length > 1;
+
+    if ((this as any).isBatch && !this.batchAction) {
+      return c.fail('不可批量操作');
+    }
+
+    if (typeof (this as any).beforeUpdate === 'function') {
+      await (this as any).beforeUpdate();
+    }
+
+    if (typeof (this as any).beforeSave === 'function') {
+      await (this as any).beforeSave();
+    }
+
+    let doc: any;
+
+    if ((this as any).isBatch) {
+      await Model.updateMany({ [this.key]: { $in: ids } }, body);
+    } else {
+      doc = await Model.findOneAndUpdate({ [this.key]: ids[0] }, body, { new: true });
+    }
+
+    if (typeof (this as any).afterSave === 'function') {
+      await (this as any).afterSave(doc);
+    }
+
+    return c.ok(undefined, '操作成功');
+  }
+
+  async delete(c: Context) {
+    const Model = this.requireModel();
+    const ids = (c.req.param('id') ?? '').split(',').filter(Boolean);
+
+    if (ids.length > 1 && !this.batchAction) {
+      return c.fail('不可批量操作');
+    }
+
+    await Model.deleteMany({ [this.key]: { $in: ids } });
+
+    return c.ok(undefined, '操作成功');
+  }
+
+  async destroy(c: Context) {
+    return this.delete(c);
+  }
+
+  protected async getFilter(extraFilter?: Record<string, any>) {
+    const query = this.context.req.query();
+    const filter: Record<string, any> = { ...(extraFilter ?? {}) };
+    const searchKeys = arrayFrom<string>((this as any).searchKey ?? (this as any).searchKeys);
+    const likeKeys = arrayFrom<string>((this as any).likeKey ?? (this as any).likeKeys);
+
+    for (const key of searchKeys) {
+      if (query[key] !== undefined && query[key] !== '') {
+        filter[key] = query[key];
+      }
+    }
+
+    for (const key of likeKeys) {
+      if (query[key] !== undefined && query[key] !== '') {
+        filter[key] = new RegExp(escapeRegex(query[key]), 'i');
+      }
+    }
+
+    const customGetFilter = getCustomMethod(this, 'getFilter', ApiController.prototype.getFilter);
+
+    if (customGetFilter) {
+      Object.assign(filter, await customGetFilter.call(this, filter));
+    } else if ((this as any).filter) {
+      Object.assign(filter, (this as any).filter);
+    }
+
+    return filter;
+  }
+
+  protected async formatList(list: any[]) {
+    return Promise.all(list.map((item) => this.formatItem(item)));
+  }
+
+  protected async formatItem(item: any) {
+    const data = item?.toJSON ? item.toJSON() : { ...item };
+
+    if (typeof (this as any).formatData === 'function') {
+      const formatted = await (this as any).formatData(data);
+
+      return formatted ?? data;
+    }
+
+    return data;
+  }
+
+  private requireModel() {
+    if (!this.Model) {
+      throw new Error(`${this.constructor.name} must define Model.`);
+    }
+
+    return this.Model;
+  }
+}
+
+function getCustomMethod(target: object, name: string, baseMethod: Function) {
+  let prototype = Object.getPrototypeOf(target);
+
+  while (prototype && prototype !== ApiController.prototype) {
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+
+    if (typeof descriptor?.value === 'function' && descriptor.value !== baseMethod) {
+      return descriptor.value;
+    }
+
+    prototype = Object.getPrototypeOf(prototype);
+  }
+
+  return undefined;
+}

package/core/app.ts

@@ -0,0 +1,199 @@
+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 { requestLog } from '../middleware/request-log';
+import type { Hono } from 'hono';
+import type { JaxHono } from './hono';
+import type { plugins as generatedPlugins } from '../generated/plugins.generated';
+
+type Models = typeof generatedModels;
+type CreateServices = typeof generatedCreateServices;
+type Services = ReturnType<CreateServices>;
+type Plugins = typeof generatedPlugins;
+
+type MaybePromise<T> = T | Promise<T>;
+
+export type AppContext = {
+  app: Hono;
+  config: Config;
+  model: Models;
+  service: Services;
+  plugin: Plugins & Record<string, any>;
+};
+
+export type AppRuntimeDeps = {
+  models: Models;
+  createServices: CreateServices;
+};
+
+export type AppPluginObject = {
+  setup?: (ctx: AppContext, options?: unknown) => MaybePromise<void>;
+  ready?: (ctx: AppContext, options?: unknown) => MaybePromise<void>;
+  close?: (ctx: AppContext, options?: unknown) => MaybePromise<void>;
+};
+
+export type AppPlugin =
+  | ((ctx: AppContext, options?: unknown) => MaybePromise<void>)
+  | AppPluginObject;
+
+type ModuleItem<T> = {
+  name: string;
+  module?: T;
+  load?: () => Promise<{ default?: T } | T>;
+  enable?: (ctx: AppContext) => boolean;
+  options?: unknown;
+};
+
+type ActivePlugin = {
+  name: string;
+  plugin: AppPluginObject;
+  options?: unknown;
+};
+
+export function createApp(deps: AppRuntimeDeps): JaxHono {
+  const app = createHono();
+
+  const ctx: AppContext = {
+    app,
+    config,
+    model: deps.models,
+    service: undefined as unknown as Services,
+    plugin: {} as Plugins
+  };
+  const activePlugins: ActivePlugin[] = [];
+
+  ctx.service = deps.createServices(ctx);
+  app.jax = ctx;
+
+  app.use('*', requestLog);
+
+  app.use('*', async (c, next) => {
+    const state = {};
+
+    c.state = state;
+    c.model = ctx.model;
+    c.service = ctx.service;
+
+    c.set('state', state);
+    c.set('model', ctx.model);
+    c.set('service', ctx.service);
+
+    await runWithJaxContext(c, next);
+  });
+
+  const ready = Promise.all(
+    (pluginModules as readonly ModuleItem<AppPlugin>[]).map((item) => setupPluginSafely(item, ctx))
+  ).then(async (plugins) => {
+    activePlugins.push(...plugins.filter((plugin): plugin is ActivePlugin => Boolean(plugin)));
+
+    printEnabledPlugins(activePlugins);
+
+    await Promise.all(activePlugins.map((plugin) => runPluginReadySafely(plugin, ctx)));
+  });
+
+  app.ready = ready;
+  app.close = async () => {
+    await ready.catch(() => undefined);
+    await closePluginsSafely(activePlugins, ctx);
+  };
+
+  return app;
+}
+
+async function setupPlugin(
+  item: ModuleItem<AppPlugin>,
+  ctx: AppContext
+): Promise<ActivePlugin | undefined> {
+  if (item.enable && !item.enable(ctx)) {
+    return;
+  }
+
+  const loadedPlugin = item.module ?? (await loadPlugin(item));
+  const plugin =
+    loadedPlugin && typeof loadedPlugin === 'object' && 'default' in loadedPlugin
+      ? loadedPlugin.default
+      : loadedPlugin;
+
+  if (typeof plugin === 'function') {
+    await plugin(ctx, item.options);
+    return;
+  }
+
+  if (isPluginObject(plugin)) {
+    await plugin.setup?.(ctx, item.options);
+    return {
+      name: item.name,
+      plugin,
+      options: item.options
+    };
+  }
+
+  throw new TypeError(`Plugin ${item.name} must export a function or lifecycle object.`);
+}
+
+function isPluginObject(plugin: unknown): plugin is AppPluginObject {
+  if (!plugin || typeof plugin !== 'object') {
+    return false;
+  }
+
+  return ['setup', 'ready', 'close'].some((key) => key in plugin);
+}
+
+async function loadPlugin(item: ModuleItem<AppPlugin>) {
+  if (!item.load) {
+    throw new TypeError(`Plugin ${item.name} must define module or load.`);
+  }
+
+  return item.load();
+}
+
+async function setupPluginSafely(item: ModuleItem<AppPlugin>, ctx: AppContext) {
+  try {
+    return await setupPlugin(item, ctx);
+  } catch (error) {
+    console.error(`Jax plugin setup failed [${item.name}]:`, error);
+    return undefined;
+  }
+}
+
+async function runPluginReadySafely(item: ActivePlugin, ctx: AppContext) {
+  if (!item.plugin.ready) {
+    return;
+  }
+
+  try {
+    await item.plugin.ready(ctx, item.options);
+  } catch (error) {
+    console.error(`Jax plugin ready failed [${item.name}]:`, error);
+  }
+}
+
+function printEnabledPlugins(plugins: ActivePlugin[]) {
+  if (plugins.length === 0) {
+    console.log('[plugins] enabled: none');
+    return;
+  }
+
+  console.log(`[plugins] enabled: ${plugins.map((plugin) => plugin.name).join(', ')}`);
+}
+
+async function closePluginsSafely(plugins: ActivePlugin[], ctx: AppContext) {
+  for (const item of [...plugins].reverse()) {
+    if (!item.plugin.close) {
+      continue;
+    }
+
+    try {
+      await item.plugin.close(ctx, item.options);
+    } catch (error) {
+      console.error(`Jax plugin close failed [${item.name}]:`, error);
+    }
+  }
+}
+
+export { createApi, createHono, registerCrudRoutes };

package/core/controller.ts

@@ -0,0 +1,86 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Context } from 'hono';
+import type { Models } from '../generated/models.generated';
+import type { Services } from '../generated/services.generated';
+
+const controllerContextStorage = new AsyncLocalStorage<Context>();
+type ControllerConstructor<T extends Controller> = new (...args: any[]) => T;
+type ControllerExport<T extends Controller> = T | ControllerConstructor<T>;
+
+export function runWithJaxContext<T>(c: Context, callback: () => T) {
+  return controllerContextStorage.run(c, callback);
+}
+
+export function getJaxContext() {
+  const context = controllerContextStorage.getStore();
+
+  if (!context) {
+    throw new Error('Jax request context is not available.');
+  }
+
+  return context;
+}
+
+export function createController<T extends Controller>(controller: ControllerExport<T>) {
+  return typeof controller === 'function' ? new controller() : controller;
+}
+
+export abstract class Controller {
+  constructor() {
+    this.bindMethods();
+  }
+
+  protected get context() {
+    return getJaxContext();
+  }
+
+  protected get ctx() {
+    return this.context;
+  }
+
+  protected get state() {
+    return this.context.get('state');
+  }
+
+  protected get model(): Models {
+    return this.context.get('model');
+  }
+
+  protected get service(): Services {
+    return this.context.get('service');
+  }
+
+  protected get session() {
+    return this.context.get('session');
+  }
+
+  private bindMethods() {
+    let prototype = Object.getPrototypeOf(this);
+
+    while (prototype && prototype !== Controller.prototype) {
+      for (const name of Object.getOwnPropertyNames(prototype)) {
+        if (name === 'constructor') {
+          continue;
+        }
+
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+
+        if (typeof descriptor?.value !== 'function') {
+          continue;
+        }
+
+        if (Object.prototype.hasOwnProperty.call(this, name)) {
+          continue;
+        }
+
+        Object.defineProperty(this, name, {
+          configurable: true,
+          writable: true,
+          value: descriptor.value.bind(this),
+        });
+      }
+
+      prototype = Object.getPrototypeOf(prototype);
+    }
+  }
+}

package/core/hono.ts

@@ -0,0 +1,64 @@
+import { Hono } from 'hono';
+import { apiResponse } from '../middleware/api-response';
+import { registerCrudRoutes, type JaxCrudController } from '../helpers/crud';
+import type { Models } from '../generated/models.generated';
+import type { Services } from '../generated/services.generated';
+import type { JaxState } from '../types/context';
+
+declare module 'hono' {
+  interface Context {
+    state: JaxState;
+    model: Models;
+    service: Services;
+  }
+
+  interface ContextVariableMap {
+    model: Models;
+    service: Services;
+    state: JaxState;
+  }
+}
+
+export type JaxHono = Hono & {
+  ready?: Promise<void>;
+  close?: () => Promise<void>;
+  jax?: unknown;
+  resources(path: string, controller: JaxCrudController): JaxHono;
+};
+
+export function createHono(): JaxHono {
+  const app = new Hono();
+
+  return withJaxRoutes(app);
+}
+
+export function createApi() {
+  const api = createHono();
+
+  // API 路由默认使用 { code, msg, data } 响应结构，并统一兜底异常返回。
+  api.use('*', apiResponse);
+  api.notFound((c) => c.fail('接口不存在'));
+  api.onError((error, c) => {
+    const message = error instanceof Error ? error.message : String(error);
+
+    console.error('API 请求失败:', error);
+
+    return c.fail(message);
+  });
+
+  return api;
+}
+
+function withJaxRoutes(app: Hono): JaxHono {
+  const jaxApp = app as JaxHono;
+
+  jaxApp.resources = (path, controller) => {
+    registerCrudRoutes(jaxApp, path, controller);
+
+    return jaxApp;
+  };
+
+  return jaxApp;
+}
+
+export { Hono };

package/core/service.ts

@@ -0,0 +1,46 @@
+import type { Config } from '../config';
+import type { Models } from '../generated/models.generated';
+import type { Services } from '../generated/services.generated';
+import type { plugins as generatedPlugins } from '../generated/plugins.generated';
+import { getJaxContext } from './controller';
+
+type Plugins = typeof generatedPlugins;
+
+export type ServiceContext = {
+  config: Config;
+  model: Models;
+  service: Services;
+  plugin: Plugins;
+};
+
+export abstract class Service {
+  constructor(protected readonly appContext: ServiceContext) {}
+
+  protected get context() {
+    return getJaxContext();
+  }
+
+  protected get ctx() {
+    return this.context;
+  }
+
+  protected get state() {
+    return this.context.get('state');
+  }
+
+  protected get config() {
+    return this.appContext.config;
+  }
+
+  protected get model() {
+    return this.appContext.model;
+  }
+
+  protected get service() {
+    return this.appContext.service;
+  }
+
+  protected get plugin(): Plugins {
+    return this.appContext.plugin;
+  }
+}