diff --git a/src/env.ts b/src/env.ts index 6287f2b..fec540f 100644 --- a/src/env.ts +++ b/src/env.ts @@ -1,5 +1,9 @@ const _envShim = Object.create(null); +/** + * Represents an environment variable object, where each key is the name of the variable + * and its value is a string or undefined. + */ export type EnvObject = Record; const _getEnv = (useShim?: boolean) => @@ -10,6 +14,9 @@ const _getEnv = (useShim?: boolean) => globalThis.__env__ || (useShim ? _envShim : globalThis); +/** + * A proxy handler for environment variables that supports reading, writing and deleting properties as well as listing all environment variable keys with a shim fallback. + */ export const env: EnvObject = new Proxy(_envShim, { get(_, prop) { const env = _getEnv(); @@ -38,5 +45,10 @@ export const env: EnvObject = new Proxy(_envShim, { }, }); +/** + * Current value of the `NODE_ENV` environment variable (or static value if replaced during build). + * + * If `NODE_ENV` is not set, this will be an empty `""` string. + */ export const nodeENV: string = (typeof process !== "undefined" && process.env && process.env.NODE_ENV) || ""; diff --git a/src/process.ts b/src/process.ts index 86da52d..8743c4e 100644 --- a/src/process.ts +++ b/src/process.ts @@ -1,5 +1,8 @@ import { type EnvObject, env } from "./env.ts"; +/** + * An interface that partially shims the Node.js `global.process`. + */ export interface Process extends Partial> { env: EnvObject; @@ -13,6 +16,9 @@ const processShims: Partial = { versions: {}, }; +/** + * A proxy for managing access to properties of the process with a shim fallback. + */ export const process: Process = new Proxy(_process, { get(target, prop: keyof Process) { if (prop === "env") { diff --git a/src/providers.ts b/src/providers.ts index 7fb647b..7c162fc 100644 --- a/src/providers.ts +++ b/src/providers.ts @@ -1,5 +1,8 @@ // Reference: https://github.com/watson/ci-info/blob/v3.2.0/vendors.json +/** + * Represents the name of a CI/CD or Deployment provider. + */ export type ProviderName = | "" | "appveyor" @@ -114,9 +117,23 @@ const providers: InternalProvider[] = [ ["FIREBASE_APP_HOSTING", "FIREBASE_APP_HOSTING", { ci: true }], ]; +/** + * Provides information about a CI/CD or Deployment provider, including its name and possibly other metadata. + */ export type ProviderInfo = { + /** + * The name of the CI/CD or Deployment provider. See {@link ProviderName} for possible values. + */ name: ProviderName; + + /** + * If is set to `true`, the environment is recognised as a CI/CD provider. + */ ci?: boolean; + + /** + * Arbitrary metadata associated with the provider. + */ [meta: string]: any; }; @@ -151,6 +168,13 @@ function _detectProvider(): ProviderInfo { }; } -/** Current provider info */ +/** + * The detected provider information for the current execution context. + * This value is evaluated once at module initialisation. + */ export const providerInfo: ProviderInfo = _detectProvider(); + +/** + * A convenience reference to the name of the detected provider. + */ export const provider: ProviderName = providerInfo.name; diff --git a/src/runtimes.ts b/src/runtimes.ts index 6d8e38c..55a9e51 100644 --- a/src/runtimes.ts +++ b/src/runtimes.ts @@ -1,4 +1,5 @@ // https://runtime-keys.proposal.wintercg.org/ + export type RuntimeName = | "workerd" | "deno" @@ -9,7 +10,12 @@ export type RuntimeName = | "fastly" | ""; -export type RuntimeInfo = { name: RuntimeName }; +export type RuntimeInfo = { + /** + * The name of the detected runtime. + */ + name: RuntimeName; +}; /** * Indicates if running in Node.js or a Node.js compatible runtime. @@ -72,6 +78,13 @@ function _detectRuntime(): RuntimeInfo | undefined { } } +/** + * Contains information about the detected runtime, if any. + */ export const runtimeInfo: RuntimeInfo | undefined = _detectRuntime(); +/** + * A convenience constant that returns the name of the detected runtime, + * defaults to an empty string if no runtime is detected. + */ export const runtime: RuntimeName = runtimeInfo?.name || "";