@zimi/remote 0.1.0

package/dist/response.d.ts

@@ -0,0 +1,104 @@
+interface RawRemoteError {
+    /**
+     * code > 0 才是合法的 Error;
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    code: number;
+    /**
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    name: string;
+    /**
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    message: string;
+}
+/**
+ * name 和 message 都是 human readable 的字符串,
+ * 仅用于调试和展示,
+ * 程序逻辑判断请使用 code
+ */
+export declare class RemoteError extends Error {
+    /**
+     * code > 0 才是合法的 Error;
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    code: number;
+    /**
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    constructor(message: string);
+    toJson(): RawRemoteError;
+    toString(): string;
+    valueOf(): string;
+    static fromError(err: unknown): RemoteError;
+    static isRemoteError(data: unknown): data is RawRemoteError;
+}
+/**
+ * name 和 message 都是 human readable 的字符串,
+ * 仅用于调试和展示,
+ * 程序逻辑判断请使用 code
+ */
+export declare class RemoteTimeoutError extends RemoteError {
+    /**
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    static code: number;
+    /**
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    code: number;
+    /**
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    constructor(message: string);
+}
+/**
+ * name 和 message 都是 human readable 的字符串,
+ * 仅用于调试和展示,
+ * 程序逻辑判断请使用 code
+ */
+export declare class RemoteNotFoundError extends RemoteError {
+    /**
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    static code: number;
+    /**
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    code: number;
+    /**
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    constructor(message: string);
+}
+export declare const response: {
+    success<T>(data: T): {
+        readonly code: 0;
+        readonly data: T;
+    };
+    error(error: RemoteError): RawRemoteError;
+};
+export {};

package/dist/response.js

@@ -0,0 +1,155 @@
+/**
+ * name 和 message 都是 human readable 的字符串,
+ * 仅用于调试和展示,
+ * 程序逻辑判断请使用 code
+ */
+export class RemoteError extends Error {
+    /**
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    constructor(message) {
+        super(message);
+        /**
+         * code > 0 才是合法的 Error;
+         * name 和 message 都是 human readable 的字符串,
+         * 仅用于调试和展示,
+         * 程序逻辑判断请使用 code
+         */
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 1
+        });
+        this.name = 'RemoteError';
+    }
+    toJson() {
+        return {
+            code: this.code,
+            name: this.name,
+            message: this.message,
+        };
+    }
+    toString() {
+        return JSON.stringify(this.toJson());
+    }
+    valueOf() {
+        return `${this.name} [${this.code}]: ${this.message}`;
+    }
+    static fromError(err) {
+        if (typeof err === 'string') {
+            return new RemoteError(err);
+        }
+        if (!err) {
+            return new RemoteError('Unknown error');
+        }
+        const json = err;
+        const error = new RemoteError(typeof json.message === 'string' ? json.message : 'Unknown error');
+        if (typeof json.code === 'number' && json.code > 0) {
+            error.code = json.code;
+        }
+        if (json.name && typeof json.name === 'string') {
+            error.name = json.name;
+        }
+        return error;
+    }
+    static isRemoteError(data) {
+        const json = data;
+        return (!!json &&
+            typeof json === 'object' &&
+            typeof json.code === 'number' &&
+            json.code > 0 &&
+            typeof json.name === 'string' &&
+            typeof json.message === 'string');
+    }
+}
+/**
+ * name 和 message 都是 human readable 的字符串,
+ * 仅用于调试和展示,
+ * 程序逻辑判断请使用 code
+ */
+export class RemoteTimeoutError extends RemoteError {
+    /**
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    constructor(message) {
+        super(message);
+        /**
+         * name 和 message 都是 human readable 的字符串,
+         * 仅用于调试和展示,
+         * 程序逻辑判断请使用 code
+         */
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 2
+        });
+        this.name = 'RemoteTimeoutError';
+    }
+}
+/**
+ * name 和 message 都是 human readable 的字符串,
+ * 仅用于调试和展示,
+ * 程序逻辑判断请使用 code
+ */
+Object.defineProperty(RemoteTimeoutError, "code", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 2
+});
+/**
+ * name 和 message 都是 human readable 的字符串,
+ * 仅用于调试和展示,
+ * 程序逻辑判断请使用 code
+ */
+export class RemoteNotFoundError extends RemoteError {
+    /**
+     * name 和 message 都是 human readable 的字符串,
+     * 仅用于调试和展示,
+     * 程序逻辑判断请使用 code
+     */
+    constructor(message) {
+        super(message);
+        /**
+         * name 和 message 都是 human readable 的字符串,
+         * 仅用于调试和展示,
+         * 程序逻辑判断请使用 code
+         */
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 3
+        });
+        this.name = 'RemoteNotFoundError';
+    }
+}
+/**
+ * name 和 message 都是 human readable 的字符串,
+ * 仅用于调试和展示,
+ * 程序逻辑判断请使用 code
+ */
+Object.defineProperty(RemoteNotFoundError, "code", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 3
+});
+export const response = {
+    success(data) {
+        return {
+            code: 0,
+            data,
+        };
+    },
+    error(error) {
+        return error.toJson();
+    },
+};
+//# sourceMappingURL=response.js.map

package/dist/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"AAuBA;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IASpC;;;;OAIG;IACH,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QAdhB;;;;;WAKG;QACH;;;;mBAAO,CAAC;WAAA;QASN,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;IAC3B,CAAC;IAED,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAA;IACH,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAA;IACtC,CAAC;IAED,OAAO;QACL,OAAO,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,OAAO,EAAE,CAAA;IACvD,CAAC;IAED,MAAM,CAAC,SAAS,CAAC,GAAY;QAC3B,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE;YAC3B,OAAO,IAAI,WAAW,CAAC,GAAG,CAAC,CAAA;SAC5B;QACD,IAAI,CAAC,GAAG,EAAE;YACR,OAAO,IAAI,WAAW,CAAC,eAAe,CAAC,CAAA;SACxC;QACD,MAAM,IAAI,GAAG,GAA8B,CAAA;QAC3C,MAAM,KAAK,GAAG,IAAI,WAAW,CAC3B,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAClE,CAAA;QACD,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE;YAClD,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;SACvB;QACD,IAAI,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE;YAC9C,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;SACvB;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,CAAC,aAAa,CAAC,IAAa;QAChC,MAAM,IAAI,GAAG,IAA+B,CAAA;QAC5C,OAAO,CACL,CAAC,CAAC,IAAI;YACN,OAAO,IAAI,KAAK,QAAQ;YACxB,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;YAC7B,IAAI,CAAC,IAAI,GAAG,CAAC;YACb,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;YAC7B,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CACjC,CAAA;IACH,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IAejD;;;;OAIG;IACH,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QAbhB;;;;WAIG;QACH;;;;mBAAO,CAAC;WAAA;QASN,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;;AAtBD;;;;GAIG;AACI;;;;WAAO,CAAC;GAAA;AAoBjB;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,WAAW;IAelD;;;;OAIG;IACH,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QAbhB;;;;WAIG;QACH;;;;mBAAO,CAAC;WAAA;QASN,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;;AAtBD;;;;GAIG;AACI;;;;WAAO,CAAC;GAAA;AAoBjB,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,OAAO,CAAI,IAAO;QAChB,OAAO;YACL,IAAI,EAAE,CAAC;YACP,IAAI;SACI,CAAA;IACZ,CAAC;IAED,KAAK,CAAC,KAAkB;QACtB,OAAO,KAAK,CAAC,MAAM,EAAE,CAAA;IACvB,CAAC;CACF,CAAA"}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@zimi/remote",
+  "license": "MIT",
+  "version": "0.1.0",
+  "author": "xiaomingTang",
+  "description": "call remote functions as local",
+  "private": false,
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": "https://github.com/xiaomingTang/xiaoming/tree/master/%40zimi/remote",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch"
+  },
+  "dependencies": {
+    "eventemitter3": "^5.0.1"
+  }
+}

package/src/adaptor.d.ts

@@ -0,0 +1,33 @@
+export interface AdaptorPackageData {
+  /**
+   * 自身设备 id，应确保唯一性（对方能凭借该 deviceId 找到该设备）
+   */
+  deviceId: string
+  /**
+   * 对方的设备 id
+   */
+  targetDeviceId: string
+  /**
+   * 远程调用的对方的方法名
+   */
+  name: string
+  data: unknown
+  /**
+   * 所需回调的方法名（如果需要回调的话）
+   */
+  callbackName?: string
+}
+
+type Func<D = unknown, R = unknown> = (data: D) => R
+
+type AdaptorCallback = Func<AdaptorPackageData, void>
+
+export interface Adaptor {
+  every: (callback: AdaptorCallback) => void
+  /**
+   * off 用于移除 once 注册的事件，当事件超时后，需要主动 off
+   */
+  off: (name: string, callback: AdaptorCallback) => void
+  once: (name: string, callback: AdaptorCallback) => void
+  emit: (data: AdaptorPackageData) => void
+}

package/src/adaptors/http.ts

@@ -0,0 +1,30 @@
+import EventEmitter from 'eventemitter3'
+
+import type { Adaptor, AdaptorPackageData } from '../adaptor'
+
+class RemoteEventManager extends EventEmitter<{
+  [key: string]: [AdaptorPackageData]
+}> {
+  EVERY_EVENT_NAME = '__remote_every__'
+
+  onEvery(fn: (data: AdaptorPackageData) => void) {
+    this.on(this.EVERY_EVENT_NAME, fn)
+  }
+}
+
+export const remoteEventManager = new RemoteEventManager()
+
+export function createHttpAdaptor({
+  onEmit,
+}: {
+  onEmit: (data: AdaptorPackageData) => void
+}) {
+  const adaptor: Adaptor = {
+    every: remoteEventManager.onEvery.bind(remoteEventManager),
+    once: remoteEventManager.once.bind(remoteEventManager),
+    off: remoteEventManager.off.bind(remoteEventManager),
+    emit: onEmit,
+  }
+
+  return adaptor
+}

package/src/adaptors/iframe.ts

@@ -0,0 +1,46 @@
+import EventEmitter from 'eventemitter3'
+import { isRemoteAdaptorData } from '../remote'
+
+import type { Adaptor, AdaptorPackageData } from '../adaptor'
+
+class RemoteEventManager extends EventEmitter<{
+  [key: string]: [AdaptorPackageData]
+}> {
+  EVERY_EVENT_NAME = '__remote_every__'
+
+  constructor() {
+    super()
+    if (typeof window === 'undefined') {
+      return
+    }
+    window.addEventListener('message', (event) => {
+      const { data } = event
+      if (isRemoteAdaptorData(data)) {
+        this.emit(data.name, data)
+        // 一定要抛出 every 事件，remote 包基于此处理远端的响应
+        this.emit(this.EVERY_EVENT_NAME, data)
+      }
+    })
+  }
+
+  onEvery(fn: (data: AdaptorPackageData) => void) {
+    this.on(this.EVERY_EVENT_NAME, fn)
+  }
+}
+
+export function createIframeAdaptor({
+  onEmit,
+}: {
+  onEmit: (data: AdaptorPackageData) => void
+}) {
+  const remoteEventManager = new RemoteEventManager()
+
+  const adaptor: Adaptor = {
+    every: remoteEventManager.onEvery.bind(remoteEventManager),
+    once: remoteEventManager.once.bind(remoteEventManager),
+    off: remoteEventManager.off.bind(remoteEventManager),
+    emit: onEmit,
+  }
+
+  return adaptor
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { Remote, isRemoteAdaptorData } from './remote'
+export type { AdaptorPackageData, Adaptor } from './adaptor'
+export {
+  RemoteError,
+  RemoteNotFoundError,
+  RemoteTimeoutError,
+  response,
+} from './response'
+export { createIframeAdaptor } from './adaptors/iframe'
+export { createHttpAdaptor, remoteEventManager } from './adaptors/http'

package/src/remote.ts

@@ -0,0 +1,257 @@
+import {
+  RemoteError,
+  RemoteNotFoundError,
+  RemoteTimeoutError,
+  response,
+} from './response'
+
+import type { Adaptor, AdaptorCallback, AdaptorPackageData } from './adaptor'
+
+const RESPONSE_PREFIX = '_response_'
+
+type LogFunc = (...data: unknown[]) => void
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type RemoteCallableFunc = (data: any) => Promise<any>
+
+interface RemoteFuncRecords {
+  [key: string]: RemoteCallableFunc
+}
+
+type FuncMapWithConfig<T extends RemoteFuncRecords> = {
+  [K in keyof T]: T[K] extends (data: infer Arg) => Promise<infer Ret>
+    ? (
+        data: Arg,
+        config?: {
+          timeoutMs?: number
+          targetDeviceId?: string
+        }
+      ) => Promise<Ret>
+    : never
+}
+
+type RegisteredFunc<T extends RemoteCallableFunc> = T extends (
+  data: infer Arg
+) => infer Ret
+  ? (
+      data: Arg,
+      ctx: {
+        /**
+         * 对方的设备 id
+         */
+        deviceId: string
+      }
+    ) => Ret
+  : never
+
+function defaultLog(
+  this: Remote<
+    {
+      [key: string]: RemoteCallableFunc
+    },
+    {
+      [key: string]: RemoteCallableFunc
+    }
+  >,
+  ...data: unknown[]
+) {
+  if (!this.debug) {
+    return
+  }
+  console.log(`[remote of ${this.deviceId}]`, ...data)
+}
+
+export class Remote<
+  /**
+   * MF means my functions
+   */
+  MF extends RemoteFuncRecords,
+  /**
+   * OF means others functions
+   */
+  OF extends RemoteFuncRecords,
+> {
+  debug = false
+
+  private log: LogFunc
+
+  /**
+   * （调用对方函数时的）默认超时时间，单位 ms
+   * @default 30000
+   */
+  private defaultTimeoutMs = 30000
+
+  private map: {
+    [key: string]: {
+      callback: RegisteredFunc<RemoteCallableFunc>
+    }
+  } = {}
+
+  private deviceIdValue = ''
+
+  /**
+   * 设备 id 应该唯一，用于区分不同设备。
+   * 你可以在任何时候修改（更新）它。
+   * @default ''
+   */
+  get deviceId() {
+    return this.deviceIdValue
+  }
+
+  set deviceId(deviceId: string) {
+    this.log(`deviceId set: from "${this.deviceIdValue}" to "${deviceId}"`)
+    this.deviceIdValue = deviceId
+  }
+
+  constructor(
+    private adaptor: Adaptor,
+    config?: {
+      /**
+       * 设备 id 应该唯一，用于区分不同设备。
+       * 你可以在任何时候修改（更新）它。
+       * @default ''
+       */
+      deviceId?: string
+      /**
+       * （调用对方函数时的）默认超时时间，单位 ms
+       * @default 30000
+       */
+      defaultTimeoutMs?: number
+      debug?: boolean
+      /**
+       * 格式化 AdaptorPackageData 的函数，
+       * 用于调试时输出日志。
+       * @default JSON.stringify
+       */
+      log?: LogFunc
+    }
+  ) {
+    this.debug = config?.debug ?? this.debug
+    this.defaultTimeoutMs = config?.defaultTimeoutMs ?? this.defaultTimeoutMs
+    this.log = config?.log ?? defaultLog.bind(this)
+    this.deviceId = config?.deviceId ?? this.deviceId
+
+    adaptor.every(async (e) => {
+      const { deviceId: selfDeviceId } = this
+      const { name, data, deviceId: targetDeviceId, callbackName } = e
+      const callback = this.map[name]?.callback
+      if (!callback) {
+        if (name.startsWith(RESPONSE_PREFIX)) {
+          // 这是响应，会在 callAsync once 中处理，这儿不用处理
+          this.log('[every] response received: ', e)
+          return
+        }
+        this.log('callback not found: ', name)
+        if (callbackName) {
+          adaptor.emit({
+            deviceId: selfDeviceId,
+            targetDeviceId,
+            name: callbackName,
+            data: response.error(
+              new RemoteNotFoundError(`callback not found: ${name}`)
+            ),
+          })
+        }
+        return
+      }
+      if (!callbackName) {
+        this.log('should not respond: ', e)
+        void callback(data, { deviceId: targetDeviceId })
+        return
+      }
+      this.log(`callback: ${name}; respondName: ${callbackName}; data: `, data)
+      try {
+        const ret = await callback(data, { deviceId: targetDeviceId })
+        this.log('callback return: ', ret)
+        adaptor.emit({
+          deviceId: selfDeviceId,
+          targetDeviceId,
+          name: callbackName,
+          data: response.success(ret),
+        })
+      } catch (error) {
+        this.log('callback error: ', error)
+        adaptor.emit({
+          deviceId: selfDeviceId,
+          targetDeviceId,
+          name: callbackName,
+          data: response.error(RemoteError.fromError(error)),
+        })
+      }
+    })
+  }
+
+  /**
+   * 调用其他端的方法；会等待对方响应。
+   * 不能直接使用该方法，应该使用 proxy。
+   * @WARNING 不能用于响应其他端。
+   */
+  private callAsync(
+    name: string,
+    data: unknown,
+    config?: {
+      timeoutMs?: number
+      targetDeviceId?: string
+    }
+  ) {
+    const timeoutMs = config?.timeoutMs ?? this.defaultTimeoutMs
+    const { deviceId } = this
+    const randomStr = Math.random().toString(36).slice(2)
+    // 本条消息的响应名
+    const responseName = `${RESPONSE_PREFIX}-${name}-${deviceId}-${randomStr}`
+    return new Promise((resolve, reject) => {
+      let timer: NodeJS.Timeout | undefined
+      this.log(`callAsync ${name}: waiting for response: ${responseName}`)
+      const callback: AdaptorCallback = (e) => {
+        clearTimeout(timer)
+        this.log(`response received: ${responseName}`, e)
+        if (RemoteError.isRemoteError(e.data)) {
+          reject(RemoteError.fromError(e.data))
+        } else {
+          resolve((e.data as ReturnType<typeof response.success>)?.data)
+        }
+      }
+      this.adaptor.once(responseName, callback)
+      timer = setTimeout(() => {
+        this.log(`timeout: ${responseName}`)
+        this.adaptor.off(responseName, callback)
+        reject(new RemoteTimeoutError(`timeout: ${name}`))
+      }, timeoutMs)
+      this.adaptor.emit({
+        deviceId,
+        targetDeviceId: config?.targetDeviceId ?? '',
+        name,
+        data,
+        callbackName: responseName,
+      })
+    })
+  }
+
+  /**
+   * 注册方法，供对方调用；
+   */
+  register<K extends keyof MF>(name: K, callback: RegisteredFunc<MF[K]>): void {
+    this.map[name as string] = { callback }
+  }
+
+  _ = new Proxy<FuncMapWithConfig<OF>>({} as FuncMapWithConfig<OF>, {
+    get: (_, k) => this.callAsync.bind(this, k as string),
+  })
+
+  self = new Proxy<MF>({} as MF, {
+    get: (_, k) => this.map[k as string]?.callback,
+  })
+}
+
+export function isRemoteAdaptorData(data: unknown): data is AdaptorPackageData {
+  return (
+    !!data &&
+    typeof data === 'object' &&
+    'deviceId' in data &&
+    'name' in data &&
+    typeof data.deviceId === 'string' &&
+    typeof data.name === 'string' &&
+    !!data.deviceId &&
+    !!data.name
+  )
+}