@planet-matrix/mobius-model 0.4.0 → 0.6.0

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,
+})

package/src/environment/geo.ts

@@ -0,0 +1,337 @@
+/**
+ * 描述来自 Cloudflare trace 接口的地理信息。
+ *
+ * @example
+ * ```
+ * fl=1232f78
+ * h=www.cloudflare.com
+ * ip=23.132.124.129
+ * ts=1772261014.000
+ * visit_scheme=https
+ * uag=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36 Edg/144.0.0.0
+ * colo=SJC
+ * sliver=none
+ * http=http/2
+ * loc=US
+ * tls=TLSv1.3
+ * sni=plaintext
+ * warp=off
+ * gateway=off
+ * rbi=off
+ * kex=X25519MLKEM768
+ * ```
+ */
+export interface GeoInfoFromCloudflare {
+  /**
+   * Data center request was handled at (Cloudflare internal code)
+   */
+  fl?: string | undefined
+  /**
+   * Hostname of the incoming HTTP request
+   */
+  h?: string | undefined
+  /**
+   * Client IP address detected by Cloudflare
+   */
+  ip?: string | undefined
+  /**
+   * Timestamp of request (in seconds)
+   */
+  ts?: string | undefined
+  /**
+   * Request scheme used by the visitor (for example: http/https)
+   */
+  visit_scheme?: string | undefined
+  /**
+   * User-Agent header value
+   */
+  uag?: string | undefined
+  /**
+   * IATA-like code of the Cloudflare edge location
+   */
+  colo?: string | undefined
+  /**
+   * Cloudflare edge “sliver” identifier
+   */
+  sliver?: string | undefined
+  /**
+   * HTTP protocol version used for the request
+   */
+  http?: string | undefined
+  /**
+   * Country code inferred from client IP (ISO 3166-1 alpha-2)
+   */
+  loc?: string | undefined
+  /**
+   * TLS protocol version negotiated for the connection
+   */
+  tls?: string | undefined
+  /**
+   * Server Name Indication (SNI) mode
+   */
+  sni?: string | undefined
+  /**
+   * Whether WARP is enabled for the client
+   */
+  warp?: string | undefined
+  /**
+   * Whether Cloudflare Gateway is enabled for the client
+   */
+  gateway?: string | undefined
+  /**
+   * Whether browser isolation (RBI) is enabled
+   */
+  rbi?: string | undefined
+  /**
+   * Key exchange algorithm used by TLS
+   */
+  kex?: string | undefined
+}
+/**
+ * Parse geolocation information from Cloudflare trace response.
+ */
+const parseGeoInfoFromCloudflare = (text: string): GeoInfoFromCloudflare => {
+  const pairs = text
+    .split('\n')
+    .map((pair: string) => pair.split('='))
+    .filter(([key]) => key !== '')
+  const result = pairs.reduce((geo: GeoInfoFromCloudflare, pair) => {
+    const [key, value] = pair
+    if (key !== undefined) {
+      // oxlint-disable-next-line no-unsafe-type-assertion
+      geo[key as keyof GeoInfoFromCloudflare] = value
+    }
+    return geo
+  }, {})
+  return result
+}
+/**
+ * Get device geolocation information from Cloudflare
+ *
+ * @see {@link https://dev.to/brojenuel/get-ip-clients-addresses-6k6}
+ * @see {@link https://dataflowkit.com/blog/determine-location-of-users/}
+ */
+export const getGeoInfoFromCloudflare = async (): Promise<GeoInfoFromCloudflare> => {
+  const response = await fetch('https://www.cloudflare.com/cdn-cgi/trace', {
+    method: 'GET',
+    mode: 'cors',
+    credentials: 'omit'
+  })
+  const responseText = await response.text()
+  const geo = parseGeoInfoFromCloudflare(responseText)
+
+  return geo
+}
+
+/**
+ * 描述来自 ipapi 响应的地理信息。
+ *
+ * @example
+ * ```
+ * {
+ *   "ip": "23.132.124.129",
+ *   "network": "23.132.124.0/24",
+ *   "version": "IPv4",
+ *   "city": "Los Angeles",
+ *   "region": "California",
+ *   "region_code": "CA",
+ *   "country": "US",
+ *   "country_name": "United States",
+ *   "country_code": "US",
+ *   "country_code_iso3": "USA",
+ *   "country_capital": "Washington",
+ *   "country_tld": ".us",
+ *   "continent_code": "NA",
+ *   "in_eu": false,
+ *   "postal": "90001",
+ *   "latitude": 34.05223,
+ *   "longitude": -118.24368,
+ *   "timezone": "America/Los_Angeles",
+ *   "utc_offset": "-0800",
+ *   "country_calling_code": "+1",
+ *   "currency": "USD",
+ *   "currency_name": "Dollar",
+ *   "languages": "en-US,es-US,haw,fr",
+ *   "country_area": 9629091,
+ *   "country_population": 327167434,
+ *   "asn": "AS7018",
+ *   "org": "AT&T Enterprises, LLC"
+ * }
+ * ```
+ */
+export interface GeoInfoFromIpapi {
+  /**
+   * Public (external) IP address (same as URL ip).
+   */
+  ip?: string | undefined
+  /**
+   * Network address in CIDR notation.
+   */
+  network?: string | undefined
+  /**
+   * IP version (IPv4 or IPv6).
+   */
+  version?: string | undefined
+  /**
+   * City name.
+   */
+  city?: string | undefined
+  /**
+   * Region name (administrative division).
+   */
+  region?: string | undefined
+  /**
+   * Region code.
+   */
+  region_code?: string | undefined
+  /**
+   * Country code (2 letter, ISO 3166-1 alpha-2).
+   */
+  country?: string | undefined
+  /**
+   * Short country name.
+   */
+  country_name?: string | undefined
+  /**
+   * Country code (2 letter, ISO 3166-1 alpha-2).
+   */
+  country_code?: string | undefined
+  /**
+   * Country code (3 letter, ISO 3166-1 alpha-3).
+   */
+  country_code_iso3?: string | undefined
+  /**
+   * Capital of the country.
+   */
+  country_capital?: string | undefined
+  /**
+   * Country specific TLD (top-level domain).
+   */
+  country_tld?: string | undefined
+  /**
+   * Continent code.
+   */
+  continent_code?: string | undefined
+  /**
+   * Whether IP address belongs to a country that is a member of the European Union (EU).
+   */
+  in_eu?: boolean | undefined
+  /**
+   * Postal code / zip code.
+   */
+  postal?: string | undefined
+  /**
+   * Latitude coordinate.
+   */
+  latitude?: number | undefined
+  /**
+   * Longitude coordinate.
+   */
+  longitude?: number | undefined
+  /**
+   * Timezone (IANA format i.e. “Area/Location”).
+   */
+  timezone?: string | undefined
+  /**
+   * UTC offset (with daylight saving time) as `+HHMM` or `-HHMM` (HH is hours, MM is minutes).
+   */
+  utc_offset?: string | undefined
+  /**
+   * Country calling code (dial in code, comma separated).
+   */
+  country_calling_code?: string | undefined
+  /**
+   * Currency code (ISO 4217 format).
+   */
+  currency?: string | undefined
+  /**
+   * Currency name.
+   */
+  currency_name?: string | undefined
+  /**
+   * Languages spoken (comma separated 2 or 3 letter ISO 639 code with optional hyphen separated country suffix).
+   */
+  languages?: string | undefined
+  /**
+   * Area of the country (in sq km).
+   */
+  country_area?: number | undefined
+  /**
+   * Population of the country.
+   */
+  country_population?: number | undefined
+  /**
+   * Autonomous System Number.
+   */
+  asn?: string | undefined
+  /**
+   * Organization name.
+   */
+  org?: string | undefined
+  /**
+   * Host or domain name associated with the IP (*optional beta add-on, please contact us for details).
+   */
+  hostname?: string | undefined
+}
+/**
+ * Get geographical information from IP address using ipapi.co API.
+ *
+ * @see {@link https://ipapi.co/}
+ */
+export const getGeoInfoFromIpapi = async (): Promise<GeoInfoFromIpapi> => {
+  const response = await fetch(`https://ipapi.co/json/`, {
+    method: 'GET',
+    mode: 'cors',
+    credentials: 'omit'
+  })
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  const geo = await response.json() as GeoInfoFromIpapi
+  return geo
+}
+
+/**
+ * 描述来自 ipify API 的公网 IP 信息。
+ *
+ * @example
+ * ```
+ * {
+ *   "ip": "23.132.124.129"
+ * }
+ * ```
+ */
+export interface GeoInfoFromIpify {
+  ip: string
+}
+/**
+ * Get public IP address using ipify API.
+ *
+ * @see {@link https://www.ipify.org/}
+ */
+export const getGeoInfoFromIpify = async (): Promise<GeoInfoFromIpify> => {
+  const response = await fetch("https://api.ipify.org?format=json", {
+    method: 'GET',
+  })
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  const geo = await response.json() as GeoInfoFromIpify
+  return geo
+}
+
+/**
+ * Describe aggregated geolocation data from all providers.
+ */
+export interface GeoInfo {
+  cloudflare: GeoInfoFromCloudflare
+  ipapi: GeoInfoFromIpapi
+  ipify: GeoInfoFromIpify
+}
+/**
+ * Get geographical information from multiple sources.
+ */
+export const getGeoInfo = async (): Promise<GeoInfo> => {
+  const [cloudflare, ipapi, ipify] = await Promise.all([
+    getGeoInfoFromCloudflare(),
+    getGeoInfoFromIpapi(),
+    getGeoInfoFromIpify()
+  ])
+  return { cloudflare, ipapi, ipify }
+}

package/src/environment/index.ts

@@ -0,0 +1,7 @@
+export * from "./basic.ts"
+export * from "./geo.ts"
+export * from "./device.ts"
+export * from "./runtime.ts"
+export * from "./feature.ts"
+export * from "./variable.ts"
+export * from "./snapshot.ts"