KDL-JS

0.3.0 verified Sat Apr 25 auth: no javascript

A JavaScript/TypeScript library for parsing and querying the KDL Document Language (v0.3.0). Provides a parse() function returning an AST of nodes, and a query() function for CSS-selector-like traversal. Unlike generic YAML/TOML parsers, it natively handles KDL-specific features like type-annotated values, interspersed properties/values, and node tags. Ships TypeScript types. Release cadence is irregular; the package is relatively stable but may break on future KDL spec changes.

Common errors

error Cannot find module 'kdljs' or its corresponding type declarations. ↓

cause Package has a typings field in package.json, but it may not be resolved in some TS setups (e.g., bundlers or older TS versions).

fix

Install @kdl-org/kdljs-types if separate; ensure tsconfig.json has 'moduleResolution': 'node' or 'bundler'.

error Uncaught TypeError: parse is not a function ↓

cause Using default import (import kdl from 'kdljs') when there is no default export; parse is a named export.

fix

Use import { parse } from 'kdljs';

error Property 'query' does not exist on type 'typeof import("kdljs")' ↓

cause Trying to use require('kdljs').query directly after default import confusion, or misspelling.

fix

Ensure correct import: import { query } from 'kdljs';

error document.forEach is not a function ↓

cause Treating parse result as a single node object instead of an array; trying to call forEach on undefined.

fix

parse returns an array, so use Array.isArray check or directly iterate.

Warnings

breaking parse() returns an array of nodes, not a single root node. Each top-level KDL node becomes an element in the array. ↓

fix Iterate over the resulting array or access by index; do not assume a single root object.

breaking query() returns an array of matched nodes, not a node or null. If no matches, returns an empty array. ↓

fix Check array length instead of truthiness; handle empty arrays.

deprecated The use of require('kdljs') with destructuring is the only correct CommonJS pattern; importing via require('kdljs').default is undefined. ↓

fix Use const { parse, query } = require('kdljs');

gotcha KDL node children are always an array (even if empty), and tags are always an object with name, properties, values. Node values are always an array. ↓

fix Always check array emptiness or use optional chaining; do not rely on undefined for missing fields.

gotcha Values can be strings, numbers, booleans, or null. The parser returns native JS types, not KDL type annotations. ↓

fix Use typeof to differentiate value types; type annotations are only preserved in tags.

Install

npm install kdljs

yarn add kdljs

pnpm add kdljs

Imports

parse
wrong
```
const kdl = require('kdljs'); kdl.parse(...)
```
correct
```
import { parse } from 'kdljs'
```
ESM import works in Node 14+ with type:module; CommonJS users must destructure require().

query

wrong

const kdl = require('kdljs'); kdl.query(...)

correct

import { query } from 'kdljs'

Same as parse — named export, not default.

KDLNode
wrong
```
import { KDLNode } from 'kdljs'
```
correct
```
import type { KDLNode } from 'kdljs'
```
KDLNode is a TypeScript type, only import as type to avoid runtime errors in transpiled code.
parse (default)
wrong
```
import kdl from 'kdljs'
```
correct
```
import { parse } from 'kdljs'
```
No default export exists; using default import will result in undefined.

Quickstart

Demonstrates parsing a simple KDL document with nested nodes and string values, showing the resulting AST structure.

import { parse } from 'kdljs';

const document = parse(`
package {
  name "my-project"
  version "1.0.0"
}
`);

console.log(JSON.stringify(document, null, 2));
/*
[
  {
    "name": "package",
    "properties": {},
    "values": [],
    "children": [
      {
        "name": "name",
        "properties": {},
        "values": ["my-project"],
        "children": [],
        "tags": {
          "name": undefined,
          "properties": {},
          "values": [undefined]
        }
      },
      {
        "name": "version",
        "properties": {},
        "values": ["1.0.0"],
        "children": [],
        "tags": {
          "name": undefined,
          "properties": {},
          "values": [undefined]
        }
      }
    ],
    "tags": {
      "name": undefined,
      "properties": {},
      "values": []
    }
  }
]
*/