Refactor language provider

Author: marcusolsson

src/components/ConfigEditor.tsx

@@ -6,7 +6,7 @@ import { JsonApiDataSourceOptions } from '../types';
 
 import {} from '@emotion/core';
 
-interface Props extends DataSourcePluginOptionsEditorProps<JsonApiDataSourceOptions> {}
+type Props = DataSourcePluginOptionsEditorProps<JsonApiDataSourceOptions>;
 
 /**
  * ConfigEditor lets the user configure connection details like the URL or

src/components/JsonPathQueryField.tsx

@@ -1,7 +1,6 @@
 import React from 'react';
 
 import { QueryField, SlatePrism, BracesPlugin, TypeaheadInput, TypeaheadOutput } from '@grafana/ui';
-import { JsonPathLanguageProvider } from 'languageProvider';
 import { JsonDataSource } from 'datasource';
 import { JsonApiQuery } from 'types';
 import { TimeRange } from '@grafana/data';
@@ -39,25 +38,15 @@ export const JsonPathQueryField: React.FC<Props> = ({
     }),
   ];
 
-  const jsonPathLanguageProvider = datasource.languageProvider as JsonPathLanguageProvider;
-
-  const cleanText = datasource.languageProvider ? jsonPathLanguageProvider.cleanText : undefined;
-
   const onTypeahead = async (input: TypeaheadInput): Promise<TypeaheadOutput> => {
-    if (!datasource.languageProvider) {
-      return { suggestions: [] };
-    }
-
-    const languageProvider = datasource.languageProvider as JsonPathLanguageProvider;
-
-    return languageProvider.provideCompletionItems(input, context, timeRange);
+    return datasource.languageProvider.getSuggestions(input, context, timeRange);
   };
 
   return (
     <QueryField
       additionalPlugins={plugins}
       query={query}
-      cleanText={cleanText}
+      cleanText={datasource.languageProvider.cleanText}
       onTypeahead={suggestions ? onTypeahead : undefined}
       onRunQuery={onBlur}
       onChange={onChange}

src/components/QueryEditor.tsx

@@ -21,8 +21,6 @@ import { css } from 'emotion';
 import { Pair } from '../types';
 import { JsonDataSource } from 'datasource';
 
-// type Props = QueryEditorProps<DataSource, JsonApiQuery, JsonApiDataSourceOptions>;
-
 interface Props {
   onRunQuery: () => void;
   onChange: (query: JsonApiQuery) => void;

src/datasource.ts

@@ -12,7 +12,6 @@ import {
   FieldType,
   ScopedVars,
   TimeRange,
-  LanguageProvider,
 } from '@grafana/data';
 import { getTemplateSrv } from '@grafana/runtime';
 
@@ -21,7 +20,7 @@ import { JsonApiQuery, JsonApiDataSourceOptions, Pair } from './types';
 import { JsonPathLanguageProvider } from './languageProvider';
 
 export class JsonDataSource extends DataSourceApi<JsonApiQuery, JsonApiDataSourceOptions> {
-  languageProvider: LanguageProvider;
+  languageProvider: JsonPathLanguageProvider;
   api: API;
 
   constructor(instanceSettings: DataSourceInstanceSettings<JsonApiDataSourceOptions>) {

src/languageProvider.ts

@@ -1,25 +1,39 @@
-import { LanguageProvider, TimeRange } from '@grafana/data';
-import { CompletionItem, TypeaheadInput, TypeaheadOutput } from '@grafana/ui';
+import { TimeRange } from '@grafana/data';
+import { TypeaheadInput, TypeaheadOutput } from '@grafana/ui';
 import { JSONPath } from 'jsonpath-plus';
 
 import { JsonApiQuery } from 'types';
 import { JsonDataSource } from 'datasource';
 
-export class JsonPathLanguageProvider extends LanguageProvider {
+/**
+ * JsonPathLanguageProvider provides suggestions for the QueryField onTypeahead
+ * callback.
+ */
+export class JsonPathLanguageProvider {
   datasource: JsonDataSource;
 
   constructor(datasource: JsonDataSource) {
-    super();
     this.datasource = datasource;
   }
 
+  // This is important if you don't want punctuation to interfere with your suggestions.
   cleanText = (s: string) => s.replace(/[{}[\]="(),!~+\-*/^%\|\$@\.]/g, '').trim();
 
-  async provideCompletionItems(
-    input: TypeaheadInput,
-    context: JsonApiQuery,
-    timeRange?: TimeRange
-  ): Promise<TypeaheadOutput> {
+  /**
+   * getSuggestions returns completion items for the current JSON Path and
+   * cursor position.
+   *
+   * In addition to the typeahead input, this method accepts the current query
+   * and time range as a context for the actual data source request.
+   *
+   * Since the language provider has a reference to the data source instance,
+   * we can invoke methods that aren't part of the DataSourceApi interface. In this case, we call a `metadataRequest`
+   * method to query the data source on-demand.
+   *
+   * Normally you'd have to parse the query language here. This function
+   * simplifies this by instead using JSON Path for getting the actual values.
+   */
+  async getSuggestions(input: TypeaheadInput, context: JsonApiQuery, timeRange?: TimeRange): Promise<TypeaheadOutput> {
     const { value } = input;
 
     const emptyResult: TypeaheadOutput = { suggestions: [] };
@@ -37,22 +51,32 @@ export class JsonPathLanguageProvider extends LanguageProvider {
 
     const toCursor = currentLine.slice(0, value.selection.anchor.offset);
 
+    // $.dat|
     const currIdentifier = /[a-zA-Z0-9]$/;
+
+    // $.data.|
     const nextIdentifier = /[\$\]a-zA-Z0-9]\.$/;
-    const currentNodeIdentifier = /@\.$/;
+
+    // $.data[|
     const enterBrackets = /\[$/;
 
-    const isValid =
+    // $.data[?(@.|
+    const currentNodeIdentifier = /@\.$/;
+
+    // Here we check whether the cursor is in a position where it should
+    // suggest.
+    const shouldSuggest =
       currIdentifier.test(toCursor) ||
       nextIdentifier.test(toCursor) ||
       currentNodeIdentifier.test(toCursor) ||
       enterBrackets.test(toCursor);
 
-    if (!isValid) {
+    if (!shouldSuggest) {
       return emptyResult;
     }
 
-    const response: any = await this.datasource.metadataRequest(context, timeRange);
+    // Get the actual JSON for parsing.
+    const response = await this.datasource.metadataRequest(context, timeRange);
 
     if (enterBrackets.test(toCursor)) {
       return {
@@ -64,9 +88,9 @@ export class JsonPathLanguageProvider extends LanguageProvider {
               { label: ':', documentation: 'Returns a slice of the array.' },
               {
                 label: '?',
-                documentation: 'Returns elements based on a filter expression.',
                 insertText: '?()',
                 move: -1,
+                documentation: 'Returns elements based on a filter expression.',
               },
             ],
           },
@@ -76,30 +100,37 @@ export class JsonPathLanguageProvider extends LanguageProvider {
 
     const insideBrackets = toCursor.lastIndexOf('[') > toCursor.lastIndexOf(']');
 
+    // Construct a JSON Path that returns the items in the current context.
     const path = insideBrackets
       ? toCursor.slice(0, toCursor.lastIndexOf('[') + 1) + ':]'
       : currentLine.slice(0, currentLine.lastIndexOf('.'));
 
     const values = JSONPath({ path, json: response });
 
+    // Don't attempt to suggest if this is a leaf node, e.g. strings, numbers, and booleans.
     if (typeof values[0] !== 'object') {
       return emptyResult;
     }
 
-    const items: CompletionItem[] = Object.entries(values[0]).map(([key, value]) => {
-      return Array.isArray(value)
-        ? { label: key, insertText: key + '[]', move: -1, documentation: `_array (${value.length})_` }
-        : { label: key, documentation: `_${typeof value}_\n\n**Preview:**\n\n\`${value}\`` };
-    });
-
-    return { suggestions: [{ label: 'Elements', items }] };
+    return {
+      suggestions: [
+        {
+          label: 'Elements', // Name of the suggestion group
+          items: Object.entries(values[0]).map(([key, value]) => {
+            return Array.isArray(value)
+              ? {
+                  label: key, // Text to display in the suggestion list
+                  insertText: key + '[]', // When selecting an array, we automatically insert the brackets ...
+                  move: -1, // ... and put the cursor between them
+                  documentation: `_array (${value.length})_`, // Markdown documentation for the suggestion
+                }
+              : {
+                  label: key,
+                  documentation: `_${typeof value}_\n\n**Preview:**\n\n\`${value}\``,
+                };
+          }),
+        },
+      ],
+    };
   }
-
-  request = async (url: string, params?: any): Promise<any> => {
-    return undefined;
-  };
-
-  start = async (): Promise<any[]> => {
-    return [];
-  };
 }