@js-utils-kit/env 1.6.0 → 1.7.0

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`@js-utils-kit/types`),t=require(`node:process`);function n(){switch(process.env.NODE_ENV){case e.Environment.PROD:return e.Environment.PROD;case e.Environment.DEV:return e.Environment.DEV;case e.Environment.TEST:return e.Environment.TEST;default:return e.Environment.UNKNOWN}}const r=`AC_APPCIRCLE.AGOLA_GIT_REF.APPCENTER_BUILD_ID.APPVEYOR.bamboo_planKey.BITBUCKET_COMMIT.BITRISE_IO.BUDDY_WORKSPACE_ID.BUILD_ID.BUILD_NUMBER.BUILDER_OUTPUT.BUILDKITE.CF_BUILD_ID.CF_PAGES.CI_XCODE_PROJECT.CIRCLECI.CIRRUS_CI.CM_BUILD_ID.CODEBUILD_BUILD_ARN.DRONE.DSARI.EARTHLY_CI.EAS_BUILD.GERRIT_PROJECT.GITEA_ACTIONS.GITHUB_ACTIONS.GITLAB_CI.GO_PIPELINE_LABEL.HARNESS_BUILD_ID.HUDSON_URL.JENKINS_URL.LAYERCI.MAGNUM.NETLIFY.NEVERCODE.NOW_BUILDER.PROW_JOB_ID.RELEASE_BUILD_ID.RENDER.RUN_ID.SAILCI.SCREWDRIVER.SEMAPHORE.STRIDER.TASK_ID.TEAMCITY_VERSION.TF_BUILD.TRAVIS.VELA.VERCEL.WORKERS_CI.XCS`.split(`.`),i=[`CI`,`CONTINUOUS_INTEGRATION`],a=[`codeship`,`sourcehut`,`woodpecker`],o=e=>{let n=t.env[e]??t.env[e.toUpperCase()]??t.env[e.toLowerCase()];return n!=null&&n!==`0`&&n.toLowerCase()!==`false`},s=r.some(o),c=s||i.some(o)&&(s||typeof t.env.CI_NAME==`string`&&a.includes(t.env.CI_NAME.toLowerCase())),l=typeof window<`u`&&window.document!==void 0,u=typeof process<`u`&&process.env.NODE_ENV===e.Environment.DEV,d=typeof process<`u`&&process.env.NODE_ENV===e.Environment.PROD,f=typeof process<`u`&&process.env.NODE_ENV===e.Environment.TEST,p=typeof process<`u`&&process.versions!=null&&process.versions.node!=null;exports.getRunTimeEnvironment=n,exports.isBrowser=l,exports.isCI=c,exports.isDev=u,exports.isNode=p,exports.isProd=d,exports.isTest=f;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`node:path`),t=require(`@js-utils-kit/system`),n=require(`@js-utils-kit/types`),r=require(`node:process`);function i(e){return t.isWindows?`%${e}%`:`$${e}`}function a(e,n){t.env[e]=n}function o(e){delete t.env[e]}function s(e){return Object.hasOwn(t.env,e)}function c(e){return t.env[e]}function l(e,t){return c(e)??t}function u(t,n,r=e.delimiter){a(t,[c(t),n].filter(Boolean).join(r))}function d(t,n,r=e.delimiter){a(t,[n,c(t)].filter(Boolean).join(r))}function f(e,t){t?a(e,`1`):o(e)}function p(e){let t=c(e);return t===void 0||t===``}function m(e){for(let[t,n]of Object.entries(e))a(t,n)}function h(){switch(process.env.NODE_ENV){case n.Environment.PROD:return n.Environment.PROD;case n.Environment.DEV:return n.Environment.DEV;case n.Environment.TEST:return n.Environment.TEST;default:return n.Environment.UNKNOWN}}const g=`AC_APPCIRCLE.AGOLA_GIT_REF.APPCENTER_BUILD_ID.APPVEYOR.bamboo_planKey.BITBUCKET_COMMIT.BITRISE_IO.BUDDY_WORKSPACE_ID.BUILD_ID.BUILD_NUMBER.BUILDER_OUTPUT.BUILDKITE.CF_BUILD_ID.CF_PAGES.CI_XCODE_PROJECT.CIRCLECI.CIRRUS_CI.CM_BUILD_ID.CODEBUILD_BUILD_ARN.DRONE.DSARI.EARTHLY_CI.EAS_BUILD.GERRIT_PROJECT.GITEA_ACTIONS.GITHUB_ACTIONS.GITLAB_CI.GO_PIPELINE_LABEL.HARNESS_BUILD_ID.HUDSON_URL.JENKINS_URL.LAYERCI.MAGNUM.NETLIFY.NEVERCODE.NOW_BUILDER.PROW_JOB_ID.RELEASE_BUILD_ID.RENDER.RUN_ID.SAILCI.SCREWDRIVER.SEMAPHORE.STRIDER.TASK_ID.TEAMCITY_VERSION.TF_BUILD.TRAVIS.VELA.VERCEL.WORKERS_CI.XCS`.split(`.`),_=[`CI`,`CONTINUOUS_INTEGRATION`],v=[`codeship`,`sourcehut`,`woodpecker`],y=e=>{let t=r.env[e]??r.env[e.toUpperCase()]??r.env[e.toLowerCase()];return t!=null&&t!==`0`&&t.toLowerCase()!==`false`},b=g.some(y),x=b||_.some(y)&&(b||typeof r.env.CI_NAME==`string`&&v.includes(r.env.CI_NAME.toLowerCase())),S=typeof window<`u`&&window.document!==void 0,C=typeof process<`u`&&process.env.NODE_ENV===n.Environment.DEV,w=typeof process<`u`&&process.env.NODE_ENV===n.Environment.PROD,T=typeof process<`u`&&process.env.NODE_ENV===n.Environment.TEST,E=typeof process<`u`&&process.versions!=null&&process.versions.node!=null;exports.appendEnv=u,exports.envRef=i,exports.getEnv=c,exports.getEnvOr=l,exports.getRunTimeEnvironment=h,exports.hasEnv=s,exports.isBrowser=S,exports.isCI=x,exports.isDev=C,exports.isEnvEmpty=p,exports.isNode=E,exports.isProd=w,exports.isTest=T,exports.prependEnv=d,exports.removeEnv=o,exports.setEnv=a,exports.setEnvMany=m,exports.toggleEnv=f;

package/dist/index.d.cts

@@ -1,5 +1,172 @@
 import { Environment } from "@js-utils-kit/types";
 
+//#region src/env.d.ts
+/**
+ * Get a shell-compatible reference to an environment variable.
+ *
+ * @remarks
+ * - This helper returns a string that can be used inside shell commands to reference an environment variable.
+ * - The format differs between operating systems:
+ *    - Unix/Linux/macOS → `$VAR`
+ *    - Windows (cmd) → `%VAR%`
+ * - Supported shells:
+ *    - cmd
+ *    - bash / sh / zsh (POSIX)
+ *
+ * This is useful when constructing shell commands dynamically.
+ *
+ *
+ * @example
+ * ```ts
+ * envRef("PATH")
+ * // Linux/macOS → "$PATH"
+ * // Windows → "%PATH%"
+ * ```
+ */
+declare function envRef(/** Environment variable name */v: string): string;
+/**
+ * Set or update an environment variable.
+ *
+ * @remarks
+ * This function writes a value to the environment map. If the variable already exists, it will be overwritten.
+ *
+ * @example
+ * ```ts
+ * setEnv("NODE_ENV", "production");
+ * ```
+ */
+declare function setEnv(/** Environment variable name */k: string, /** Value to assign */v: string): void;
+/**
+ * Remove an environment variable.
+ *
+ * @remarks
+ * - Deletes the specified key from the environment object.
+ * - After removal, the variable will behave as if it was never set.
+ *
+ * @example
+ * ```ts
+ * removeEnv("DEBUG");
+ * ```
+ */
+declare function removeEnv(/** Environment variable name */k: string): void;
+/**
+ * Check if an environment variable exists.
+ *
+ * @remarks
+ * - This only checks whether the variable key is present in the environment object.
+ * - It does not check whether the value is empty.
+ *
+ * @example
+ * ```ts
+ * if (hasEnv("CI")) {
+ *   console.log("Running in CI environment");
+ * }
+ * ```
+ */
+declare function hasEnv(/** Environment variable name */k: string): boolean;
+/**
+ * Retrieve the value of an environment variable.
+ *
+ * @remarks
+ * - Returns the raw string value stored in the environment object.
+ * - If the variable is not defined, `undefined` will be returned.
+ *
+ * @example
+ * ```ts
+ * const port = getEnv("PORT");
+ * ```
+ */
+declare function getEnv(/** Environment variable name */k: string): string | undefined;
+/**
+ * Retrieve an environment variable with a fallback value.
+ *
+ * @remarks
+ * If the requested variable does not exist, the provided fallback value will be returned instead.
+ *
+ * @example
+ * ```ts
+ * const port = getEnvOr("PORT", "3000");
+ * ```
+ */
+declare function getEnvOr(/** Environment variable name */k: string, /**  Default value if variable is not set */fallback: string): string;
+/**
+ * Append a value to an existing environment variable.
+ *
+ * @remarks
+ * - Useful for variables like `PATH` that contain multiple entries.
+ * - The platform-specific delimiter is used by default:
+ *    - Windows → `;`
+ *    - Unix/Linux/macOS → `:`
+ *
+ * @example
+ * ```ts
+ * appendEnv("PATH", "/custom/bin");
+ * ```
+ */
+declare function appendEnv(/** Environment variable name */k: string, /** Value to append */v: string, /** Separator */sep?: ";" | ":"): void;
+/**
+ * Prepend a value to an existing environment variable.
+ *
+ * @remarks
+ * - Works similarly to {@link appendEnv} but places the new value at the beginning of the variable.
+ * - This is often used to prioritize a binary path.
+ *
+ * @example
+ * ```ts
+ * prependEnv("PATH", "/my/bin");
+ * ```
+ */
+declare function prependEnv(/** Environment variable name */k: string, /** Value to prepend */v: string, /** Separator */sep?: ";" | ":"): void;
+/**
+ * Enable or disable a flag-style environment variable.
+ *
+ * @remarks
+ * - When enabled, the variable is set to `"1"`.
+ * - When disabled, it is removed from the environment.
+ *
+ * This pattern is commonly used for boolean flags in CLI tools.
+ *
+ * @example
+ * ```ts
+ * toggleEnv("DEBUG", true);
+ * toggleEnv("DEBUG", false);
+ * ```
+ */
+declare function toggleEnv(/** Environment variable name */k: string, /** Whether the variable should be enabled */enabled: boolean): void;
+/**
+ * Check if an environment variable is empty.
+ *
+ * @remarks
+ * A variable is considered empty when:
+ *
+ * - It does not exist
+ * - Its value is an empty string
+ *
+ * @example
+ * ```ts
+ * if (isEnvEmpty("API_KEY")) {
+ *   console.warn("API key is missing");
+ * }
+ * ```
+ */
+declare function isEnvEmpty(/** Environment variable name */k: string): boolean;
+/**
+ * Set multiple environment variables at once.
+ *
+ * @remarks
+ * This helper allows batch updates of environment variables using an object map.
+ *
+ * @example
+ * ```ts
+ * setEnvMany({
+ *   NODE_ENV: "production",
+ *   DEBUG: "1",
+ *   PORT: "8080"
+ * });
+ * ```
+ */
+declare function setEnvMany(/** Object containing key-value pairs */vars: Record<string, string>): void;
+//#endregion
 //#region src/getRunTimeEnvironment.d.ts
 /**
  * Returns the current runtime environment as one of the defined `Environment` enum values.
@@ -124,4 +291,4 @@ declare const isTest: boolean;
  */
 declare const isNode: boolean;
 //#endregion
-export { getRunTimeEnvironment, isBrowser, isCI, isDev, isNode, isProd, isTest };
+export { appendEnv, envRef, getEnv, getEnvOr, getRunTimeEnvironment, hasEnv, isBrowser, isCI, isDev, isEnvEmpty, isNode, isProd, isTest, prependEnv, removeEnv, setEnv, setEnvMany, toggleEnv };

package/dist/index.d.mts

@@ -1,5 +1,172 @@
 import { Environment } from "@js-utils-kit/types";
 
+//#region src/env.d.ts
+/**
+ * Get a shell-compatible reference to an environment variable.
+ *
+ * @remarks
+ * - This helper returns a string that can be used inside shell commands to reference an environment variable.
+ * - The format differs between operating systems:
+ *    - Unix/Linux/macOS → `$VAR`
+ *    - Windows (cmd) → `%VAR%`
+ * - Supported shells:
+ *    - cmd
+ *    - bash / sh / zsh (POSIX)
+ *
+ * This is useful when constructing shell commands dynamically.
+ *
+ *
+ * @example
+ * ```ts
+ * envRef("PATH")
+ * // Linux/macOS → "$PATH"
+ * // Windows → "%PATH%"
+ * ```
+ */
+declare function envRef(/** Environment variable name */v: string): string;
+/**
+ * Set or update an environment variable.
+ *
+ * @remarks
+ * This function writes a value to the environment map. If the variable already exists, it will be overwritten.
+ *
+ * @example
+ * ```ts
+ * setEnv("NODE_ENV", "production");
+ * ```
+ */
+declare function setEnv(/** Environment variable name */k: string, /** Value to assign */v: string): void;
+/**
+ * Remove an environment variable.
+ *
+ * @remarks
+ * - Deletes the specified key from the environment object.
+ * - After removal, the variable will behave as if it was never set.
+ *
+ * @example
+ * ```ts
+ * removeEnv("DEBUG");
+ * ```
+ */
+declare function removeEnv(/** Environment variable name */k: string): void;
+/**
+ * Check if an environment variable exists.
+ *
+ * @remarks
+ * - This only checks whether the variable key is present in the environment object.
+ * - It does not check whether the value is empty.
+ *
+ * @example
+ * ```ts
+ * if (hasEnv("CI")) {
+ *   console.log("Running in CI environment");
+ * }
+ * ```
+ */
+declare function hasEnv(/** Environment variable name */k: string): boolean;
+/**
+ * Retrieve the value of an environment variable.
+ *
+ * @remarks
+ * - Returns the raw string value stored in the environment object.
+ * - If the variable is not defined, `undefined` will be returned.
+ *
+ * @example
+ * ```ts
+ * const port = getEnv("PORT");
+ * ```
+ */
+declare function getEnv(/** Environment variable name */k: string): string | undefined;
+/**
+ * Retrieve an environment variable with a fallback value.
+ *
+ * @remarks
+ * If the requested variable does not exist, the provided fallback value will be returned instead.
+ *
+ * @example
+ * ```ts
+ * const port = getEnvOr("PORT", "3000");
+ * ```
+ */
+declare function getEnvOr(/** Environment variable name */k: string, /**  Default value if variable is not set */fallback: string): string;
+/**
+ * Append a value to an existing environment variable.
+ *
+ * @remarks
+ * - Useful for variables like `PATH` that contain multiple entries.
+ * - The platform-specific delimiter is used by default:
+ *    - Windows → `;`
+ *    - Unix/Linux/macOS → `:`
+ *
+ * @example
+ * ```ts
+ * appendEnv("PATH", "/custom/bin");
+ * ```
+ */
+declare function appendEnv(/** Environment variable name */k: string, /** Value to append */v: string, /** Separator */sep?: ";" | ":"): void;
+/**
+ * Prepend a value to an existing environment variable.
+ *
+ * @remarks
+ * - Works similarly to {@link appendEnv} but places the new value at the beginning of the variable.
+ * - This is often used to prioritize a binary path.
+ *
+ * @example
+ * ```ts
+ * prependEnv("PATH", "/my/bin");
+ * ```
+ */
+declare function prependEnv(/** Environment variable name */k: string, /** Value to prepend */v: string, /** Separator */sep?: ";" | ":"): void;
+/**
+ * Enable or disable a flag-style environment variable.
+ *
+ * @remarks
+ * - When enabled, the variable is set to `"1"`.
+ * - When disabled, it is removed from the environment.
+ *
+ * This pattern is commonly used for boolean flags in CLI tools.
+ *
+ * @example
+ * ```ts
+ * toggleEnv("DEBUG", true);
+ * toggleEnv("DEBUG", false);
+ * ```
+ */
+declare function toggleEnv(/** Environment variable name */k: string, /** Whether the variable should be enabled */enabled: boolean): void;
+/**
+ * Check if an environment variable is empty.
+ *
+ * @remarks
+ * A variable is considered empty when:
+ *
+ * - It does not exist
+ * - Its value is an empty string
+ *
+ * @example
+ * ```ts
+ * if (isEnvEmpty("API_KEY")) {
+ *   console.warn("API key is missing");
+ * }
+ * ```
+ */
+declare function isEnvEmpty(/** Environment variable name */k: string): boolean;
+/**
+ * Set multiple environment variables at once.
+ *
+ * @remarks
+ * This helper allows batch updates of environment variables using an object map.
+ *
+ * @example
+ * ```ts
+ * setEnvMany({
+ *   NODE_ENV: "production",
+ *   DEBUG: "1",
+ *   PORT: "8080"
+ * });
+ * ```
+ */
+declare function setEnvMany(/** Object containing key-value pairs */vars: Record<string, string>): void;
+//#endregion
 //#region src/getRunTimeEnvironment.d.ts
 /**
  * Returns the current runtime environment as one of the defined `Environment` enum values.
@@ -124,4 +291,4 @@ declare const isTest: boolean;
  */
 declare const isNode: boolean;
 //#endregion
-export { getRunTimeEnvironment, isBrowser, isCI, isDev, isNode, isProd, isTest };
+export { appendEnv, envRef, getEnv, getEnvOr, getRunTimeEnvironment, hasEnv, isBrowser, isCI, isDev, isEnvEmpty, isNode, isProd, isTest, prependEnv, removeEnv, setEnv, setEnvMany, toggleEnv };

package/dist/index.mjs

@@ -1 +1 @@
-import{Environment as e}from"@js-utils-kit/types";import{env as t}from"node:process";function n(){switch(process.env.NODE_ENV){case e.PROD:return e.PROD;case e.DEV:return e.DEV;case e.TEST:return e.TEST;default:return e.UNKNOWN}}const r=`AC_APPCIRCLE.AGOLA_GIT_REF.APPCENTER_BUILD_ID.APPVEYOR.bamboo_planKey.BITBUCKET_COMMIT.BITRISE_IO.BUDDY_WORKSPACE_ID.BUILD_ID.BUILD_NUMBER.BUILDER_OUTPUT.BUILDKITE.CF_BUILD_ID.CF_PAGES.CI_XCODE_PROJECT.CIRCLECI.CIRRUS_CI.CM_BUILD_ID.CODEBUILD_BUILD_ARN.DRONE.DSARI.EARTHLY_CI.EAS_BUILD.GERRIT_PROJECT.GITEA_ACTIONS.GITHUB_ACTIONS.GITLAB_CI.GO_PIPELINE_LABEL.HARNESS_BUILD_ID.HUDSON_URL.JENKINS_URL.LAYERCI.MAGNUM.NETLIFY.NEVERCODE.NOW_BUILDER.PROW_JOB_ID.RELEASE_BUILD_ID.RENDER.RUN_ID.SAILCI.SCREWDRIVER.SEMAPHORE.STRIDER.TASK_ID.TEAMCITY_VERSION.TF_BUILD.TRAVIS.VELA.VERCEL.WORKERS_CI.XCS`.split(`.`),i=[`CI`,`CONTINUOUS_INTEGRATION`],a=[`codeship`,`sourcehut`,`woodpecker`],o=e=>{let n=t[e]??t[e.toUpperCase()]??t[e.toLowerCase()];return n!=null&&n!==`0`&&n.toLowerCase()!==`false`},s=r.some(o),c=s||i.some(o)&&(s||typeof t.CI_NAME==`string`&&a.includes(t.CI_NAME.toLowerCase())),l=typeof window<`u`&&window.document!==void 0,u=typeof process<`u`&&process.env.NODE_ENV===e.DEV,d=typeof process<`u`&&process.env.NODE_ENV===e.PROD,f=typeof process<`u`&&process.env.NODE_ENV===e.TEST,p=typeof process<`u`&&process.versions!=null&&process.versions.node!=null;export{n as getRunTimeEnvironment,l as isBrowser,c as isCI,u as isDev,p as isNode,d as isProd,f as isTest};
+import{delimiter as e}from"node:path";import{env as t,isWindows as n}from"@js-utils-kit/system";import{Environment as r}from"@js-utils-kit/types";import{env as i}from"node:process";function a(e){return n?`%${e}%`:`$${e}`}function o(e,n){t[e]=n}function s(e){delete t[e]}function c(e){return Object.hasOwn(t,e)}function l(e){return t[e]}function u(e,t){return l(e)??t}function d(t,n,r=e){o(t,[l(t),n].filter(Boolean).join(r))}function f(t,n,r=e){o(t,[n,l(t)].filter(Boolean).join(r))}function p(e,t){t?o(e,`1`):s(e)}function m(e){let t=l(e);return t===void 0||t===``}function h(e){for(let[t,n]of Object.entries(e))o(t,n)}function g(){switch(process.env.NODE_ENV){case r.PROD:return r.PROD;case r.DEV:return r.DEV;case r.TEST:return r.TEST;default:return r.UNKNOWN}}const _=`AC_APPCIRCLE.AGOLA_GIT_REF.APPCENTER_BUILD_ID.APPVEYOR.bamboo_planKey.BITBUCKET_COMMIT.BITRISE_IO.BUDDY_WORKSPACE_ID.BUILD_ID.BUILD_NUMBER.BUILDER_OUTPUT.BUILDKITE.CF_BUILD_ID.CF_PAGES.CI_XCODE_PROJECT.CIRCLECI.CIRRUS_CI.CM_BUILD_ID.CODEBUILD_BUILD_ARN.DRONE.DSARI.EARTHLY_CI.EAS_BUILD.GERRIT_PROJECT.GITEA_ACTIONS.GITHUB_ACTIONS.GITLAB_CI.GO_PIPELINE_LABEL.HARNESS_BUILD_ID.HUDSON_URL.JENKINS_URL.LAYERCI.MAGNUM.NETLIFY.NEVERCODE.NOW_BUILDER.PROW_JOB_ID.RELEASE_BUILD_ID.RENDER.RUN_ID.SAILCI.SCREWDRIVER.SEMAPHORE.STRIDER.TASK_ID.TEAMCITY_VERSION.TF_BUILD.TRAVIS.VELA.VERCEL.WORKERS_CI.XCS`.split(`.`),v=[`CI`,`CONTINUOUS_INTEGRATION`],y=[`codeship`,`sourcehut`,`woodpecker`],b=e=>{let t=i[e]??i[e.toUpperCase()]??i[e.toLowerCase()];return t!=null&&t!==`0`&&t.toLowerCase()!==`false`},x=_.some(b),S=x||v.some(b)&&(x||typeof i.CI_NAME==`string`&&y.includes(i.CI_NAME.toLowerCase())),C=typeof window<`u`&&window.document!==void 0,w=typeof process<`u`&&process.env.NODE_ENV===r.DEV,T=typeof process<`u`&&process.env.NODE_ENV===r.PROD,E=typeof process<`u`&&process.env.NODE_ENV===r.TEST,D=typeof process<`u`&&process.versions!=null&&process.versions.node!=null;export{d as appendEnv,a as envRef,l as getEnv,u as getEnvOr,g as getRunTimeEnvironment,c as hasEnv,C as isBrowser,S as isCI,w as isDev,m as isEnvEmpty,D as isNode,T as isProd,E as isTest,f as prependEnv,s as removeEnv,o as setEnv,h as setEnvMany,p as toggleEnv};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@js-utils-kit/env",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Environment utilities",
   "homepage": "https://js-utils.js.org",
   "repository": {
@@ -35,7 +35,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@js-utils-kit/types": "1.4.0"
+    "@js-utils-kit/system": "1.0.0",
+    "@js-utils-kit/types": "1.5.0"
   },
   "scripts": {
     "build": "tsdown",