refactor: improve jsdocs (#166)

Co-authored-by: Maxi <maximogarciamtnez@gmail.com>

Author: pi0

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<string, string | undefined>;
 
 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<EnvObject>(_envShim, {
  get(_, prop) {
  const env = _getEnv();
@@ -38,5 +45,10 @@ export const env: EnvObject = new Proxy<EnvObject>(_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) || "";

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<Omit<typeof globalThis.process, "versions">> {
  env: EnvObject;
@@ -13,6 +16,9 @@ const processShims: Partial<Process> = {
  versions: {},
 };
 
+/**
+ * A proxy for managing access to properties of the process with a shim fallback.
+ */
 export const process: Process = new Proxy<Process>(_process, {
  get(target, prop: keyof Process) {
  if (prop === "env") {

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;

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 || "";