@effectstream/utils 0.103.0 → 0.103.2

package/README.md

@@ -59,7 +59,7 @@ state machine, and the batcher pulls something from here.
 
 Address types and validators:
 
-- `AddressType` - enum of chain identifiers (EVM, CARDANO, SUBSTRATE, ALGORAND, MINA, MIDNIGHT, AVAIL, POLKADOT, NEAR).
+- `AddressType` - enum of chain identifiers (EVM, CARDANO, SUBSTRATE, ALGORAND, MINA, MIDNIGHT, AVAIL, POLKADOT, NEAR, SOLANA), plus `NONE` for unattributed inputs.
 - `AddressValidator` - `Record<AddressType, TSchema>` of TypeBox validators, one per chain.
 - `AddressAndType` - tagged-union shape for `{ type, address }` pairs.
 
@@ -95,9 +95,10 @@ Concurrency (Effection-based):
 
 Subpath entries:
 
-- `@effectstream/utils/node-env` - `dotenv`-aware env loader, for Node-only callers.
+- `@effectstream/utils/node-env` - `dotenv`-aware env loader exposing the typed `ENV` object, for Node-only callers. Every registered variable is listed in the [environment variables reference](https://effectstream.github.io/docs/home/components/environment-variables).
 - `@effectstream/utils/runtime` - Effection runtime helpers.
 - `@effectstream/utils/runtime-spawn` - child-process spawn helpers built on Effection.
+- `@effectstream/utils/fs` - promise-based filesystem helpers used by the orchestrator and binary wrappers: `makeTempDir`, `mkdirRecursive`, `writeTextFile`, `setFileTimes`, `remove`, and directory listing via `DirEntry`.
 
 ## Examples
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/utils",
-  "version": "0.103.0",
+  "version": "0.103.2",
   "license": "(MIT OR Apache-2.0)",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -13,6 +13,7 @@
   },
   "exports": {
     ".": "./src/mod.ts",
+    "./types": "./src/types/mod.ts",
     "./node-env": "./src/config.ts",
     "./runtime": "./src/runtime.ts",
     "./runtime-spawn": "./src/runtime-spawn.ts",

package/src/runtime.ts

@@ -39,15 +39,35 @@ export function getRuntime(): {runtime: Runtime, environment: RuntimeEnvironment
 
 /**
  * Helpers for common process operations.
+ *
+ * These are node-only by nature, but this module is reachable from BROWSER
+ * bundles: `AddressType` is a value export of this package, so importing it
+ * (as @effectstream/wallets' IProvider does) pulls the barrel, and the barrel
+ * re-exports config.ts — which calls getEnv() at module top level. An
+ * unguarded `process` there is a hard `ReferenceError: process is not defined`
+ * at import time, before any app code runs.
+ *
+ * `getEnv` therefore degrades to `undefined` in a browser (an unset variable
+ * is the truthful answer there). The mutating/process-control helpers below
+ * still throw, because silently doing nothing would hide a real porting bug.
  */
 
-/** Get environment variable. */
+const hasProcess = (): boolean =>
+  typeof process !== "undefined" && process != null;
+
+/** Get environment variable. Returns undefined where there is no process. */
 export function getEnv(key: string): string | undefined {
-  return process.env[key];
+  if (!hasProcess()) return undefined;
+  return process.env?.[key];
 }
 
 /** Set environment variable. */
 export function setEnv(key: string, value: string): void {
+  if (!hasProcess()) {
+    throw new Error(
+      `setEnv(${key}) is not available in this runtime — there is no process to mutate.`,
+    );
+  }
   process.env[key] = value;
 }
 

package/src/types/mod.ts

@@ -1,3 +1,11 @@
+// Exposed as `@effectstream/utils/types` — the browser-safe subset.
+//
+// The ROOT barrel re-exports config.ts, which runs dotenv (.env loading from
+// disk) at import time. Any browser bundle that imports the root for a mere
+// type or enum (AddressType, Result, WalletAddress…) drags that bootstrap —
+// and once crashed outright on `process`. Browser-reachable code should import
+// this subpath instead; keep this tree free of node-only modules (node:buffer
+// is the one allowed exception — it has a real browser polyfill).
 export type * from "./misc.ts";
 export type * from "./json-query.ts";
 export type * from "./nominal.ts";