@ms-cloudpack/environment 0.1.1

package/README.md

@@ -0,0 +1,9 @@
+# @ms-cloudpack/environment
+
+Environment-related utilities for Cloudpack. This helps centralize `process.env` access to a single place.
+
+### Development notes
+
+This package is written in JS so it can be consumed by Cloudpack's internal scripts package `@ms-cloudpack/scripts`. Only `.d.ts` files are emitted to `lib`.
+
+The package also builds with the `cloudpack-scripts` bin from `@ms-cloudpack/scripts` (via the repo root dependency on that package). Technically this is circular, but it won't be an issue in practice because the scripts package is also written in JS.

package/lib/environmentInfo.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Non-Cloudpack-specific environment information.
+ */
+export const environmentInfo: Readonly<{
+    /** True if running in PR/CI (github or ADO) */
+    isCI: boolean;
+    /** True if running in a codespace */
+    isCodespaces: boolean;
+    /** True if running within jest */
+    isJest: boolean;
+    /** True if running via lage */
+    isLage: boolean;
+    /**
+     * True if debugging in VS Code.
+     *
+     * NOTE: This only works if running with a launch configuration that sets `VS_CODE_DEBUG`
+     * (it's not automatically set by VS Code).
+     */
+    isVsCodeDebug: boolean;
+    /** True if running on Windows (shorthand for `process.platform === 'win32'`) */
+    isWindows: boolean;
+    /** Info only applicable if running in Azure DevOps */
+    ado: Readonly<{
+        buildId: string | undefined;
+        definitionId: string | undefined;
+        buildReason: string | undefined;
+        pullRequestId: string | undefined;
+    }> | undefined;
+    /** Info only applicable if running on Windows. Only set if running on Windows. */
+    windows: Readonly<{
+        appData: string | undefined;
+        computerName: string | undefined;
+        programFiles: string | undefined;
+    }> | undefined;
+    cloudpack: Readonly<{
+        /** Whether cloudpack sync is enabled (default true) */
+        isSyncEnabled: boolean;
+        /** Custom telemetry connection string */
+        telemetryConnectionString: string | undefined;
+        /** External correlation ID used to correlate telemetry across different services */
+        telemetryExternalCorrelationId: string | undefined;
+    }>;
+}>;

package/lib/getAdjustedTimeout.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Get a timeout value with an appropriate multiplier for the current environment.
+ * - x3 for windows CI
+ * - x1.5 for other CI or windows local
+ * @param baseTimeout - Base timeout in ms
+ */
+export function getAdjustedTimeout(baseTimeout: number): number;

package/lib/getEnvBoolean.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Get a boolean value from an environment variable.
+ * @param {string} name - variable name
+ * @returns {boolean | undefined} false if the value is set to '0' or 'false',
+ * true if set to anything else, undefined if not set
+ */
+export function getEnvBoolean(name: string): boolean | undefined;

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { environmentInfo } from "./environmentInfo.js";
+export { getAdjustedTimeout } from "./getAdjustedTimeout.js";

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ms-cloudpack/environment",
+  "version": "0.1.1",
+  "description": "Environment-related utilities for Cloudpack.",
+  "license": "MIT",
+  "type": "module",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.js",
+      "types": "./lib/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "devDependencies": {
+    "@ms-cloudpack/eslint-plugin-internal": "^0.0.1"
+  },
+  "scripts": {
+    "api": "yarn run -T cloudpack-scripts api",
+    "build:watch": "yarn run -T cloudpack-scripts build-watch",
+    "build": "yarn run -T cloudpack-scripts build",
+    "lint:update": "yarn run -T cloudpack-scripts lint-update",
+    "lint": "yarn run -T cloudpack-scripts lint"
+  },
+  "files": [
+    "lib/**/!(*.test.*)",
+    "src/**/!(*.test.*)"
+  ]
+}

package/src/environmentInfo.js

@@ -0,0 +1,64 @@
+/* eslint-disable no-restricted-properties -- this is the file that reads the environment */
+import { getEnvBoolean } from './getEnvBoolean.js';
+
+const isADO = !!getEnvBoolean('TF_BUILD');
+const isWindows = process.platform === 'win32';
+
+/**
+ * Non-Cloudpack-specific environment information.
+ */
+// Objects are frozen to prevent accidental modification.
+export const environmentInfo = Object.freeze({
+  /** True if running in PR/CI (github or ADO) */
+  isCI: !!getEnvBoolean('CI') || isADO,
+
+  /** True if running in a codespace */
+  isCodespaces: !!getEnvBoolean('CODESPACES'),
+
+  /** True if running within jest */
+  isJest: !!process.env.JEST_WORKER_ID,
+
+  /** True if running via lage */
+  isLage: !!process.env.LAGE_PACKAGE_NAME,
+
+  /**
+   * True if debugging in VS Code.
+   *
+   * NOTE: This only works if running with a launch configuration that sets `VS_CODE_DEBUG`
+   * (it's not automatically set by VS Code).
+   */
+  isVsCodeDebug: !!process.env.VS_CODE_DEBUG,
+
+  /** True if running on Windows (shorthand for `process.platform === 'win32'`) */
+  isWindows,
+
+  /** Info only applicable if running in Azure DevOps */
+  ado: isADO
+    ? Object.freeze({
+        buildId: process.env.BUILD_BUILDID,
+        definitionId: process.env.SYSTEM_DEFINITIONID,
+        buildReason: process.env.BUILD_REASON,
+        pullRequestId: process.env.SYSTEM_PULLREQUEST_PULLREQUESTID,
+      })
+    : undefined,
+
+  /** Info only applicable if running on Windows. Only set if running on Windows. */
+  windows: isWindows
+    ? Object.freeze({
+        appData: process.env.APPDATA,
+        computerName: process.env.COMPUTERNAME,
+        programFiles: process.env.ProgramFiles,
+      })
+    : undefined,
+
+  cloudpack: Object.freeze({
+    /** Whether cloudpack sync is enabled (default true) */
+    isSyncEnabled: getEnvBoolean('CLOUDPACK_SYNC') ?? true,
+
+    /** Custom telemetry connection string */
+    telemetryConnectionString: process.env.CLOUDPACK_TELEMETRY_CONNECTION_STRING,
+
+    /** External correlation ID used to correlate telemetry across different services */
+    telemetryExternalCorrelationId: process.env.CLOUDPACK_TELEMETRY_EXTERNAL_CORRELATION_ID,
+  }),
+});

package/src/getAdjustedTimeout.js

@@ -0,0 +1,14 @@
+import { environmentInfo } from './environmentInfo.js';
+
+/**
+ * Get a timeout value with an appropriate multiplier for the current environment.
+ * - x3 for windows CI
+ * - x1.5 for other CI or windows local
+ * @param baseTimeout - Base timeout in ms
+ */
+export function getAdjustedTimeout(/** @type {number} */ baseTimeout) {
+  if (environmentInfo.isCI) {
+    return environmentInfo.isWindows ? baseTimeout * 3 : Math.round(baseTimeout * 1.5);
+  }
+  return environmentInfo.isWindows ? Math.round(baseTimeout * 1.5) : baseTimeout;
+}

package/src/getEnvBoolean.js

@@ -0,0 +1,12 @@
+/* eslint-disable no-restricted-properties -- this is the file that reads the environment */
+
+/**
+ * Get a boolean value from an environment variable.
+ * @param {string} name - variable name
+ * @returns {boolean | undefined} false if the value is set to '0' or 'false',
+ * true if set to anything else, undefined if not set
+ */
+export function getEnvBoolean(name) {
+  const value = process.env[name]?.toLowerCase();
+  return value ? value !== '0' && value !== 'false' : undefined;
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// See README.md for why this package uses JS.
+
+export { environmentInfo } from './environmentInfo.js';
+export { getAdjustedTimeout } from './getAdjustedTimeout.js';