@gobing-ai/ts-utils 0.4.63 → 0.4.67

package/dist/env.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Environment-variable gateway — the sanctioned funnel for `process.env` access
+ * (mirrors `packages/config` in gobing-ai/spur; enforced by the
+ * `boundary/env-var-hygiene` rule). Direct `process.env`/`Bun.env` access is
+ * banned outside this module so the set of env consumers stays greppable.
+ *
+ * These accessors are node-bun only: on `cloudflare-workers` there is no
+ * `process`; inject config explicitly rather than calling them (ADR-008).
+ */
+/**
+ * Read one environment variable. Only an unset variable yields `fallback`;
+ * an empty string is a set value and is returned as-is.
+ */
+export declare function getEnvVar(name: string, fallback?: string): string | undefined;
+/**
+ * Read the live environment as a record. The returned object IS `process.env`
+ * (not a copy): whole-record operations (`{ ...getEnvVars(), ...vars }`,
+ * `Object.entries(getEnvVars())`) see later mutations, which child-spawn
+ * composition relies on. For single variables prefer {@link getEnvVar},
+ * {@link setEnvVar}, or {@link removeEnvVar}.
+ */
+export declare function getEnvVars(): Record<string, string | undefined>;
+/**
+ * Set one environment variable through the sanctioned gateway. Passing
+ * `undefined` removes the key, so the save/restore idiom
+ * (`const prev = getEnvVar(k); … setEnvVar(k, prev)`) restores absence exactly.
+ */
+export declare function setEnvVar(name: string, value: string | undefined): void;
+/** Remove one environment variable; a no-op when the key is absent. */
+export declare function removeEnvVar(name: string): void;
+/**
+ * Read a runtime option from a `bootstrap.options`-style option bag, returning
+ * `fallback` when the config, section, or key is absent (or null). The typed
+ * replacement surface for config-carrying environment variables — call sites
+ * own key naming and value coercion.
+ */
+export declare function getAppOptions<T>(config: {
+    bootstrap?: {
+        options?: Record<string, unknown> | null;
+    } | null;
+} | null | undefined, key: string, fallback: T): T;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG7E;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGvE;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC3B,MAAM,EAAE;IAAE,SAAS,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EAC9F,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,CAAC,GACZ,CAAC,CAGH"}

package/dist/env.js

@@ -0,0 +1,52 @@
+/**
+ * Environment-variable gateway — the sanctioned funnel for `process.env` access
+ * (mirrors `packages/config` in gobing-ai/spur; enforced by the
+ * `boundary/env-var-hygiene` rule). Direct `process.env`/`Bun.env` access is
+ * banned outside this module so the set of env consumers stays greppable.
+ *
+ * These accessors are node-bun only: on `cloudflare-workers` there is no
+ * `process`; inject config explicitly rather than calling them (ADR-008).
+ */
+/**
+ * Read one environment variable. Only an unset variable yields `fallback`;
+ * an empty string is a set value and is returned as-is.
+ */
+export function getEnvVar(name, fallback) {
+    const raw = process.env[name];
+    return raw === undefined ? fallback : raw;
+}
+/**
+ * Read the live environment as a record. The returned object IS `process.env`
+ * (not a copy): whole-record operations (`{ ...getEnvVars(), ...vars }`,
+ * `Object.entries(getEnvVars())`) see later mutations, which child-spawn
+ * composition relies on. For single variables prefer {@link getEnvVar},
+ * {@link setEnvVar}, or {@link removeEnvVar}.
+ */
+export function getEnvVars() {
+    return process.env;
+}
+/**
+ * Set one environment variable through the sanctioned gateway. Passing
+ * `undefined` removes the key, so the save/restore idiom
+ * (`const prev = getEnvVar(k); … setEnvVar(k, prev)`) restores absence exactly.
+ */
+export function setEnvVar(name, value) {
+    if (value === undefined)
+        delete process.env[name];
+    else
+        process.env[name] = value;
+}
+/** Remove one environment variable; a no-op when the key is absent. */
+export function removeEnvVar(name) {
+    delete process.env[name];
+}
+/**
+ * Read a runtime option from a `bootstrap.options`-style option bag, returning
+ * `fallback` when the config, section, or key is absent (or null). The typed
+ * replacement surface for config-carrying environment variables — call sites
+ * own key naming and value coercion.
+ */
+export function getAppOptions(config, key, fallback) {
+    const value = config?.bootstrap?.options?.[key];
+    return value === undefined || value === null ? fallback : value;
+}

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from './api-response';
 export * from './const';
 export * from './cursor';
 export * from './date';
+export * from './env';
 export * from './errors';
 export * from './event-severity';
 export * from './object';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -3,6 +3,7 @@ export * from './api-response.js';
 export * from './const.js';
 export * from './cursor.js';
 export * from './date.js';
+export * from './env.js';
 export * from './errors.js';
 export * from './event-severity.js';
 export * from './object.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-utils",
-    "version": "0.4.63",
+    "version": "0.4.67",
     "description": "Zero-dependency TypeScript utilities for dates, cursors, errors, output, origins, roles, and API responses.",
     "keywords": [
         "typescript",

package/src/env.ts

@@ -0,0 +1,59 @@
+/**
+ * Environment-variable gateway — the sanctioned funnel for `process.env` access
+ * (mirrors `packages/config` in gobing-ai/spur; enforced by the
+ * `boundary/env-var-hygiene` rule). Direct `process.env`/`Bun.env` access is
+ * banned outside this module so the set of env consumers stays greppable.
+ *
+ * These accessors are node-bun only: on `cloudflare-workers` there is no
+ * `process`; inject config explicitly rather than calling them (ADR-008).
+ */
+
+/**
+ * Read one environment variable. Only an unset variable yields `fallback`;
+ * an empty string is a set value and is returned as-is.
+ */
+export function getEnvVar(name: string, fallback?: string): string | undefined {
+    const raw = process.env[name];
+    return raw === undefined ? fallback : raw;
+}
+
+/**
+ * Read the live environment as a record. The returned object IS `process.env`
+ * (not a copy): whole-record operations (`{ ...getEnvVars(), ...vars }`,
+ * `Object.entries(getEnvVars())`) see later mutations, which child-spawn
+ * composition relies on. For single variables prefer {@link getEnvVar},
+ * {@link setEnvVar}, or {@link removeEnvVar}.
+ */
+export function getEnvVars(): Record<string, string | undefined> {
+    return process.env;
+}
+
+/**
+ * Set one environment variable through the sanctioned gateway. Passing
+ * `undefined` removes the key, so the save/restore idiom
+ * (`const prev = getEnvVar(k); … setEnvVar(k, prev)`) restores absence exactly.
+ */
+export function setEnvVar(name: string, value: string | undefined): void {
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+}
+
+/** Remove one environment variable; a no-op when the key is absent. */
+export function removeEnvVar(name: string): void {
+    delete process.env[name];
+}
+
+/**
+ * Read a runtime option from a `bootstrap.options`-style option bag, returning
+ * `fallback` when the config, section, or key is absent (or null). The typed
+ * replacement surface for config-carrying environment variables — call sites
+ * own key naming and value coercion.
+ */
+export function getAppOptions<T>(
+    config: { bootstrap?: { options?: Record<string, unknown> | null } | null } | null | undefined,
+    key: string,
+    fallback: T,
+): T {
+    const value = config?.bootstrap?.options?.[key];
+    return value === undefined || value === null ? fallback : (value as T);
+}

package/src/index.ts

@@ -3,6 +3,7 @@ export * from './api-response';
 export * from './const';
 export * from './cursor';
 export * from './date';
+export * from './env';
 export * from './errors';
 export * from './event-severity';
 export * from './object';