Implementation:Apache Druid Hjson Context

Knowledge Sources	Apache_Druid
Domains	Web Console, Editor, Autocompletion
Last Updated	2026-02-10 10:00 GMT

Overview

Provides context analysis for HJSON documents by parsing text up to the cursor position and returning structural information about the current editing location.

Description

This module implements a state-machine-based HJSON parser that analyzes text from the beginning of a document to the cursor position. It determines the cursor's structural context within the JSON hierarchy, including the path of keys leading to the current position, whether the user is editing a key or a value, the current key name, whether the cursor is inside a comment, and the current object being edited. This context information is used by the autocompletion system to provide intelligent suggestions in the HJSON editor.

Usage

Call getHjsonContext() with the HJSON text from the start of the document to the cursor position. The returned HjsonContext object is used by completion providers to determine what suggestions to offer.

Code Reference

Source Location

• Repository: Apache Druid
• File: web-console/src/utils/hjson-context.ts
• Lines: 1-408

Signature

export interface HjsonContext {
  path: string[];
  isEditingKey: boolean;
  currentKey?: string;
  isEditingComment: boolean;
  currentObject: any;
}

export function getHjsonContext(hjson: string): HjsonContext

Import

import { getHjsonContext } from '../../utils/hjson-context';
import type { HjsonContext } from '../../utils/hjson-context';

I/O Contract

Inputs

Name	Type	Required	Description
hjson	string	Yes	The HJSON text from the beginning of the document to the current cursor position.

Outputs

Name	Type	Description
path	string[]	The path of keys from root to the current cursor position. For arrays, indices are represented as string keys (e.g., ["filters", "0", "dimension"]). Empty array at root level.
isEditingKey	boolean	true if the cursor is positioned where a key should be entered; false if where a value should be entered.
currentKey	undefined	The key for the value being edited when isEditingKey is false. Undefined when editing a key.
isEditingComment	boolean	true if the cursor is inside a single-line or multi-line comment.
currentObject	any	The current JSON object being edited at the cursor position, providing context about what properties already exist.

Usage Examples

Basic Context Analysis

import { getHjsonContext } from '../../utils/hjson-context';

// Cursor after "dataSource": in a query spec
const context = getHjsonContext('{\n  "queryType": "topN",\n  "dataSource": ');

// Result:
// {
//   path: [],
//   isEditingKey: false,
//   currentKey: "dataSource",
//   isEditingComment: false,
//   currentObject: { queryType: "topN" }
// }

Nested Object Context

const context = getHjsonContext('{\n  "filter": {\n    "type": "selector",\n    ');

// Result:
// {
//   path: ["filter"],
//   isEditingKey: true,
//   currentKey: undefined,
//   isEditingComment: false,
//   currentObject: { type: "selector" }
// }

Internals

State Machine

The parser uses a character-by-character state machine with these states:

State	Description
normal	Default state, processing structural characters and whitespace
quoted-string	Inside a double-quoted or single-quoted string
single-line-comment	Inside a // or # comment until newline
multi-line-comment	Inside a /* ... */ block comment
multiline-string	Inside a triple-single-quoted HJSON multiline string

Tracking Stacks

The parser maintains parallel stacks:

• containerStack -- Tracks whether the current container is an object or array, with array index tracking
• objectStack -- Tracks the actual parsed objects/arrays being built, enabling currentObject in the output
• path -- Tracks the key path from root to current position

Helper Functions

Function	Description
extractKey(token)	Strips quotes from a key token if present
parseValue(token)	Converts a string token to the appropriate JS type (boolean, null, number, or string)
parseMultilineString(content)	Processes triple-quoted HJSON multiline strings, trimming common leading whitespace

Related Pages

• Environment:Apache_Druid_Web_Console_Development