Make it easy to take NODE_OPTIONS and set the old space flag

Author: matt-aitken

packages/core/src/v3/machines/index.ts

@@ -8,6 +8,50 @@ import { MachinePreset } from "../schemas/common.js";
  * @param {number} [overhead=0.2] - The memory overhead factor (0.2 = 20% reserved for system operations)
  * @returns {number} The calculated max old space size in MiB
  */
-export function maxOldSpaceSizeForMachine(machine: MachinePreset, overhead = 0.2) {
-  return machine.memory * 1_024 * (1 - overhead);
+export function maxOldSpaceSizeForMachine(machine: MachinePreset, overhead: number = 0.2): number {
+  return Math.round(machine.memory * 1_024 * (1 - overhead));
+}
+
+/**
+ * Returns a flag to be used for `--max-old-space-size`. It is in MiB.
+ * Setting this correctly means V8 spends more times running Garbage Collection (GC).
+ * It won't eliminate crashes but it will help avoid them.
+ * @param {MachinePreset} machine - The machine preset configuration containing memory specifications
+ * @param {number} [overhead=0.2] - The memory overhead factor (0.2 = 20% reserved for system operations)
+ * @returns {string} The calculated max old space size flag
+ */
+export function maxOldSpaceSizeFlag(machine: MachinePreset, overhead: number = 0.2): string {
+  return `--max-old-space-size=${maxOldSpaceSizeForMachine(machine, overhead)}`;
+}
+
+/**
+ * Takes the existing NODE_OPTIONS value, removes any existing max-old-space-size flag, and adds a new one.
+ * @param {string | undefined} existingOptions - The existing NODE_OPTIONS value
+ * @param {MachinePreset} machine - The machine preset configuration containing memory specifications
+ * @param {number} [overhead=0.2] - The memory overhead factor (0.2 = 20% reserved for system operations)
+ * @returns {string} The updated NODE_OPTIONS value with the new max-old-space-size flag
+ */
+export function nodeOptionsWithMaxOldSpaceSize(
+  existingOptions: string | undefined,
+  machine: MachinePreset,
+  overhead: number = 0.2
+): string {
+  let options = existingOptions ?? "";
+
+  //remove existing max-old-space-size flag
+  options = options.replace(/--max-old-space-size=\d+/g, "").trim();
+
+  //get max-old-space-size flag
+  const flag = maxOldSpaceSizeFlag(machine, overhead);
+
+  return normalizeCommandLineFlags(options ? `${options} ${flag}` : flag);
+}
+
+/**
+ * Normalizes spaces in a string of command line flags, ensuring single spaces between flags
+ * @param {string} input - The string to normalize
+ * @returns {string} The normalized string with single spaces between flags
+ */
+function normalizeCommandLineFlags(input: string): string {
+  return input.split(/\s+/).filter(Boolean).join(" ");
 }

packages/core/src/v3/machines/max-old-space.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { nodeOptionsWithMaxOldSpaceSize } from "./index.js";
+import { MachinePreset } from "../schemas/common.js";
+
+describe("nodeOptionsWithMaxOldSpaceSize", () => {
+  const testMachine: MachinePreset = {
+    name: "small-2x",
+    memory: 1, // 1GB = 1024 MiB
+    cpu: 1,
+    centsPerMs: 0,
+  };
+
+  // With default 0.2 overhead, max-old-space-size should be 819 (1024 * 0.8)
+  const expectedFlag = "--max-old-space-size=819";
+
+  it("handles undefined NODE_OPTIONS", () => {
+    const result = nodeOptionsWithMaxOldSpaceSize(undefined, testMachine);
+    expect(result).toBe(expectedFlag);
+  });
+
+  it("handles empty string NODE_OPTIONS", () => {
+    const result = nodeOptionsWithMaxOldSpaceSize("", testMachine);
+    expect(result).toBe(expectedFlag);
+  });
+
+  it("preserves existing flags while adding max-old-space-size", () => {
+    const result = nodeOptionsWithMaxOldSpaceSize("--inspect --trace-warnings", testMachine);
+    expect(result).toBe(`--inspect --trace-warnings ${expectedFlag}`);
+  });
+
+  it("replaces existing max-old-space-size flag", () => {
+    const result = nodeOptionsWithMaxOldSpaceSize(
+      "--max-old-space-size=4096 --inspect",
+      testMachine
+    );
+    expect(result).toBe(`--inspect ${expectedFlag}`);
+  });
+
+  it("handles multiple existing max-old-space-size flags", () => {
+    const result = nodeOptionsWithMaxOldSpaceSize(
+      "--max-old-space-size=4096 --inspect --max-old-space-size=8192",
+      testMachine
+    );
+    expect(result).toBe(`--inspect ${expectedFlag}`);
+  });
+
+  it("handles extra spaces between flags", () => {
+    const result = nodeOptionsWithMaxOldSpaceSize("--inspect    --trace-warnings", testMachine);
+    expect(result).toBe(`--inspect --trace-warnings ${expectedFlag}`);
+  });
+
+  it("uses custom overhead value", () => {
+    const result = nodeOptionsWithMaxOldSpaceSize("--inspect", testMachine, 0.5);
+    // With 0.5 overhead, max-old-space-size should be 512 (1024 * 0.5)
+    expect(result).toBe("--inspect --max-old-space-size=512");
+  });
+});

packages/core/vitest.config.ts

@@ -2,7 +2,7 @@ import { defineConfig } from "vitest/config";
 
 export default defineConfig({
   test: {
-    include: ["test/**/*.test.ts"],
+    include: ["test/**/*.test.ts", "src/v3/**/*.test.ts"],
     globals: true,
   },
 });