@xano/xanoscript-language-server 11.0.5 → 11.1.0

package/CLAUDE.md

@@ -30,12 +30,14 @@ This is a Language Server Protocol (LSP) implementation for XanoScript, built on
 ### Core Components
 
 **Lexer (`lexer/`)**: Token definitions and lexical analysis
+
 - `tokens.js` - Main token registry
 - `lexer.js` - Chevrotain lexer implementation
 - Domain tokens: `api.js`, `db.js`, `cloud.js`, `function.js`, etc.
 - `utils.js` - Token creation utilities (`createToken`, `createTokenByName`)
 
 **Parser (`parser/`)**: Grammar rules and parsing logic
+
 - `base_parser.js` - Core XanoBaseParser extending Chevrotain
 - Main parsers: `query_parser.js`, `function_parser.js`, `task_parser.js`, `api_group_parser.js`, `table_parser.js`, `workflow_test_parser.js`, `table_trigger_parser.js`
 - `attributes/` - Field attributes (description, disabled, sensitive)
@@ -45,6 +47,7 @@ This is a Language Server Protocol (LSP) implementation for XanoScript, built on
 - `generic/` - Reusable parsing components
 
 **Language Server (`server.js` + feature directories)**:
+
 - `onCompletion/` - Auto-completion logic
 - `onDidChangeContent/` - Live diagnostics and error reporting
 - `onHover/` - Documentation and hover information
@@ -53,6 +56,7 @@ This is a Language Server Protocol (LSP) implementation for XanoScript, built on
 ### XanoScript Object Types
 
 Primary constructs parsed by dedicated parsers:
+
 - **query** - API endpoints with HTTP verbs, input validation, processing logic, responses
 - **function** - Reusable logic blocks with testing capabilities
 - **task** - Scheduled operations with cron-like triggers
@@ -63,18 +67,147 @@ Primary constructs parsed by dedicated parsers:
 
 ## Adding New Features
 
-### New Object Type
-1. Create a new parser in `parser/` (e.g., `my_object_parser.js`)
-2. Follow existing parser patterns (see `query_parser.js`, `function_parser.js`)
-3. Register it in `server.js`
+### New Top-Level Parser (e.g., `run.job`, `run.service`)
+
+Follow this step-by-step process:
+
+**1. Create lexer tokens (`lexer/my_feature.js`)**
+
+```javascript
+import { Identifier } from "./identifier.js";
+import { createTokenByName } from "./utils.js";
+
+export const MyToken = createTokenByName("my_keyword", {
+  longer_alt: Identifier,
+  categories: [Identifier],
+});
+
+export const MyFeatureTokens = [MyToken];
+
+export function mapTokenToType(token) {
+  switch (token) {
+    case MyToken.name:
+      return "keyword";
+    default:
+      return null;
+  }
+}
+```
+
+**2. Register tokens in `lexer/tokens.js`**
+
+- Import tokens and mapper at the top
+- Add `...MyFeatureTokens` to `allTokens` array
+- Add `mapMyFeatureTokenToType` to `tokenMappers` array
+
+**3. Create parser (`parser/my_feature_parser.js`)**
+
+```javascript
+import { StringLiteral } from "../lexer/literal.js";
+import { MyToken } from "../lexer/my_feature.js";
+import { Identifier, NewlineToken } from "../lexer/tokens.js";
+
+export function myFeatureDeclaration($) {
+  return () => {
+    $.sectionStack.push("myFeatureDeclaration");
+    $.SUBRULE($.optionalCommentBlockFn);
+
+    const parent = $.CONSUME(MyToken);
+    $.OR([
+      { ALT: () => $.CONSUME(StringLiteral) },
+      { ALT: () => $.CONSUME(Identifier) },
+    ]);
+
+    // Use schemaParseAttributeFn for body with declarative schema
+    $.SUBRULE($.schemaParseAttributeFn, {
+      ARGS: [
+        parent,
+        {
+          required_attr: "[string]",
+          "optional_attr?": "[boolean]",
+          "nested?": {
+            name: "[string]",
+            "value?": { "[string]": "[constant]" },
+          },
+          "array_of_strings?": ["[string]"],
+        },
+      ],
+    });
+
+    $.MANY2(() => $.CONSUME2(NewlineToken));
+    $.sectionStack.pop();
+  };
+}
+```
+
+**4. Register parser in `parser/register.js`**
+
+```javascript
+import { myFeatureDeclaration } from "./my_feature_parser.js";
+// In register function:
+$.myFeatureDeclaration = $.RULE(
+  "myFeatureDeclaration",
+  myFeatureDeclaration($)
+);
+```
+
+**5. Add scheme detection in `utils.js`**
+
+```javascript
+const schemeByFirstWord = {
+  // ... existing entries
+  my_feature: "my_feature",
+};
+```
+
+**6. Route scheme in `parser/parser.js`**
+
+```javascript
+case "my_feature":
+  parser.myFeatureDeclaration();
+  return parser;
+```
+
+**7. Write tests (`parser/my_feature_parser.spec.js`)**
+
+```javascript
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { xanoscriptParser } from "./parser.js";
+
+describe("my_feature", () => {
+  it("should parse a basic my_feature", () => {
+    const parser = xanoscriptParser(`my_feature "name" {
+      required_attr = "value"
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+});
+```
+
+### Schema Definition Types (for `schemaParseAttributeFn`)
+
+| Schema                         | Description                        | Example                   |
+| ------------------------------ | ---------------------------------- | ------------------------- |
+| `"[string]"`                   | String literal                     | `"hello"`                 |
+| `"[number]"`                   | Number literal                     | `123`                     |
+| `"[boolean]"`                  | Boolean value                      | `true` / `false`          |
+| `"[constant]"`                 | Value expression (no variables)    | `"text"`, `123`, `{a: 1}` |
+| `"[expression]"`               | Any expression including variables | `$var`, `$input.name`     |
+| `["[string]"]`                 | Array of strings                   | `["a", "b"]`              |
+| `{ "[string]": "[constant]" }` | Object with string keys            | `{key: "value"}`          |
+| `"attr?"`                      | Optional attribute                 | May be omitted            |
+| `"!attr"`                      | Can be disabled                    | `!attr = value`           |
 
 ### New Keyword/Function
+
 1. Add token definition in appropriate `lexer/` file
 2. Create function implementation in `parser/functions/[domain]/`
 3. Register in parent clause or parser
 4. Add comprehensive tests in corresponding `.spec.js` file
 
 ### Token Creation Pattern
+
 ```javascript
 export const MyToken = createTokenByName("keyword", {
   longer_alt: Identifier,
@@ -83,6 +216,7 @@ export const MyToken = createTokenByName("keyword", {
 ```
 
 ### Parser Rule Pattern
+
 ```javascript
 myRule = this.RULE("myRule", () => {
   this.CONSUME(MyToken);
@@ -100,6 +234,7 @@ myRule = this.RULE("myRule", () => {
 - CI requires all tests to pass
 
 ### Test Pattern
+
 ```javascript
 function parse(inputText) {
   const lexResult = lexDocument(inputText);
@@ -118,4 +253,4 @@ function parse(inputText) {
 - Follow existing code conventions when adding features
 - Check neighboring files for patterns and conventions
 - Never assume a library is available - check `package.json` first
-- 3 low-severity npm audit warnings are known and acceptable
+- 3 low-severity npm audit warnings are known and acceptable

package/cache/documentCache.js

@@ -0,0 +1,91 @@
+import { lexDocument } from "../lexer/lexer.js";
+import { xanoscriptParser } from "../parser/parser.js";
+import { getSchemeFromContent } from "../utils.js";
+
+/**
+ * Cache for parsed documents to avoid redundant parsing.
+ * Stores parse results keyed by document URI + version.
+ * Note: We cache a snapshot of parser state, not the parser instance itself,
+ * since the parser is a singleton that gets mutated on each parse.
+ */
+class DocumentCache {
+  constructor() {
+    // Map<uri, { version: number, lexResult: Object, parserState: Object, scheme: string }>
+    this.cache = new Map();
+  }
+
+  /**
+   * Get cached parse result or parse and cache if not available.
+   * @param {string} uri - Document URI
+   * @param {number} version - Document version
+   * @param {string} text - Document text
+   * @returns {{ lexResult: Object, parser: Object, scheme: string }}
+   */
+  getOrParse(uri, version, text) {
+    const cached = this.cache.get(uri);
+    const textLength = text.length;
+
+    // Check version and text length to detect same URI with different content (e.g., in tests)
+    if (
+      cached &&
+      cached.version === version &&
+      cached.textLength === textLength
+    ) {
+      // Return cached result with a proxy parser object containing cached state
+      return {
+        lexResult: cached.lexResult,
+        parser: cached.parserState,
+        scheme: cached.scheme,
+      };
+    }
+
+    // Parse and cache a snapshot of the parser state
+    const scheme = getSchemeFromContent(text);
+    const lexResult = lexDocument(text);
+    const parser = xanoscriptParser(text, scheme, lexResult);
+
+    // Create a snapshot of the parser's state including symbol table
+    const parserState = {
+      errors: [...parser.errors],
+      warnings: [...parser.warnings],
+      informations: [...parser.informations],
+      hints: [...parser.hints],
+      __symbolTable: parser.__symbolTable
+        ? JSON.parse(JSON.stringify(parser.__symbolTable))
+        : null,
+    };
+
+    const cacheEntry = {
+      version,
+      textLength,
+      lexResult,
+      parserState,
+      scheme,
+    };
+
+    this.cache.set(uri, cacheEntry);
+
+    return {
+      lexResult,
+      parser: parserState,
+      scheme,
+    };
+  }
+
+  /**
+   * Invalidate cache for a document.
+   * @param {string} uri - Document URI
+   */
+  invalidate(uri) {
+    this.cache.delete(uri);
+  }
+
+  /**
+   * Clear all cached documents.
+   */
+  clear() {
+    this.cache.clear();
+  }
+}
+
+export const documentCache = new DocumentCache();

package/debug.js

@@ -0,0 +1,18 @@
+/* global process */
+/**
+ * Debug logging utility.
+ * Set XS_DEBUG=1 environment variable to enable debug logging.
+ */
+const isDebug = process.env.XS_DEBUG === "1";
+
+export function debugLog(...args) {
+  if (isDebug) {
+    console.log(...args);
+  }
+}
+
+export function debugError(...args) {
+  if (isDebug) {
+    console.error(...args);
+  }
+}

package/lexer/run.js

@@ -0,0 +1,37 @@
+import { Identifier } from "./identifier.js";
+import { createTokenByName } from "./utils.js";
+
+// "run"
+export const RunToken = createTokenByName("run", {
+  longer_alt: Identifier,
+  categories: [Identifier],
+});
+
+// "job"
+export const JobToken = createTokenByName("job", {
+  longer_alt: Identifier,
+  categories: [Identifier],
+});
+
+// "service"
+export const ServiceToken = createTokenByName("service", {
+  longer_alt: Identifier,
+  categories: [Identifier],
+});
+
+export const RunTokens = [RunToken, JobToken, ServiceToken];
+
+/**
+ * Maps a token name to a type
+ * @param {string} token the token name
+ */
+export function mapTokenToType(token) {
+  switch (token) {
+    case RunToken.name:
+    case JobToken.name:
+    case ServiceToken.name:
+      return "keyword";
+    default:
+      return null;
+  }
+}

package/lexer/tokens.js

@@ -93,6 +93,7 @@ import {
   RealtimeTriggerTokens,
 } from "./realtime_trigger.js";
 import { mapTokenToType as mapRedisTokenToType, RedisTokens } from "./redis.js";
+import { mapTokenToType as mapRunTokenToType, RunTokens } from "./run.js";
 import {
   mapTokenToType as mapSecurityTokenToType,
   SecurityTokens,
@@ -382,6 +383,7 @@ export const allTokens = uniq([
   ...DbTokens,
   ...RedisTokens,
   ...TextTokens,
+  ...RunTokens,
   ...ObjectTokens,
   ...StreamTokens,
   ...DebugTokens,
@@ -430,6 +432,7 @@ const tokenMappers = [
   mapQueryTokenToType,
   mapRealtimeTriggerTokenToType,
   mapRedisTokenToType,
+  mapRunTokenToType,
   mapSecurityTokenToType,
   mapStorageTokenToType,
   mapStreamTokenToType,
@@ -447,80 +450,91 @@ const tokenMappers = [
   mapZipTokenToType,
 ];
 
-/**
- * Map a token to a type (e.g., keyword, variable, etc.)
- * @param {import('chevrotain').TokenType} token
- * @returns string | null | undefined The type of the token
- */
-export function mapTokenToType(token) {
-  // Check if the token is a keyword
-  for (const mapper of tokenMappers) {
-    const type = mapper(token);
-    if (type) {
-      return type;
-    }
-  }
-
-  switch (token) {
-    // Structural and control keywords (e.g., query blocks, conditionals)
-    case Cachetoken.name:
-    case HistoryToken.name:
-    case IndexToken.name:
-    case InputToken.name:
-    case MiddlewareToken.name:
-    case MockToken.name:
-    case ResponseToken.name:
-    case ViewToken.name:
-    case SchemaToken.name:
-    case SecurityToken.name:
-    case StackToken.name:
-    case TestToken.name:
-    case FiltersToken.name:
-      return "keyword";
-
-    case DbLinkToken.name:
-      return "function";
+// Pre-built token type map for O(1) lookups
+const tokenTypeMap = new Map();
+
+// Build the map at module initialization time
+function buildTokenTypeMap() {
+  // Add local token mappings first
+  const localMappings = {
+    // Structural and control keywords
+    [Cachetoken.name]: "keyword",
+    [HistoryToken.name]: "keyword",
+    [IndexToken.name]: "keyword",
+    [InputToken.name]: "keyword",
+    [MiddlewareToken.name]: "keyword",
+    [MockToken.name]: "keyword",
+    [ResponseToken.name]: "keyword",
+    [ViewToken.name]: "keyword",
+    [SchemaToken.name]: "keyword",
+    [SecurityToken.name]: "keyword",
+    [StackToken.name]: "keyword",
+    [TestToken.name]: "keyword",
+    [FiltersToken.name]: "keyword",
+
+    [DbLinkToken.name]: "function",
 
     // Variable-related tokens
-    case AuthToken.name:
-    case DbIdentifier.name:
-    case DbReturnAggregateToken.name:
-    case DescriptionToken.name:
-    case DisabledToken.name:
-    case DocsToken.name:
-    case FieldToken.name: // field is also used as variable name in index definitio.namen
-    case GuidToken.name:
-    case SensitiveToken.name:
-    case TagsToken.name:
-    case TypeToken.name: // type is used as a variable name in index definitio.namen
-    case ValueToken.name:
-    case ValuesToken.name:
-      return "variable";
-
-    case Identifier.name:
-      return "property";
-
-    case FalseToken.name:
-    case NowToken.name:
-    case NullToken.name:
-    case TrueToken.name:
-      return "enumMember";
-
-    case DotToken.name:
-      return "punctuation";
-
-    case RegExpToken.name:
-      return "regexp";
-
-    case JsonInToken.name:
-      return "operator";
+    [AuthToken.name]: "variable",
+    [DbIdentifier.name]: "variable",
+    [DbReturnAggregateToken.name]: "variable",
+    [DescriptionToken.name]: "variable",
+    [DisabledToken.name]: "variable",
+    [DocsToken.name]: "variable",
+    [FieldToken.name]: "variable",
+    [GuidToken.name]: "variable",
+    [SensitiveToken.name]: "variable",
+    [TagsToken.name]: "variable",
+    [TypeToken.name]: "variable",
+    [ValueToken.name]: "variable",
+    [ValuesToken.name]: "variable",
+
+    [Identifier.name]: "property",
+
+    [FalseToken.name]: "enumMember",
+    [NowToken.name]: "enumMember",
+    [NullToken.name]: "enumMember",
+    [TrueToken.name]: "enumMember",
+
+    [DotToken.name]: "punctuation",
+    [RegExpToken.name]: "regexp",
+    [JsonInToken.name]: "operator",
 
     // Skip whitespace and newlines
-    case NewlineToken.name:
-    case WhiteSpace.name:
-      return null;
+    [NewlineToken.name]: null,
+    [WhiteSpace.name]: null,
+  };
+
+  for (const [tokenName, type] of Object.entries(localMappings)) {
+    tokenTypeMap.set(tokenName, type);
+  }
+
+  // Iterate through all tokens and populate the map using the mappers
+  for (const token of allTokens) {
+    if (tokenTypeMap.has(token.name)) continue;
 
-    default:
-      return undefined; // Skip unmapped or unknown tokens
+    for (const mapper of tokenMappers) {
+      const type = mapper(token.name);
+      if (type) {
+        tokenTypeMap.set(token.name, type);
+        break;
+      }
+    }
+  }
+}
+
+// Initialize the map at module load
+buildTokenTypeMap();
+
+/**
+ * Map a token to a type (e.g., keyword, variable, etc.)
+ * Uses pre-built map for O(1) lookup instead of O(n) iteration.
+ * @param {string} token - Token name
+ * @returns {string | null | undefined} The type of the token
+ */
+export function mapTokenToType(token) {
+  if (tokenTypeMap.has(token)) {
+    return tokenTypeMap.get(token);
   }
+  return undefined; // Skip unmapped or unknown tokens
 }

package/onCompletion/contentAssist.js

@@ -109,22 +109,23 @@ function isAfterPipeToken(tokens) {
   return lastToken.tokenType === PipeToken;
 }
 
-function createFilterSuggestions() {
-  return filterNames.map((filterName) => {
+// Pre-computed filter suggestions - frozen to prevent accidental mutations
+const filterSuggestions = Object.freeze(
+  filterNames.map((filterName) => {
     const documentation = filterMessageProvider.__filterDoc[filterName];
 
-    return {
+    return Object.freeze({
       label: filterName,
       kind: encodeTokenType("function"), // Filters are function-like
       documentation: documentation
-        ? {
+        ? Object.freeze({
             kind: "markdown",
             value: documentation,
-          }
+          })
         : undefined,
-    };
-  });
-}
+    });
+  })
+);
 
 export function getContentAssistSuggestions(text, scheme) {
   try {
@@ -134,7 +135,7 @@ export function getContentAssistSuggestions(text, scheme) {
 
     // Check if we're after a pipe token - if so, suggest filters
     if (isAfterPipeToken(partialTokenVector)) {
-      return createFilterSuggestions();
+      return filterSuggestions;
     }
 
     let syntacticSuggestions;

package/onDidChangeContent/onDidChangeContent.js

@@ -1,5 +1,55 @@
-import { xanoscriptParser } from "../parser/parser";
-import { getSchemeFromContent } from "../utils";
+import { documentCache } from "../cache/documentCache.js";
+import { debugError, debugLog } from "../debug.js";
+
+// Diagnostic severity constants
+const SEVERITY = {
+  ERROR: 1,
+  WARNING: 2,
+  INFORMATION: 3,
+  HINT: 4,
+};
+
+/**
+ * Creates diagnostics from parser results in a single pass.
+ * @param {Object} parser - The parser with errors, warnings, informations, hints
+ * @param {Object} document - The text document for position conversion
+ * @returns {Array} Array of diagnostic objects
+ */
+function createDiagnostics(parser, document) {
+  const diagnostics = [];
+  const defaultRange = {
+    start: { line: 0, character: 0 },
+    end: { line: 0, character: 1 },
+  };
+
+  const addDiagnostic = (item, severity) => {
+    diagnostics.push({
+      severity,
+      range: item.token
+        ? {
+            start: document.positionAt(item.token.startOffset),
+            end: document.positionAt(item.token.endOffset + 1),
+          }
+        : defaultRange,
+      message: item.message,
+    });
+  };
+
+  for (const error of parser.errors) {
+    addDiagnostic(error, SEVERITY.ERROR);
+  }
+  for (const warning of parser.warnings) {
+    addDiagnostic(warning, SEVERITY.WARNING);
+  }
+  for (const info of parser.informations) {
+    addDiagnostic(info, SEVERITY.INFORMATION);
+  }
+  for (const hint of parser.hints) {
+    addDiagnostic(hint, SEVERITY.HINT);
+  }
+
+  return diagnostics;
+}
 
 /**
  *
@@ -11,7 +61,7 @@ export function onDidChangeContent(params, connection) {
   const document = params.document;
 
   if (!document) {
-    console.error(
+    debugError(
       "onDidChangeContent(): Document not found for URI:",
       params.textDocument.uri
     );
@@ -20,96 +70,36 @@ export function onDidChangeContent(params, connection) {
 
   const text = document.getText();
 
-  const scheme = getSchemeFromContent(text);
-
   try {
-    // Parse the XanoScript file
-    const parser = xanoscriptParser(text, scheme);
+    // Parse the XanoScript file using cache
+    const { parser, scheme } = documentCache.getOrParse(
+      document.uri,
+      document.version,
+      text
+    );
 
-    if (parser.errors.length > 0) {
-      // If parsing succeeds, send an empty diagnostics array (no errors)
+    if (parser.errors.length === 0) {
+      // If parsing succeeds with no errors, send an empty diagnostics array
       connection.sendDiagnostics({ uri: document.uri, diagnostics: [] });
     }
 
     for (const error of parser.errors) {
-      console.error(
+      debugError(
         `onDidChangeContent(): Error parsing document: ${error.name}`
       );
     }
 
-    // If parsing fails, create a diagnostic (error message) to display in VS Code
-    const errors = parser.errors.map((error) => {
-      return {
-        severity: 1,
-        range: error.token
-          ? {
-              start: document.positionAt(error.token.startOffset),
-              end: document.positionAt(error.token.endOffset + 1),
-            }
-          : {
-              start: { line: 0, character: 0 },
-              end: { line: 0, character: 1 },
-            },
-        message: error.message,
-      };
-    });
-
-    const warnings = parser.warnings.map((warning) => {
-      return {
-        severity: 2,
-        range: warning.token
-          ? {
-              start: document.positionAt(warning.token.startOffset),
-              end: document.positionAt(warning.token.endOffset + 1),
-            }
-          : {
-              start: { line: 0, character: 0 },
-              end: { line: 0, character: 1 },
-            },
-        message: warning.message,
-      };
-    });
-
-    const informations = parser.informations.map((info) => {
-      return {
-        severity: 3,
-        range: info.token
-          ? {
-              start: document.positionAt(info.token.startOffset),
-              end: document.positionAt(info.token.endOffset + 1),
-            }
-          : {
-              start: { line: 0, character: 0 },
-              end: { line: 0, character: 1 },
-            },
-        message: info.message,
-      };
-    });
-
-    const hints = parser.hints.map((hint) => {
-      return {
-        severity: 4,
-        range: hint.token
-          ? {
-              start: document.positionAt(hint.token.startOffset),
-              end: document.positionAt(hint.token.endOffset + 1),
-            }
-          : {
-              start: { line: 0, character: 0 },
-              end: { line: 0, character: 1 },
-            },
-        message: hint.message,
-      };
-    });
+    // Create diagnostics in a single pass
+    const diagnostics = createDiagnostics(parser, document);
 
-    console.log(
+    debugLog(
       `onDidChangeContent(): sending diagnostic (${parser.errors.length} errors) for scheme:`,
       scheme
     );
 
     connection.sendDiagnostics({
       uri: document.uri,
-      diagnostics: [...errors, ...warnings, ...informations, ...hints],
+      diagnostics,
     });
   } catch (error) {
     // If parsing fails, create a diagnostic (error message) to display in VS Code

package/onHover/functions.md

@@ -287,6 +287,62 @@ A `task` file defines a scheduled job that runs automatically at specified times
 
 Tasks are ideal for automating recurring operations like generating reports or syncing data.
 
+# run.job
+
+```xs
+run.job "Gemini -> Image Understanding" {
+  main = {
+    name: "Gemini -> Image Understanding"
+    input: {
+      model: "gemini-1.5-flash"
+      prompt: "Describe what is happening in this image."
+      image: "(attach image file)"
+    }
+  }
+  env = ["gemini_api_key"]
+}
+```
+
+A `run.job` file defines a job configuration for execution in the Xano Job Runner. It includes:
+
+- A name (e.g., `"Gemini -> Image Understanding"`) to identify the job,
+- A required `main` attribute specifying the function to execute:
+  - `name`: The name of the function to call,
+  - `input`: Optional input parameters to pass to the function,
+- An optional `env` array listing environment variable names required by the job.
+
+Jobs are used to run functions as standalone processes, typically for long-running or resource-intensive operations.
+
+# run.service
+
+```xs
+run.service "email proxy" {
+  pre = {
+    name: "email_proxy_init"
+    input: {
+      config: "default"
+    }
+  }
+  env = ["email_proxy_api_key"]
+}
+```
+
+A `run.service` file defines a service configuration for the Xano Job Runner. It includes:
+
+- A name (e.g., `"email proxy"`) to identify the service,
+- An optional `pre` attribute specifying an initialization function to run before the service starts:
+  - `name`: The name of the initialization function,
+  - `input`: Optional input parameters for the initialization,
+- An optional `env` array listing environment variable names required by the service.
+
+Services can also be defined in minimal form without a body:
+
+```xs
+run.service "email proxy"
+```
+
+Services are ideal for long-running background processes like proxies, webhooks listeners, or daemon-style operations.
+
 # action.call
 
 ```xs

package/onHover/onHoverDocument.js

@@ -1,6 +1,32 @@
-import { lexDocument } from "../lexer/lexer.js";
-import { xanoscriptParser } from "../parser/parser.js";
-import { getSchemeFromContent } from "../utils.js";
+import { documentCache } from "../cache/documentCache.js";
+import { debugError } from "../debug.js";
+
+/**
+ * Binary search to find token index at the given offset.
+ * Reduces complexity from O(n) to O(log n).
+ * @param {Array} tokens - Array of tokens sorted by startOffset
+ * @param {number} offset - Cursor offset position
+ * @returns {number} Token index or -1 if not found
+ */
+function findTokenAtOffset(tokens, offset) {
+  let left = 0;
+  let right = tokens.length - 1;
+
+  while (left <= right) {
+    const mid = Math.floor((left + right) / 2);
+    const token = tokens[mid];
+
+    if (token.startOffset <= offset && token.endOffset >= offset) {
+      return mid;
+    } else if (token.endOffset < offset) {
+      left = mid + 1;
+    } else {
+      right = mid - 1;
+    }
+  }
+
+  return -1;
+}
 
 /**
  *
@@ -12,7 +38,7 @@ export function onHoverDocument(params, documents, hoverProviders = []) {
   const document = documents.get(params.textDocument.uri);
 
   if (!document) {
-    console.error(
+    debugError(
       "onHover(): Document not found for URI:",
       params.textDocument.uri
     );
@@ -22,21 +48,19 @@ export function onHoverDocument(params, documents, hoverProviders = []) {
   const text = document.getText();
   const offset = document.offsetAt(params.position);
 
-  // Tokenize the document
-  const lexResult = lexDocument(text);
-  if (lexResult.errors.length > 0) return null;
+  // Get cached parse result or parse and cache
+  const { lexResult, parser } = documentCache.getOrParse(
+    params.textDocument.uri,
+    document.version,
+    text
+  );
 
-  // attempt to get the scheme from the document uri
-  const scheme = getSchemeFromContent(text);
+  if (lexResult.errors.length > 0) return null;
 
-  // Parse the XanoScript file
-  const parser = xanoscriptParser(text, scheme);
   const tokens = lexResult.tokens;
 
-  // Find the token under the cursor
-  const tokenIdx = tokens.findIndex(
-    (token) => token.startOffset <= offset && token.endOffset >= offset
-  );
+  // Find the token under the cursor using binary search (O(log n))
+  const tokenIdx = findTokenAtOffset(tokens, offset);
 
   if (tokenIdx === -1) {
     return null;

package/onSemanticCheck/highlight.js

@@ -1,3 +1,4 @@
+import { debugLog } from "../debug.js";
 import { lexDocument } from "../lexer/lexer.js";
 import { mapTokenToType } from "../lexer/tokens.js";
 import { encodeTokenType } from "./tokens.js";
@@ -33,7 +34,7 @@ function higlightDefault(text, SemanticTokensBuilder) {
         0 // No modifiers for now
       );
     } else if (tokenType === undefined) {
-      console.log(
+      debugLog(
         `token type not mapped to a type: ${JSON.stringify(
           token.tokenType.name
         )}`

package/onSemanticCheck/onSemanticCheck.js

@@ -1,3 +1,4 @@
+import { debugError } from "../debug.js";
 import { getSchemeFromContent } from "../utils";
 import { higlightText } from "./highlight";
 
@@ -11,7 +12,7 @@ export function onSemanticCheck(params, documents, SemanticTokensBuilder) {
   const document = documents.get(params.textDocument.uri);
 
   if (!document) {
-    console.error(
+    debugError(
       "onSemanticCheck(): Document not found for URI:",
       params.textDocument.uri
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/xanoscript-language-server",
-  "version": "11.0.5",
+  "version": "11.1.0",
   "description": "Language Server Protocol implementation for XanoScript",
   "type": "module",
   "main": "server.js",
@@ -24,10 +24,8 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "chai": "^5.2.0",
     "chevrotain": "^11.0.3",
     "lodash-es": "^4.17.21",
-    "mocha": "^11.1.0",
     "vscode-languageserver": "^9.0.1",
     "vscode-languageserver-textdocument": "^1.0.12"
   },
@@ -38,11 +36,13 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.22.0",
+    "chai": "^5.2.0",
     "eslint": "^9.22.0",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "eslint-plugin-unused-imports": "^4.2.0",
     "globals": "^16.0.0",
     "husky": "^9.1.7",
-    "lint-staged": "^16.2.4"
+    "lint-staged": "^16.2.4",
+    "mocha": "^11.1.0"
   }
 }

package/parser/attributes/docsFieldAttribute.spec.js

@@ -32,6 +32,11 @@ describe("docsFieldAttribute", () => {
     expect(parser.errors).to.be.empty;
   });
 
+  it("docsFieldAttribute can be multiline", () => {
+    const parser = parse('docs="""\nanother docs\n"""');
+    expect(parser.errors).to.be.empty;
+  });
+
   it("docsFieldAttribute does not require a new line", () => {
     const parser = parse('docs="some docs"');
     expect(parser.errors).to.be.empty;

package/parser/functions/api/apiCallFn.spec.js

@@ -47,12 +47,12 @@ describe("apiCallFn", () => {
   });
 
   it("apiCallFn requires a url and method field", () => {
-    let parser = parse(`request {
+    let parser = parse(`call foo {
       url = "https://www.example.com"
     } as $user`);
     expect(parser.errors).to.not.be.empty;
 
-    parser = parse(`request {
+    parser = parse(`call foo {
       method = "GET"
     } as $user`);
     expect(parser.errors).to.not.be.empty;

package/parser/functions/controls/tryCatchFn.spec.js

@@ -59,7 +59,6 @@ describe("tryCatchFn", () => {
         }
       }
     }`);
-    console.log(parser.errors);
     expect(parser.errors).to.be.empty;
   });
 

package/parser/generic/objectWithAttributes.js

@@ -5,6 +5,7 @@ import { Identifier, NewlineToken } from "../../lexer/tokens.js";
 import { getVarName } from "./utils.js";
 
 /**
+ * @deprecated use parser/functions/schema/schemaParseAttributeFn.js instead
  * @param {import('../base_parser.js').XanoBaseParser} $
  */
 export function objectWithAttributes($) {

package/parser/parser.js

@@ -5,15 +5,16 @@ import { XanoBaseParser } from "./base_parser.js";
 
 /**
  * Will parse the content of the file based on its scheme (db:/, task:/, api:/...)
- * @param {string} scheme
  * @param {string} text
+ * @param {string} scheme
+ * @param {Object} [preTokenized] - Optional pre-tokenized result from lexDocument to avoid re-lexing
  * @returns
  */
-export function xanoscriptParser(text, scheme) {
+export function xanoscriptParser(text, scheme, preTokenized = null) {
   if (!scheme) {
     scheme = getSchemeFromContent(text);
   }
-  const lexResult = lexDocument(text);
+  const lexResult = preTokenized || lexDocument(text);
   parser.input = lexResult.tokens;
   switch (scheme.toLowerCase()) {
     case "addon":
@@ -52,6 +53,9 @@ export function xanoscriptParser(text, scheme) {
     case "realtime_channel":
       parser.realtimeChannelDeclaration();
       return parser;
+    case "run":
+      parser.runDeclaration();
+      return parser;
     case "table_trigger":
       parser.tableTriggerDeclaration();
       return parser;

package/parser/register.js

@@ -16,6 +16,11 @@ import { middlewareDeclaration } from "./middleware_parser.js";
 import { queryDeclaration } from "./query_parser.js";
 import { realtimeChannelDeclaration } from "./realtime_channel_parser.js";
 import { realtimeTriggerDeclaration } from "./realtime_trigger_parser.js";
+import {
+  runDeclaration,
+  runJobClause,
+  runServiceClause,
+} from "./run_parser.js";
 import { tableDeclaration } from "./table_parser.js";
 import { tableTriggerDeclaration } from "./table_trigger_parser.js";
 import { taskDeclaration } from "./task_parser.js";
@@ -66,6 +71,9 @@ export const register = ($) => {
     "realtimeChannelDeclaration",
     realtimeChannelDeclaration($)
   );
+  $.runDeclaration = $.RULE("runDeclaration", runDeclaration($));
+  $.runJobClause = $.RULE("runJobClause", runJobClause($));
+  $.runServiceClause = $.RULE("runServiceClause", runServiceClause($));
   $.tableTriggerDeclaration = $.RULE(
     "tableTriggerDeclaration",
     tableTriggerDeclaration($)

package/parser/run_parser.js

@@ -0,0 +1,70 @@
+import { StringLiteral } from "../lexer/literal.js";
+import { JobToken, RunToken, ServiceToken } from "../lexer/run.js";
+import { DotToken, Identifier, NewlineToken } from "../lexer/tokens.js";
+
+export function runDeclaration($) {
+  return () => {
+    $.sectionStack.push("runDeclaration");
+    // Allow leading comments and newlines before the run declaration
+    $.SUBRULE($.optionalCommentBlockFn);
+
+    $.CONSUME(RunToken); // "run"
+    $.CONSUME(DotToken); // "."
+
+    $.OR([
+      { ALT: () => $.SUBRULE($.runJobClause) },
+      { ALT: () => $.SUBRULE($.runServiceClause) },
+    ]);
+
+    $.MANY2(() => $.CONSUME2(NewlineToken)); // optional trailing newlines
+    $.sectionStack.pop();
+  };
+}
+
+export function runJobClause($) {
+  return () => {
+    const parent = $.CONSUME(JobToken); // "job"
+
+    $.OR([
+      { ALT: () => $.CONSUME(StringLiteral) },
+      { ALT: () => $.CONSUME(Identifier) },
+    ]);
+
+    $.SUBRULE($.schemaParseAttributeFn, {
+      ARGS: [
+        parent,
+        {
+          main: {
+            name: "[string]",
+            input: { "[string]?": "[constant]" },
+          },
+          "env?": ["[string]"],
+        },
+      ],
+    });
+  };
+}
+
+export function runServiceClause($) {
+  return () => {
+    const parent = $.CONSUME(ServiceToken); // "service"
+
+    $.OR([
+      { ALT: () => $.CONSUME(StringLiteral) },
+      { ALT: () => $.CONSUME(Identifier) },
+    ]);
+
+    $.SUBRULE($.schemaParseAttributeFn, {
+      ARGS: [
+        parent,
+        {
+          "pre?": {
+            name: "[string]",
+            input: { "[string]?": "[constant]" },
+          },
+          "env?": ["[string]"],
+        },
+      ],
+    });
+  };
+}

package/parser/run_parser.spec.js

@@ -0,0 +1,100 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { xanoscriptParser } from "./parser.js";
+
+describe("run", () => {
+  it("should parse a basic run.job", () => {
+    const parser = xanoscriptParser(`run.job "Average of values" {
+      main = {name: "avg_value", input: {}}
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("should parse a basic run.job with inputs", () => {
+    const parser = xanoscriptParser(`run.job "Average of values" {
+      main = {name: "avg_value", input: {left: 1, right: 2}}
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("run.job requires a main attribute", () => {
+    let parser = xanoscriptParser(`run.job "Average of values" {
+      pre = {name: "avg_value", input: {left: 1, right: 2}}
+    }`);
+    expect(parser.errors).to.not.be.empty;
+
+    parser = xanoscriptParser(`run.job "Average of values" {}`);
+    expect(parser.errors).to.not.be.empty;
+  });
+
+  it("should accept env variable", () => {
+    const parser = xanoscriptParser(`run.job "Gemini -> Image Understanding" {
+      main = {
+        name : "Gemini -> Image Understanding"
+        input: {
+          model : "gemini-1.5-flash"
+          prompt: "Describe what is happening in this image."
+          image : "(attach image file)"
+        }
+      }
+    
+      env = ["gemini_api_key"]
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("should parse a basic run.service", () => {
+    const parser = xanoscriptParser(`run.service "email proxy" {
+      pre = {name: "email_proxy_fn", input: {}}
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("run.service has a minimal form", () => {
+    const parser = xanoscriptParser(`run.service "email proxy"`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("environment variables can only be an array of strings", () => {
+    let parser = xanoscriptParser(`run.service "email proxy" {
+      env = ["email_proxy_api_key", 123, true]
+    }`);
+    expect(parser.errors).to.not.be.empty;
+
+    parser = xanoscriptParser(`run.job "Average of values" {
+      main = {name: "avg_value", input: {}}
+      env = ["email_proxy_api_key", 123, true]
+    }`);
+    expect(parser.errors).to.not.be.empty;
+
+    parser = xanoscriptParser(`run.service "email proxy" {
+      env = []
+    }`);
+    expect(parser.errors).to.be.empty;
+
+    parser = xanoscriptParser(`run.service "email proxy" {
+      env = ["a_value", "another value"]
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("run.service does not require a pre", () => {
+    const parser = xanoscriptParser(`run.service "email proxy"`);
+    expect(parser.errors).to.be.empty;
+  });
+
+  it("run.service does not accept a main", () => {
+    const parser = xanoscriptParser(`run.service "email proxy" {
+      main = { name : "some_fn", input: {} }
+    }`);
+    expect(parser.errors).to.not.be.empty;
+  });
+
+  it("run.service accepts env variables", () => {
+    const parser = xanoscriptParser(`run.service "email proxy" {
+      pre = {name: "email_proxy_init", input: {}}
+      env = ["email_proxy_api_key"]
+    }`);
+    expect(parser.errors).to.be.empty;
+  });
+});

package/server.js

@@ -5,6 +5,7 @@ import {
   TextDocuments,
 } from "vscode-languageserver/node.js";
 import { TextDocument } from "vscode-languageserver-textdocument";
+import { debugLog } from "./debug.js";
 import { onCompletion } from "./onCompletion/onCompletion.js";
 import { onDidChangeContent } from "./onDidChangeContent/onDidChangeContent.js";
 import { onHover } from "./onHover/onHover.js";
@@ -50,7 +51,7 @@ documents.onDidChangeContent((params) =>
   onDidChangeContent(params, connection)
 );
 connection.onDidOpenTextDocument((params) => {
-  console.log("Document opened:", params.textDocument.uri);
+  debugLog("Document opened:", params.textDocument.uri);
   // Existing handler logic
 });
 

package/utils.js

@@ -30,6 +30,7 @@ const schemeByFirstWord = {
   query: "api",
   realtime_trigger: "realtime_trigger",
   realtime_channel: "realtime_channel",
+  run: "run",
   table: "db",
   table_trigger: "table_trigger",
   task: "task",

package/.claude/settings.local.json

@@ -1,34 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm test:*)",
-      "Bash(npm run lint)",
-      "Bash(npm run test:*)",
-      "Bash(npx eslint:*)",
-      "Bash(node:*)",
-      "Bash(npm install)",
-      "Bash(grep:*)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log --all --pretty=format:\"%h %s\")",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log --all -S \"password\\\\|secret\\\\|api_key\\\\|token\" --oneline)",
-      "Bash(xargs file:*)",
-      "Bash(find:*)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log -p --all -S \"webhook\\\\|Bearer\\\\|discord\\\\|slack\\\\|xano_insiders\" -- \"*.xs\" \"*.js\")",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server ls-files:*)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server status)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server diff --stat)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log --oneline -5)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server add README.md LICENSE package.json lexer/tests/query/valid_sources/basic_query.xs parser/functions/stream/streamFromRequestFn.js parser/functions/stream/streamFromRequestFn.spec.js parser/tests/function/valid_sources/discord_poll_send_to_slack.xs parser/tests/query/valid_sources/all_basics.xs)",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server commit -m \"$\\(cat <<''EOF''\nPrepare package for public npm release as @xano/xanoscript-language-server\n\n- Rename package to @xano/xanoscript-language-server\n- Add MIT LICENSE file\n- Add npm metadata \\(description, repository, author, license, bugs, homepage\\)\n- Remove private flag to allow publishing\n- Sanitize test files: replace internal URLs, IDs, and env var names with placeholders\n- Simplify README maintainer section\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
-      "Bash(git -C /Users/justinalbrecht/git/xs-language-server log -1 --oneline)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git push)",
-      "Bash(npm whoami:*)",
-      "Bash(npm view:*)",
-      "Bash(npm version:*)",
-      "Bash(npm publish:*)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}