@morphql/language-definitions 0.1.3 → 0.1.5

package/dist/index.cjs

@@ -0,0 +1,533 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FUNCTIONS: () => FUNCTIONS,
+  KEYWORDS: () => KEYWORDS,
+  MORPHQL_LANGUAGE: () => MORPHQL_LANGUAGE,
+  OPERATORS: () => OPERATORS,
+  generateHoverDocs: () => generateHoverDocs,
+  generateMonacoLanguageConfig: () => generateMonacoLanguageConfig,
+  generateTextMateFunctionsPattern: () => generateTextMateFunctionsPattern,
+  generateTextMateKeywordsPattern: () => generateTextMateKeywordsPattern,
+  getFunctionDoc: () => getFunctionDoc,
+  getFunctionNames: () => getFunctionNames,
+  getKeywordDoc: () => getKeywordDoc,
+  getKeywordNames: () => getKeywordNames,
+  getKeywordsByCategory: () => getKeywordsByCategory,
+  getMultiCharOperators: () => getMultiCharOperators,
+  getOperatorSymbols: () => getOperatorSymbols,
+  getOperatorsByCategory: () => getOperatorsByCategory,
+  getSingleCharOperators: () => getSingleCharOperators
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/keywords.ts
+var KEYWORDS = [
+  {
+    name: "from",
+    category: "control",
+    doc: {
+      signature: "from <format>",
+      description: "Specifies the input data format.",
+      parameters: [
+        {
+          name: "format",
+          description: "If used as first keyword: The starting format, one of `json`, `xml`, or `object`. When used after a section, defines its source"
+        }
+      ],
+      example: "from json to xml"
+    }
+  },
+  {
+    name: "to",
+    category: "control",
+    doc: {
+      signature: "to <format>",
+      description: "Specifies the output data format.",
+      parameters: [
+        { name: "format", description: "One of: `json`, `xml`, or `object`" }
+      ],
+      example: "from json to xml"
+    }
+  },
+  {
+    name: "transform",
+    category: "control",
+    doc: {
+      signature: "transform",
+      description: "Begins the transformation block containing actions.",
+      example: "transform\n  set name = firstName"
+    }
+  },
+  {
+    name: "set",
+    category: "action",
+    doc: {
+      signature: "set <target> = <expression>",
+      description: "Assigns a value to a field in the output.",
+      parameters: [
+        { name: "target", description: "The field name to set" },
+        {
+          name: "expression",
+          description: "The value or expression to assign"
+        }
+      ],
+      example: 'set fullName = firstName + " " + lastName'
+    }
+  },
+  {
+    name: "section",
+    category: "action",
+    doc: {
+      signature: "section [multiple] <name>( [subquery] <actions> ) [from <path>]",
+      description: "Creates a nested object or array in the output. Can optionally include a subquery for format conversion.",
+      parameters: [
+        { name: "multiple", description: "(Optional) Treat as array mapping" },
+        { name: "name", description: "The section/field name" },
+        {
+          name: "subquery",
+          description: "(Optional) Nested query: from <format> to <format> [transform]"
+        },
+        {
+          name: "actions",
+          description: "Actions to perform within the section"
+        },
+        {
+          name: "from",
+          description: "(Optional) Source path for the section data"
+        }
+      ],
+      example: "section metadata(\n  from xml to object\n  transform\n    set name = root.productName\n) from xmlString"
+    }
+  },
+  {
+    name: "multiple",
+    category: "action",
+    doc: {
+      signature: "section multiple <name>(...)",
+      description: "Modifier for `section` to map over an array.",
+      example: "section multiple items(\n  set id = itemId\n) from products"
+    }
+  },
+  {
+    name: "clone",
+    category: "action",
+    doc: {
+      signature: "clone([field1, field2, ...])",
+      description: "Copies fields from the source to the output.",
+      parameters: [
+        {
+          name: "fields",
+          description: "(Optional) Specific fields to clone. If omitted, clones all fields."
+        }
+      ],
+      example: "clone(id, name, email)"
+    }
+  },
+  {
+    name: "delete",
+    category: "action",
+    doc: {
+      signature: "delete <field>",
+      description: "Removes a field from the output (useful after `clone`).",
+      parameters: [{ name: "field", description: "The field name to delete" }],
+      example: "clone()\ndelete password"
+    }
+  },
+  {
+    name: "define",
+    category: "action",
+    doc: {
+      signature: "define <alias> = <expression>",
+      description: "Creates a local variable/alias for use in subsequent expressions.",
+      parameters: [
+        { name: "alias", description: "The variable name" },
+        { name: "expression", description: "The value to assign" }
+      ],
+      example: "define taxRate = 0.22\nset totalWithTax = total * (1 + taxRate)"
+    }
+  },
+  {
+    name: "if",
+    category: "control",
+    doc: {
+      signature: "if (condition) ( actions ) [else ( actions )]",
+      description: "Conditional execution of action blocks.",
+      parameters: [
+        { name: "condition", description: "Boolean expression" },
+        { name: "actions", description: "Actions to execute if true/false" }
+      ],
+      example: 'if (age >= 18) (\n  set status = "adult"\n) else (\n  set status = "minor"\n)'
+    }
+  },
+  {
+    name: "else",
+    category: "control",
+    doc: {
+      signature: "else ( actions )",
+      description: "Defines the else branch of an `if` statement.",
+      example: "if (condition) (\n  ...\n) else (\n  ...\n)"
+    }
+  },
+  {
+    name: "modify",
+    category: "action",
+    doc: {
+      signature: "modify <target> = <expression>",
+      description: "Modifies a field in the output by reading from the target (not source). Useful for post-processing already-mapped values.",
+      parameters: [
+        { name: "target", description: "The field name to modify" },
+        {
+          name: "expression",
+          description: "The expression to assign (reads from target, not source)"
+        }
+      ],
+      example: "set total = price * quantity\nmodify total = total * 1.10"
+    }
+  }
+];
+var getKeywordsByCategory = (category) => KEYWORDS.filter((k) => k.category === category);
+var getKeywordNames = () => KEYWORDS.map((k) => k.name);
+var getKeywordDoc = (name) => KEYWORDS.find((k) => k.name.toLowerCase() === name.toLowerCase())?.doc;
+
+// src/functions.ts
+var FUNCTIONS = [
+  {
+    name: "substring",
+    doc: {
+      signature: "substring(str, start, [length])",
+      description: "Extracts a portion of a string. Supports negative indices.",
+      parameters: [
+        { name: "str", description: "The source string" },
+        {
+          name: "start",
+          description: "Starting index (0-based, negative counts from end)"
+        },
+        {
+          name: "length",
+          description: "(Optional) Number of characters to extract"
+        }
+      ],
+      returns: "string",
+      example: 'substring("Hello World", 0, 5)  // "Hello"\nsubstring("Hello World", -5)     // "World"'
+    }
+  },
+  {
+    name: "split",
+    doc: {
+      signature: "split(str, [separator], [limit])",
+      description: "Splits a string into an array.",
+      parameters: [
+        { name: "str", description: "The string to split" },
+        {
+          name: "separator",
+          description: '(Optional) Delimiter string. Default: ""'
+        },
+        { name: "limit", description: "(Optional) Maximum number of splits" }
+      ],
+      returns: "array",
+      example: 'split("a,b,c", ",")  // ["a", "b", "c"]'
+    }
+  },
+  {
+    name: "replace",
+    doc: {
+      signature: "replace(str, search, replacement)",
+      description: "Replaces occurrences in a string.",
+      parameters: [
+        { name: "str", description: "The source string" },
+        { name: "search", description: "The substring to find" },
+        { name: "replacement", description: "The replacement string" }
+      ],
+      returns: "string",
+      example: 'replace("Hello World", "World", "MorphQL")  // "Hello MorphQL"'
+    }
+  },
+  {
+    name: "text",
+    doc: {
+      signature: "text(value)",
+      description: "Converts a value to a string.",
+      parameters: [{ name: "value", description: "The value to convert" }],
+      returns: "string",
+      example: 'text(123)  // "123"'
+    }
+  },
+  {
+    name: "number",
+    doc: {
+      signature: "number(value)",
+      description: "Converts a value to a number.",
+      parameters: [{ name: "value", description: "The value to convert" }],
+      returns: "number",
+      example: 'number("42")  // 42'
+    }
+  },
+  {
+    name: "uppercase",
+    doc: {
+      signature: "uppercase(str)",
+      description: "Converts a string to uppercase.",
+      parameters: [{ name: "str", description: "The string to convert" }],
+      returns: "string",
+      example: 'uppercase("hello")  // "HELLO"'
+    }
+  },
+  {
+    name: "lowercase",
+    doc: {
+      signature: "lowercase(str)",
+      description: "Converts a string to lowercase.",
+      parameters: [{ name: "str", description: "The string to convert" }],
+      returns: "string",
+      example: 'lowercase("HELLO")  // "hello"'
+    }
+  },
+  {
+    name: "extractnumber",
+    doc: {
+      signature: "extractnumber(str)",
+      description: "Extracts the first numeric sequence from a string.",
+      parameters: [{ name: "str", description: "The string to extract from" }],
+      returns: "number",
+      example: 'extractnumber("Price: 100USD")  // 100'
+    }
+  },
+  {
+    name: "xmlnode",
+    doc: {
+      signature: "xmlnode(value, [attrKey, attrVal, ...])",
+      description: "Wraps a value for XML output with optional attributes.",
+      parameters: [
+        { name: "value", description: "The node content" },
+        {
+          name: "attrKey, attrVal",
+          description: "(Optional) Pairs of attribute keys and values"
+        }
+      ],
+      returns: "XML node",
+      example: 'xmlnode(content, "id", 1, "type", "text")'
+    }
+  },
+  {
+    name: "to_base64",
+    doc: {
+      signature: "to_base64(value)",
+      description: "Encodes a string value to Base64.",
+      parameters: [{ name: "value", description: "The string to encode" }],
+      returns: "string",
+      example: 'to_base64("hello")  // "aGVsbG8="'
+    }
+  },
+  {
+    name: "from_base64",
+    doc: {
+      signature: "from_base64(value)",
+      description: "Decodes a Base64 string value.",
+      parameters: [
+        { name: "value", description: "The Base64 string to decode" }
+      ],
+      returns: "string",
+      example: 'from_base64("aGVsbG8=")  // "hello"'
+    }
+  },
+  {
+    name: "aslist",
+    doc: {
+      signature: "aslist(value)",
+      description: "Ensures a value is an array. Useful for XML nodes that might be a single object or an array.",
+      parameters: [{ name: "value", description: "The value to normalize" }],
+      returns: "array",
+      example: "aslist(items)  // Always returns an array"
+    }
+  }
+];
+var getFunctionNames = () => FUNCTIONS.map((f) => f.name);
+var getFunctionDoc = (name) => FUNCTIONS.find((f) => f.name.toLowerCase() === name.toLowerCase())?.doc;
+
+// src/operators.ts
+var OPERATORS = [
+  // Comparison operators
+  { symbol: "===", category: "comparison", precedence: 7 },
+  { symbol: "!==", category: "comparison", precedence: 7 },
+  { symbol: "==", category: "comparison", precedence: 7 },
+  { symbol: "!=", category: "comparison", precedence: 7 },
+  { symbol: "<=", category: "comparison", precedence: 6 },
+  { symbol: ">=", category: "comparison", precedence: 6 },
+  { symbol: "<", category: "comparison", precedence: 6 },
+  { symbol: ">", category: "comparison", precedence: 6 },
+  // Logical operators
+  { symbol: "&&", category: "logical", precedence: 5 },
+  { symbol: "||", category: "logical", precedence: 4 },
+  { symbol: "!", category: "logical", precedence: 9 },
+  // Arithmetic operators
+  { symbol: "+", category: "arithmetic", precedence: 10 },
+  { symbol: "-", category: "arithmetic", precedence: 10 },
+  { symbol: "*", category: "arithmetic", precedence: 11 },
+  { symbol: "/", category: "arithmetic", precedence: 11 },
+  // Assignment
+  { symbol: "=", category: "assignment", precedence: 1 }
+];
+var getOperatorsByCategory = (category) => OPERATORS.filter((op) => op.category === category);
+var getOperatorSymbols = () => OPERATORS.map((op) => op.symbol);
+var getMultiCharOperators = () => OPERATORS.filter((op) => op.symbol.length > 1).map((op) => op.symbol);
+var getSingleCharOperators = () => OPERATORS.filter((op) => op.symbol.length === 1).map((op) => op.symbol);
+
+// src/index.ts
+var MORPHQL_LANGUAGE = {
+  keywords: KEYWORDS,
+  functions: FUNCTIONS,
+  operators: OPERATORS,
+  comments: {
+    line: "//",
+    blockStart: "/*",
+    blockEnd: "*/"
+  }
+};
+function generateTextMateKeywordsPattern() {
+  const controlKeywords = getKeywordsByCategory("control").map((k) => k.name);
+  const actionKeywords = getKeywordsByCategory("action").map((k) => k.name);
+  return JSON.stringify(
+    {
+      patterns: [
+        {
+          name: "keyword.control.morphql",
+          match: `\\b(${controlKeywords.join("|")})\\b`
+        },
+        {
+          name: "keyword.other.morphql",
+          match: `\\b(${actionKeywords.join("|")})\\b`
+        }
+      ]
+    },
+    null,
+    2
+  );
+}
+function generateTextMateFunctionsPattern() {
+  const functionNames = getFunctionNames();
+  return JSON.stringify(
+    {
+      patterns: [
+        {
+          name: "entity.name.function.morphql",
+          match: `\\b(${functionNames.join("|")})(?=\\s*\\()`
+        }
+      ]
+    },
+    null,
+    2
+  );
+}
+function generateMonacoLanguageConfig() {
+  return {
+    keywords: getKeywordNames(),
+    builtinFunctions: getFunctionNames(),
+    operators: getOperatorSymbols(),
+    symbols: /[=><!~?:&|+\-*\/\^%]+/,
+    escapes: /\\(?:[abfnrtv\\"']|x[0-9A-Fa-f]{1,4}|u[0-9A-Fa-f]{4}|U[0-9A-Fa-f]{8})/,
+    tokenizer: {
+      root: [
+        // Comments
+        [/\/\/.*$/, "comment"],
+        [/\/\*/, "comment", "@comment"],
+        // Keywords
+        [
+          /[a-zA-Z_$][\w$]*/,
+          {
+            cases: {
+              "@keywords": "keyword",
+              "@builtinFunctions": "predefined",
+              "@default": "identifier"
+            }
+          }
+        ],
+        // Strings
+        [/"([^"\\]|\\.)*$/, "string.invalid"],
+        [/'([^'\\]|\\.)*$/, "string.invalid"],
+        [/"/, "string", "@string_double"],
+        [/'/, "string", "@string_single"],
+        // Numbers
+        [/-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/, "number"],
+        // Operators
+        [/[{}()\[\]]/, "@brackets"],
+        [
+          /@symbols/,
+          {
+            cases: {
+              "@operators": "operator",
+              "@default": ""
+            }
+          }
+        ]
+      ],
+      comment: [
+        [/[^\/*]+/, "comment"],
+        [/\*\//, "comment", "@pop"],
+        [/[\/*]/, "comment"]
+      ],
+      string_double: [
+        [/[^\\"]+/, "string"],
+        [/@escapes/, "string.escape"],
+        [/\\./, "string.escape.invalid"],
+        [/"/, "string", "@pop"]
+      ],
+      string_single: [
+        [/[^\\']+/, "string"],
+        [/@escapes/, "string.escape"],
+        [/\\./, "string.escape.invalid"],
+        [/'/, "string", "@pop"]
+      ]
+    }
+  };
+}
+function generateHoverDocs() {
+  const keywordDocs = {};
+  KEYWORDS.forEach((k) => {
+    keywordDocs[k.name] = k.doc;
+  });
+  const functionDocs = {};
+  FUNCTIONS.forEach((f) => {
+    functionDocs[f.name] = f.doc;
+  });
+  return { keywordDocs, functionDocs };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FUNCTIONS,
+  KEYWORDS,
+  MORPHQL_LANGUAGE,
+  OPERATORS,
+  generateHoverDocs,
+  generateMonacoLanguageConfig,
+  generateTextMateFunctionsPattern,
+  generateTextMateKeywordsPattern,
+  getFunctionDoc,
+  getFunctionNames,
+  getKeywordDoc,
+  getKeywordNames,
+  getKeywordsByCategory,
+  getMultiCharOperators,
+  getOperatorSymbols,
+  getOperatorsByCategory,
+  getSingleCharOperators
+});

package/dist/index.d.cts

@@ -0,0 +1,142 @@
+/**
+ * Documentation entry for a keyword or function
+ */
+interface DocEntry {
+    signature: string;
+    description: string;
+    parameters?: {
+        name: string;
+        description: string;
+    }[];
+    returns?: string;
+    example?: string;
+    category?: "control" | "action" | "function" | "operator";
+}
+/**
+ * Keyword definition
+ */
+interface KeywordDef {
+    name: string;
+    category: "control" | "action";
+    doc: DocEntry;
+}
+/**
+ * Function definition
+ */
+interface FunctionDef {
+    name: string;
+    doc: DocEntry;
+}
+/**
+ * Operator definition
+ */
+interface OperatorDef {
+    symbol: string;
+    category: "arithmetic" | "comparison" | "logical" | "assignment";
+    precedence?: number;
+}
+/**
+ * Complete language definition
+ */
+interface LanguageDefinition {
+    keywords: KeywordDef[];
+    functions: FunctionDef[];
+    operators: OperatorDef[];
+    comments: {
+        line: string;
+        blockStart: string;
+        blockEnd: string;
+    };
+}
+
+/**
+ * MorphQL Keywords - Single source of truth
+ *
+ * When adding a new keyword:
+ * 1. Add it here
+ * 2. Update the lexer in @morphql/core
+ * 3. Run build to regenerate VSCode/Monaco configs
+ */
+declare const KEYWORDS: KeywordDef[];
+declare const getKeywordsByCategory: (category: "control" | "action") => KeywordDef[];
+declare const getKeywordNames: () => string[];
+declare const getKeywordDoc: (name: string) => DocEntry | undefined;
+
+/**
+ * MorphQL Functions - Single source of truth
+ *
+ * When adding a new function:
+ * 1. Add it here
+ * 2. Implement in @morphql/core/src/functions.ts
+ * 3. Run build to regenerate VSCode/Monaco configs
+ */
+declare const FUNCTIONS: FunctionDef[];
+declare const getFunctionNames: () => string[];
+declare const getFunctionDoc: (name: string) => DocEntry | undefined;
+
+/**
+ * MorphQL Operators - Single source of truth
+ *
+ * When adding a new operator:
+ * 1. Add it here
+ * 2. Update the lexer in @morphql/core (MIND THE ORDER!)
+ * 3. Run build to regenerate VSCode/Monaco configs
+ */
+declare const OPERATORS: OperatorDef[];
+declare const getOperatorsByCategory: (category: OperatorDef["category"]) => OperatorDef[];
+declare const getOperatorSymbols: () => string[];
+declare const getMultiCharOperators: () => string[];
+declare const getSingleCharOperators: () => string[];
+
+/**
+ * Complete MorphQL language definition
+ */
+declare const MORPHQL_LANGUAGE: LanguageDefinition;
+
+/**
+ * Generators for different platforms
+ */
+/**
+ * Generate TextMate grammar keywords pattern
+ */
+declare function generateTextMateKeywordsPattern(): string;
+/**
+ * Generate TextMate grammar functions pattern
+ */
+declare function generateTextMateFunctionsPattern(): string;
+/**
+ * Generate Monaco language configuration
+ */
+declare function generateMonacoLanguageConfig(): {
+    keywords: string[];
+    builtinFunctions: string[];
+    operators: string[];
+    symbols: RegExp;
+    escapes: RegExp;
+    tokenizer: {
+        root: ((string | RegExp)[] | (RegExp | {
+            cases: {
+                "@keywords": string;
+                "@builtinFunctions": string;
+                "@default": string;
+            };
+        })[] | (RegExp | {
+            cases: {
+                "@operators": string;
+                "@default": string;
+            };
+        })[])[];
+        comment: (string | RegExp)[][];
+        string_double: (string | RegExp)[][];
+        string_single: (string | RegExp)[][];
+    };
+};
+/**
+ * Generate hover documentation map for VSCode
+ */
+declare function generateHoverDocs(): {
+    keywordDocs: Record<string, DocEntry>;
+    functionDocs: Record<string, DocEntry>;
+};
+
+export { type DocEntry, FUNCTIONS, type FunctionDef, KEYWORDS, type KeywordDef, type LanguageDefinition, MORPHQL_LANGUAGE, OPERATORS, type OperatorDef, generateHoverDocs, generateMonacoLanguageConfig, generateTextMateFunctionsPattern, generateTextMateKeywordsPattern, getFunctionDoc, getFunctionNames, getKeywordDoc, getKeywordNames, getKeywordsByCategory, getMultiCharOperators, getOperatorSymbols, getOperatorsByCategory, getSingleCharOperators };