cobolx-2 1.2.3 → 1.2.4

package/runtime/src/math_utils.ts

@@ -0,0 +1,316 @@
+/**
+ * COBOL-X Standard Library — Math Built-in Functions
+ *
+ * Provides COBOL-style mathematical operations that extend the standard
+ * COMPUTE verb with advanced numerical functions. All functions operate
+ * on numeric (PIC 9 / PIC S9V9) values and return numbers.
+ *
+ * COBOL traditionally provides FUNCTION SQRT, FUNCTION ABS, etc.
+ * This module provides a comprehensive set with consistent error handling.
+ *
+ * @module math_utils
+ */
+
+/**
+ * COMPUTE-POWER — Raises a base number to a specified exponent.
+ *
+ * COBOL equivalent: base ** exponent (COBOL 2002+), or manual multiplication.
+ *
+ * @param base - The base number.
+ * @param exponent - The exponent (must be non-negative for integer bases).
+ * @returns The result of base raised to the power of exponent.
+ * @throws {Error} If base is negative and exponent is not an integer.
+ *
+ * @example
+ * COMPUTE_POWER(2, 10)   // => 1024
+ * COMPUTE_POWER(3, 3)    // => 27
+ * COMPUTE_POWER(9, 0.5)  // => 3
+ */
+export function COMPUTE_POWER(base: number, exponent: number): number {
+  if (typeof base !== "number" || typeof exponent !== "number") {
+    throw new Error(
+      `COMPUTE-POWER: expected PIC 9 for both arguments, received ${typeof base} and ${typeof exponent}`
+    );
+  }
+  if (base < 0 && !Number.isInteger(exponent)) {
+    throw new Error(
+      `COMPUTE-POWER: negative base ${base} with non-integer exponent ${exponent} produces NaN`
+    );
+  }
+  return Math.pow(base, exponent);
+}
+
+/**
+ * COMPUTE-SQRT — Computes the square root of a number.
+ *
+ * COBOL equivalent: FUNCTION SQRT.
+ *
+ * @param value - The numeric value (must be non-negative).
+ * @returns The square root of the value.
+ * @throws {Error} If the value is negative or not a number.
+ *
+ * @example
+ * COMPUTE_SQRT(144)  // => 12
+ * COMPUTE_SQRT(2)    // => 1.4142135623730951
+ */
+export function COMPUTE_SQRT(value: number): number {
+  if (typeof value !== "number") {
+    throw new Error(`COMPUTE-SQRT: expected PIC 9, received ${typeof value}`);
+  }
+  if (value < 0) {
+    throw new Error(`COMPUTE-SQRT: argument must be non-negative, received ${value}`);
+  }
+  return Math.sqrt(value);
+}
+
+/**
+ * COMPUTE-ABS — Returns the absolute value of a number.
+ *
+ * COBOL equivalent: FUNCTION ABS.
+ *
+ * @param value - The numeric value.
+ * @returns The absolute (non-negative) value.
+ * @throws {Error} If the value is not a number.
+ *
+ * @example
+ * COMPUTE_ABS(-42)   // => 42
+ * COMPUTE_ABS(42)    // => 42
+ * COMPUTE_ABS(0)     // => 0
+ */
+export function COMPUTE_ABS(value: number): number {
+  if (typeof value !== "number") {
+    throw new Error(`COMPUTE-ABS: expected PIC 9, received ${typeof value}`);
+  }
+  return Math.abs(value);
+}
+
+/**
+ * COMPUTE-MOD — Computes the remainder of division (modulo operation).
+ *
+ * COBOL equivalent: result = dividend / divisor with REMAINDER.
+ * Unlike JavaScript's % operator, this always returns a non-negative
+ * result when the divisor is positive, matching COBOL's REM behavior.
+ *
+ * @param dividend - The number to be divided.
+ * @param divisor - The number to divide by (must not be zero).
+ * @returns The remainder of the division.
+ * @throws {Error} If either argument is not a number, or divisor is zero.
+ *
+ * @example
+ * COMPUTE_MOD(17, 5)   // => 2
+ * COMPUTE_MOD(20, 4)   // => 0
+ * COMPUTE_MOD(-7, 3)   // => 2 (COBOL-style, always non-negative)
+ */
+export function COMPUTE_MOD(dividend: number, divisor: number): number {
+  if (typeof dividend !== "number" || typeof divisor !== "number") {
+    throw new Error(
+      `COMPUTE-MOD: expected PIC 9 for both arguments, received ${typeof dividend} and ${typeof divisor}`
+    );
+  }
+  if (divisor === 0) {
+    throw new Error("COMPUTE-MOD: division by zero — divisor must not be zero");
+  }
+  // COBOL-style: remainder is always non-negative when divisor is positive
+  const remainder = dividend % divisor;
+  return remainder < 0 ? remainder + Math.abs(divisor) : remainder;
+}
+
+/**
+ * COMPUTE-MIN — Returns the smallest of the given numeric values.
+ *
+ * COBOL equivalent: FUNCTION MIN.
+ *
+ * @param values - Array of numeric values to compare.
+ * @returns The smallest value.
+ * @throws {Error} If values array is empty or contains non-numeric elements.
+ *
+ * @example
+ * COMPUTE_MIN([3, 1, 4, 1, 5])  // => 1
+ * COMPUTE_MIN([-10, 0, 10])     // => -10
+ */
+export function COMPUTE_MIN(values: number[]): number {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error("COMPUTE-MIN: values array must not be empty");
+  }
+  for (let i = 0; i < values.length; i++) {
+    if (typeof values[i] !== "number" || Number.isNaN(values[i])) {
+      throw new Error(
+        `COMPUTE-MIN: element at index ${i} is not a valid PIC 9 (received ${values[i]})`
+      );
+    }
+  }
+  return Math.min(...values);
+}
+
+/**
+ * COMPUTE-MAX — Returns the largest of the given numeric values.
+ *
+ * COBOL equivalent: FUNCTION MAX.
+ *
+ * @param values - Array of numeric values to compare.
+ * @returns The largest value.
+ * @throws {Error} If values array is empty or contains non-numeric elements.
+ *
+ * @example
+ * COMPUTE_MAX([3, 1, 4, 1, 5])  // => 5
+ * COMPUTE_MAX([-10, 0, 10])     // => 10
+ */
+export function COMPUTE_MAX(values: number[]): number {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error("COMPUTE-MAX: values array must not be empty");
+  }
+  for (let i = 0; i < values.length; i++) {
+    if (typeof values[i] !== "number" || Number.isNaN(values[i])) {
+      throw new Error(
+        `COMPUTE-MAX: element at index ${i} is not a valid PIC 9 (received ${values[i]})`
+      );
+    }
+  }
+  return Math.max(...values);
+}
+
+/**
+ * COMPUTE-ROUND — Rounds a number to a specified number of decimal places.
+ *
+ * COBOL equivalent: ROUNDED MODE IS NEAREST-AWAY-FROM-ZERO on COMPUTE.
+ * Uses "round half away from zero" (banker's rounding), which is the
+ * standard COBOL ROUNDED behavior.
+ *
+ * @param value - The numeric value to round.
+ * @param decimalPlaces - The number of decimal places (default: 0).
+ * @returns The rounded number.
+ * @throws {Error} If arguments are invalid.
+ *
+ * @example
+ * COMPUTE_ROUND(3.456, 2)  // => 3.46
+ * COMPUTE_ROUND(3.454, 2)  // => 3.45
+ * COMPUTE_ROUND(2.5, 0)    // => 3
+ * COMPUTE_ROUND(-2.5, 0)   // => -3
+ */
+export function COMPUTE_ROUND(value: number, decimalPlaces: number = 0): number {
+  if (typeof value !== "number") {
+    throw new Error(`COMPUTE-ROUND: expected PIC 9 for value, received ${typeof value}`);
+  }
+  if (!Number.isInteger(decimalPlaces) || decimalPlaces < 0) {
+    throw new Error(
+      `COMPUTE-ROUND: decimalPlaces must be a non-negative integer, received ${decimalPlaces}`
+    );
+  }
+  // COBOL "round half away from zero" behavior
+  const factor = Math.pow(10, decimalPlaces);
+  const shifted = value * factor;
+  // Use Math.sign to handle negative numbers correctly (away from zero)
+  return (Math.sign(shifted) * Math.round(Math.abs(shifted))) / factor;
+}
+
+/**
+ * COMPUTE-FLOOR — Returns the largest integer less than or equal to a number.
+ *
+ * COBOL equivalent: FUNCTION INTEGER when value is positive.
+ *
+ * @param value - The numeric value.
+ * @returns The floor of the value.
+ * @throws {Error} If the value is not a number.
+ *
+ * @example
+ * COMPUTE_FLOOR(3.7)   // => 3
+ * COMPUTE_FLOOR(-3.2)  // => -4
+ * COMPUTE_FLOOR(5)     // => 5
+ */
+export function COMPUTE_FLOOR(value: number): number {
+  if (typeof value !== "number") {
+    throw new Error(`COMPUTE-FLOOR: expected PIC 9, received ${typeof value}`);
+  }
+  return Math.floor(value);
+}
+
+/**
+ * COMPUTE-CEIL — Returns the smallest integer greater than or equal to a number.
+ *
+ * COBOL equivalent: FUNCTION INTEGER-PART + 1 when value has a fraction.
+ *
+ * @param value - The numeric value.
+ * @returns The ceiling of the value.
+ * @throws {Error} If the value is not a number.
+ *
+ * @example
+ * COMPUTE_CEIL(3.2)   // => 4
+ * COMPUTE_CEIL(-3.7)  // => -3
+ * COMPUTE_CEIL(5)     // => 5
+ */
+export function COMPUTE_CEIL(value: number): number {
+  if (typeof value !== "number") {
+    throw new Error(`COMPUTE-CEIL: expected PIC 9, received ${typeof value}`);
+  }
+  return Math.ceil(value);
+}
+
+/**
+ * COMPUTE-SIGN — Determines the sign of a number.
+ *
+ * Returns -1, 0, or 1 depending on whether the value is negative, zero, or positive.
+ *
+ * @param value - The numeric value to test.
+ * @returns -1 if negative, 0 if zero, 1 if positive.
+ * @throws {Error} If the value is not a number.
+ *
+ * @example
+ * COMPUTE_SIGN(-42)  // => -1
+ * COMPUTE_SIGN(0)    // => 0
+ * COMPUTE_SIGN(42)   // => 1
+ */
+export function COMPUTE_SIGN(value: number): -1 | 0 | 1 {
+  if (typeof value !== "number") {
+    throw new Error(`COMPUTE-SIGN: expected PIC 9, received ${typeof value}`);
+  }
+  if (value < 0) return -1;
+  if (value > 0) return 1;
+  return 0;
+}
+
+/**
+ * COMPUTE-CLAMP — Restricts a value to be within a specified range.
+ *
+ * Useful for ensuring values stay within COBOL PIC bounds.
+ *
+ * @param value - The numeric value to clamp.
+ * @param min - The minimum allowed value.
+ * @param max - The maximum allowed value.
+ * @returns The value clamped to [min, max].
+ * @throws {Error} If arguments are invalid or min > max.
+ *
+ * @example
+ * COMPUTE_CLAMP(15, 0, 10)   // => 10
+ * COMPUTE_CLAMP(-5, 0, 10)   // => 0
+ * COMPUTE_CLAMP(5, 0, 10)    // => 5
+ */
+export function COMPUTE_CLAMP(value: number, min: number, max: number): number {
+  if (typeof value !== "number" || typeof min !== "number" || typeof max !== "number") {
+    throw new Error("COMPUTE-CLAMP: all arguments must be PIC 9");
+  }
+  if (min > max) {
+    throw new Error(`COMPUTE-CLAMP: min (${min}) must not exceed max (${max})`);
+  }
+  return Math.max(min, Math.min(max, value));
+}
+
+/**
+ * COMPUTE-PERCENTAGE — Calculates a percentage of a value.
+ *
+ * Common business computation in COBOL programs.
+ *
+ * @param value - The base value.
+ * @param percentage - The percentage (e.g., 25 for 25%).
+ * @returns The calculated percentage of the value.
+ * @throws {Error} If arguments are not numbers.
+ *
+ * @example
+ * COMPUTE_PERCENTAGE(200, 15)  // => 30
+ * COMPUTE_PERCENTAGE(100, 0.5) // => 0.5
+ */
+export function COMPUTE_PERCENTAGE(value: number, percentage: number): number {
+  if (typeof value !== "number" || typeof percentage !== "number") {
+    throw new Error("COMPUTE-PERCENTAGE: all arguments must be PIC 9");
+  }
+  return (value * percentage) / 100;
+}

package/runtime/src/string_utils.ts

@@ -0,0 +1,307 @@
+/**
+ * COBOL-X Standard Library — String Handling Built-in Functions
+ *
+ * Provides COBOL-style string manipulation utilities that mirror
+ * classic COBOL STRING/UNSTRING operations while offering modern
+ * conveniences. All functions accept and return PIC X (string) values
+ * and follow COBOL naming conventions.
+ *
+ * @module string_utils
+ */
+
+/**
+ * STRING-REVERSE — Reverses the characters in the given string.
+ *
+ * COBOL equivalent: Manual INSPECT TALLYING/REPLACING loop.
+ *
+ * @param value - The alphanumeric string to reverse.
+ * @returns The reversed string.
+ * @throws {Error} If the input is not a string.
+ *
+ * @example
+ * STRING_REVERSE("HELLO WORLD")  // => "DLROW OLLEH"
+ */
+export function STRING_REVERSE(value: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`STRING-REVERSE: expected PIC X, received ${typeof value}`);
+  }
+  return value.split("").reverse().join("");
+}
+
+/**
+ * STRING-UPPER — Converts all alphabetic characters in the string to uppercase.
+ *
+ * COBOL equivalent: FUNCTION UPPER-CASE.
+ *
+ * @param value - The alphanumeric string to convert.
+ * @returns The uppercase version of the string.
+ * @throws {Error} If the input is not a string.
+ *
+ * @example
+ * STRING_UPPER("Hello World")  // => "HELLO WORLD"
+ */
+export function STRING_UPPER(value: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`STRING-UPPER: expected PIC X, received ${typeof value}`);
+  }
+  return value.toUpperCase();
+}
+
+/**
+ * STRING-LOWER — Converts all alphabetic characters in the string to lowercase.
+ *
+ * COBOL equivalent: FUNCTION LOWER-CASE.
+ *
+ * @param value - The alphanumeric string to convert.
+ * @returns The lowercase version of the string.
+ * @throws {Error} If the input is not a string.
+ *
+ * @example
+ * STRING_LOWER("Hello World")  // => "hello world"
+ */
+export function STRING_LOWER(value: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`STRING-LOWER: expected PIC X, received ${typeof value}`);
+  }
+  return value.toLowerCase();
+}
+
+/**
+ * STRING-TRIM — Removes leading and trailing whitespace from the string.
+ *
+ * In COBOL, fields are fixed-width so trailing spaces are normal.
+ * This utility trims both leading and trailing spaces, which is useful
+ * when interfacing with non-COBOL systems.
+ *
+ * @param value - The alphanumeric string to trim.
+ * @param mode - Trim mode: "BOTH" (default), "LEADING", or "TRAILING".
+ * @returns The trimmed string.
+ * @throws {Error} If the input is not a string or mode is invalid.
+ *
+ * @example
+ * STRING_TRIM("  HELLO  ")        // => "HELLO"
+ * STRING_TRIM("  HELLO  ", "LEADING")  // => "HELLO  "
+ * STRING_TRIM("  HELLO  ", "TRAILING") // => "  HELLO"
+ */
+export function STRING_TRIM(value: string, mode: "BOTH" | "LEADING" | "TRAILING" = "BOTH"): string {
+  if (typeof value !== "string") {
+    throw new Error(`STRING-TRIM: expected PIC X, received ${typeof value}`);
+  }
+  const validModes = ["BOTH", "LEADING", "TRAILING"];
+  if (!validModes.includes(mode)) {
+    throw new Error(`STRING-TRIM: invalid mode '${mode}', expected one of ${validModes.join(", ")}`);
+  }
+  switch (mode) {
+    case "LEADING":
+      return value.replace(/^\s+/, "");
+    case "TRAILING":
+      return value.replace(/\s+$/, "");
+    case "BOTH":
+    default:
+      return value.trim();
+  }
+}
+
+/**
+ * STRING-SPLIT — Splits a string into an array of substrings using a delimiter.
+ *
+ * COBOL equivalent: UNSTRING ... DELIMITED BY ...
+ *
+ * @param value - The alphanumeric string to split.
+ * @param delimiter - The delimiter character or string.
+ * @returns An array of substrings.
+ * @throws {Error} If the input is not a string or delimiter is not a string.
+ *
+ * @example
+ * STRING_SPLIT("A,B,C", ",")  // => ["A", "B", "C"]
+ * STRING_SPLIT("KEY=VALUE", "=")  // => ["KEY", "VALUE"]
+ */
+export function STRING_SPLIT(value: string, delimiter: string): string[] {
+  if (typeof value !== "string") {
+    throw new Error(`STRING-SPLIT: expected PIC X for value, received ${typeof value}`);
+  }
+  if (typeof delimiter !== "string") {
+    throw new Error(`STRING-SPLIT: expected PIC X for delimiter, received ${typeof delimiter}`);
+  }
+  if (delimiter === "") {
+    throw new Error("STRING-SPLIT: delimiter must not be empty");
+  }
+  return value.split(delimiter);
+}
+
+/**
+ * STRING-JOIN — Joins an array of strings into a single string using a separator.
+ *
+ * COBOL equivalent: STRING ... DELIMITED BY ... INTO ...
+ *
+ * @param items - Array of strings to join.
+ * @param separator - The separator string to insert between items.
+ * @returns The joined string.
+ * @throws {Error} If items is not an array or contains non-string elements.
+ *
+ * @example
+ * STRING_JOIN(["A", "B", "C"], ", ")  // => "A, B, C"
+ * STRING_JOIN(["LINE1", "LINE2"], "\n")  // => "LINE1\nLINE2"
+ */
+export function STRING_JOIN(items: string[], separator: string): string {
+  if (!Array.isArray(items)) {
+    throw new Error(`STRING-JOIN: expected array of PIC X, received ${typeof items}`);
+  }
+  if (typeof separator !== "string") {
+    throw new Error(`STRING-JOIN: expected PIC X for separator, received ${typeof separator}`);
+  }
+  for (let i = 0; i < items.length; i++) {
+    if (typeof items[i] !== "string") {
+      throw new Error(
+        `STRING-JOIN: element at index ${i} is not PIC X (received ${typeof items[i]})`
+      );
+    }
+  }
+  return items.join(separator);
+}
+
+/**
+ * STRING-REPLACE — Replaces all occurrences of a search string within the target.
+ *
+ * COBOL equivalent: INSPECT ... REPLACING ALL ...
+ *
+ * @param value - The original string.
+ * @param search - The substring to search for.
+ * @param replacement - The replacement string.
+ * @returns The string with all occurrences replaced.
+ * @throws {Error} If any argument is not a string, or if search is empty.
+ *
+ * @example
+ * STRING_REPLACE("Hello World", "World", "COBOL-X")  // => "Hello COBOL-X"
+ * STRING_REPLACE("aaa", "a", "bb")  // => "bbbbbb"
+ */
+export function STRING_REPLACE(value: string, search: string, replacement: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`STRING-REPLACE: expected PIC X for value, received ${typeof value}`);
+  }
+  if (typeof search !== "string") {
+    throw new Error(`STRING-REPLACE: expected PIC X for search, received ${typeof search}`);
+  }
+  if (typeof replacement !== "string") {
+    throw new Error(`STRING-REPLACE: expected PIC X for replacement, received ${typeof replacement}`);
+  }
+  if (search === "") {
+    throw new Error("STRING-REPLACE: search string must not be empty");
+  }
+  return value.split(search).join(replacement);
+}
+
+/**
+ * STRING-CONTAINS — Checks whether the target string contains the specified substring.
+ *
+ * COBOL equivalent: INSPECT ... TALLYING ... FOR LEADING/ALL ...
+ *
+ * @param value - The string to search within.
+ * @param search - The substring to look for.
+ * @returns 1 (true) if found, 0 (false) otherwise. Returns COBOL-style boolean.
+ * @throws {Error} If any argument is not a string.
+ *
+ * @example
+ * STRING_CONTAINS("Hello World", "World")  // => 1
+ * STRING_CONTAINS("Hello World", "xyz")    // => 0
+ */
+export function STRING_CONTAINS(value: string, search: string): 0 | 1 {
+  if (typeof value !== "string") {
+    throw new Error(`STRING-CONTAINS: expected PIC X for value, received ${typeof value}`);
+  }
+  if (typeof search !== "string") {
+    throw new Error(`STRING-CONTAINS: expected PIC X for search, received ${typeof search}`);
+  }
+  return value.includes(search) ? 1 : 0;
+}
+
+/**
+ * STRING-LENGTH — Returns the length of the given string.
+ *
+ * COBOL equivalent: FUNCTION LENGTH.
+ *
+ * @param value - The string whose length is to be determined.
+ * @returns The number of characters in the string.
+ * @throws {Error} If the input is not a string.
+ *
+ * @example
+ * STRING_LENGTH("HELLO")  // => 5
+ * STRING_LENGTH("")       // => 0
+ */
+export function STRING_LENGTH(value: string): number {
+  if (typeof value !== "string") {
+    throw new Error(`STRING-LENGTH: expected PIC X, received ${typeof value}`);
+  }
+  return value.length;
+}
+
+/**
+ * STRING-SUBSTRING — Extracts a portion of the string.
+ *
+ * COBOL equivalent: reference-modification (e.g., STRING(1:5)).
+ *
+ * @param value - The source string.
+ * @param start - The 1-based starting position.
+ * @param length - The number of characters to extract.
+ * @returns The extracted substring.
+ * @throws {Error} If arguments are invalid or out of range.
+ *
+ * @example
+ * STRING_SUBSTRING("HELLO WORLD", 1, 5)   // => "HELLO"
+ * STRING_SUBSTRING("HELLO WORLD", 7, 5)   // => "WORLD"
+ */
+export function STRING_SUBSTRING(value: string, start: number, length: number): string {
+  if (typeof value !== "string") {
+    throw new Error(`STRING-SUBSTRING: expected PIC X, received ${typeof value}`);
+  }
+  if (!Number.isInteger(start) || start < 1) {
+    throw new Error(`STRING-SUBSTRING: start position must be a positive integer, received ${start}`);
+  }
+  if (!Number.isInteger(length) || length < 0) {
+    throw new Error(`STRING-SUBSTRING: length must be a non-negative integer, received ${length}`);
+  }
+  if (start - 1 >= value.length) {
+    throw new Error(
+      `STRING-SUBSTRING: start position ${start} exceeds string length ${value.length}`
+    );
+  }
+  return value.substring(start - 1, start - 1 + length);
+}
+
+/**
+ * STRING-PAD — Pads a string to a target length.
+ *
+ * COBOL equivalent: MOVE SPACES TO or manual padding with STRING.
+ *
+ * @param value - The source string.
+ * @param targetLength - The desired total length.
+ * @param padChar - The character to pad with (default: space).
+ * @param mode - "RIGHT" (default) or "LEFT".
+ * @returns The padded string.
+ * @throws {Error} If arguments are invalid.
+ *
+ * @example
+ * STRING_PAD("ABC", 10)            // => "ABC       "
+ * STRING_PAD("123", 8, "0", "LEFT") // => "00000123"
+ */
+export function STRING_PAD(
+  value: string,
+  targetLength: number,
+  padChar: string = " ",
+  mode: "RIGHT" | "LEFT" = "RIGHT"
+): string {
+  if (typeof value !== "string") {
+    throw new Error(`STRING-PAD: expected PIC X for value, received ${typeof value}`);
+  }
+  if (typeof padChar !== "string" || padChar.length !== 1) {
+    throw new Error(`STRING-PAD: padChar must be a single character, received '${padChar}'`);
+  }
+  if (!Number.isInteger(targetLength) || targetLength < 0) {
+    throw new Error(`STRING-PAD: targetLength must be a non-negative integer, received ${targetLength}`);
+  }
+  if (value.length >= targetLength) {
+    return value.substring(0, targetLength);
+  }
+  const padding = padChar.repeat(targetLength - value.length);
+  return mode === "LEFT" ? padding + value : value + padding;
+}