@elaraai/east-node-std 1.0.35 → 1.0.37

package/dist/src/env.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { StringType, OptionType } from "@elaraai/east";
+import type { PlatformFunction } from "@elaraai/east/internal";
+/**
+ * Reads an environment variable from the process environment.
+ *
+ * Returns `some(value)` when the variable is set (including when set to the
+ * empty string) and `none` when it is not set. Like `Time.now()`, this is an
+ * impure platform function: the value comes from the process environment at
+ * runtime and is never part of the compiled program.
+ *
+ * This is the supported way to consume credentials in East programs — the IR
+ * carries only the variable *name*, and whatever launched the process supplies
+ * the value (a developer's shell locally, a secret store in hosted runtimes).
+ * Never write a credential as a string literal: East IR is content-addressed,
+ * stored, exported, and replicated, so a literal secret in it is effectively
+ * unredactable.
+ *
+ * This is a platform function for the East language, enabling environment
+ * access in East programs running on Node.js.
+ *
+ * @param name - The environment variable name (e.g. "ERP_DB_PASSWORD")
+ * @returns `some(value)` if the variable is set, `none` otherwise
+ *
+ * @example
+ * ```ts
+ * const readToken = East.function([], OptionType(StringType), $ => {
+ *     return Env.get("API_TOKEN");
+ *     // Returns: some("...") when API_TOKEN is set, none otherwise
+ * });
+ * ```
+ */
+export declare const env_get: import("@elaraai/east").PlatformDefinition<[StringType], OptionType<StringType>>;
+/**
+ * Node.js implementation of environment platform functions.
+ *
+ * Pass this array to {@link East.compile} or {@link East.compileAsync} to
+ * enable environment access.
+ */
+declare const EnvImpl: PlatformFunction[];
+/**
+ * Grouped environment platform functions.
+ *
+ * Provides read access to process environment variables for East programs.
+ * Use this for values that must be supplied by the runtime environment rather
+ * than compiled into the program — above all credentials, which must never
+ * appear as literals in East code (the IR is content-addressed and replicated;
+ * a literal secret in it cannot be redacted).
+ *
+ * @example
+ * ```ts
+ * import { East, StringType } from "@elaraai/east";
+ * import { Env } from "@elaraai/east-node-std";
+ *
+ * const connectionPassword = East.function([], StringType, $ => {
+ *     // Name in IR; value from the environment. `.unwrap()` errors at
+ *     // runtime if the variable is not set.
+ *     return Env.get("ERP_DB_PASSWORD").unwrap();
+ * });
+ *
+ * const compiled = East.compile(connectionPassword.toIR(), Env.Implementation);
+ * compiled();
+ * ```
+ */
+export declare const Env: {
+    /**
+     * Reads an environment variable from the process environment.
+     *
+     * Returns `some(value)` when the variable is set (including when set to
+     * the empty string) and `none` when it is not set. Impure by design —
+     * the value is read at runtime and never participates in the compiled
+     * program or task input hashing, which is the desired semantics for
+     * credentials: rotating a secret does not invalidate caches.
+     *
+     * Use `.unwrap()` on the result for the must-exist case, or
+     * `.unwrap("some", $ => ...)` to supply a default.
+     *
+     * @param name - The environment variable name (e.g. "ERP_DB_PASSWORD")
+     * @returns `some(value)` if the variable is set, `none` otherwise
+     *
+     * @example
+     * ```ts
+     * const readToken = East.function([], OptionType(StringType), $ => {
+     *     return Env.get("API_TOKEN");
+     * });
+     *
+     * const compiled = East.compile(readToken.toIR(), Env.Implementation);
+     * compiled();  // Returns: some("...") when API_TOKEN is set, none otherwise
+     * ```
+     */
+    readonly get: import("@elaraai/east").PlatformDefinition<[StringType], OptionType<StringType>>;
+    /**
+     * Node.js implementation of environment platform functions.
+     *
+     * Pass this to {@link East.compile} or {@link East.compileAsync} to
+     * enable environment access.
+     */
+    readonly Implementation: PlatformFunction[];
+};
+export { EnvImpl };
+//# sourceMappingURL=env.d.ts.map

package/dist/src/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAQ,UAAU,EAAE,UAAU,EAAc,MAAM,eAAe,CAAC;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,OAAO,kFAAiE,CAAC;AAEtF;;;;;GAKG;AACH,QAAA,MAAM,OAAO,EAAE,gBAAgB,EAY9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,GAAG;IACZ;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;;IAGH;;;;;OAKG;;CAEG,CAAC;AAGX,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/src/env.js

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { East, StringType, OptionType, some, none } from "@elaraai/east";
+import { EastError } from "@elaraai/east/internal";
+/**
+ * Reads an environment variable from the process environment.
+ *
+ * Returns `some(value)` when the variable is set (including when set to the
+ * empty string) and `none` when it is not set. Like `Time.now()`, this is an
+ * impure platform function: the value comes from the process environment at
+ * runtime and is never part of the compiled program.
+ *
+ * This is the supported way to consume credentials in East programs — the IR
+ * carries only the variable *name*, and whatever launched the process supplies
+ * the value (a developer's shell locally, a secret store in hosted runtimes).
+ * Never write a credential as a string literal: East IR is content-addressed,
+ * stored, exported, and replicated, so a literal secret in it is effectively
+ * unredactable.
+ *
+ * This is a platform function for the East language, enabling environment
+ * access in East programs running on Node.js.
+ *
+ * @param name - The environment variable name (e.g. "ERP_DB_PASSWORD")
+ * @returns `some(value)` if the variable is set, `none` otherwise
+ *
+ * @example
+ * ```ts
+ * const readToken = East.function([], OptionType(StringType), $ => {
+ *     return Env.get("API_TOKEN");
+ *     // Returns: some("...") when API_TOKEN is set, none otherwise
+ * });
+ * ```
+ */
+export const env_get = East.platform("env_get", [StringType], OptionType(StringType));
+/**
+ * Node.js implementation of environment platform functions.
+ *
+ * Pass this array to {@link East.compile} or {@link East.compileAsync} to
+ * enable environment access.
+ */
+const EnvImpl = [
+    env_get.implement((name) => {
+        try {
+            const value = process.env[name];
+            return value === undefined ? none : some(value);
+        }
+        catch (err) {
+            throw new EastError(`Failed to read environment variable "${name}": ${err.message}`, {
+                location: [{ filename: "env_get", line: 0n, column: 0n }],
+                cause: err,
+            });
+        }
+    }),
+];
+/**
+ * Grouped environment platform functions.
+ *
+ * Provides read access to process environment variables for East programs.
+ * Use this for values that must be supplied by the runtime environment rather
+ * than compiled into the program — above all credentials, which must never
+ * appear as literals in East code (the IR is content-addressed and replicated;
+ * a literal secret in it cannot be redacted).
+ *
+ * @example
+ * ```ts
+ * import { East, StringType } from "@elaraai/east";
+ * import { Env } from "@elaraai/east-node-std";
+ *
+ * const connectionPassword = East.function([], StringType, $ => {
+ *     // Name in IR; value from the environment. `.unwrap()` errors at
+ *     // runtime if the variable is not set.
+ *     return Env.get("ERP_DB_PASSWORD").unwrap();
+ * });
+ *
+ * const compiled = East.compile(connectionPassword.toIR(), Env.Implementation);
+ * compiled();
+ * ```
+ */
+export const Env = {
+    /**
+     * Reads an environment variable from the process environment.
+     *
+     * Returns `some(value)` when the variable is set (including when set to
+     * the empty string) and `none` when it is not set. Impure by design —
+     * the value is read at runtime and never participates in the compiled
+     * program or task input hashing, which is the desired semantics for
+     * credentials: rotating a secret does not invalidate caches.
+     *
+     * Use `.unwrap()` on the result for the must-exist case, or
+     * `.unwrap("some", $ => ...)` to supply a default.
+     *
+     * @param name - The environment variable name (e.g. "ERP_DB_PASSWORD")
+     * @returns `some(value)` if the variable is set, `none` otherwise
+     *
+     * @example
+     * ```ts
+     * const readToken = East.function([], OptionType(StringType), $ => {
+     *     return Env.get("API_TOKEN");
+     * });
+     *
+     * const compiled = East.compile(readToken.toIR(), Env.Implementation);
+     * compiled();  // Returns: some("...") when API_TOKEN is set, none otherwise
+     * ```
+     */
+    get: env_get,
+    /**
+     * Node.js implementation of environment platform functions.
+     *
+     * Pass this to {@link East.compile} or {@link East.compileAsync} to
+     * enable environment access.
+     */
+    Implementation: EnvImpl,
+};
+// Export for consistency with the other module implementation arrays
+export { EnvImpl };
+//# sourceMappingURL=env.js.map

package/dist/src/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAEzE,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;AAEtF;;;;;GAKG;AACH,MAAM,OAAO,GAAuB;IAChC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAY,EAAE,EAAE;QAC/B,IAAI,CAAC;YACD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChC,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAChB,MAAM,IAAI,SAAS,CAAC,wCAAwC,IAAI,MAAM,GAAG,CAAC,OAAO,EAAE,EAAE;gBACjF,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;gBACzD,KAAK,EAAE,GAAG;aACb,CAAC,CAAC;QACP,CAAC;IACL,CAAC,CAAC;CACL,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG;IACf;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,GAAG,EAAE,OAAO;IAEZ;;;;;OAKG;IACH,cAAc,EAAE,OAAO;CACjB,CAAC;AAEX,qEAAqE;AACrE,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/src/index.d.ts

@@ -9,6 +9,7 @@
  */
 export * from "./test.js";
 export * from "./console.js";
+export * from "./env.js";
 export * from "./fs.js";
 export * from "./path.js";
 export * from "./crypto.js";

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AAGH,cAAc,WAAW,CAAC;AAG1B,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAY5B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,YAAY,qDASxB,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,qDAQ5B,CAAC;AAGF,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AAGH,cAAc,WAAW,CAAC;AAG1B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAa5B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,YAAY,qDAUxB,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,qDAS5B,CAAC;AAGF,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC"}

package/dist/src/index.js

@@ -11,6 +11,7 @@
 export * from "./test.js";
 // Export platform function definitions and implementations
 export * from "./console.js";
+export * from "./env.js";
 export * from "./fs.js";
 export * from "./path.js";
 export * from "./crypto.js";
@@ -19,6 +20,7 @@ export * from "./fetch.js";
 export * from "./random.js";
 // Import implementations for combined export
 import { ConsoleImpl } from "./console.js";
+import { EnvImpl } from "./env.js";
 import { FileSystemImpl } from "./fs.js";
 import { PathImpl } from "./path.js";
 import { CryptoImpl } from "./crypto.js";
@@ -48,6 +50,7 @@ import { TestImpl } from "./test.js";
  */
 export const NodePlatform = [
     ...ConsoleImpl,
+    ...EnvImpl,
     ...FileSystemImpl,
     ...PathImpl,
     ...CryptoImpl,
@@ -76,6 +79,7 @@ export const NodePlatform = [
  */
 export const NodePlatformSync = [
     ...ConsoleImpl,
+    ...EnvImpl,
     ...FileSystemImpl,
     ...PathImpl,
     ...CryptoImpl,

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AAEH,wBAAwB;AACxB,cAAc,WAAW,CAAC;AAE1B,2DAA2D;AAC3D,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAE5B,6CAA6C;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IACxB,GAAG,WAAW;IACd,GAAG,cAAc;IACjB,GAAG,QAAQ;IACX,GAAG,UAAU;IACb,GAAG,QAAQ;IACX,GAAG,SAAS;IACZ,GAAG,UAAU;IACb,GAAG,QAAQ;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC5B,GAAG,WAAW;IACd,GAAG,cAAc;IACjB,GAAG,QAAQ;IACX,GAAG,UAAU;IACb,GAAG,UAAU;IACb,sCAAsC;IACtC,iCAAiC;CACpC,CAAC;AAEF,oFAAoF;AACpF,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AAEH,wBAAwB;AACxB,cAAc,WAAW,CAAC;AAE1B,2DAA2D;AAC3D,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAE5B,6CAA6C;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IACxB,GAAG,WAAW;IACd,GAAG,OAAO;IACV,GAAG,cAAc;IACjB,GAAG,QAAQ;IACX,GAAG,UAAU;IACb,GAAG,QAAQ;IACX,GAAG,SAAS;IACZ,GAAG,UAAU;IACb,GAAG,QAAQ;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC5B,GAAG,WAAW;IACd,GAAG,OAAO;IACV,GAAG,cAAc;IACjB,GAAG,QAAQ;IACX,GAAG,UAAU;IACb,GAAG,UAAU;IACb,sCAAsC;IACtC,iCAAiC;CACpC,CAAC;AAEF,oFAAoF;AACpF,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elaraai/east-node-std",
-  "version": "1.0.35",
+  "version": "1.0.37",
   "description": "East Node - Node.js platform integration for East language",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -50,7 +50,7 @@
     "typescript": "~5.9.2"
   },
   "peerDependencies": {
-    "@elaraai/east": "1.0.35"
+    "@elaraai/east": "1.0.37"
   },
   "scripts": {
     "build": "rm -rf dist && tsc",