@effectstream/utils 0.100.13 → 0.100.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/utils",
-  "version": "0.100.13",
+  "version": "0.100.14",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -15,7 +15,8 @@
     ".": "./src/mod.ts",
     "./node-env": "./src/config.ts",
     "./runtime": "./src/runtime.ts",
-    "./runtime-spawn": "./src/runtime-spawn.ts"
+    "./runtime-spawn": "./src/runtime-spawn.ts",
+    "./fs": "./src/fs.ts"
   },
   "dependencies": {
     "@coderspirit/nominal": "^4.1.1",

package/src/config.ts

@@ -155,26 +155,50 @@ const definitions: Record<string, ConfigDefinition> = {
   MQTT_ENGINE_BROKER_URL: {
     key: "MQTT_ENGINE_BROKER_URL",
     type: "string",
-    defaultValue: "ws://127.0.0.1:8883",
-    description: "MQTT Engine Broker URL. Example: 'ws://127.0.0.1:8883'",
+    defaultValue: "mqtt://127.0.0.1:8883",
+    description: "MQTT Engine Broker TCP URL. Example: 'mqtt://127.0.0.1:8883'",
   },
   MQTT_ENGINE_BROKER_PORT: {
     key: "MQTT_ENGINE_BROKER_PORT",
     type: "number",
     defaultValue: 8883,
-    description: "MQTT Engine Broker Port. Example: '8883'",
+    description: "MQTT Engine Broker TCP Port. Example: '8883'",
+  },
+  MQTT_ENGINE_BROKER_WS_URL: {
+    key: "MQTT_ENGINE_BROKER_WS_URL",
+    type: "string",
+    defaultValue: "ws://127.0.0.1:9883",
+    description: "MQTT Engine Broker WebSocket URL (for browser clients). Example: 'ws://127.0.0.1:9883'",
+  },
+  MQTT_ENGINE_BROKER_WS_PORT: {
+    key: "MQTT_ENGINE_BROKER_WS_PORT",
+    type: "number",
+    defaultValue: 9883,
+    description: "MQTT Engine Broker WebSocket Port. Example: '9883'",
   },
   MQTT_BATCHER_BROKER_URL: {
     key: "MQTT_BATCHER_BROKER_URL",
     type: "string",
-    defaultValue: "ws://127.0.0.1:8884",
-    description: "MQTT Batcher Broker URL. Example: 'ws://127.0.0.1:8884'",
+    defaultValue: "mqtt://127.0.0.1:8884",
+    description: "MQTT Batcher Broker TCP URL. Example: 'mqtt://127.0.0.1:8884'",
   },
   MQTT_BATCHER_BROKER_PORT: {
     key: "MQTT_BATCHER_BROKER_PORT",
     type: "number",
     defaultValue: 8884,
-    description: "MQTT Batcher Broker Port. Example: '8884'",
+    description: "MQTT Batcher Broker TCP Port. Example: '8884'",
+  },
+  MQTT_BATCHER_BROKER_WS_URL: {
+    key: "MQTT_BATCHER_BROKER_WS_URL",
+    type: "string",
+    defaultValue: "ws://127.0.0.1:9884",
+    description: "MQTT Batcher Broker WebSocket URL (for browser clients). Example: 'ws://127.0.0.1:9884'",
+  },
+  MQTT_BATCHER_BROKER_WS_PORT: {
+    key: "MQTT_BATCHER_BROKER_WS_PORT",
+    type: "number",
+    defaultValue: 9884,
+    description: "MQTT Batcher Broker WebSocket Port. Example: '9884'",
   },
   EFFECTSTREAM_API_PORT: {
     key: "EFFECTSTREAM_API_PORT",
@@ -297,15 +321,27 @@ export class ENV {
   static get MQTT_ENGINE_BROKER_PORT(): number {
     return ENV.getConfig(definitions.MQTT_ENGINE_BROKER_PORT);
   }
+  static get MQTT_ENGINE_BROKER_WS_PORT(): number {
+    return ENV.getConfig(definitions.MQTT_ENGINE_BROKER_WS_PORT);
+  }
   static get MQTT_BATCHER_BROKER_PORT(): number {
     return ENV.getConfig(definitions.MQTT_BATCHER_BROKER_PORT);
   }
+  static get MQTT_BATCHER_BROKER_WS_PORT(): number {
+    return ENV.getConfig(definitions.MQTT_BATCHER_BROKER_WS_PORT);
+  }
   static get MQTT_ENGINE_BROKER_URL(): string {
     return ENV.getConfig(definitions.MQTT_ENGINE_BROKER_URL);
   }
+  static get MQTT_ENGINE_BROKER_WS_URL(): string {
+    return ENV.getConfig(definitions.MQTT_ENGINE_BROKER_WS_URL);
+  }
   static get MQTT_BATCHER_BROKER_URL(): string {
     return ENV.getConfig(definitions.MQTT_BATCHER_BROKER_URL);
   }
+  static get MQTT_BATCHER_BROKER_WS_URL(): string {
+    return ENV.getConfig(definitions.MQTT_BATCHER_BROKER_WS_URL);
+  }
   static get DB_HOST(): string {
     return ENV.getConfig(definitions.DB_HOST);
   }

package/src/fs.ts

@@ -0,0 +1,88 @@
+/**
+ * Cross-runtime filesystem primitives.
+ *
+ * Thin wrappers over `node:fs/promises`, which works identically under Deno,
+ * Node, and Bun — no runtime branching. The surface area is intentionally
+ * small: only what the codebase actually uses.
+ *
+ * ## Why this lives in its own entry, not in `runtime.ts`
+ *
+ * `runtime.ts` is re-exported from the package barrel (`mod.ts`). Anything
+ * that imports from `@effectstream/utils` (e.g. the explorer client bundled
+ * by Vite) drags the entire re-exported graph along. Keeping fs helpers in
+ * `runtime.ts` means any browser build pulls `node:fs/promises`,
+ * `node:os`, and `node:path` into its bundle — which Vite rightly rejects.
+ *
+ * This file is deliberately **not** re-exported from `mod.ts`. Importers
+ * must reach for the `@effectstream/utils/fs` subpath explicitly, and
+ * client/browser code stays clean.
+ */
+
+import { mkdir, mkdtemp, readdir, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isNotFoundError } from "./runtime.ts";
+
+/** Create a unique temp directory and return its absolute path. */
+export async function makeTempDir(opts: { prefix?: string } = {}): Promise<string> {
+  return await mkdtemp(join(tmpdir(), opts.prefix ?? "tmp-"));
+}
+
+/** Create a directory (and parents) if missing. */
+export async function mkdirRecursive(path: string): Promise<void> {
+  await mkdir(path, { recursive: true });
+}
+
+/** Write a UTF-8 string to `path`, overwriting any existing file. */
+export async function writeTextFile(path: string, data: string): Promise<void> {
+  await writeFile(path, data, "utf8");
+}
+
+/** Set access and modification times on `path` (accepts Date or ms). */
+export async function setFileTimes(
+  path: string,
+  atime: Date | number,
+  mtime: Date | number,
+): Promise<void> {
+  await utimes(
+    path,
+    atime instanceof Date ? atime : new Date(atime),
+    mtime instanceof Date ? mtime : new Date(mtime),
+  );
+}
+
+/**
+ * Remove a file or directory. Pass `recursive` to delete non-empty dirs,
+ * and `ignoreMissing` to swallow ENOENT.
+ */
+export async function remove(
+  path: string,
+  opts: { recursive?: boolean; ignoreMissing?: boolean } = {},
+): Promise<void> {
+  try {
+    await rm(path, { recursive: opts.recursive ?? false, force: false });
+  } catch (e) {
+    if (opts.ignoreMissing && isNotFoundError(e)) return;
+    throw e;
+  }
+}
+
+export interface DirEntry {
+  name: string;
+  isFile: boolean;
+  isDirectory: boolean;
+}
+
+/** List entries in a directory. Throws (with a NotFound-shaped error) if missing. */
+export async function* readDir(path: string): AsyncIterable<DirEntry> {
+  const entries = await readdir(path, { withFileTypes: true });
+  for (const e of entries) {
+    yield { name: e.name, isFile: e.isFile(), isDirectory: e.isDirectory() };
+  }
+}
+
+/** Stat a file; returns mtime as ms since epoch (0 if unavailable). */
+export async function statMtime(path: string): Promise<number> {
+  const s = await stat(path);
+  return s.mtimeMs ?? s.mtime?.getTime() ?? 0;
+}

package/src/runtime.ts

@@ -87,3 +87,8 @@ export function isNotFoundError(err: unknown): boolean {
   }
   return false;
 }
+
+// Filesystem helpers (makeTempDir, readDir, etc.) live in `./fs.ts` under
+// the `@effectstream/utils/fs` subpath export. They intentionally do NOT
+// re-export from this file, because this file is re-exported by the package
+// barrel (`mod.ts`) — dragging `node:fs/promises` into browser bundles.