Plugin Development for Geode

Creating plugins and extensions for Geode enables developers to enhance their editor experience with GQL-specific features like syntax highlighting, intelligent auto-completion, real-time diagnostics, and integrated query execution. Whether you are building a plugin for your team’s custom editor, extending an existing integration, or contributing to the Geode ecosystem, this guide provides comprehensive coverage of plugin development patterns and best practices. Geode’s plugin architecture leverages the Language Server Protocol (LSP) for cross-editor compatibility, allowing you to build language intelligence features once and deploy them across VS Code, Neovim, Vim, Emacs, Sublime Text, and any other LSP-compatible editor. This guide covers LSP client implementation, syntax highlighting packages, completion sources, query execution integration, result visualization, testing strategies, and publishing workflows for various editor ecosystems. <h3 id="architecture-overview" class="position-relative d-flex align-items-center group"> Architecture Overview <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="architecture-overview" aria-haspopup="dialog" aria-label="Share link: Architecture Overview"> Share link </button> </h3><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden> <div class="hsm-dialog" role="document"> <div class="hsm-header"> <h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2> <button type="button" class="hsm-close" aria-label="Close"> </button> </div> <div class="hsm-body"> <label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label> <div class="input-group mb-4 hsm-url-group"> <input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" /> <button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy"> </button> </div> <div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div> <div class="hsm-share-grid"> <a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Twitter </a> <a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> LinkedIn </a> <a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Facebook </a> </div> </div> </div> </div> <style> .heading-share-modal { position: fixed; inset: 0; display: flex; justify-content: center; align-items: center; background: rgba(0, 0, 0, 0.6); z-index: 1050; padding: 1rem; backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px); } .heading-share-modal[hidden] { display: none !important; } .hsm-dialog { max-width: 420px; width: 100%; background: var(--bs-body-bg, #fff); color: var(--bs-body-color, #212529); border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); border-radius: 1rem; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); overflow: hidden; animation: hsm-fade-in 0.2s ease-out; } @keyframes hsm-fade-in { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } } [data-bs-theme="dark"] .hsm-dialog { background: #1e293b; border-color: rgba(255,255,255,0.1); color: #f8f9fa; } .hsm-header { display: flex; justify-content: space-between; align-items: center; padding: 1rem 1.5rem; border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); background: rgba(0,0,0,0.02); } [data-bs-theme="dark"] .hsm-header { background: rgba(255,255,255,0.02); border-color: rgba(255,255,255,0.1); } .hsm-close { background: transparent; border: none; color: inherit; opacity: 0.5; padding: 0.25rem 0.5rem; border-radius: 0.25rem; font-size: 1.2rem; line-height: 1; transition: opacity 0.2s; } .hsm-close:hover { opacity: 1; } .hsm-body { padding: 1.5rem; } .hsm-url-group { display: flex !important; align-items: stretch; } .hsm-url-group .form-control { flex: 1; min-width: 0; margin: 0; background: var(--bs-secondary-bg, #f8f9fa); border-color: var(--bs-border-color, #dee2e6); border-top-right-radius: 0; border-bottom-right-radius: 0; height: 42px; } .hsm-url-group .btn { flex: 0 0 auto; margin: 0; margin-left: -1px; border-top-left-radius: 0; border-bottom-left-radius: 0; height: 42px; display: flex; align-items: center; justify-content: center; padding: 0 1.25rem; z-index: 2; } [data-bs-theme="dark"] .hsm-url-group .form-control { background: #0f172a; border-color: #334155; color: #e2e8f0; } .hsm-share-grid { display: flex; flex-direction: column; gap: 0.5rem; } .hsm-share-grid .btn { display: flex; align-items: center; justify-content: center; font-size: 0.9rem; padding: 0.6rem; border-color: var(--bs-border-color); width: 100%; } [data-bs-theme="dark"] .hsm-share-grid .btn { color: #e2e8f0; border-color: #475569; } [data-bs-theme="dark"] .hsm-share-grid .btn:hover { background: #334155; border-color: #cbd5e1; } </style> <script> (function(){ const modal = document.getElementById('headingShareModal'); if(!modal) return; const input = modal.querySelector('#headingShareInput'); const copyBtn = modal.querySelector('.hsm-copy'); const twitter = modal.querySelector('#share-twitter'); const linkedin = modal.querySelector('#share-linkedin'); const facebook = modal.querySelector('#share-facebook'); const closeBtn = modal.querySelector('.hsm-close'); let lastFocus=null; let trapBound=false; function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; } function isOpen(){ return !modal.hasAttribute('hidden'); } function hydrate(id){ const url=buildUrl(id); input.value=url; const enc=encodeURIComponent(url); const text=encodeURIComponent(document.title); if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`; if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`; if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`; } function openModal(id){ lastFocus=document.activeElement; hydrate(id); if(!isOpen()){ modal.removeAttribute('hidden'); } requestAnimationFrame(()=>{ input.focus(); }); trapFocus(); } function closeModal(){ if(!isOpen()) return; modal.setAttribute('hidden',''); if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus(); } function copyCurrent(){ try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); } catch(e){ fallback(); } } function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} } function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); } function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); } function bindShareButtons(){ document.querySelectorAll('.h-share').forEach(btn=>{ if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; } }); } bindShareButtons(); if(document.readyState==='loading'){ document.addEventListener('DOMContentLoaded', bindShareButtons); } else { requestAnimationFrame(bindShareButtons); } document.addEventListener('click', function(e){ const shareBtn=e.target.closest && e.target.closest('.h-share'); if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); } }, true); document.addEventListener('click', e=>{ if(e.target===modal) closeModal(); if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); } if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); } }); document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); }); function trapFocus(){ if(trapBound) return; trapBound=true; modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } }); } if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); }); })(); </script> <h4 id="plugin-components" class="position-relative d-flex align-items-center group"> Plugin Components <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="plugin-components" aria-haspopup="dialog" aria-label="Share link: Plugin Components"> Share link </button> </h4>A complete Geode editor plugin typically includes: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">geode-editor-plugin/ ├── src/ │ ├── extension.ts # Extension entry point │ ├── lsp-client.ts # LSP client implementation │ ├── completion.ts # Completion providers │ ├── diagnostics.ts # Diagnostic handling │ ├── execution.ts # Query execution │ ├── results.ts # Result visualization │ └── schema.ts # Schema explorer ├── syntaxes/ │ └── gql.tmLanguage.json # TextMate grammar ├── snippets/ │ └── gql.json # Code snippets ├── languages/ │ └── gql-language-configuration.json ├── package.json # Extension manifest └── README.md </code></pre></div> <h4 id="integration-points" class="position-relative d-flex align-items-center group"> Integration Points <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="integration-points" aria-haspopup="dialog" aria-label="Share link: Integration Points"> Share link </button> </h4><table> <thead> <tr> <th>Component</th> <th>Purpose</th> <th>Technology</th> </tr> </thead> <tbody> <tr> <td>Language Server</td> <td>Intelligence features</td> <td>LSP (JSON-RPC)</td> </tr> <tr> <td>Syntax Highlighting</td> <td>Tokenization</td> <td>TextMate/Tree-sitter</td> </tr> <tr> <td>Snippets</td> <td>Code templates</td> <td>Editor-specific</td> </tr> <tr> <td>Commands</td> <td>User actions</td> <td>Editor API</td> </tr> <tr> <td>UI</td> <td>Results, explorer</td> <td>Editor widgets</td> </tr> </tbody> </table> <h3 id="language-server-protocol-client" class="position-relative d-flex align-items-center group"> Language Server Protocol Client <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="language-server-protocol-client" aria-haspopup="dialog" aria-label="Share link: Language Server Protocol Client"> Share link </button> </h3> <h4 id="basic-lsp-client" class="position-relative d-flex align-items-center group"> Basic LSP Client <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="basic-lsp-client" aria-haspopup="dialog" aria-label="Share link: Basic LSP Client"> Share link </button> </h4>Implement an LSP client to communicate with Geode’s language server: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript">// src/lsp-client.ts import { LanguageClient, LanguageClientOptions, ServerOptions, TransportKind, } from 'vscode-languageclient/node'; export function createLanguageClient(context: ExtensionContext): LanguageClient { // Server options - how to start the language server const serverOptions: ServerOptions = { command: 'geode', args: ['lsp', '--stdio'], transport: TransportKind.stdio, }; // Client options - document types and synchronization const clientOptions: LanguageClientOptions = { documentSelector: [ { scheme: 'file', language: 'gql' }, { scheme: 'untitled', language: 'gql' }, ], synchronize: { fileEvents: workspace.createFileSystemWatcher('**/*.gql'), }, initializationOptions: { connection: { host: workspace.getConfiguration('geode').get('host'), port: workspace.getConfiguration('geode').get('port'), database: workspace.getConfiguration('geode').get('database'), }, diagnostics: { enabled: true, validateLabels: true, validateProperties: true, }, }, }; // Create and return the client return new LanguageClient( 'geode-gql', 'Geode GQL Language Server', serverOptions, clientOptions ); } </code></pre></div> <h4 id="handling-lsp-notifications" class="position-relative d-flex align-items-center group"> Handling LSP Notifications <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="handling-lsp-notifications" aria-haspopup="dialog" aria-label="Share link: Handling LSP Notifications"> Share link </button> </h4>Handle custom notifications from the language server: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript">// src/notifications.ts import { LanguageClient } from 'vscode-languageclient/node'; export function registerNotificationHandlers(client: LanguageClient): void { // Connection status updates client.onNotification('geode/connectionStatus', (params: ConnectionStatus) => { updateStatusBar(params); if (!params.connected) { showConnectionError(params.error); } }); // Schema changes client.onNotification('geode/schemaChanged', (params: SchemaChange) => { refreshSchemaExplorer(params); showNotification(`Schema updated: ${params.changeType}`); }); // Query execution progress client.onNotification('geode/queryProgress', (params: QueryProgress) => { updateProgressIndicator(params); }); // Diagnostic updates client.onNotification('geode/diagnosticsUpdated', (params: DiagnosticUpdate) => { handleDiagnostics(params); }); } interface ConnectionStatus { connected: boolean; host: string; port: number; database: string; error?: string; } interface SchemaChange { changeType: 'labels' | 'relationships' | 'indexes' | 'full'; timestamp: string; } interface QueryProgress { queryId: string; stage: string; progress: number; rowsProcessed: number; } </code></pre></div> <h4 id="custom-lsp-requests" class="position-relative d-flex align-items-center group"> Custom LSP Requests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="custom-lsp-requests" aria-haspopup="dialog" aria-label="Share link: Custom LSP Requests"> Share link </button> </h4>Send custom requests to the language server: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript">// src/requests.ts import { LanguageClient } from 'vscode-languageclient/node'; export class GeodeRequests { constructor(private client: LanguageClient) {} // Execute a GQL query async executeQuery(query: string, params?: Record<string, any>): Promise<QueryResult> { return this.client.sendRequest('geode/executeQuery', { query, params, timeout: 30000, }); } // Get execution plan async explainQuery(query: string): Promise<ExecutionPlan> { return this.client.sendRequest('geode/explainQuery', { query }); } // Profile query execution async profileQuery(query: string): Promise<ProfileResult> { return this.client.sendRequest('geode/profileQuery', { query }); } // Get schema information async getSchema(): Promise<Schema> { return this.client.sendRequest('geode/getSchema', {}); } // Get labels with statistics async getLabels(): Promise<LabelInfo[]> { return this.client.sendRequest('geode/getLabels', {}); } // Get properties for a label async getProperties(label: string): Promise<PropertyInfo[]> { return this.client.sendRequest('geode/getProperties', { label }); } // Get relationship types async getRelationships(): Promise<RelationshipInfo[]> { return this.client.sendRequest('geode/getRelationships', {}); } // Cancel running query async cancelQuery(queryId: string): Promise<void> { return this.client.sendRequest('geode/cancelQuery', { queryId }); } } interface QueryResult { columns: string[]; rows: any[][]; rowCount: number; executionTime: number; queryId: string; } interface ExecutionPlan { plan: PlanNode; estimatedCost: number; warnings: string[]; } interface ProfileResult extends QueryResult { profile: ProfileNode; dbHits: number; memoryUsage: number; } </code></pre></div> <h3 id="syntax-highlighting" class="position-relative d-flex align-items-center group"> Syntax Highlighting <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="syntax-highlighting" aria-haspopup="dialog" aria-label="Share link: Syntax Highlighting"> Share link </button> </h3> <h4 id="textmate-grammar" class="position-relative d-flex align-items-center group"> TextMate Grammar <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="textmate-grammar" aria-haspopup="dialog" aria-label="Share link: TextMate Grammar"> Share link </button> </h4>Create a TextMate grammar for GQL syntax: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json", "name": "GQL", "scopeName": "source.gql", "patterns": [ { "include": "#comments" }, { "include": "#strings" }, { "include": "#numbers" }, { "include": "#keywords" }, { "include": "#functions" }, { "include": "#labels" }, { "include": "#relationships" }, { "include": "#properties" }, { "include": "#variables" }, { "include": "#operators" } ], "repository": { "comments": { "patterns": [ { "name": "comment.line.double-dash.gql", "match": "--.*$" }, { "name": "comment.block.gql", "begin": "/\\*", "end": "\\*/" } ] }, "strings": { "patterns": [ { "name": "string.quoted.single.gql", "begin": "'", "end": "'", "patterns": [ { "name": "constant.character.escape.gql", "match": "\\\\." } ] }, { "name": "string.quoted.double.gql", "begin": "\"", "end": "\"", "patterns": [ { "name": "constant.character.escape.gql", "match": "\\\\." } ] } ] }, "numbers": { "patterns": [ { "name": "constant.numeric.float.gql", "match": "\\b\\d+\\.\\d+([eE][+-]?\\d+)?\\b" }, { "name": "constant.numeric.integer.gql", "match": "\\b\\d+\\b" } ] }, "keywords": { "patterns": [ { "name": "keyword.control.gql", "match": "\\b(?i:MATCH|WHERE|RETURN|CREATE|DELETE|MERGE|SET|REMOVE|WITH|UNWIND|CALL|YIELD|ORDER|BY|SKIP|LIMIT|OPTIONAL|DISTINCT|AS|CASE|WHEN|THEN|ELSE|END)\\b" }, { "name": "keyword.operator.logical.gql", "match": "\\b(?i:AND|OR|NOT|XOR|IN|IS|NULL|TRUE|FALSE)\\b" }, { "name": "keyword.control.transaction.gql", "match": "\\b(?i:BEGIN|COMMIT|ROLLBACK|TRANSACTION)\\b" } ] }, "functions": { "patterns": [ { "name": "support.function.aggregate.gql", "match": "\\b(?i:COUNT|SUM|AVG|MIN|MAX|COLLECT|STDEV|PERCENTILE)\\b" }, { "name": "support.function.string.gql", "match": "\\b(?i:UPPER|LOWER|TRIM|LTRIM|RTRIM|SUBSTRING|REPLACE|SPLIT|REVERSE|SIZE|LENGTH)\\b" }, { "name": "support.function.math.gql", "match": "\\b(?i:ABS|CEIL|FLOOR|ROUND|SIGN|RAND|LOG|LOG10|EXP|SQRT|SIN|COS|TAN)\\b" }, { "name": "support.function.temporal.gql", "match": "\\b(?i:DATE|DATETIME|TIME|DURATION|LOCALDATETIME|LOCALTIME)\\b" }, { "name": "support.function.misc.gql", "match": "\\b(?i:COALESCE|NULLIF|ID|TYPE|LABELS|PROPERTIES|KEYS|NODES|RELATIONSHIPS|HEAD|TAIL|LAST)\\b" } ] }, "labels": { "patterns": [ { "name": "entity.name.type.label.gql", "match": ":\\s*([A-Za-z_][A-Za-z0-9_]*)", "captures": { "1": { "name": "entity.name.type.gql" } } } ] }, "relationships": { "patterns": [ { "name": "entity.name.type.relationship.gql", "match": "-\\[\\s*:?([A-Za-z_][A-Za-z0-9_]*)", "captures": { "1": { "name": "entity.name.type.gql" } } } ] }, "properties": { "patterns": [ { "name": "variable.other.property.gql", "match": "\\.([A-Za-z_][A-Za-z0-9_]*)" } ] }, "variables": { "patterns": [ { "name": "variable.parameter.gql", "match": "\\$([A-Za-z_][A-Za-z0-9_]*)" } ] }, "operators": { "patterns": [ { "name": "keyword.operator.comparison.gql", "match": "=|<>|!=|<|>|<=|>=|=~" }, { "name": "keyword.operator.arithmetic.gql", "match": "\\+|-|\\*|/|%|\\^" }, { "name": "keyword.operator.string.gql", "match": "\\b(?i:STARTS|ENDS|CONTAINS|LIKE)\\b" } ] } } } </code></pre></div> <h4 id="tree-sitter-grammar" class="position-relative d-flex align-items-center group"> Tree-sitter Grammar <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="tree-sitter-grammar" aria-haspopup="dialog" aria-label="Share link: Tree-sitter Grammar"> Share link </button> </h4>For editors supporting Tree-sitter (Neovim, Helix): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-javascript" data-lang="javascript">// grammar.js module.exports = grammar({ name: 'gql', extras: $ => [ /\s/, $.comment, ], rules: { source_file: $ => repeat($.statement), statement: $ => seq( choice( $.match_clause, $.create_clause, $.merge_clause, $.delete_clause, $.return_clause, $.with_clause, ), optional(';') ), match_clause: $ => seq( caseInsensitive('MATCH'), $.pattern, optional($.where_clause), ), pattern: $ => seq( $.node_pattern, repeat(seq($.relationship_pattern, $.node_pattern)) ), node_pattern: $ => seq( '(', optional($.variable), optional($.label), optional($.properties), ')' ), relationship_pattern: $ => choice( seq('-[', optional($.variable), optional($.rel_type), optional($.properties), ']-'), seq('-[', optional($.variable), optional($.rel_type), optional($.properties), ']->'), seq('<-[', optional($.variable), optional($.rel_type), optional($.properties), ']-'), ), label: $ => seq(':', $.identifier), rel_type: $ => seq(':', $.identifier), variable: $ => $.identifier, identifier: $ => /[A-Za-z_][A-Za-z0-9_]*/, properties: $ => seq( '{', sepBy(',', $.property_assignment), '}' ), property_assignment: $ => seq( $.identifier, ':', $.expression ), where_clause: $ => seq( caseInsensitive('WHERE'), $.expression ), return_clause: $ => seq( caseInsensitive('RETURN'), sepBy(',', $.return_item) ), return_item: $ => seq( $.expression, optional(seq(caseInsensitive('AS'), $.identifier)) ), expression: $ => choice( $.literal, $.variable, $.property_access, $.function_call, $.binary_expression, $.unary_expression, seq('(', $.expression, ')'), ), literal: $ => choice( $.string, $.number, $.boolean, $.null, ), string: $ => choice( seq("'", /[^']*/, "'"), seq('"', /[^"]*/, '"'), ), number: $ => /\d+(\.\d+)?/, boolean: $ => choice( caseInsensitive('TRUE'), caseInsensitive('FALSE') ), null: $ => caseInsensitive('NULL'), property_access: $ => seq( $.variable, '.', $.identifier ), function_call: $ => seq( $.identifier, '(', optional(sepBy(',', $.expression)), ')' ), binary_expression: $ => prec.left(seq( $.expression, choice('+', '-', '*', '/', '=', '<>', '<', '>', '<=', '>=', 'AND', 'OR'), $.expression )), unary_expression: $ => prec.right(seq( choice('NOT', '-'), $.expression )), comment: $ => choice( seq('--', /.*/), seq('/*', /[^*]*\*+([^/*][^*]*\*+)*/, '/') ), } }); function caseInsensitive(keyword) { return new RegExp(keyword.split('').map(c => `[${c.toLowerCase()}${c.toUpperCase()}]` ).join('')); } function sepBy(sep, rule) { return optional(seq(rule, repeat(seq(sep, rule)))); } </code></pre></div> <h3 id="auto-completion" class="position-relative d-flex align-items-center group"> Auto-Completion <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="auto-completion" aria-haspopup="dialog" aria-label="Share link: Auto-Completion"> Share link </button> </h3> <h4 id="completion-provider" class="position-relative d-flex align-items-center group"> Completion Provider <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="completion-provider" aria-haspopup="dialog" aria-label="Share link: Completion Provider"> Share link </button> </h4>Implement a completion provider for rich suggestions: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript">// src/completion.ts import * as vscode from 'vscode'; import { GeodeRequests } from './requests'; export class GeodeCompletionProvider implements vscode.CompletionItemProvider { constructor(private geode: GeodeRequests) {} async provideCompletionItems( document: vscode.TextDocument, position: vscode.Position, token: vscode.CancellationToken ): Promise<vscode.CompletionItem[]> { const context = this.getCompletionContext(document, position); switch (context.type) { case 'label': return this.getLabelCompletions(); case 'property': return this.getPropertyCompletions(context.label); case 'relationship': return this.getRelationshipCompletions(); case 'function': return this.getFunctionCompletions(); case 'keyword': return this.getKeywordCompletions(context.previousKeyword); default: return []; } } private getCompletionContext( document: vscode.TextDocument, position: vscode.Position ): CompletionContext { const lineText = document.lineAt(position).text; const textBeforeCursor = lineText.substring(0, position.character); // After colon - label completion if (textBeforeCursor.match(/:\s*\w*$/)) { return { type: 'label' }; } // After dot - property completion const propMatch = textBeforeCursor.match(/(\w+)\.\w*$/); if (propMatch) { const label = this.inferLabel(document, propMatch[1], position); return { type: 'property', variable: propMatch[1], label }; } // After -[ or relationship context if (textBeforeCursor.match(/-\[\s*:?\w*$/)) { return { type: 'relationship' }; } // After function name opening paren if (textBeforeCursor.match(/\w+\(\s*$/)) { return { type: 'function_args' }; } // Default to keyword completion return { type: 'keyword', previousKeyword: this.getPreviousKeyword(textBeforeCursor) }; } private async getLabelCompletions(): Promise<vscode.CompletionItem[]> { const labels = await this.geode.getLabels(); return labels.map(label => { const item = new vscode.CompletionItem( label.name, vscode.CompletionItemKind.Class ); item.detail = `Label (${label.nodeCount} nodes)`; item.documentation = new vscode.MarkdownString( `**${label.name}**\n\n` + `- Nodes: ${label.nodeCount}\n` + `- Properties: ${label.properties.join(', ')}\n` + `- Indexes: ${label.indexes.join(', ')}` ); return item; }); } private async getPropertyCompletions(label?: string): Promise<vscode.CompletionItem[]> { if (!label) return []; const properties = await this.geode.getProperties(label); return properties.map(prop => { const item = new vscode.CompletionItem( prop.name, vscode.CompletionItemKind.Property ); item.detail = `${prop.type}${prop.indexed ? ' (indexed)' : ''}`; item.documentation = new vscode.MarkdownString( `**${prop.name}**: ${prop.type}\n\n` + `- Nullable: ${prop.nullable}\n` + `- Indexed: ${prop.indexed}\n` + `- Unique: ${prop.unique}` ); return item; }); } private async getRelationshipCompletions(): Promise<vscode.CompletionItem[]> { const relationships = await this.geode.getRelationships(); return relationships.map(rel => { const item = new vscode.CompletionItem( rel.type, vscode.CompletionItemKind.Reference ); item.detail = `Relationship (${rel.count} edges)`; item.documentation = new vscode.MarkdownString( `**${rel.type}**\n\n` + `- Count: ${rel.count}\n` + `- From: ${rel.fromLabels.join(', ')}\n` + `- To: ${rel.toLabels.join(', ')}` ); return item; }); } private getFunctionCompletions(): vscode.CompletionItem[] { return GQL_FUNCTIONS.map(fn => { const item = new vscode.CompletionItem( fn.name, vscode.CompletionItemKind.Function ); item.detail = fn.signature; item.documentation = new vscode.MarkdownString( `**${fn.signature}**\n\n${fn.description}\n\n` + `**Example:**\n\`\`\`gql\n${fn.example}\n\`\`\`` ); item.insertText = new vscode.SnippetString(`${fn.name}($1)`); return item; }); } private getKeywordCompletions(previousKeyword?: string): vscode.CompletionItem[] { const keywords = this.getContextualKeywords(previousKeyword); return keywords.map(kw => { const item = new vscode.CompletionItem( kw.name, vscode.CompletionItemKind.Keyword ); item.detail = 'Keyword'; item.documentation = kw.description; if (kw.snippet) { item.insertText = new vscode.SnippetString(kw.snippet); } return item; }); } private inferLabel( document: vscode.TextDocument, variable: string, position: vscode.Position ): string | undefined { // Search backwards for variable binding with label const text = document.getText(new vscode.Range(0, 0, position.line, position.character)); const match = text.match(new RegExp(`\$${variable}:(\\w+)\$`)); return match ? match[1] : undefined; } private getPreviousKeyword(text: string): string | undefined { const keywords = ['MATCH', 'WHERE', 'RETURN', 'CREATE', 'DELETE', 'SET', 'WITH']; for (const kw of keywords) { if (text.toUpperCase().includes(kw)) { return kw; } } return undefined; } private getContextualKeywords(previous?: string): KeywordInfo[] { // Return keywords valid in current context const all = [ { name: 'MATCH', description: 'Match patterns in the graph', snippet: 'MATCH ($1)' }, { name: 'WHERE', description: 'Filter results', snippet: 'WHERE $1' }, { name: 'RETURN', description: 'Return results', snippet: 'RETURN $1;' }, { name: 'CREATE', description: 'Create nodes/relationships', snippet: 'CREATE ($1)' }, { name: 'DELETE', description: 'Delete nodes/relationships' }, { name: 'SET', description: 'Set properties', snippet: 'SET $1 = $2' }, { name: 'ORDER BY', description: 'Order results', snippet: 'ORDER BY $1' }, { name: 'LIMIT', description: 'Limit results', snippet: 'LIMIT $1' }, { name: 'SKIP', description: 'Skip results', snippet: 'SKIP $1' }, ]; // Filter based on context if (previous === 'MATCH') { return all.filter(k => ['WHERE', 'RETURN', 'WITH', 'CREATE', 'DELETE'].includes(k.name)); } if (previous === 'WHERE') { return all.filter(k => ['AND', 'OR', 'RETURN', 'WITH'].includes(k.name)); } return all; } } interface CompletionContext { type: 'label' | 'property' | 'relationship' | 'function' | 'function_args' | 'keyword'; variable?: string; label?: string; previousKeyword?: string; } interface KeywordInfo { name: string; description: string; snippet?: string; } </code></pre></div> <h3 id="query-execution" class="position-relative d-flex align-items-center group"> Query Execution <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="query-execution" aria-haspopup="dialog" aria-label="Share link: Query Execution"> Share link </button> </h3> <h4 id="execution-provider" class="position-relative d-flex align-items-center group"> Execution Provider <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="execution-provider" aria-haspopup="dialog" aria-label="Share link: Execution Provider"> Share link </button> </h4>Implement query execution with result handling: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript">// src/execution.ts import * as vscode from 'vscode'; import { GeodeRequests, QueryResult } from './requests'; import { ResultsPanel } from './results-panel'; export class QueryExecutor { private resultsPanel: ResultsPanel; private runningQueries: Map<string, vscode.CancellationTokenSource> = new Map(); constructor(private geode: GeodeRequests) { this.resultsPanel = new ResultsPanel(); } async executeQuery(document: vscode.TextDocument, selection?: vscode.Selection): Promise<void> { const query = selection ? document.getText(selection) : this.getCurrentQuery(document); if (!query.trim()) { vscode.window.showWarningMessage('No query to execute'); return; } const queryId = this.generateQueryId(); const cancellation = new vscode.CancellationTokenSource(); this.runningQueries.set(queryId, cancellation); try { // Show progress await vscode.window.withProgress( { location: vscode.ProgressLocation.Notification, title: 'Executing query...', cancellable: true, }, async (progress, token) => { token.onCancellationRequested(() => { this.cancelQuery(queryId); }); const startTime = Date.now(); const result = await this.geode.executeQuery(query); const executionTime = Date.now() - startTime; this.resultsPanel.showResults({ ...result, executionTime, query, }); } ); } catch (error) { this.handleError(error); } finally { this.runningQueries.delete(queryId); } } async explainQuery(document: vscode.TextDocument): Promise<void> { const query = this.getCurrentQuery(document); try { const plan = await this.geode.explainQuery(query); this.resultsPanel.showPlan(plan); } catch (error) { this.handleError(error); } } async profileQuery(document: vscode.TextDocument): Promise<void> { const query = this.getCurrentQuery(document); try { const profile = await this.geode.profileQuery(query); this.resultsPanel.showProfile(profile); } catch (error) { this.handleError(error); } } private getCurrentQuery(document: vscode.TextDocument): string { const text = document.getText(); const editor = vscode.window.activeTextEditor; if (!editor) return text; const position = editor.selection.active; const queries = this.splitQueries(text); // Find query containing cursor let currentOffset = 0; const cursorOffset = document.offsetAt(position); for (const query of queries) { const queryEnd = currentOffset + query.length; if (cursorOffset >= currentOffset && cursorOffset <= queryEnd) { return query; } currentOffset = queryEnd + 1; // +1 for semicolon } return text; } private splitQueries(text: string): string[] { // Split on semicolons, but respect strings const queries: string[] = []; let current = ''; let inString = false; let stringChar = ''; for (const char of text) { if ((char === "'" || char === '"') && !inString) { inString = true; stringChar = char; } else if (char === stringChar && inString) { inString = false; } else if (char === ';' && !inString) { if (current.trim()) { queries.push(current.trim()); } current = ''; continue; } current += char; } if (current.trim()) { queries.push(current.trim()); } return queries; } private async cancelQuery(queryId: string): Promise<void> { const cancellation = this.runningQueries.get(queryId); if (cancellation) { cancellation.cancel(); await this.geode.cancelQuery(queryId); this.runningQueries.delete(queryId); } } private handleError(error: any): void { const message = error.message || 'Query execution failed'; vscode.window.showErrorMessage(`Geode Error: ${message}`); this.resultsPanel.showError(error); } private generateQueryId(): string { return `query-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`; } } </code></pre></div> <h4 id="results-panel" class="position-relative d-flex align-items-center group"> Results Panel <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="results-panel" aria-haspopup="dialog" aria-label="Share link: Results Panel"> Share link </button> </h4>Create a webview panel for displaying results: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript">// src/results-panel.ts import * as vscode from 'vscode'; export class ResultsPanel { private panel: vscode.WebviewPanel | undefined; showResults(result: QueryResultWithMeta): void { this.ensurePanel(); this.panel!.webview.html = this.getResultsHtml(result); this.panel!.reveal(); } showPlan(plan: ExecutionPlan): void { this.ensurePanel(); this.panel!.webview.html = this.getPlanHtml(plan); this.panel!.reveal(); } showProfile(profile: ProfileResult): void { this.ensurePanel(); this.panel!.webview.html = this.getProfileHtml(profile); this.panel!.reveal(); } showError(error: any): void { this.ensurePanel(); this.panel!.webview.html = this.getErrorHtml(error); this.panel!.reveal(); } private ensurePanel(): void { if (!this.panel) { this.panel = vscode.window.createWebviewPanel( 'geodeResults', 'Geode Results', vscode.ViewColumn.Two, { enableScripts: true, retainContextWhenHidden: true, } ); this.panel.onDidDispose(() => { this.panel = undefined; }); } } private getResultsHtml(result: QueryResultWithMeta): string { const tableRows = result.rows.map(row => `<tr>${result.columns.map(col => `<td>${this.formatValue(row[col])}</td>` ).join('')}</tr>` ).join(''); return `<!DOCTYPE html> <html> <head> <style> body { font-family: var(--vscode-font-family); padding: 10px; } .stats { color: var(--vscode-descriptionForeground); margin-bottom: 10px; } table { border-collapse: collapse; width: 100%; } th, td { border: 1px solid var(--vscode-panel-border); padding: 8px; text-align: left; } th { background: var(--vscode-editor-lineHighlightBackground); } tr:hover { background: var(--vscode-list-hoverBackground); } .toolbar { margin-bottom: 10px; } button { background: var(--vscode-button-background); color: var(--vscode-button-foreground); border: none; padding: 5px 10px; cursor: pointer; } button:hover { background: var(--vscode-button-hoverBackground); } </style> </head> <body> <div class="toolbar"> <button onclick="copyResults()">Copy</button> <button onclick="exportCsv()">Export CSV</button> <button onclick="exportJson()">Export JSON</button> </div> <div class="stats"> ${result.rowCount} rows in ${result.executionTime}ms </div> <table> <thead> <tr>${result.columns.map(c => `<th>${c}</th>`).join('')}</tr> </thead> <tbody> ${tableRows} </tbody> </table> <script> const vscode = acquireVsCodeApi(); const results = ${JSON.stringify(result)}; function copyResults() { vscode.postMessage({ command: 'copy', data: results }); } function exportCsv() { vscode.postMessage({ command: 'exportCsv', data: results }); } function exportJson() { vscode.postMessage({ command: 'exportJson', data: results }); } </script> </body> </html>`; } private formatValue(value: any): string { if (value === null || value === undefined) { return 'null'; } if (typeof value === 'object') { return `<pre>${JSON.stringify(value, null, 2)}</pre>`; } return String(value); } private getPlanHtml(plan: ExecutionPlan): string { // Render execution plan as tree return `<!DOCTYPE html> <html> <head> <style> body { font-family: var(--vscode-font-family); padding: 10px; } .plan-node { margin-left: 20px; border-left: 2px solid var(--vscode-panel-border); padding-left: 10px; } .node-type { font-weight: bold; color: var(--vscode-symbolIcon-functionForeground); } .node-cost { color: var(--vscode-descriptionForeground); } </style> </head> <body> <h2>Execution Plan</h2> <div class="plan-tree"> ${this.renderPlanNode(plan.plan)} </div> Estimated cost: ${plan.estimatedCost} </body> </html>`; } private renderPlanNode(node: PlanNode): string { const children = node.children?.map(c => this.renderPlanNode(c)).join('') || ''; return ` <div class="plan-node"> ${node.type} (cost: ${node.cost}, rows: ${node.estimatedRows}) ${children} </div> `; } private getProfileHtml(profile: ProfileResult): string { // Similar to results but with profiling data return this.getResultsHtml(profile) + ` <h3>Profile</h3> DB Hits: ${profile.dbHits} Memory: ${(profile.memoryUsage / 1024 / 1024).toFixed(2)} MB `; } private getErrorHtml(error: any): string { return `<!DOCTYPE html> <html> <head> <style> body { font-family: var(--vscode-font-family); padding: 10px; } .error { color: var(--vscode-errorForeground); } .details { background: var(--vscode-editor-background); padding: 10px; margin-top: 10px; } </style> </head> <body> <h2 class="error">Error</h2> ${error.message || 'Unknown error'} ${error.code ? `Code: ${error.code}` : ''} ${error.details ? `<div class="details"><pre>${JSON.stringify(error.details, null, 2)}</pre></div>` : ''} </body> </html>`; } } </code></pre></div> <h3 id="testing" class="position-relative d-flex align-items-center group"> Testing <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="testing" aria-haspopup="dialog" aria-label="Share link: Testing"> Share link </button> </h3> <h4 id="unit-tests" class="position-relative d-flex align-items-center group"> Unit Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="unit-tests" aria-haspopup="dialog" aria-label="Share link: Unit Tests"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript">// test/completion.test.ts import * as assert from 'assert'; import { GeodeCompletionProvider } from '../src/completion'; suite('Completion Provider', () => { test('should complete labels after colon', async () => { const provider = new GeodeCompletionProvider(mockGeode); const document = createMockDocument('MATCH (u:'); const position = new Position(0, 10); const completions = await provider.provideCompletionItems(document, position); assert.ok(completions.length > 0); assert.ok(completions.some(c => c.label === 'User')); }); test('should complete properties after dot', async () => { const provider = new GeodeCompletionProvider(mockGeode); const document = createMockDocument('MATCH (u:User) WHERE u.'); const position = new Position(0, 23); const completions = await provider.provideCompletionItems(document, position); assert.ok(completions.length > 0); assert.ok(completions.some(c => c.label === 'email')); }); }); </code></pre></div> <h4 id="integration-tests" class="position-relative d-flex align-items-center group"> Integration Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="integration-tests" aria-haspopup="dialog" aria-label="Share link: Integration Tests"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript">// test/integration/execution.test.ts import * as vscode from 'vscode'; import * as assert from 'assert'; suite('Query Execution Integration', () => { suiteSetup(async () => { // Activate extension const ext = vscode.extensions.getExtension('geodedb.geode-gql'); await ext?.activate(); }); test('should execute simple query', async () => { const doc = await vscode.workspace.openTextDocument({ language: 'gql', content: 'RETURN 1 + 1 AS result;' }); await vscode.window.showTextDocument(doc); await vscode.commands.executeCommand('geode.executeQuery'); // Verify results panel appeared // Check result value }); }); </code></pre></div> <h3 id="publishing" class="position-relative d-flex align-items-center group"> Publishing <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="publishing" aria-haspopup="dialog" aria-label="Share link: Publishing"> Share link </button> </h3> <h4 id="vs-code-marketplace" class="position-relative d-flex align-items-center group"> VS Code Marketplace <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="vs-code-marketplace" aria-haspopup="dialog" aria-label="Share link: VS Code Marketplace"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">// package.json { "name": "geode-gql", "displayName": "Geode GQL", "description": "GQL language support for Geode graph database", "version": "1.0.0", "publisher": "geodedb", "engines": { "vscode": "^1.85.0" }, "categories": ["Programming Languages", "Linters", "Formatters"], "activationEvents": ["onLanguage:gql"], "main": "./out/extension.js", "contributes": { "languages": [{ "id": "gql", "extensions": [".gql"], "aliases": ["GQL"] }], "grammars": [{ "language": "gql", "scopeName": "source.gql", "path": "./syntaxes/gql.tmLanguage.json" }], "commands": [ { "command": "geode.executeQuery", "title": "Execute Query" } ] } } </code></pre></div>Publishing: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Install vsce npm install -g @vscode/vsce # Package extension vsce package # Publish vsce publish </code></pre></div> <h4 id="neovim-plugin-registry" class="position-relative d-flex align-items-center group"> Neovim Plugin Registry <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="neovim-plugin-registry" aria-haspopup="dialog" aria-label="Share link: Neovim Plugin Registry"> Share link </button> </h4>Submit to awesome-neovim and nvim-lspconfig. <h4 id="vimorg" class="position-relative d-flex align-items-center group"> Vim.org <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="vimorg" aria-haspopup="dialog" aria-label="Share link: Vim.org"> Share link </button> </h4>Submit to vim.org scripts or use vim-plug registry. <h3 id="best-practices" class="position-relative d-flex align-items-center group"> Best Practices <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="best-practices" aria-haspopup="dialog" aria-label="Share link: Best Practices"> Share link </button> </h3>Use LSP for Cross-Editor Features: Implement features in the language server to share across editors. Follow Editor Conventions: Match UI patterns and keybindings of the target editor. Handle Errors Gracefully: Provide clear error messages and recovery options. Support Offline Mode: Cache schema for basic completion when disconnected. Document Configuration: Provide clear documentation for all settings. Test Thoroughly: Cover unit, integration, and end-to-end scenarios. Version Compatibility: Support multiple editor versions where possible. Performance: Keep completion and diagnostics fast (< 100ms). <h3 id="related-topics" class="position-relative d-flex align-items-center group"> Related Topics <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="related-topics" aria-haspopup="dialog" aria-label="Share link: Related Topics"> Share link </button> </h3><ul> <li><a href="/tags/vscode/" >VS Code Extension</a> - VS Code integration details</li> <li><a href="/tags/neovim/" >Neovim Plugin</a> - Neovim configuration</li> <li><a href="/tags/vim/" >Vim Plugin</a> - Vim setup guide</li> <li><a href="/tags/editor/" >Editor Integrations</a> - Overview of all integrations</li> <li><a href="/tags/ide/" >IDE Integration</a> - IDE-specific features</li> <li><a href="/docs/development/lsp-guide/" >LSP Guide</a> - LSP implementation</li> </ul> <h3 id="further-reading" class="position-relative d-flex align-items-center group"> Further Reading <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="further-reading" aria-haspopup="dialog" aria-label="Share link: Further Reading"> Share link </button> </h3><ul> <li>Language Server Protocol Specification</li> <li>VS Code Extension API</li> <li>Neovim Plugin Development</li> <li>Tree-sitter Grammar Development</li> <li>TextMate Grammar Reference</li> <li>Editor Plugin Best Practices</li> </ul>

Popular

Related Articles

Neovim Plugin

Vim Plugin

VSCode Extension

Claude Code Plugin