@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/src/web/permission.ts

@@ -0,0 +1,172 @@
+/**
+ * 表示可用于 Web 权限查询与订阅的权限名称。
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Permissions}
+ */
+export type WebPermissionName =
+  | PermissionName
+  | "accelerometer"
+  | "accessibility-events"
+  | "ambient-light-sensor"
+  | "background-sync"
+  | "camera"
+  | "capture-surface-control"
+  | "clipboard-read"
+  | "clipboard-write"
+  | "geolocation"
+  | "gyroscope"
+  | "local-fonts"
+  | "magnetometer"
+  | "microphone"
+  | "midi"
+  | "notifications"
+  | "payment-handler"
+  | "persistent-storage"
+  | "push"
+  | "screen-wake-lock"
+  | "top-level-storage-access"
+  | "window-management"
+
+/**
+ * 表示查询单个 Web 权限时的输入选项。
+ */
+export interface QueryPermissionOptions {
+  name: WebPermissionName
+}
+
+/**
+ * 表示单个 Web 权限查询后的标准化结果。
+ */
+export interface QueryPermissionResult {
+  name: WebPermissionName
+  state: PermissionState | "unsupported" | "exception"
+  detail?: string | undefined
+}
+/**
+ * 查询指定 Web 权限的当前状态。
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Permissions/query}
+ */
+export const queryPermission = async (options: QueryPermissionOptions): Promise<QueryPermissionResult> => {
+  const { name } = options
+  try {
+    const permissionStatus = await navigator.permissions.query({
+      // oxlint-disable-next-line no-unsafe-type-assertion
+      name: name as PermissionName
+    })
+
+    return {
+      name: name,
+      state: permissionStatus.state
+    }
+  } catch (exception) {
+    if (exception instanceof TypeError) {
+      return {
+        name: name,
+        state: "unsupported",
+        detail: exception.message
+      }
+    } else if (exception instanceof DOMException) {
+      return {
+        name: name,
+        state: "exception",
+        detail: exception.message
+      }
+    } else {
+      return {
+        name: name,
+        state: "exception",
+        detail: String(exception)
+      }
+    }
+  }
+}
+
+/**
+ * 确保指定权限已被授予；如果权限状态不为 "granted"，则抛出错误。
+ */
+export const ensurePermissionGranted = async (options: QueryPermissionOptions): Promise<void> => {
+  try {
+    const queryResult = await queryPermission(options)
+    if (queryResult.state !== "granted") {
+      throw new Error(`Permission "${options.name}" is not granted. Current state: ${queryResult.state}`)
+    }
+  } catch (exception) {
+    throw new Error(`Failed to ensure permission "${options.name}"`, { cause: exception })
+  }
+}
+
+/**
+ * 表示订阅单个 Web 权限变化时的输入选项。
+ */
+export interface SubscribePermissionOptions {
+  name: WebPermissionName
+  subscribe: (queryPermissionResult: QueryPermissionResult) => void
+}
+/**
+ * 订阅指定权限状态的变化。当权限状态发生变化时，回调函数会被调用并传入最新的权限状态。
+ */
+export const subscribePermission = (options: SubscribePermissionOptions): (() => void) => {
+  const { name, subscribe } = options
+
+  let unsubscribed = false
+  let internalUnsubscribe: (() => void) | undefined = undefined
+  const unsubscribe = (): void => {
+    unsubscribed = true
+    internalUnsubscribe?.()
+  }
+
+  try {
+    void navigator.permissions.query({
+      // oxlint-disable-next-line no-unsafe-type-assertion
+      name: name as PermissionName
+    }).then((permissionStatus) => {
+      if (unsubscribed === true) {
+        return
+      }
+
+      const internalSubscribe = (): void => {
+        subscribe({
+          name: name,
+          state: permissionStatus.state
+        })
+      }
+      permissionStatus.addEventListener("change", internalSubscribe)
+      internalUnsubscribe = (): void => {
+        permissionStatus.removeEventListener("change", internalSubscribe)
+      }
+    }).catch((exception: unknown) => {
+      if (unsubscribed === true) {
+        return
+      }
+
+      if (exception instanceof TypeError) {
+        subscribe({
+          name: name,
+          state: "unsupported",
+          detail: exception.message
+        })
+      } else if (exception instanceof DOMException) {
+        subscribe({
+          name: name,
+          state: "exception",
+          detail: exception.message
+        })
+      } else {
+        subscribe({
+          name: name,
+          state: "exception",
+          detail: String(exception)
+        })
+      }
+    })
+  } catch (exception: unknown) {
+    subscribe({
+      name: name,
+      state: "unsupported",
+      detail: String(exception)
+    })
+  }
+
+  return unsubscribe
+}

package/src/web/script-loader.ts

@@ -0,0 +1,432 @@
+
+/**
+ * 将脚本地址转换为基于当前文档的绝对地址，避免相对路径、完整地址和等价地址之间比较不一致。
+ */
+export const normalizeScriptSrc = (src: string): string => {
+  return new URL(src, document.baseURI).href
+}
+
+/**
+ * 在当前页面中查找与目标地址匹配的 `<script>` 元素。
+ *
+ * 查找时会先将输入地址与现有脚本地址都标准化为绝对地址，
+ * 因此可以识别相同脚本的不同写法。
+ */
+export const findScript = (src: string): HTMLScriptElement | null => {
+  const normalizedSrc = normalizeScriptSrc(src)
+  return Array.from(document.scripts).find((item) => {
+    if (item.hasAttribute("src") === false || item.src === "") {
+      return false
+    }
+    return normalizeScriptSrc(item.src) === normalizedSrc
+  }) ?? null
+}
+
+/**
+ * 表示页面中的内联 JavaScript 脚本项。
+ */
+export interface JavaScriptCollectionInternalItem {
+  element: HTMLScriptElement
+}
+
+/**
+ * 表示页面中的外部 JavaScript 脚本项。
+ */
+export interface JavaScriptCollectionExternalItem {
+  element: HTMLScriptElement
+  src: string
+}
+
+/**
+ * 表示页面中脚本采集结果的集合。
+ */
+export interface JavaScriptCollection {
+  internal: JavaScriptCollectionInternalItem[]
+  external: JavaScriptCollectionExternalItem[]
+}
+
+/**
+ * 采集页面中已经存在的 JavaScript 脚本，包括内部脚本和外部脚本两种。
+ *
+ * - 内部脚本：（InternalScript）指 JavaScript 代码直接写在 `<script></script>` 标签内部。
+ *
+ * - 外部脚本：（ExternalScript）指通过设置 `<script></script>` 标签的 `src` 属性进行引入的 JavaScript 脚本文件。
+ *
+ * {@link https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/script#attr-type | \<script\> 脚本元素}
+ */
+export const collectJavaScript = (): JavaScriptCollection => {
+  const scripts = Array.from(document.scripts)
+  const collection = scripts.reduce<JavaScriptCollection>((value, item) => {
+    if (item.hasAttribute("src")) {
+      const normalizedSrc = normalizeScriptSrc(item.src)
+      value.external.push({ src: normalizedSrc, element: item })
+    }
+    else {
+      value.internal.push({ element: item })
+    }
+    return value
+  }, { internal: [], external: [] })
+  return collection
+}
+
+/**
+ * 表示单个脚本的加载选项。
+ */
+export interface ScriptLoadOptions {
+  /**
+   * 待加载脚本的地址。
+   */
+  src: string
+  /**
+   * 调用方自定义的脚本标识，仅用于透传到结果与回调中。
+   */
+  name?: string | undefined
+  /**
+   * 指定脚本类型。
+   */
+  type?: "module" | undefined
+  /**
+   * 是否为插入的脚本节点设置 `async=true`。
+   */
+  async?: boolean | undefined
+  /**
+   * 加载超时时间，单位为毫秒。
+   */
+  timeout?: number | undefined
+  /**
+   * 脚本可用后执行的采集函数，返回值会保存在加载结果中。
+   */
+  collect?: ((element: HTMLScriptElement) => unknown) | undefined
+  /**
+   * 在后续脚本开始加载前执行，用于隔离当前脚本对全局环境的影响。
+   */
+  isolate?: (() => void) | undefined
+  /**
+   * 在后续脚本加载完成后执行，用于恢复当前脚本的全局环境。
+   */
+  deisolate?: (() => void) | undefined
+  beforeLoad?: ((context: { options: ScriptLoadOptions }) => void) | undefined
+  onLoad?: ((context: { options: ScriptLoadOptions, element: HTMLScriptElement }) => void) | undefined
+  afterLoad?: ((context: { options: ScriptLoadOptions, element: HTMLScriptElement }) => void) | undefined
+  onError?: ((context: { options: ScriptLoadOptions, error: unknown }) => void) | undefined
+}
+
+/**
+ * 表示单个脚本的加载结果。
+ */
+export interface SingleScriptLoadResult extends ScriptLoadOptions {
+  element: HTMLScriptElement
+  /**
+   * Save result of `collect` function.
+   */
+  collected?: unknown | undefined
+}
+
+/**
+ * 表示批量脚本加载的输入选项。
+ */
+export interface MultipleScriptLoadOptions {
+  /**
+   * 待加载脚本列表。字符串会被视为仅包含 `src` 的加载项。
+   */
+  items: Array<string | ScriptLoadOptions>
+  /**
+   * 为未单独指定 `onLoad` 的加载项提供统一的成功回调。
+   */
+  onLoad?: ScriptLoadOptions["onLoad"] | undefined
+  /**
+   * 为未单独指定 `onError` 的加载项提供统一的失败回调。
+   */
+  onError?: ScriptLoadOptions["onError"] | undefined
+}
+
+/**
+ * 表示批量脚本加载的汇总结果。
+ */
+export interface MultipleScriptLoadResult {
+  success: SingleScriptLoadResult[]
+  failure: Array<{ src: string, reason: unknown }>
+}
+
+/**
+ * 按串行队列将指定脚本加载到当前页面中。
+ *
+ * 加载之前进行检测：
+ * - 如果指定地址（src）的脚本已经存在于页面中，直接返回该脚本作为加载结果。
+ * - 如果指定地址（src）的脚本不存在于页面中，则通过插入 `script` 标签的方式将脚本加载到页面中，然后返回加载结果。
+ *
+ * 以 `script` 标签加载到页面中的脚本全部拥有 JavaScript 环境的完全访问权限，当脚本加载涉及到全局变量的变更时，
+ * 并行加载会出现难以预料的错误，所以这里统一采用串行加载。
+ * - 加载器会维护一个加载队列，只有先申请的脚本加载完成之后才会加载后申请的脚本，
+ * - 脚本加载的选项中可以定义辅助隔离全局变量的函数（isolate、deisolate），
+ *   在加载某个脚本之前，加载器会遍历执行其它已加载的脚本的 isolate 函数，加载完成之后，再遍历执行已加载脚本的 deisolate 函数。
+ */
+export class ScriptLoader {
+  private queue: Promise<void>
+  private readonly registry: Map<string, Promise<SingleScriptLoadResult>>
+
+  private readonly loaded: Map<string, SingleScriptLoadResult>
+
+  constructor() {
+    this.queue = Promise.resolve()
+    this.registry = new Map()
+
+    this.loaded = new Map()
+  }
+
+  protected hasLoaded(src: string): boolean {
+    return this.loaded.has(normalizeScriptSrc(src))
+  }
+
+  protected getLoaded(src: string): SingleScriptLoadResult | undefined {
+    return this.loaded.get(normalizeScriptSrc(src))
+  }
+
+  private setLoaded(src: string, result: SingleScriptLoadResult): void {
+    this.loaded.set(normalizeScriptSrc(src), result)
+  }
+
+  protected removeLoaded(src: string): void {
+    this.loaded.delete(normalizeScriptSrc(src))
+  }
+
+  protected isolateAll(): void {
+    this.loaded.forEach((item) => {
+      if (item.isolate !== undefined) {
+        item.isolate()
+      }
+    })
+  }
+
+  protected deisolateAll(): void {
+    this.loaded.forEach((item) => {
+      if (item.deisolate !== undefined) {
+        item.deisolate()
+      }
+    })
+  }
+
+  /**
+   * 统一组装加载结果，并在需要时执行 `collect`。
+   */
+  private createResult(options: ScriptLoadOptions, element: HTMLScriptElement): SingleScriptLoadResult {
+    const result: SingleScriptLoadResult = { ...options, element }
+    if (options.collect !== undefined) {
+      result.collected = options.collect(element)
+    }
+    return result
+  }
+
+  /**
+   * 将各种失败原因统一转换为 `Error` 实例，便于上层消费。
+   */
+  private toError(error: unknown): Error {
+    if (typeof error === "object" && error !== null && "message" in error) {
+      const { message } = error as { message?: unknown }
+      if (typeof message === "string") {
+        return new Error(message)
+      }
+    }
+    return new Error(typeof error === "string" ? error : "Unknown script load error.")
+  }
+
+  /**
+   * 实际创建并注入 `<script>` 节点，负责处理生命周期回调、超时与错误清理。
+   */
+  private async injectScript(options: ScriptLoadOptions): Promise<SingleScriptLoadResult> {
+    const { src, type, async, timeout, beforeLoad, onLoad, afterLoad, onError } = options
+
+    return await new Promise<SingleScriptLoadResult>((resolve, reject) => {
+      const head = document.head ?? document.querySelector("head")
+      if (head === null) {
+        throw new Error("Unable to find document head.")
+      }
+
+      const script = document.createElement("script")
+      script.src = src
+      script.type = type === "module" ? "module" : "text/javascript"
+      if (async === true) {
+        script.async = true
+      }
+
+      let settled = false
+      let timeoutId: ReturnType<typeof setTimeout> | undefined
+
+      const start = (): void => {
+        script.addEventListener("load", handleLoad)
+        script.addEventListener("error", handleError)
+        head.append(script)
+      }
+
+      const cleanup = (): void => {
+        script.removeEventListener("load", handleLoad)
+        script.removeEventListener("error", handleError)
+        if (timeoutId !== undefined) {
+          clearTimeout(timeoutId)
+        }
+      }
+
+      const fail = (exception: unknown, shouldRemove: boolean): void => {
+        if (settled === true) {
+          return
+        }
+        settled = true
+        cleanup()
+        if (shouldRemove === true) {
+          script.remove()
+        }
+        const actualError = this.toError(exception)
+        onError?.({ options, error: actualError })
+        reject(actualError)
+      }
+
+      const handleError = (event: Event): void => {
+        fail(event, true)
+      }
+
+      const handleLoad = (): void => {
+        try {
+          onLoad?.({ options, element: script })
+        } catch (exception) {
+          fail(exception, false)
+          return
+        }
+
+        try {
+          afterLoad?.({ options, element: script })
+        } catch (exception) {
+          fail(exception, false)
+          return
+        }
+
+        try {
+          const result = this.createResult(options, script)
+          cleanup()
+          resolve(result)
+        } catch (exception) {
+          fail(exception, false)
+        }
+      }
+
+      if (timeout !== undefined && timeout > 0) {
+        timeoutId = setTimeout(() => {
+          const exception = new Error(`Script load timeout: ${src}`)
+          fail(exception, true)
+        }, timeout)
+      }
+
+      try {
+        beforeLoad?.({ options })
+      } catch (exception) {
+        fail(exception, false)
+        return
+      }
+
+      start()
+    })
+  }
+
+  /**
+   * 执行一次脚本加载。
+   *
+   * 如果页面中已经存在目标脚本，则直接返回现有节点；
+   * 否则在隔离已加载脚本的前提下插入新脚本。
+   */
+  private async executeLoad(options: ScriptLoadOptions): Promise<SingleScriptLoadResult> {
+    const { src } = options
+
+    const existingScript = findScript(src)
+    if (existingScript !== null) {
+      const result = this.createResult(options, existingScript)
+      this.setLoaded(src, result)
+      return result
+    }
+
+    this.isolateAll()
+    try {
+      const result = await this.injectScript(options)
+      this.setLoaded(src, result)
+      return result
+    }
+    finally {
+      this.deisolateAll()
+    }
+  }
+
+  /**
+   * 加载单个脚本。
+   *
+   * - 同一标准化地址只会注册一个进行中的加载任务；重复请求会复用同一个 Promise。
+   * - 已完成加载的脚本会缓存在实例内部，后续请求会直接返回缓存结果。
+   */
+  async load(options: ScriptLoadOptions): Promise<SingleScriptLoadResult> {
+    options.src = normalizeScriptSrc(options.src)
+    const { src } = options
+
+    const loaded = this.getLoaded(src)
+    if (loaded !== undefined) {
+      return loaded
+    }
+
+    const registeredTask = this.registry.get(src)
+    if (registeredTask !== undefined) {
+      return await registeredTask
+    }
+
+    const task = this.queue.then(async () => {
+      return await this.executeLoad(options)
+    })
+    this.registry.set(src, task)
+    this.queue = task.then(() => undefined, () => undefined)
+
+    void task.finally(() => {
+      if (this.registry.get(src) === task) {
+        this.registry.delete(src)
+      }
+    })
+
+    return await task
+  }
+
+  /**
+   * 批量加载多个脚本，并汇总成功与失败结果。
+   *
+   * 每一项最终仍通过 `load` 进入同一串行队列，因此不会破坏加载顺序约束。
+   */
+  async loadMultiple(options: MultipleScriptLoadOptions): Promise<MultipleScriptLoadResult> {
+    const { items, onLoad, onError } = options
+
+    const preparedItems = items.map<ScriptLoadOptions>((item) => {
+      if (typeof item === "string") {
+        return { src: item }
+      }
+      return {
+        src: item.src,
+        name: item.name,
+        type: item.type,
+        async: item.async,
+        timeout: item.timeout,
+        collect: item.collect,
+        isolate: item.isolate,
+        deisolate: item.deisolate,
+        beforeLoad: item.beforeLoad,
+        onLoad: item.onLoad ?? onLoad,
+        afterLoad: item.afterLoad,
+        onError: item.onError ?? onError,
+      }
+    })
+
+    const settledResults = await Promise.allSettled(preparedItems.map(async item => await this.load(item)))
+    const result = settledResults.reduce<MultipleScriptLoadResult>((value, item, index) => {
+      if (item.status === "fulfilled") {
+        value.success.push(item.value)
+      }
+      else {
+        value.failure.push({ src: preparedItems[index]!.src, reason: item.reason })
+      }
+      return value
+    }, { success: [], failure: [] })
+
+    return result
+  }
+}