@planet-matrix/mobius-model 0.4.0 → 0.6.0

package/src/environment/runtime.ts

@@ -0,0 +1,400 @@
+// oxlint-disable no-unsafe-member-access
+// oxlint-disable no-undef
+// oxlint-disable no-typeof-undefined
+
+import type { StringAutoCompletable } from "#Source/type/index.ts"
+import type { Use } from "./basic.ts"
+
+import { useFactory } from "./basic.ts"
+
+/**
+ * Define built-in and custom runtime keys.
+ */
+export type Runtime =
+  | StringAutoCompletable
+  | "browser"
+  | "nodejs"
+  | "deno"
+  | "bun"
+  | "web-worker"
+  | "service-worker"
+  | "unknown"
+
+interface RuntimeRegistryItem {
+  runtime: Runtime
+  detect: () => boolean
+  // oxlint-disable-next-line no-explicit-any
+  getGlobalContext: () => any
+  // oxlint-disable-next-line no-explicit-any
+  use: Use<any>
+}
+const internalRuntimeRegistry = new Map<Runtime, RuntimeRegistryItem>();
+/**
+ * Check whether a runtime is registered.
+ */
+export const isRuntimeRegistered = (runtime: Runtime): boolean => {
+  return internalRuntimeRegistry.has(runtime);
+};
+/**
+ * Register a runtime detector and context provider.
+ */
+export const registerRuntime = (item: RuntimeRegistryItem): void => {
+  internalRuntimeRegistry.set(item.runtime, item);
+};
+/**
+ * Unregister a runtime by key.
+ */
+export const unregisterRuntime = (name: Runtime): void => {
+  internalRuntimeRegistry.delete(name);
+};
+/**
+ * List all registered runtime keys.
+ */
+export const listRuntimes = (): Runtime[] => {
+  return Array.from(internalRuntimeRegistry.keys());
+}
+
+/**
+ * Check if the environment is a browser.
+ */
+export const isBrowser = (): boolean => {
+  return typeof window !== "undefined" && typeof window.document !== "undefined"
+}
+/**
+ * Describe runtime context values available in browser.
+ */
+export interface RuntimeContextBrowser {
+  global: Window & typeof globalThis
+  self: Window & typeof globalThis
+  window: Window & typeof globalThis
+  globalThis: typeof globalThis
+  importMeta: ImportMeta
+}
+/**
+ * Return browser runtime context values.
+ */
+export const getRuntimeContextBrowser = (): RuntimeContextBrowser => {
+  return { global: window, self, window, globalThis, importMeta: import.meta }
+}
+/**
+ * Execute logic with browser runtime context when available.
+ */
+export const useBrowser: Use<RuntimeContextBrowser> = useFactory(getRuntimeContextBrowser, isBrowser)
+registerRuntime({
+  runtime: "browser",
+  detect: isBrowser,
+  getGlobalContext: getRuntimeContextBrowser,
+  use: useBrowser,
+});
+
+/**
+ * Check if the environment is Node.js.
+ */
+export const isNodejs = (): boolean => {
+  return typeof process !== "undefined" && process.versions !== null && process.versions.node !== null
+}
+/**
+ * Describe runtime context values available in Node.js.
+ */
+export interface RuntimeContextNodejs {
+  global: typeof globalThis
+  globalThis: typeof globalThis
+}
+/**
+ * Return Node.js runtime context values.
+ */
+export const getRuntimeContextNodejs = (): RuntimeContextNodejs => {
+  return { global: globalThis, globalThis }
+}
+/**
+ * Execute logic with Node.js runtime context when available.
+ */
+export const useNodejs: Use<RuntimeContextNodejs> = useFactory(getRuntimeContextNodejs, isNodejs)
+registerRuntime({
+  runtime: "nodejs",
+  detect: isNodejs,
+  getGlobalContext: getRuntimeContextNodejs,
+  use: useNodejs,
+});
+
+/**
+ * Check if the environment is Deno.
+ */
+export const isDeno = (): boolean => {
+  // @ts-expect-error Deno is not defined in some environments
+  return typeof Deno !== "undefined" && typeof Deno.version !== "undefined" && typeof Deno.version.deno !== "undefined"
+}
+/**
+ * Describe runtime context values available in Deno.
+ */
+export interface RuntimeContextDeno {
+  global: typeof globalThis
+  globalThis: typeof globalThis
+}
+/**
+ * Return Deno runtime context values.
+ */
+export const getRuntimeContextDeno = (): RuntimeContextDeno => {
+  return { global: globalThis, globalThis }
+};
+/**
+ * Execute logic with Deno runtime context when available.
+ */
+export const useDeno: Use<RuntimeContextDeno> = useFactory(getRuntimeContextDeno, isDeno)
+registerRuntime({
+  runtime: "deno",
+  detect: isDeno,
+  getGlobalContext: getRuntimeContextDeno,
+  use: useDeno,
+});
+
+/**
+ * Check if the environment is Bun.
+ */
+export const isBun = (): boolean => {
+  return typeof Bun !== "undefined" && typeof Bun.version !== "undefined" && typeof Bun.version !== "undefined"
+}
+/**
+ * Describe runtime context values available in Bun.
+ */
+export interface RuntimeContextBun {
+  global: typeof globalThis
+  Bun: typeof Bun
+  globalThis: typeof globalThis
+  importMeta: ImportMeta
+}
+/**
+ * Return Bun runtime context values.
+ */
+export const getRuntimeContextBun = (): RuntimeContextBun => {
+  return { global: globalThis, Bun, globalThis, importMeta: import.meta }
+};
+/**
+ * Execute logic with Bun runtime context when available.
+ */
+export const useBun: Use<RuntimeContextBun> = useFactory(getRuntimeContextBun, isBun)
+registerRuntime({
+  runtime: "bun",
+  detect: isBun,
+  getGlobalContext: getRuntimeContextBun,
+  use: useBun,
+});
+
+/**
+ * Check if the environment is a Web Worker.
+ */
+export const isWebWorker = (): boolean => {
+  return (
+    typeof self !== "undefined" &&
+    typeof WorkerGlobalScope !== "undefined" &&
+    self instanceof WorkerGlobalScope &&
+    (
+      typeof ServiceWorkerGlobalScope === "undefined" ||
+      !(self instanceof ServiceWorkerGlobalScope)
+    )
+  )
+}
+/**
+ * Describe runtime context values available in Web Worker.
+ */
+export interface RuntimeContextWebWorker {
+  global: typeof globalThis
+  self: WorkerGlobalScope & typeof globalThis
+  globalThis: typeof globalThis
+}
+/**
+ * Return Web Worker runtime context values.
+ */
+export const getRuntimeContextWebWorker = (): RuntimeContextWebWorker => {
+  // @ts-expect-error - self is not defined in some environments
+  return { global: self, self, globalThis }
+}
+/**
+ * Execute logic with Web Worker runtime context when available.
+ */
+export const useWebWorker: Use<RuntimeContextWebWorker> = useFactory(getRuntimeContextWebWorker, isWebWorker)
+registerRuntime({
+  runtime: "web-worker",
+  detect: isWebWorker,
+  getGlobalContext: getRuntimeContextWebWorker,
+  use: useWebWorker,
+});
+
+/**
+ * Check if the environment is a Service Worker.
+ */
+export const isServiceWorker = (): boolean => {
+  return (
+    typeof self !== "undefined" &&
+    typeof ServiceWorkerGlobalScope !== "undefined" &&
+    self instanceof ServiceWorkerGlobalScope
+  )
+}
+/**
+ * Describe runtime context values available in Service Worker.
+ */
+export interface RuntimeContextServiceWorker {
+  global: typeof globalThis
+  self: ServiceWorkerGlobalScope & typeof globalThis
+  globalThis: typeof globalThis
+}
+/**
+ * Return Service Worker runtime context values.
+ */
+export const getServiceWorkerContext = (): RuntimeContextServiceWorker => {
+  // @ts-expect-error - self is not defined in some environments
+  return { global: self, self, globalThis }
+};
+/**
+ * Execute logic with Service Worker runtime context when available.
+ */
+export const useServiceWorker: Use<RuntimeContextServiceWorker> = useFactory(getServiceWorkerContext, isServiceWorker)
+registerRuntime({
+  runtime: "service-worker",
+  detect: isServiceWorker,
+  getGlobalContext: getServiceWorkerContext,
+  use: useServiceWorker,
+});
+
+/**
+ * Check if the environment is unknown.
+ */
+export const isUnknown = (): boolean => {
+  return getRuntimeRegistryItem().runtime === "unknown";
+}
+/**
+ * Describe runtime context values for unknown runtime.
+ */
+export interface RuntimeContextUnknown {
+  global: unknown
+}
+/**
+ * Return unknown runtime context values.
+ */
+export const getRuntimeContextUnknown = (): RuntimeContextUnknown => {
+  return { global: undefined }
+};
+/**
+ * Execute logic with unknown runtime context when available.
+ */
+export const useUnknown: Use<RuntimeContextUnknown> = useFactory(getRuntimeContextUnknown, isUnknown)
+registerRuntime({
+  runtime: "unknown",
+  detect: isUnknown,
+  getGlobalContext: getRuntimeContextUnknown,
+  use: useUnknown,
+});
+
+/**
+ * Get the current runtime environment.
+ */
+export const getRuntimeRegistryItem = (): RuntimeRegistryItem => {
+  // 如果不是其它任何 Runtime，则是 unknown
+  // 这样写可以兼容用户自行注册的 Runtime
+  for (const [name, item] of internalRuntimeRegistry) {
+    if (name === "unknown") {
+      continue;
+    }
+    if (item.detect() === true) {
+      return item;
+    }
+  }
+  return internalRuntimeRegistry.get("unknown")!;
+}
+
+/**
+ * Get the key of the current runtime environment.
+ */
+export const getRuntime = (): RuntimeRegistryItem['runtime'] => {
+  return getRuntimeRegistryItem().runtime;
+};
+
+/**
+ * Define detection results for registered runtimes.
+ */
+export type RuntimeFlags = Record<Runtime, boolean>;
+/**
+ * Define a function type that resolves all runtime flags.
+ */
+export type GetRuntimeFlags = () => RuntimeFlags;
+/**
+ * Get the runtime flags for all registered runtimes.
+ */
+export const getRuntimeFlags: GetRuntimeFlags = (): RuntimeFlags => {
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  const flags = {} as RuntimeFlags;
+
+  for (const [name, item] of internalRuntimeRegistry) {
+    flags[name] = item.detect() === true;
+  }
+
+  return flags
+}
+
+/**
+ * Check if the current runtime satisfies the specified runtime.
+ */
+export const isSatisfiesRuntime = (runtime: Runtime): boolean => {
+  const runtimeRegistryItem = internalRuntimeRegistry.get(runtime);
+  if (runtimeRegistryItem === undefined) {
+    throw new Error(`Runtime "${runtime}" is not registered.`);
+  }
+  return runtimeRegistryItem.detect() === true;
+}
+
+/**
+ * Check if the current runtime satisfies the specified runtimes condition.
+ */
+export const isSatisfiesRuntimes = (condition: Partial<RuntimeFlags>): boolean => {
+  let result: boolean = true
+  Object.keys(condition).forEach(runtime => {
+    const runtimeRegistryItem = internalRuntimeRegistry.get(runtime);
+    if (runtimeRegistryItem === undefined) {
+      throw new Error(`Runtime "${runtime}" is not registered.`);
+    }
+    if (runtimeRegistryItem.detect() !== condition[runtime]) {
+      result = false
+    }
+  })
+  return result
+}
+
+/**
+ * Map runtime keys to their typed context payloads.
+ */
+export interface RuntimeContexts {
+  browser: RuntimeContextBrowser
+  nodejs: RuntimeContextNodejs
+  deno: RuntimeContextDeno
+  bun: RuntimeContextBun
+  "web-worker": RuntimeContextWebWorker
+  "service-worker": RuntimeContextServiceWorker
+  unknown: RuntimeContextUnknown
+}
+/**
+ * Define handler options for runtime-conditional execution.
+ */
+export type UseRuntimesOptions<R> = {
+  // 这里用 unknown 更合理，但 unknown 会有类型问题无法解决，暂时不得不用 any
+  // 若有解决方案请替换回 unknown
+  // oxlint-disable-next-line no-explicit-any
+  [K in Runtime]?: (context: K extends keyof RuntimeContexts ? RuntimeContexts[K] : any) => R
+} & {
+  default?: (() => R)
+}
+/**
+ * Execute a runtime-specific handler with fallback support.
+ */
+export const useRuntimes = <R>(options: UseRuntimesOptions<R>): R => {
+  const runtimeRegisterItem = getRuntimeRegistryItem()
+  const runtime = runtimeRegisterItem.runtime
+
+  if (options[runtime] !== undefined) {
+    return options[runtime](runtimeRegisterItem.getGlobalContext())
+  }
+  if (options.default !== undefined) {
+    return options.default()
+  } else {
+    throw new Error(`Neither runtime-specific nor default handler provided for runtime: ${String(runtime)}`)
+  }
+}

package/src/environment/snapshot.ts

@@ -0,0 +1,60 @@
+import { getDeviceInfo } from "./device.ts"
+import { getFeatureFlags } from "./feature.ts"
+import { getGeoInfo } from "./geo.ts"
+import { getRuntimeFlags } from "./runtime.ts"
+import { getVariableHosted } from "./variable.ts"
+
+import type { AnyVariable } from "./variable.ts"
+import type { DeviceInfo } from "./device.ts"
+import type { FeatureFlags } from "./feature.ts"
+import type { GeoInfo } from "./geo.ts"
+import type { RuntimeFlags } from "./runtime.ts"
+
+/**
+ * Describe a consolidated environment snapshot.
+ */
+export interface Snapshot {
+  geo: GeoInfo
+  device: DeviceInfo
+  runtime: RuntimeFlags
+  feature: FeatureFlags
+  variable: AnyVariable
+  timestamp: number
+}
+
+/**
+ * Collect a consolidated environment snapshot.
+ */
+export const getSnapshot = async (): Promise<Snapshot> => {
+  const geoInfo = await getGeoInfo();
+  const deviceInfo = getDeviceInfo(navigator.userAgent);
+  const runtimeFlags = getRuntimeFlags();
+  const featureFlags = getFeatureFlags();
+  const variable = getVariableHosted();
+  const timestamp = Date.now();
+
+  return {
+    geo: geoInfo,
+    device: deviceInfo,
+    runtime: runtimeFlags,
+    feature: featureFlags,
+    variable: variable,
+    timestamp: timestamp
+  };
+}
+
+/**
+ * Print the consolidated environment snapshot to console.
+ */
+export const printSnapshot = async (): Promise<void> => {
+  const snap = await getSnapshot();
+
+  console.group('[detect]');
+  console.table(snap.geo);
+  console.table(snap.device);
+  console.table(snap.runtime);
+  console.table(snap.feature);
+  console.table(snap.variable);
+  console.log('time:', new Date(snap.timestamp).toISOString());
+  console.groupEnd();
+}

package/src/environment/variable.ts

@@ -0,0 +1,239 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+
+import { isPromise } from "#Source/basic/index.ts"
+import { parse } from "@dotenvx/dotenvx"
+import { useRuntimes } from "./runtime.ts"
+
+/**
+ * Define a key-value map for environment variables.
+ */
+export type AnyVariable = Record<string, string>
+/**
+ * Define options for parsing dotenv-style variable content.
+ */
+export interface ParseVariableOptions {
+  variableContent: string
+}
+/**
+ * Parses an environment variable string into an object.
+ */
+export const parseVariable = (options: ParseVariableOptions): AnyVariable => {
+  const { variableContent } = options;
+  const dotenvParseOutput = parse(variableContent);
+  return dotenvParseOutput;
+}
+
+/**
+ * Describe a writable host for resolved environment variables.
+ */
+export interface VariableHost {
+  /**
+   * Can be used to change the default timezone at runtime
+   *
+   * @see {@link NodeJS.ProcessEnv}, {@link Bun.Env}
+   */
+  TZ?: string | undefined
+  /**
+   * @see {@link Bun.Env}
+   */
+  NODE_ENV?: string | undefined
+  /**
+   * @see {@link ImportMetaEnv}
+   */
+  [key: string]: string | undefined
+}
+/**
+ * Get the variable host for the current runtime.
+ */
+export const getVariableHost = (): VariableHost => {
+  const variableHost = useRuntimes<VariableHost>({
+    browser: (context) => {
+      return context.importMeta.env;
+    },
+    nodejs: (context) => {
+      return context.global.process.env;
+    },
+    bun: (context) => {
+      return context.global.process.env;
+    }
+  })
+  return variableHost
+}
+
+/**
+ * Define options for loading parsed variables into a host.
+ */
+export interface LoadVariableOptions {
+  variable: AnyVariable
+  variablePrefixs: string[]
+  variableHost: VariableHost
+}
+/**
+ * Define the result of loading variables into host storage.
+ */
+export interface LoadVariableResult {
+  variable: AnyVariable
+  variableLoaded: AnyVariable
+  variableHost: VariableHost
+}
+/**
+ * Load environment variables from the provided `variable` object to the `variableHost`.
+ * Variables without prefix will be ignored.
+ *
+ * @see {@link https://github.com/vitejs/vite/blob/main/packages/vite/src/node/env.ts#L27-L95}
+ */
+export const loadVariable = (options: LoadVariableOptions): LoadVariableResult => {
+  const { variable, variablePrefixs, variableHost } = options
+
+  const variableLoaded: AnyVariable = {}
+
+  // only keys that start with prefix are exposed to client
+  for (const [key, value] of Object.entries(variable)) {
+    if (variablePrefixs.some(prefix => key.startsWith(prefix))) {
+      variableHost[key] = value
+      variableLoaded[key] = value
+    }
+  }
+
+  // check if there are actual env variables starting with variablePrefix
+  // these are typically provided inline and should be prioritized
+  for (const key in variableHost) {
+    if (variablePrefixs.some(prefix => key.startsWith(prefix))) {
+      variableLoaded[key] = String(variableHost[key])
+    }
+  }
+
+  return {
+    variable,
+    variableLoaded,
+    variableHost
+  }
+}
+
+/**
+ * Define options for validating variables with a standard schema.
+ */
+export interface VerifyVariableOptions<VariableSchema extends StandardSchemaV1> {
+  variable: AnyVariable
+  variableSchema: VariableSchema
+}
+/**
+ * Verifies the provided variable against the given schema.
+ *
+ * @see {@link https://github.com/t3-oss/t3-env}
+ */
+export const verifyVariable = <VariableSchema extends StandardSchemaV1>(
+  options: VerifyVariableOptions<VariableSchema>
+): StandardSchemaV1.InferOutput<VariableSchema> => {
+  const { variable, variableSchema } = options
+
+  const validateResult = variableSchema['~standard'].validate(variable)
+
+  if (isPromise(validateResult)) {
+    throw new Error("Validation result is a promise, expected synchronous validation.")
+  }
+
+  if (validateResult.issues !== undefined) {
+    throw new Error(`Variable validation failed: ${JSON.stringify(validateResult.issues)}`)
+  }
+
+  const value = validateResult.value
+  return value
+}
+
+/**
+ * Gets the hosted variable.
+ */
+export const getVariableHosted = (): AnyVariable => {
+  const variableHost = getVariableHost();
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  return variableHost as AnyVariable
+}
+
+/**
+ * Define options for parsing, loading, and validating variables.
+ */
+export interface GetVariableOptions<VariableSchema extends StandardSchemaV1> {
+  variableContent?: ParseVariableOptions["variableContent"] | undefined
+  variablePrefixs?: LoadVariableOptions["variablePrefixs"] | undefined
+  variableHost?: LoadVariableOptions["variableHost"] | undefined
+  variableSchema: VerifyVariableOptions<VariableSchema>["variableSchema"]
+}
+/**
+ * Gets the variable based on the provided options.
+ */
+export const getVariable = <VariableSchema extends StandardSchemaV1>(
+  options: GetVariableOptions<VariableSchema>
+): StandardSchemaV1.InferOutput<VariableSchema> => {
+  const hasVariableContent = options.variableContent !== undefined;
+
+  const parseResult = parseVariable({ variableContent: options.variableContent ?? "" })
+
+  const loadResult = loadVariable({
+    variable: parseResult,
+    variablePrefixs: options.variablePrefixs ?? [],
+    variableHost: options.variableHost ?? getVariableHost()
+  })
+
+  const variableToVerify = hasVariableContent === true
+    ? loadResult.variableLoaded
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    : loadResult.variableHost as AnyVariable;
+  const verifyResult = verifyVariable({
+    variable: variableToVerify,
+    variableSchema: options.variableSchema
+  })
+
+  return verifyResult
+}
+
+/**
+ * Define options used to construct a variable manager.
+ */
+export interface VariableManagerOptions<VariableSchema extends StandardSchemaV1> {
+  variableContent?: ParseVariableOptions["variableContent"] | undefined
+  variablePrefixs?: LoadVariableOptions["variablePrefixs"] | undefined
+  variableHost?: LoadVariableOptions["variableHost"] | undefined
+  variableSchema: VariableSchema
+}
+/**
+ * Manage typed environment variables with cached access.
+ */
+export class VariableManager<VariableSchema extends StandardSchemaV1> {
+  private options: VariableManagerOptions<VariableSchema>
+  private variableSchema: VariableSchema
+  private variable: StandardSchemaV1.InferOutput<VariableSchema>
+
+  constructor(options: VariableManagerOptions<VariableSchema>) {
+    this.options = options;
+    this.variableSchema = options.variableSchema;
+    this.variable = this.getFreshVariable();
+  }
+
+  /**
+   * Refresh variables from current options and schema.
+   */
+  getFreshVariable(): StandardSchemaV1.InferOutput<VariableSchema> {
+    const variable = getVariable({
+      variableContent: this.options.variableContent,
+      variablePrefixs: this.options.variablePrefixs,
+      variableHost: this.options.variableHost,
+      variableSchema: this.variableSchema
+    });
+    return variable;
+  }
+
+  /**
+   * Return the schema used by this manager.
+   */
+  getSchema(): VariableSchema {
+    return this.variableSchema;
+  }
+
+  /**
+   * Return the cached variable snapshot.
+   */
+  getVariable(): StandardSchemaV1.InferOutput<VariableSchema> {
+    return this.variable;
+  }
+}