@elaraai/east 0.0.1-beta.0

package/dist/src/expr/string.js

@@ -0,0 +1,683 @@
+import { get_location } from "../location.js";
+import { ArrayType, BlobType, BooleanType, IntegerType, isDataType, StringType } from "../types.js";
+import { valueOrExprToAstTyped } from "./ast.js";
+import { AstSymbol, Expr, FactorySymbol } from "./expr.js";
+import { validateCrossPlatformCompatible } from "./regex_validation.js";
+/**
+ * Expression representing string values and operations.
+ *
+ * StringExpr provides methods for string manipulation, parsing, searching (including regex),
+ * splitting, formatting, and encoding. Strings are immutable Unicode text values.
+ *
+ * @example
+ * ```ts
+ * // String manipulation
+ * const formatName = East.function([StringType, StringType], StringType, ($, first, last) => {
+ *   const full = first.concat(" ").concat(last);
+ *   $.return(full.upperCase());
+ * });
+ *
+ * // String parsing and validation
+ * const extractNumber = East.function([StringType], StringType, ($, text) => {
+ *   const trimmed = text.trim();
+ *   $.if(trimmed.contains(/^\d+$/), $ => $.return(trimmed));
+ *   $.return("0");
+ * });
+ *
+ * // String splitting and joining
+ * const processCsv = East.function([StringType], ArrayType(StringType), ($, csv) => {
+ *   $.return(csv.split(","));
+ * });
+ * ```
+ */
+export class StringExpr extends Expr {
+    constructor(ast, createExpr) {
+        super(StringType, ast, createExpr);
+    }
+    /**
+     * Parses a value of the given type from the string using East's canonical text format.
+     *
+     * @param type - The East type to parse the string as
+     * @returns An expression of the specified type
+     *
+     * @remarks The string must be formatted as produced by `East.print()`. For example, strings must be
+     *          double-quoted, arrays use `[...]`, structs use `(...)`. This is NOT JSON parsing.
+     *
+     * @throws East runtime error if the string is not a valid representation of the type
+     *
+     * @example
+     * ```ts
+     * const parseInteger = East.function([StringType], IntegerType, ($, text) => {
+     *   $.return(text.parse(IntegerType));
+     * });
+     * const compiled = East.compile(parseInteger.toIR(), []);
+     * compiled("42");       // 42n
+     * compiled("-100");     // -100n
+     * // compiled("3.14") would throw error (not an integer format)
+     * ```
+     */
+    parse(type) {
+        if (!isDataType(type)) {
+            throw new Error(`parse expected a DataType, but got: ${type}`);
+        }
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: type,
+            location: get_location(2),
+            builtin: "Parse",
+            type_parameters: [type],
+            arguments: [this[AstSymbol]],
+        });
+    }
+    /**
+     * Parses a value of the given type from JSON using East's canonical JSON format.
+     *
+     * @param type - The East type to parse the JSON as
+     * @returns An expression of the specified type
+     *
+     * @throws East runtime error if the JSON is invalid or doesn't match the type
+     *
+     * @example
+     * ```ts
+     * const parseJsonArray = East.function([StringType], ArrayType(IntegerType), ($, json) => {
+     *   $.return(json.parseJson(ArrayType(IntegerType)));
+     * });
+     * const compiled = East.compile(parseJsonArray.toIR(), []);
+     * compiled("[1, 2, 3]");        // [1n, 2n, 3n]
+     * compiled("[]");               // []
+     * // compiled("{\"a\": 1}") would throw error (not an array)
+     * ```
+     */
+    parseJson(type) {
+        return Expr.fromAst({
+            ast_type: "Builtin",
+            type: type,
+            builtin: "StringParseJSON",
+            location: { filename: "stdlib", line: 1, column: 1 },
+            type_parameters: [type],
+            arguments: [this[AstSymbol]],
+        });
+    }
+    /**
+     * Concatenates two strings together (str + other).
+     *
+     * @param string - The string to append
+     * @returns A StringExpr representing the concatenated result
+     *
+     * @example
+     * ```ts
+     * const joinStrings = East.function([StringType, StringType], StringType, ($, a, b) => {
+     *   $.return(a.concat(b));
+     * });
+     * const compiled = East.compile(joinStrings.toIR(), []);
+     * compiled("Hello, ", "World!");  // "Hello, World!"
+     * compiled("foo", "bar");         // "foobar"
+     * compiled("", "test");           // "test"
+     * ```
+     */
+    concat(string) {
+        const stringAst = valueOrExprToAstTyped(string, StringType);
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: StringType,
+            location: get_location(2),
+            builtin: "StringConcat",
+            type_parameters: [],
+            arguments: [this[AstSymbol], stringAst],
+        });
+    }
+    /**
+     * Repeats the string a specified number of times.
+     *
+     * @param count - The number of times to repeat the string
+     * @returns A StringExpr representing the repeated string
+     *
+     * @example
+     * ```ts
+     * const repeatString = East.function([StringType, IntegerType], StringType, ($, str, n) => {
+     *   $.return(str.repeat(n));
+     * });
+     * const compiled = East.compile(repeatString.toIR(), []);
+     * compiled("abc", 3n);   // "abcabcabc"
+     * compiled("x", 5n);     // "xxxxx"
+     * compiled("test", 0n);  // ""
+     * compiled("hi", 1n);    // "hi"
+     * ```
+     */
+    repeat(count) {
+        const countAst = valueOrExprToAstTyped(count, IntegerType);
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: StringType,
+            location: get_location(2),
+            builtin: "StringRepeat",
+            type_parameters: [],
+            arguments: [this[AstSymbol], countAst],
+        });
+    }
+    /**
+     * Returns the length of the string in Unicode code points.
+     *
+     * @returns An IntegerExpr representing the string length
+     *
+     * @example
+     * ```ts
+     * const getLength = East.function([StringType], IntegerType, ($, str) => {
+     *   $.return(str.length());
+     * });
+     * const compiled = East.compile(getLength.toIR(), []);
+     * compiled("hello");     // 5n
+     * compiled("");          // 0n
+     * compiled("😀🎉");      // 2n (2 emoji code points)
+     * ```
+     */
+    length() {
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: IntegerType,
+            location: get_location(2),
+            builtin: "StringLength",
+            type_parameters: [],
+            arguments: [this[AstSymbol]],
+        });
+    }
+    /**
+     * Extracts a substring from the string between two indices.
+     *
+     * @param from - The starting index (inclusive)
+     * @param to - The ending index (exclusive)
+     * @returns A StringExpr containing the substring
+     *
+     * @remarks Indices are zero-based. Negative indices not supported.
+     *
+     * @example
+     * ```ts
+     * const substr = East.function([StringType, IntegerType, IntegerType], StringType, ($, str, start, end) => {
+     *   $.return(str.substring(start, end));
+     * });
+     * const compiled = East.compile(substr.toIR(), []);
+     * compiled("hello world", 0n, 5n);    // "hello"
+     * compiled("hello world", 6n, 11n);   // "world"
+     * compiled("test", 1n, 3n);           // "es"
+     * ```
+     */
+    substring(from, to) {
+        const fromAst = valueOrExprToAstTyped(from, IntegerType);
+        const toAst = valueOrExprToAstTyped(to, IntegerType);
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: StringType,
+            location: get_location(2),
+            builtin: "StringSubstring",
+            type_parameters: [],
+            arguments: [this[AstSymbol], fromAst, toAst],
+        });
+    }
+    /**
+     * Converts the string to uppercase.
+     *
+     * @returns A StringExpr with all characters converted to uppercase
+     *
+     * @example
+     * ```ts
+     * const toUpper = East.function([StringType], StringType, ($, str) => {
+     *   $.return(str.upperCase());
+     * });
+     * const compiled = East.compile(toUpper.toIR(), []);
+     * compiled("hello");         // "HELLO"
+     * compiled("Hello World");   // "HELLO WORLD"
+     * compiled("test123");       // "TEST123"
+     * ```
+     */
+    upperCase() {
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: StringType,
+            location: get_location(2),
+            builtin: "StringUpperCase",
+            type_parameters: [],
+            arguments: [this[AstSymbol]],
+        });
+    }
+    /**
+     * Converts the string to lowercase.
+     *
+     * @returns A StringExpr with all characters converted to lowercase
+     *
+     * @example
+     * ```ts
+     * const toLower = East.function([StringType], StringType, ($, str) => {
+     *   $.return(str.lowerCase());
+     * });
+     * const compiled = East.compile(toLower.toIR(), []);
+     * compiled("HELLO");         // "hello"
+     * compiled("Hello World");   // "hello world"
+     * compiled("TEST123");       // "test123"
+     * ```
+     */
+    lowerCase() {
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: StringType,
+            location: get_location(2),
+            builtin: "StringLowerCase",
+            type_parameters: [],
+            arguments: [this[AstSymbol]],
+        });
+    }
+    /**
+     * Splits the string into an array of substrings using a delimiter.
+     *
+     * @param delimiter - The string to split on
+     * @returns An ArrayExpr of StringType containing the split parts
+     *
+     * @example
+     * ```ts
+     * const splitString = East.function([StringType, StringType], ArrayType(StringType), ($, str, delim) => {
+     *   $.return(str.split(delim));
+     * });
+     * const compiled = East.compile(splitString.toIR(), []);
+     * compiled("a,b,c", ",");           // ["a", "b", "c"]
+     * compiled("hello world", " ");     // ["hello", "world"]
+     * compiled("one", ",");             // ["one"]
+     * compiled("a,,b", ",");            // ["a", "", "b"]
+     * ```
+     */
+    split(delimiter) {
+        const delimiterAst = valueOrExprToAstTyped(delimiter, StringType);
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: ArrayType(StringType),
+            location: get_location(2),
+            builtin: "StringSplit",
+            type_parameters: [],
+            arguments: [this[AstSymbol], delimiterAst],
+        });
+    }
+    /**
+     * Removes whitespace from both the beginning and end of the string.
+     *
+     * @returns A StringExpr with whitespace trimmed
+     *
+     * @example
+     * ```ts
+     * const trimString = East.function([StringType], StringType, ($, str) => {
+     *   $.return(str.trim());
+     * });
+     * const compiled = East.compile(trimString.toIR(), []);
+     * compiled("  hello  ");      // "hello"
+     * compiled("test\n");         // "test"
+     * compiled("  ");             // ""
+     * compiled("no-space");       // "no-space"
+     * ```
+     */
+    trim() {
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: StringType,
+            location: get_location(2),
+            builtin: "StringTrim",
+            type_parameters: [],
+            arguments: [this[AstSymbol]],
+        });
+    }
+    /**
+     * Removes whitespace from the beginning of the string.
+     *
+     * @returns A StringExpr with leading whitespace removed
+     *
+     * @example
+     * ```ts
+     * const trimLeft = East.function([StringType], StringType, ($, str) => {
+     *   $.return(str.trimStart());
+     * });
+     * const compiled = East.compile(trimLeft.toIR(), []);
+     * compiled("  hello");        // "hello"
+     * compiled("\ttest");         // "test"
+     * compiled("  hello  ");      // "hello  "
+     * ```
+     */
+    trimStart() {
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: StringType,
+            location: get_location(2),
+            builtin: "StringTrimStart",
+            type_parameters: [],
+            arguments: [this[AstSymbol]],
+        });
+    }
+    /**
+     * Removes whitespace from the end of the string.
+     *
+     * @returns A StringExpr with trailing whitespace removed
+     *
+     * @example
+     * ```ts
+     * const trimRight = East.function([StringType], StringType, ($, str) => {
+     *   $.return(str.trimEnd());
+     * });
+     * const compiled = East.compile(trimRight.toIR(), []);
+     * compiled("hello  ");        // "hello"
+     * compiled("test\n");         // "test"
+     * compiled("  hello  ");      // "  hello"
+     * ```
+     */
+    trimEnd() {
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: StringType,
+            location: get_location(2),
+            builtin: "StringTrimEnd",
+            type_parameters: [],
+            arguments: [this[AstSymbol]],
+        });
+    }
+    /**
+     * Tests if the string starts with a specified prefix.
+     *
+     * @param prefix - The prefix to test for
+     * @returns A BooleanExpr that is true if the string starts with the prefix
+     *
+     * @example
+     * ```ts
+     * const checkPrefix = East.function([StringType, StringType], BooleanType, ($, str, prefix) => {
+     *   $.return(str.startsWith(prefix));
+     * });
+     * const compiled = East.compile(checkPrefix.toIR(), []);
+     * compiled("hello world", "hello");   // true
+     * compiled("test", "te");             // true
+     * compiled("hello", "world");         // false
+     * compiled("", "");                   // true
+     * ```
+     */
+    startsWith(prefix) {
+        const prefixAst = valueOrExprToAstTyped(prefix, StringType);
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: BooleanType,
+            location: get_location(2),
+            builtin: "StringStartsWith",
+            type_parameters: [],
+            arguments: [this[AstSymbol], prefixAst],
+        });
+    }
+    /**
+     * Tests if the string ends with a specified suffix.
+     *
+     * @param suffix - The suffix to test for
+     * @returns A BooleanExpr that is true if the string ends with the suffix
+     *
+     * @example
+     * ```ts
+     * const checkSuffix = East.function([StringType, StringType], BooleanType, ($, str, suffix) => {
+     *   $.return(str.endsWith(suffix));
+     * });
+     * const compiled = East.compile(checkSuffix.toIR(), []);
+     * compiled("hello world", "world");   // true
+     * compiled("test", "st");             // true
+     * compiled("hello", "world");         // false
+     * compiled("", "");                   // true
+     * ```
+     */
+    endsWith(suffix) {
+        const suffixAst = valueOrExprToAstTyped(suffix, StringType);
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: BooleanType,
+            location: get_location(2),
+            builtin: "StringEndsWith",
+            type_parameters: [],
+            arguments: [this[AstSymbol], suffixAst],
+        });
+    }
+    /**
+     * Tests if the string contains a substring or matches a regular expression.
+     *
+     * @param substringOrRegex - The substring or RegExp pattern to search for
+     * @returns A BooleanExpr that is true if the string contains the substring or matches the regex
+     *
+     * @example
+     * ```ts
+     * const hasSubstring = East.function([StringType, StringType], BooleanType, ($, str, substr) => {
+     *   $.return(str.contains(substr));
+     * });
+     * const compiled = East.compile(hasSubstring.toIR(), []);
+     * compiled("hello world", "world");   // true
+     * compiled("test", "xyz");            // false
+     *
+     * // With regex
+     * const hasDigits = East.function([StringType], BooleanType, ($, str) => {
+     *   $.return(str.contains(/\d+/));
+     * });
+     * compiled = East.compile(hasDigits.toIR(), []);
+     * compiled("test123");                // true
+     * compiled("test");                   // false
+     * ```
+     */
+    contains(substringOrRegex) {
+        if (substringOrRegex instanceof RegExp) {
+            const regexObj = substringOrRegex;
+            const validation = validateCrossPlatformCompatible(regexObj);
+            if (!validation.isValid) {
+                console.warn(`RegExp pattern may not be portable across backends: ${regexObj.source}`);
+                for (const error of validation.errors) {
+                    console.warn(`  Error: ${error}`);
+                }
+            }
+            if (validation.warnings.length > 0) {
+                console.warn(`RegExp pattern has portability warnings: ${regexObj.source}`);
+                for (const warning of validation.warnings) {
+                    console.warn(`  Warning: ${warning}`);
+                }
+            }
+            const patternAst = valueOrExprToAstTyped(regexObj.source, StringType);
+            const flagsAst = valueOrExprToAstTyped(regexObj.flags, StringType);
+            return this[FactorySymbol]({
+                ast_type: "Builtin",
+                type: BooleanType,
+                location: get_location(2),
+                builtin: "RegexContains",
+                type_parameters: [],
+                arguments: [this[AstSymbol], patternAst, flagsAst],
+            });
+        }
+        else {
+            const substringAst = valueOrExprToAstTyped(substringOrRegex, StringType);
+            return this[FactorySymbol]({
+                ast_type: "Builtin",
+                type: BooleanType,
+                location: get_location(2),
+                builtin: "StringContains",
+                type_parameters: [],
+                arguments: [this[AstSymbol], substringAst],
+            });
+        }
+    }
+    /**
+     * Finds the index of the first occurrence of a substring or regex match.
+     *
+     * @param substringOrRegex - The substring or RegExp pattern to search for
+     * @returns An IntegerExpr representing the zero-based index, or -1 if not found
+     *
+     * @example
+     * ```ts
+     * const findIndex = East.function([StringType, StringType], IntegerType, ($, str, substr) => {
+     *   $.return(str.indexOf(substr));
+     * });
+     * const compiled = East.compile(findIndex.toIR(), []);
+     * compiled("hello world", "world");   // 6n
+     * compiled("test", "t");              // 0n
+     * compiled("hello", "xyz");           // -1n
+     *
+     * // With regex
+     * const findDigit = East.function([StringType], IntegerType, ($, str) => {
+     *   $.return(str.indexOf(/\d/));
+     * });
+     * compiled = East.compile(findDigit.toIR(), []);
+     * compiled("abc123");                 // 3n
+     * ```
+     */
+    indexOf(substringOrRegex) {
+        if (substringOrRegex instanceof RegExp) {
+            const regexObj = substringOrRegex;
+            const validation = validateCrossPlatformCompatible(regexObj);
+            if (!validation.isValid) {
+                console.warn(`RegExp pattern may not be portable across backends: ${regexObj.source}`);
+                for (const error of validation.errors) {
+                    console.warn(`  Error: ${error}`);
+                }
+            }
+            if (validation.warnings.length > 0) {
+                console.warn(`RegExp pattern has portability warnings: ${regexObj.source}`);
+                for (const warning of validation.warnings) {
+                    console.warn(`  Warning: ${warning}`);
+                }
+            }
+            const patternAst = valueOrExprToAstTyped(regexObj.source, StringType);
+            const flagsAst = valueOrExprToAstTyped(regexObj.flags, StringType);
+            return this[FactorySymbol]({
+                ast_type: "Builtin",
+                type: IntegerType,
+                location: get_location(2),
+                builtin: "RegexIndexOf",
+                type_parameters: [],
+                arguments: [this[AstSymbol], patternAst, flagsAst],
+            });
+        }
+        else {
+            const substringAst = valueOrExprToAstTyped(substringOrRegex, StringType);
+            return this[FactorySymbol]({
+                ast_type: "Builtin",
+                type: IntegerType,
+                location: get_location(2),
+                builtin: "StringIndexOf",
+                type_parameters: [],
+                arguments: [this[AstSymbol], substringAst],
+            });
+        }
+    }
+    /**
+     * Replaces all occurrences of a substring or regex pattern with a replacement string.
+     *
+     * @param searchValue - The substring or RegExp pattern to search for
+     * @param replaceValue - The replacement string (can include regex capture groups like $1, $2)
+     * @returns A StringExpr with all occurrences replaced
+     *
+     * @example
+     * ```ts
+     * const replaceAll = East.function([StringType, StringType, StringType], StringType, ($, str, search, replace) => {
+     *   $.return(str.replace(search, replace));
+     * });
+     * const compiled = East.compile(replaceAll.toIR(), []);
+     * compiled("hello hello", "hello", "hi");         // "hi hi"
+     * compiled("test_test_value", "test", "prod");    // "prod_prod_value"
+     *
+     * // With regex and capture groups
+     * const swapWords = East.function([StringType], StringType, ($, str) => {
+     *   $.return(str.replace(/(\w+) (\w+)/, "$2 $1"));
+     * });
+     * compiled = East.compile(swapWords.toIR(), []);
+     * compiled("hello world");                        // "world hello"
+     * ```
+     */
+    replace(searchValue, replaceValue) {
+        if (searchValue instanceof RegExp) {
+            const regexObj = searchValue;
+            // Strip 'g' flag before validation since we handle replaceAll semantics in the backend
+            const flagsWithoutG = regexObj.flags.replace(/g/g, '');
+            const regexForValidation = new RegExp(regexObj.source, flagsWithoutG);
+            const validation = validateCrossPlatformCompatible(regexForValidation);
+            if (!validation.isValid) {
+                console.warn(`RegExp pattern may not be portable across backends: ${regexObj.source}`);
+                for (const error of validation.errors) {
+                    console.warn(`  Error: ${error}`);
+                }
+            }
+            if (validation.warnings.length > 0) {
+                console.warn(`RegExp pattern has portability warnings: ${regexObj.source}`);
+                for (const warning of validation.warnings) {
+                    console.warn(`  Warning: ${warning}`);
+                }
+            }
+            const patternAst = valueOrExprToAstTyped(regexObj.source, StringType);
+            const flagsAst = valueOrExprToAstTyped(regexObj.flags, StringType);
+            const replaceAst = valueOrExprToAstTyped(replaceValue, StringType);
+            return this[FactorySymbol]({
+                ast_type: "Builtin",
+                type: StringType,
+                location: get_location(2),
+                builtin: "RegexReplace",
+                type_parameters: [],
+                arguments: [this[AstSymbol], patternAst, flagsAst, replaceAst],
+            });
+        }
+        else {
+            const searchAst = valueOrExprToAstTyped(searchValue, StringType);
+            const replaceAst = valueOrExprToAstTyped(replaceValue, StringType);
+            return this[FactorySymbol]({
+                ast_type: "Builtin",
+                type: StringType,
+                location: get_location(2),
+                builtin: "StringReplace",
+                type_parameters: [],
+                arguments: [this[AstSymbol], searchAst, replaceAst],
+            });
+        }
+    }
+    /**
+     * Encodes the string as UTF-8 bytes, returning a Blob.
+     *
+     * @returns A BlobExpr containing the UTF-8 encoded bytes
+     *
+     * @remarks No byte-order mark (BOM) is added. UTF-8 is a superset of ASCII.
+     *
+     * @example
+     * ```ts
+     * const encodeUtf8 = East.function([StringType], BlobType, ($, str) => {
+     *   $.return(str.encodeUtf8());
+     * });
+     * const compiled = East.compile(encodeUtf8.toIR(), []);
+     * compiled("hello");          // Blob with UTF-8 bytes
+     * compiled("😀");             // Blob with UTF-8 encoded emoji
+     * ```
+     */
+    encodeUtf8() {
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: BlobType,
+            location: get_location(2),
+            builtin: "StringEncodeUtf8",
+            type_parameters: [],
+            arguments: [this[AstSymbol]],
+        });
+    }
+    /**
+     * Encodes the string as UTF-16 bytes, returning a Blob.
+     *
+     * @returns A BlobExpr containing the UTF-16 encoded bytes
+     *
+     * @remarks Always uses little-endian with a byte-order mark (BOM). UTF-16 is common on Windows.
+     *
+     * @example
+     * ```ts
+     * const encodeUtf16 = East.function([StringType], BlobType, ($, str) => {
+     *   $.return(str.encodeUtf16());
+     * });
+     * const compiled = East.compile(encodeUtf16.toIR(), []);
+     * compiled("hello");          // Blob with UTF-16 LE bytes + BOM
+     * compiled("😀");             // Blob with UTF-16 encoded emoji
+     * ```
+     */
+    encodeUtf16() {
+        return this[FactorySymbol]({
+            ast_type: "Builtin",
+            type: BlobType,
+            location: get_location(2),
+            builtin: "StringEncodeUtf16",
+            type_parameters: [],
+            arguments: [this[AstSymbol]],
+        });
+    }
+}
+//# sourceMappingURL=string.js.map