@planet-matrix/mobius-model 0.5.0 → 0.9.0

package/src/environment/device.ts

@@ -0,0 +1,311 @@
+import type { BrowserName, BrowserType, CPUArch, DeviceType, DeviceVendor, EngineName, Extension, OSName } from "ua-parser-js/enums"
+
+import { UAParser } from "ua-parser-js"
+import { isAppleSilicon } from "ua-parser-js/device-detection"
+import { isFrozenUA } from "ua-parser-js/helpers"
+import { isAIAssistant, isAICrawler, isBot } from "ua-parser-js/bot-detection"
+import { isChromeFamily, isElectron, isFromEU, isStandalonePWA } from "ua-parser-js/browser-detection"
+
+import { Bots, CLIs, Crawlers, Emails, ExtraDevices, Fetchers, InApps, Libraries, MediaPlayers, Vehicles } from "ua-parser-js/extensions"
+
+import type { IResult } from "ua-parser-js"
+
+interface NetworkInformation {
+  downlink: number
+  downlinkMax: number
+  effectiveType: "slow-2g" | "2g" | "3g" | "4g"
+  rtt: number
+  saveData: boolean
+  type: "bluetooth" | "cellular" | "ethernet" | "none" | "wifi" | "wimax" | "other" | "unknown"
+}
+const getNetworkInformation = (): NetworkInformation | undefined => {
+  let connection: NetworkInformation | undefined;
+  if ("connection" in navigator) {
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    connection = navigator.connection as NetworkInformation;
+  } else if ("mozConnection" in navigator) {
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    connection = navigator.mozConnection as NetworkInformation;
+  } else if ("webkitConnection" in navigator) {
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    connection = navigator.webkitConnection as NetworkInformation;
+  }
+  return connection;
+};
+
+/**
+ * Describe navigator-level device and network metadata.
+ */
+export interface DeviceNavigatorInfo {
+  oscpu: string | undefined
+  deviceMemory: number | undefined
+  hardwareConcurrency: number | undefined
+  maxTouchPoints: number | undefined
+  platform: Navigator['platform']
+
+  devicePosture: "continuous" | "folded" | undefined
+  connectionDownlink: NetworkInformation['downlink'] | undefined
+  connectionDownlinkMax: NetworkInformation['downlinkMax'] | undefined
+  connectionEffectiveType: NetworkInformation['effectiveType'] | undefined
+  connectionRtt: NetworkInformation['rtt'] | undefined
+  connectionSaveData: NetworkInformation['saveData'] | undefined
+  connectionType: NetworkInformation['type'] | undefined
+  online: boolean
+  cookiesEnabled: boolean
+  language: string
+  languages: string[]
+  pdfViewerEnabled: boolean
+}
+/**
+ * Collect device information from the Navigator API.
+ */
+export const getDeviceNavigatorInfo = (): DeviceNavigatorInfo => {
+  const connection = getNetworkInformation();
+
+  return {
+    oscpu: "oscpu" in navigator ? String(navigator.oscpu) : undefined,
+    hardwareConcurrency: "hardwareConcurrency" in navigator ? Number.parseInt(String(navigator.hardwareConcurrency), 10) : undefined,
+    deviceMemory: "deviceMemory" in navigator ? Number.parseFloat(String(navigator.deviceMemory)) : undefined,
+    maxTouchPoints: navigator.maxTouchPoints,
+    platform: navigator.platform,
+
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    devicePosture: "devicePosture" in navigator ? (navigator.devicePosture as { type: "continuous" | "folded" }).type : undefined,
+    connectionDownlink: connection?.downlink ?? undefined,
+    connectionDownlinkMax: connection?.downlinkMax ?? undefined,
+    connectionEffectiveType: connection?.effectiveType ?? undefined,
+    connectionRtt: connection?.rtt ?? undefined,
+    connectionSaveData: connection?.saveData ?? undefined,
+    connectionType: connection?.type ?? undefined,
+    online: navigator.onLine,
+    cookiesEnabled: navigator.cookieEnabled,
+    language: navigator.language,
+    languages: [...navigator.languages],
+    pdfViewerEnabled: navigator.pdfViewerEnabled,
+  }
+}
+
+/**
+ * Describe device metadata parsed from a user-agent string.
+ */
+export interface DeviceUserAgentInfo {
+  ua: string
+  uaIsFrozen: boolean
+
+  cpuArchitecture: typeof CPUArch[keyof typeof CPUArch] | undefined
+
+  osName: typeof OSName[keyof typeof OSName] | undefined
+  osVersion: IResult['os']['version'] | undefined
+
+  engineName: typeof EngineName[keyof typeof EngineName] | undefined
+  engineVersion: IResult['engine']['version'] | undefined
+
+  browserName:
+  | typeof BrowserName[keyof typeof BrowserName]
+  | typeof Extension['BrowserName']['CLI'][keyof typeof Extension['BrowserName']['CLI']]
+  | typeof Extension['BrowserName']['Crawler'][keyof typeof Extension['BrowserName']['Crawler']]
+  | typeof Extension['BrowserName']['Email'][keyof typeof Extension['BrowserName']['Email']]
+  | typeof Extension['BrowserName']['Fetcher'][keyof typeof Extension['BrowserName']['Fetcher']]
+  | typeof Extension['BrowserName']['InApp'][keyof typeof Extension['BrowserName']['InApp']]
+  | typeof Extension['BrowserName']['Library'][keyof typeof Extension['BrowserName']['Library']]
+  | undefined
+  browserVersion: IResult['browser']['version'] | undefined
+  browserMajor: IResult['browser']['major'] | undefined
+  browserType: typeof BrowserType[keyof typeof BrowserType] | undefined
+  browserIsAiAssistant: boolean
+  browserIsAiCrawler: boolean
+  browserIsBot: boolean
+  browserIsChromeFamily: boolean
+  browserIsElectron: boolean
+  browserIsFromEU: boolean
+  browserIsStandalonePWA: boolean
+
+  deviceType: typeof DeviceType[keyof typeof DeviceType] | undefined
+  deviceVendor:
+  | typeof DeviceVendor[keyof typeof DeviceVendor]
+  | typeof Extension['DeviceVendor']['Vehicle'][keyof typeof Extension['DeviceVendor']['Vehicle']]
+  | undefined
+  deviceModel: IResult['device']['model'] | undefined
+  deviceIsAppleSilicon: boolean
+}
+/**
+ * Parse the user-agent string into normalized device metadata.
+ *
+ * @see {@link https://docs.uaparser.dev/ | UAParser.js}
+ */
+export const parseUserAgent = (userAgent: string): DeviceUserAgentInfo => {
+  // @ts-expect-error - UAParser.js type definitions has unknown issue with extensions
+  const parser = new UAParser([Bots, CLIs, Crawlers, Emails, ExtraDevices, Fetchers, InApps, Libraries, MediaPlayers, Vehicles])
+  parser.setUA(userAgent)
+  const result = parser.getResult()
+
+  let browserIsElectron: boolean
+  try {
+    browserIsElectron = isElectron()
+  } catch {
+    browserIsElectron = false
+  }
+
+  let browserIsStandalonePWA: boolean
+  try {
+    browserIsStandalonePWA = isStandalonePWA()
+  } catch {
+    browserIsStandalonePWA = false
+  }
+
+  return {
+    ua: userAgent,
+    uaIsFrozen: isFrozenUA(userAgent),
+
+    cpuArchitecture: result.cpu.architecture,
+
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    osName: result.os.name as typeof OSName[keyof typeof OSName],
+    osVersion: result.os.version,
+
+    engineName: result.engine.name,
+    engineVersion: result.engine.version,
+
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    browserName: result.browser.name as typeof BrowserName[keyof typeof BrowserName],
+    browserVersion: result.browser.version,
+    browserMajor: result.browser.major,
+    browserType: result.browser.type,
+    browserIsAiAssistant: isAIAssistant(userAgent),
+    browserIsAiCrawler: isAICrawler(userAgent),
+    browserIsBot: isBot(userAgent),
+    browserIsChromeFamily: isChromeFamily(userAgent),
+    browserIsElectron,
+    browserIsFromEU: isFromEU(),
+    browserIsStandalonePWA,
+
+    deviceType: result.device.type,
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    deviceVendor: result.device.vendor as typeof DeviceVendor[keyof typeof DeviceVendor],
+    deviceModel: result.device.model,
+    deviceIsAppleSilicon: isAppleSilicon(userAgent),
+  }
+}
+
+const getSafeAreaInset = (edge: "top" | "bottom" | "left" | "right"): number => {
+  const style = getComputedStyle(document.documentElement);
+
+  // 尝试 env()，现代 Safari
+  let value = style.getPropertyValue(`env(safe-area-inset-${edge})`);
+  if (value === "") {
+    // 尝试 constant()，旧版 iOS
+    value = style.getPropertyValue(`constant(safe-area-inset-${edge})`);
+  }
+
+  return value !== "" ? Number.parseFloat(value) : 0;
+}
+
+/**
+ * Describe screen, viewport, and safe-area metadata.
+ */
+export interface DeviceScreenInfo {
+  pixelRatio: number
+  orientationOriginal: OrientationType | 'unknown'
+  orientationCalculated: 'portrait' | 'landscape'
+
+  screenWidth: number
+  screenHeight: number
+  screenAvailableWidth: number
+  screenAvailableHeight: number
+  browserWidth: number
+  browserHeight: number
+  /**
+   * With scrollbar.
+   */
+  viewportWidth: number
+  /**
+   * With scrollbar.
+   */
+  viewportHeight: number
+  /**
+   * Without scrollbar.
+   */
+  viewportAvailableWidth: number
+  /**
+   * Without scrollbar.
+   */
+  viewportAvailableHeight: number
+  /**
+   * Without scrollbar.
+   */
+  visualViewportWidth: number | undefined
+  /**
+   * Without scrollbar.
+   */
+  visualViewportHeight: number | undefined
+  visualViewportOffsetLeft: number | undefined
+  visualViewportOffsetTop: number | undefined
+  visualViewportPageLeft: number | undefined
+  visualViewportPageTop: number | undefined
+  visualViewportScale: number | undefined
+  safeAreaTop: number
+  safeAreaBottom: number
+  safeAreaLeft: number
+  safeAreaRight: number
+  contentWidth: number
+  contentHeight: number
+}
+/**
+ * Collect screen and viewport information from the current window.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/visualViewport}
+ */
+export const getDeviceScreenInfo = (): DeviceScreenInfo => {
+  return {
+    pixelRatio: window.devicePixelRatio,
+    orientationOriginal: window.screen.orientation?.type || 'unknown',
+    orientationCalculated: window.innerWidth > window.innerHeight ? 'landscape' : 'portrait',
+
+    screenWidth: window.screen.width,
+    screenHeight: window.screen.height,
+    screenAvailableWidth: window.screen.availWidth,
+    screenAvailableHeight: window.screen.availHeight,
+    browserWidth: window.outerWidth,
+    browserHeight: window.outerHeight,
+    viewportWidth: window.innerWidth,
+    viewportHeight: window.innerHeight,
+    viewportAvailableWidth: document.documentElement.clientWidth,
+    viewportAvailableHeight: document.documentElement.clientHeight,
+    visualViewportWidth: window.visualViewport?.width,
+    visualViewportHeight: window.visualViewport?.height,
+    visualViewportOffsetLeft: window.visualViewport?.offsetLeft,
+    visualViewportOffsetTop: window.visualViewport?.offsetTop,
+    visualViewportPageLeft: window.visualViewport?.pageLeft,
+    visualViewportPageTop: window.visualViewport?.pageTop,
+    visualViewportScale: window.visualViewport?.scale,
+    safeAreaTop: getSafeAreaInset('top'),
+    safeAreaBottom: getSafeAreaInset('bottom'),
+    safeAreaLeft: getSafeAreaInset('left'),
+    safeAreaRight: getSafeAreaInset('right'),
+    contentWidth: document.documentElement.scrollWidth,
+    contentHeight: document.documentElement.scrollHeight
+  };
+}
+
+/**
+ * Describe merged device information from navigator, UA, and screen.
+ */
+export interface DeviceInfo {
+  navigator: DeviceNavigatorInfo
+  userAgent: DeviceUserAgentInfo
+  screen: DeviceScreenInfo
+}
+/**
+ * Get merged device information from navigator, user-agent, and screen.
+ */
+export const getDeviceInfo = (userAgent: string): DeviceInfo => {
+  const navigatorInfo = getDeviceNavigatorInfo();
+  const userAgentInfo = parseUserAgent(userAgent);
+  const screenInfo = getDeviceScreenInfo();
+
+  return {
+    navigator: navigatorInfo,
+    userAgent: userAgentInfo,
+    screen: screenInfo
+  };
+}

package/src/environment/feature.ts

@@ -0,0 +1,285 @@
+import { useFactory } from "./basic.ts"
+
+import type { Use } from "./basic.ts"
+
+import type { StringAutoCompletable } from "../type/string.ts"
+
+/**
+ * Define built-in and custom feature keys for capability detection.
+ */
+export type Feature =
+  | StringAutoCompletable
+  | "process"
+  | "navigator"
+  | "permissions"
+  | "document"
+  | "css"
+
+interface FeatureRegistryItem {
+  feature: Feature
+  detect: () => boolean
+}
+const internalFeatureRegistry = new Map<Feature, FeatureRegistryItem>();
+/**
+ * Check whether a feature is registered.
+ */
+export const isFeatureRegistered = (feature: Feature): boolean => {
+  return internalFeatureRegistry.has(feature);
+};
+/**
+ * Register a feature detector.
+ */
+export const registerFeature = (item: FeatureRegistryItem): void => {
+  internalFeatureRegistry.set(item.feature, item);
+};
+/**
+ * Unregister a feature detector.
+ */
+export const unregisterFeature = (feature: Feature): void => {
+  internalFeatureRegistry.delete(feature);
+};
+/**
+ * List all registered feature keys.
+ */
+export const listFeatures = (): Feature[] => {
+  return Array.from(internalFeatureRegistry.keys());
+}
+
+/**
+ * Get a feature registry item by feature key.
+ */
+export const getFeatureRegistryItem = (feature: Feature): FeatureRegistryItem | undefined => {
+  return internalFeatureRegistry.get(feature);
+}
+
+/**
+ * Define detection results for registered features.
+ */
+export type FeatureFlags = Record<Feature, boolean>;
+/**
+ * Get the flags for all registered features.
+ */
+export const getFeatureFlags = (): FeatureFlags => {
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  const flags: FeatureFlags = {} as FeatureFlags;
+
+  for (const [name, item] of internalFeatureRegistry) {
+    flags[name] = item.detect();
+  }
+
+  return flags;
+}
+
+/**
+ * Check if the current environment satisfies the specified feature.
+ */
+export const isSatisfiesFeature = (feature: Feature): boolean => {
+  const featureRegistryItem = getFeatureRegistryItem(feature);
+  if (featureRegistryItem === undefined) {
+    throw new Error(`Feature "${feature}" is not registered.`);
+  }
+  return featureRegistryItem.detect() === true;
+}
+
+/**
+ * Check if the current environment satisfies the specified feature conditions.
+ */
+export const isSatisfiesFeatures = (condition: Partial<FeatureFlags>): boolean => {
+  let result = true;
+  Object.keys(condition).forEach((feature) => {
+    const featureRegistryItem = getFeatureRegistryItem(feature as Feature);
+    if (featureRegistryItem === undefined) {
+      throw new Error(`Feature "${feature}" is not registered.`);
+    }
+    if (featureRegistryItem.detect() !== condition[feature]) {
+      result = false;
+    }
+  });
+  return result;
+}
+
+/**
+ * Check if the `process` object is available in the environment.
+ */
+export const supportProcess = (): boolean => {
+  return typeof process !== "undefined" && process !== null && typeof process === "object"
+}
+/**
+ * Get the `process` object from the current environment.
+ */
+export const getProcess = (): NodeJS.Process => {
+  return globalThis.process
+}
+/**
+ * Get the `process` object if it is available, otherwise throw an error.
+ */
+export const ensureProcess = (): NodeJS.Process => {
+  if (supportProcess() === true) {
+    return getProcess()
+  } else {
+    throw new Error("The process object is not supported in the current environment.")
+  }
+}
+/**
+ * Execute a function with the `process` object if it is available.
+ */
+export const useProcess: Use<NodeJS.Process> = useFactory(getProcess, supportProcess)
+registerFeature({
+  feature: "process",
+  detect: supportProcess,
+})
+
+/**
+ * Check if the `navigator` object is available in the environment.
+ */
+export const supportNavigator = (): boolean => {
+  return typeof navigator !== "undefined" && navigator !== null && typeof navigator === "object"
+}
+/**
+ * Get the `navigator` object from the current environment.
+ */
+export const getNavigator = (): Navigator => {
+  return globalThis.navigator
+}
+/**
+ * Get the `navigator` object if it is available, otherwise throw an error.
+ */
+export const ensureNavigator = (): Navigator => {
+  if (supportNavigator() === true) {
+    return getNavigator()
+  } else {
+    throw new Error("The navigator object is not supported in the current environment.")
+  }
+}
+/**
+ * Execute a function with the `navigator` object if it is available.
+ */
+export const useNavigator: Use<Navigator> = useFactory(getNavigator, supportNavigator)
+registerFeature({
+  feature: "navigator",
+  detect: supportNavigator,
+})
+
+/**
+ * Check if the `clipboard` API is available in the environment.
+ */
+export const supportClipboard = (): boolean => {
+  return supportNavigator() && "clipboard" in navigator
+}
+/**
+ * Get the `clipboard` API from the current environment.
+ */
+export const getClipboard = (): Clipboard => {
+  return navigator.clipboard
+}
+/**
+ * Get the `clipboard` API if it is available, otherwise throw an error.
+ */
+export const ensureClipboard = (): Clipboard => {
+  if (supportClipboard() === true) {
+    return getClipboard()
+  } else {
+    throw new Error("The clipboard API is not supported in the current environment.")
+  }
+}
+/**
+ * Execute a function with the `clipboard` API if it is available.
+ */
+export const useClipboard: Use<Clipboard> = useFactory(getClipboard, supportClipboard)
+registerFeature({
+  feature: "clipboard",
+  detect: supportClipboard,
+})
+
+/**
+ * Check if the `permissions` API is available in the environment.
+ */
+export const supportPermissions = (): boolean => {
+  return supportNavigator() && "permissions" in navigator
+}
+/**
+ * Get the `permissions` API from the current environment.
+ */
+export const getPermissions = (): Permissions => {
+  return navigator.permissions
+}
+/**
+ * Get the `permissions` API if it is available, otherwise throw an error.
+ */
+export const ensurePermissions = (): Permissions => {
+  if (supportPermissions() === true) {
+    return getPermissions()
+  } else {
+    throw new Error("The permissions API is not supported in the current environment.")
+  }
+}
+/**
+ * Execute a function with the `permissions` API if it is available.
+ */
+export const usePermissions: Use<Permissions> = useFactory(getPermissions, supportPermissions)
+registerFeature({
+  feature: "permissions",
+  detect: supportPermissions,
+})
+
+/**
+ * Check if the `document` object is available in the environment.
+ */
+export const supportDocument = (): boolean => {
+  return typeof document !== "undefined" && document !== null && typeof document === "object"
+}
+/**
+ * Get the `document` object from the current environment.
+ */
+export const getDocument = (): Document => {
+  return globalThis.document
+}
+/**
+ * Get the `document` object if it is available, otherwise throw an error.
+ */
+export const ensureDocument = (): Document => {
+  if (supportDocument() === true) {
+    return getDocument()
+  } else {
+    throw new Error("The document object is not supported in the current environment.")
+  }
+}
+/**
+ * Execute a function with the `document` object if it is available.
+ */
+export const useDocument: Use<Document> = useFactory(getDocument, supportDocument)
+registerFeature({
+  feature: "document",
+  detect: supportDocument,
+})
+
+/**
+ * Check if the `CSS` object is available in the environment.
+ */
+export const supportCSS = (): boolean => {
+  return typeof CSS !== "undefined" && CSS !== null && typeof CSS === "object"
+}
+/**
+ * Get the `CSS` object from the current environment.
+ */
+export const getCSS = (): typeof CSS => {
+  return globalThis.CSS
+}
+/**
+ * Get the `CSS` object if it is available, otherwise throw an error.
+ */
+export const ensureCSS = (): typeof CSS => {
+  if (supportCSS() === true) {
+    return getCSS()
+  } else {
+    throw new Error("The CSS object is not supported in the current environment.")
+  }
+}
+/**
+ * Execute a function with the `CSS` object if it is available.
+ */
+export const useCSS: Use<typeof CSS> = useFactory(getCSS, supportCSS)
+registerFeature({
+  feature: "css",
+  detect: supportCSS,
+})