moonbridge-ts 0.1.0

package/src/moonbridge/annotation/registry.ts

@@ -0,0 +1,118 @@
+/**
+ * MoonBridge 注解注册表，对应 Flutter annotation 生成的元信息。
+ * 维护模块名到类、模块+方法别名到方法元信息的映射。
+ */
+
+import { Bridge } from '../kernel/bridge';
+import { BridgeModule } from '../kernel/bridge_module';
+import { logger } from '../utils/logger';
+
+/** 
+ * 方法元信息 
+ * 通过 className 和 methodName 就可以定位到指定类的方法
+ */
+export interface MethodSpec {
+  /** 类名 */
+  className: string;
+  /** 方法名 */
+  methodName: string;
+}
+
+/**
+ * module 构造函数类型：
+ * - 所有通过 @MoonBridgeModule 装饰的类都必须继承自 BridgeModule
+ * - 构造函数签名固定为 new (bridge: Bridge)
+ */
+export type ModuleConstructor = new (bridge: Bridge) => BridgeModule;
+
+// PUBLIC CLASS
+
+/**
+ * MoonBridge 注册表
+ */
+export class MoonBridgeRegistry {
+  private static instance: MoonBridgeRegistry | undefined = undefined;
+
+  // PROPERTIES
+
+  /** 模块名 -> 类构造函数 */
+  public readonly moduleCtorMap = new Map<string, ModuleConstructor>();
+  /** "module:alias" -> 方法元信息 */
+  private readonly methodSpecMap = new Map<string, MethodSpec>();
+
+  // CONSTRUCTOR
+
+  private constructor() { }
+
+  // PUBLIC METHODS
+
+  /**
+   * 获取注册表实例
+   * @returns 注册表实例
+   */
+  static getInstance(): MoonBridgeRegistry {
+    if (!this.instance) {
+      this.instance = new MoonBridgeRegistry();
+    }
+    return this.instance;
+  }
+
+  /**
+   * 注册模块
+   * @param module 模块名
+   * @param clazz 模块类构造函数
+   */
+  registerModule(module: string, clazz: ModuleConstructor): void {
+    logger.info(`[Registry] 模块注册 moduleName=${module} className=${clazz.name}`);
+    this.moduleCtorMap.set(module, clazz);
+  }
+
+  /**
+   * 注册方法
+   * @param module 模块名
+   * @param method 方法别名
+   * @param spec 方法元信息
+   */
+  registerMethod(
+    module: string,
+    method: string,
+    spec: MethodSpec,
+  ): void {
+    logger.info(`[Registry] 方法注册 moduleName=${module} methodAlias=${method} methodName=${spec.methodName}`);
+    const key = this.formatMethodKey(module, method);
+    this.methodSpecMap.set(key, spec);
+  }
+
+  /**
+   * 获取模块类构造函数
+   * @param module 模块名
+   * @returns 模块类构造函数
+   */
+  getModuleCtor(module: string): ModuleConstructor | undefined {
+    return this.moduleCtorMap.get(module);
+  }
+
+  /**
+   * 获取方法元信息
+   * @param module 模块名
+   * @param method 方法别名
+   * @returns 方法元信息
+   */
+  getMethodSpec(module: string, method: string): MethodSpec | undefined {
+    const key = this.formatMethodKey(module, method);
+    return this.methodSpecMap.get(key);
+  }
+
+  // PRIVATE METHODS
+
+  /**
+   * 格式化方法 key
+   * @param module 模块名
+   * @param method 方法别名
+   * @returns 方法 key
+   */
+  private formatMethodKey(module: string, method: string): string {
+    return `${module}:${method}`;
+  }
+}
+

package/src/moonbridge/index.ts

@@ -0,0 +1,5 @@
+export * from './kernel/bridge_module';
+export * from './kernel/bridge';
+export * from './annotation/decorators';
+export * from './annotation/registry';
+export * from './logger/logger';

package/src/moonbridge/kernel/bridge.ts

@@ -0,0 +1,28 @@
+/**
+ * 桥接接口抽象，对应 Flutter lib/kernel/bridge.dart Bridge。
+ *
+ * Bridge 负责提供：
+ * - 方法执行器 Executor；
+ * - module 实例构造器 ModuleCreator；
+ * - 消息解析器管理器 MessageParserManager。
+ *
+ * 具体实现由上层在 JS 端根据运行环境提供。
+ */
+
+import { Executor } from '../kernel/executor';
+import { ModuleCreator } from '../module/module_creator';
+import { MessageParserManager } from '../message/message_parser_manager';
+
+// PUBLIC TYPES
+
+export interface Bridge {
+  /** 获取方法执行器 */
+  readonly executor: Executor;
+
+  /** 获取 module 实例构造器 */
+  readonly moduleCreator: ModuleCreator;
+
+  /** 获取消息解析器实例 */
+  readonly parserManager: MessageParserManager;
+}
+

package/src/moonbridge/kernel/bridge_module.ts

@@ -0,0 +1,38 @@
+/**
+ * 自定义 module 抽象接口，对应 Flutter lib/kernel/bridge_module.dart BridgeModule。
+ *
+ * JS 端职责：
+ * - 绑定一个 Bridge 实例（构造函数 BridgeModule(bridge: Bridge)）；
+ * - 暴露只读的 bridge getter。
+ *
+ * 方法暴露信息完全由装饰器 + MoonBridgeRegistry 负责，
+ * BridgeModule 本身不再提供 methodsToExport 等注册表接口。
+ */
+
+import { Bridge } from './bridge';
+
+export abstract class BridgeModule {
+  // PROPERTIES
+
+  /** 绑定的 bridge 引用（WeakReference 在 JS 中用普通引用表达）。 */
+  private readonly _bridge: Bridge;
+
+  // CONSTRUCTOR
+
+  /**
+   * 指定构造方法，并在这里传递绑定的 bridge 实例。
+   */
+  public constructor(bridge: Bridge) {
+    this._bridge = bridge;
+  }
+
+  // PUBLIC METHODS
+
+  /**
+   * 获取绑定的 bridge 对象。
+   */
+  get bridge(): Bridge {
+    return this._bridge;
+  }
+}
+

package/src/moonbridge/kernel/executor.ts

@@ -0,0 +1,41 @@
+/**
+ * 消息执行器抽象接口，对应 Flutter lib/kernel/executor.dart Executor。
+ *
+ * Executor 绑定一个 Bridge 实例，并根据元数据执行指定模块中的方法。
+ */
+
+import { Bridge } from './bridge';
+
+export abstract class Executor {
+  // PROPERTIES
+
+  /** 绑定的 bridge 引用（WeakReference 在 JS 中用普通引用表达）。 */
+  private readonly _bridge: Bridge;
+
+  // CONSTRUCTOR
+
+  /**
+   * 指定构造方法，并在这里传递绑定的 bridge 实例。
+   */
+  protected constructor(bridge: Bridge) {
+    this._bridge = bridge;
+  }
+
+  // PUBLIC METHODS
+
+  /**
+   * 获取绑定的 bridge 对象。
+   */
+  get bridge(): Bridge {
+    // Flutter 使用 WeakReference<Bridge>，这里先用普通引用表示；
+    // 如需弱引用语义，可在未来扩展。
+    return this._bridge;
+  }
+
+  /**
+   * 根据原数据 metaData 执行指定类中的指定方法，需要在子类中实现，
+   * 并返回最终执行结果：true 为执行成功，false 为执行失败。
+   */
+  abstract invokeMethod(metaData: unknown): boolean;
+}
+

package/src/moonbridge/kernel/result_callback.ts

@@ -0,0 +1,19 @@
+/**
+ * 自定义 module 中的回调接口定义。
+ * 对应 Flutter lib/kernel/result_callback.dart ResultCallback。
+ *
+ * 通过该接口可以向请求方发送响应数据：
+ * - 使用 invoke(args) 发送一批响应数据；
+ * - 可选参数 finished 用于标记响应链路是否结束，默认为 true。
+ */
+
+export interface ResultCallback {
+  /**
+   * 向请求方发送响应数据。
+   *
+   * @param args    用于传递响应数据的参数数组
+   * @param finished 可选，控制响应链路完成状态，默认为 true
+   */
+  invoke(args: unknown[], finished?: boolean): void;
+}
+

package/src/moonbridge/logger/logger.ts

@@ -0,0 +1,95 @@
+/**
+ * Logger 类，对应 Flutter lib/statistics/logger.dart。
+ * 支持 tag 缓存、LogSubscriber 订阅、多级别日志。
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+export type LogSubscriber = (
+  tag: string,
+  level: LogLevel,
+  message: string,
+  opts?: { file?: string; func?: string }
+) => void;
+
+/**
+ * Logger 类
+ * 支持 tag 缓存、LogSubscriber 订阅、多级别日志。
+ */
+export class Logger {
+  private static readonly _loggers = new Map<string, Logger>();
+  private static _subscribers: LogSubscriber[] = [];
+
+  readonly tag: string;
+  private _subscriber?: LogSubscriber;
+
+  private constructor(tag: string) {
+    this.tag = tag;
+  }
+
+  /** 
+   * 工厂：按 tag 缓存，同 tag 返回同一实例。 
+   */
+  static get(tag: string): Logger {
+    let logger = Logger._loggers.get(tag);
+    if (!logger) {
+      logger = new Logger(tag);
+      Logger._loggers.set(tag, logger);
+    }
+    return logger;
+  }
+
+  static addSubscriber(callback: LogSubscriber): void {
+    Logger._subscribers.push(callback);
+  }
+
+  static removeSubscriber(callback: LogSubscriber): void {
+    Logger._subscribers = Logger._subscribers.filter((cb) => cb !== callback);
+  }
+
+  static enumerate(action: (tag: string, logger: Logger) => void): void {
+    Logger._loggers.forEach((logger, tag) => action(tag, logger));
+  }
+
+  set subscriber(cb: LogSubscriber) {
+    this._subscriber = cb;
+  }
+
+  private notify(level: LogLevel, message: string, opts?: { file?: string; func?: string }): void {
+    const subs = [...Logger._subscribers];
+    if (this._subscriber) subs.push(this._subscriber);
+    for (const cb of subs) {
+      try {
+        cb(this.tag, level, message, opts);
+      } catch {
+        // 静默处理，不影响 SDK
+      }
+    }
+  }
+
+  log(level: LogLevel, message: string, opts?: { file?: string; func?: string }): void {
+    this.notify(level, message, opts);
+    const levelUpper = level.toUpperCase();
+    console.log(`[${this.tag}|${levelUpper}] ${message}`);
+  }
+
+  debug(message: string, opts?: { file?: string; func?: string }): void {
+    this.log('debug', message, opts);
+  }
+
+  info(message: string, opts?: { file?: string; func?: string }): void {
+    this.log('info', message, opts);
+  }
+
+  warn(message: string, opts?: { file?: string; func?: string }): void {
+    this.log('warn', message, opts);
+  }
+
+  error(message: string, opts?: { file?: string; func?: string }): void {
+    this.log('error', message, opts);
+  }
+
+  fatal(message: string, opts?: { file?: string; func?: string }): void {
+    this.log('fatal', message, opts);
+  }
+}

package/src/moonbridge/message/internal/generic_message_parser.internal.ts

@@ -0,0 +1,39 @@
+import { Message } from '../message';
+import { MessageParser, MessageParserChain } from '../message_parser';
+
+// PUBLIC CLASS
+
+/**
+ * 通用消息解析器
+ *
+ * 约定 metaData 为形如：
+ * {
+ *   moduleName: string;
+ *   methodName: string;
+ *   arguments?: unknown[];
+ * }
+ */
+export class GenericMessageParser extends MessageParser {
+  // PUBLIC METHODS
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  parse(chain: MessageParserChain): Message | Message[] | undefined {
+    const metaData = chain.metaData;
+    if (metaData === null || typeof metaData !== 'object') {
+      return chain.proceed(metaData);
+    }
+
+    const moduleName = (metaData as any).moduleName;
+    const methodName = (metaData as any).methodName;
+    if (typeof moduleName !== 'string' || typeof methodName !== 'string') {
+      return chain.proceed(metaData);
+    }
+
+    const args = (metaData as any).arguments as unknown[] | undefined;
+    return {
+      moduleName,
+      methodName,
+      arguments: args,
+    };
+  }
+}

package/src/moonbridge/message/message.ts

@@ -0,0 +1,16 @@
+/**
+ * 消息体结构定义，对应 Flutter lib/message/message.dart 中的 Message。
+ */
+
+// PUBLIC TYPES
+
+export interface Message {
+  /** 模块名称 */
+  readonly moduleName: string;
+
+  /** 方法名称 */
+  readonly methodName: string;
+
+  /** 参数列表 */
+  readonly arguments?: unknown[];
+}

package/src/moonbridge/message/message_parser.ts

@@ -0,0 +1,31 @@
+import { Message } from './message';
+
+// PUBLIC CLASS
+
+/**
+ * 消息解析器，对应 Flutter lib/message/message_parser.dart 中的 MessageParser。
+ *
+ * 解析链返回值语义：
+ * - Message: 单个消息
+ * - Message[]: 批量消息
+ * - undefined: 无法解析
+ */
+export abstract class MessageParser {
+  abstract parse(chain: MessageParserChain): Message | Message[] | undefined;
+}
+
+/**
+ * 消息解析拦截器链，对应 Flutter MessageParserChain。
+ */
+export abstract class MessageParserChain {
+  /** 当前解析器处理的原始 metaData。 */
+  abstract get metaData(): any;
+
+  /**
+   * 处理 metaData 并返回解析结果。
+   *
+   * 返回值语义同 MessageParser.parse。
+   */
+  abstract proceed(metaData: any): Message | Message[] | undefined;
+}
+

package/src/moonbridge/message/message_parser_manager.ts

@@ -0,0 +1,96 @@
+import { Message } from './message';
+import { GenericMessageParser } from './internal/generic_message_parser.internal';
+import { MessageParser, MessageParserChain } from './message_parser';
+
+// PUBLIC CLASS
+
+/**
+ * 解析管理器，对应 Flutter lib/message/message_parser_manager.dart。
+ */
+export class MessageParserManager {
+  // PROPERTIES
+
+  private readonly parsers: MessageParser[];
+
+  // CONSTRUCTOR
+
+  constructor(parsers?: MessageParser[]) {
+    this.parsers = [...(parsers ?? []), new GenericMessageParser()];
+  }
+
+  // PUBLIC METHODS
+
+  /**
+   * 解析 metaData 并返回解析结果。
+   *
+   * 返回值：
+   * - Message: 单个消息
+   * - Message[]: 批量消息
+   * - undefined: 无法解析
+   */
+  parse(metaData: unknown): Message | Message[] | undefined {
+    if (metaData == null || this.parsers.length === 0) {
+      return undefined;
+    }
+
+    const chain = new RealMessageParserChain({
+      parsers: this.parsers,
+      metaData,
+      index: 0,
+    });
+
+    return chain.proceed(metaData) as Message | Message[] | undefined;
+  }
+}
+
+// INTERNAL TYPES
+
+interface RealMessageParserChainInit {
+  parsers: MessageParser[];
+  metaData: unknown;
+  index: number;
+}
+
+// INTERNAL CLASS
+
+/**
+ * 消息解析器链实现类，对应 Flutter _RealMessageParserChain。
+ */
+class RealMessageParserChain extends MessageParserChain {
+  // PROPERTIES
+
+  private readonly parsers: MessageParser[];
+  private readonly index: number;
+  private readonly currentMetaData: unknown;
+
+  // CONSTRUCTOR
+
+  constructor(init: RealMessageParserChainInit) {
+    super();
+    this.parsers = init.parsers;
+    this.index = init.index;
+    this.currentMetaData = init.metaData;
+  }
+
+  // PUBLIC METHODS
+
+  get metaData(): unknown {
+    return this.currentMetaData;
+  }
+
+  proceed(metaData: unknown): Message | Message[] | undefined {
+    if (this.index >= this.parsers.length) {
+      return undefined;
+    }
+
+    const next = new RealMessageParserChain({
+      parsers: this.parsers,
+      index: this.index + 1,
+      metaData,
+    });
+
+    const parser = this.parsers[this.index];
+    return parser.parse(next) as Message | Message[] | undefined;
+  }
+}
+

package/src/moonbridge/module/method_invoker.ts

@@ -0,0 +1,90 @@
+import { BridgeModule } from '../kernel/bridge_module';
+import { MoonBridgeRegistry } from '../annotation/registry';
+
+// PUBLIC CLASS
+
+/**
+ * 方法调用功能抽象（自定义 module 中的函数最终在这里被调用），
+ * 对应 Flutter lib/module/method_invoker.dart。
+ *
+ * JS 端：通过 MoonBridgeRegistry 中的方法元信息找到真实方法并执行。
+ */
+export class InvokerProvider {
+  // PROPERTIES
+
+  /** Key - invokerId，由 moduleName 与 methodAlias 组合而成。Value - MethodInvoker 实例。 */
+  private readonly invokerMap = new Map<string, MethodInvoker>();
+
+  // PUBLIC METHODS
+
+  /**
+   * 根据 moduleName 与 methodAlias 获取指定的方法执行器。
+   *
+   * 真实函数来源：
+   * - 由 @MoonBridgeMethod 装饰器注册到 MoonBridgeRegistry；
+   * - 从传入的 module 实例上按真实方法名获取。
+   */
+  getInvoker(
+    module: BridgeModule,
+    moduleName: string,
+    methodAlias: string,
+  ): MethodInvoker | undefined {
+    const invokerId = this.formatInvokerId(moduleName, methodAlias);
+    const cached = this.invokerMap.get(invokerId);
+    if (cached) {
+      return cached;
+    }
+
+    const registry = MoonBridgeRegistry.getInstance();
+    const methodSpec = registry.getMethodSpec(moduleName, methodAlias);
+    if (!methodSpec) {
+      return undefined;
+    }
+
+    // 重点：
+    //  从 module 实例上根据 methodSpec.methodName 获取函数
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fn = (module as any)[methodSpec.methodName];
+    if (typeof fn !== 'function') {
+      return undefined;
+    }
+
+    // 创建方法调用器并缓存
+    const invoker = new MethodInvoker(fn);
+    this.invokerMap.set(invokerId, invoker);
+    return invoker;
+  }
+
+  // PRIVATE METHODS
+
+  /**
+   * 格式化方法调用器 ID
+   * @param moduleName 模块名
+   * @param methodAlias 方法别名
+   * @returns 方法调用器 ID
+   */
+  private formatInvokerId(moduleName: string, methodAlias: string): string {
+    return `${moduleName}-${methodAlias}`;
+  }
+}
+
+/**
+ * 方法调用器，对应 Flutter MethodInvoker。
+ */
+export class MethodInvoker {
+  // CONSTRUCTOR
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  constructor(public readonly f: (...args: any[]) => any) { }
+
+  // PUBLIC METHODS
+
+  /**
+   * 执行具体函数。
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  invoke(_module: BridgeModule, args: any[]): any {
+    return this.f(...args);
+  }
+}
+

package/src/moonbridge/module/module_creator.ts

@@ -0,0 +1,60 @@
+import { Bridge } from '../kernel/bridge';
+import { BridgeModule } from '../kernel/bridge_module';
+import { MoonBridgeRegistry } from '../annotation/registry';
+
+// PUBLIC CLASS
+
+/**
+ * module 实例构造器，对应 Flutter lib/module/module_creator.dart。
+ *
+ * JS 端：通过 MoonBridgeRegistry 中已注册的模块构造函数创建实例，
+ * 不再依赖 ModuleFactory 列表。
+ */
+export class ModuleCreator {
+  // PROPERTIES
+
+  private readonly cacheMap = new Map<string, BridgeModule>();
+  /** JS 中没有 WeakReference 的通用实现，这里直接持有强引用。 */
+  private readonly _bridge: Bridge;
+
+  // CONSTRUCTOR
+
+  constructor(bridge: Bridge) {
+    this._bridge = bridge;
+  }
+
+  // PUBLIC METHODS
+
+  /**
+   * 获取绑定的 bridge 对象。
+   */
+  get bridge(): Bridge {
+    return this._bridge;
+  }
+
+  /**
+   * 获取名为 name 的 module 实例。
+   *
+   * 创建流程：
+   * - 优先从本地缓存中读取；
+   * - 若无缓存，则从 MoonBridgeRegistry 中获取构造函数并创建实例；
+   * - 创建成功后写入缓存并返回。
+   */
+  getModule(name: string): BridgeModule | undefined {
+    const cached = this.cacheMap.get(name);
+    if (cached) {
+      return cached;
+    }
+
+    const registry = MoonBridgeRegistry.getInstance();
+    const ctor = registry.getModuleCtor(name);
+    if (!ctor) {
+      return undefined;
+    }
+
+    const module = new ctor(this.bridge);
+    this.cacheMap.set(name, module);
+    return module;
+  }
+}
+

package/src/moonbridge/utils/logger.ts

@@ -0,0 +1,6 @@
+/**
+ * moonbridge 模块共享 logger 实例，tag 为 moonbridge。
+ */
+import { Logger } from '../logger/logger';
+
+export const logger = Logger.get('moonbridge');