kdljs

library0.3.0jsnpmunverified

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.

serialization web-framework

npm install kdljs

github ↗package ↗

INSTALL

IMPORT

SIG · KDLJS

kdljs

serializationjavascriptv0.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import { parse } from 'kdljs'

✗ const kdl = require('kdljs'); kdl.parse(...)

ESM import works in Node 14+ with type:module; CommonJS users must destructure require().

query

✓ import { query } from 'kdljs'

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

Same as parse — named export, not default.

KDLNode

✓ import type { KDLNode } from 'kdljs'

✗ import { KDLNode } from 'kdljs'

KDLNode is a TypeScript type, only import as type to avoid runtime errors in transpiled code.

parse (default)

✓ import { parse } from 'kdljs'

✗ import kdl from 'kdljs'

No default export exists; using default import will result in undefined.

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": [] } } ] */

Debug

Known issues

breakingparse() 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.

affects: >=0.0.0

breakingquery() 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.

affects: >=0.0.0

deprecatedThe 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');

affects: >=0.0.0

gotchaKDL 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.

affects: >=0.0.0

gotchaValues 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.

affects: >=0.0.0

Errors

Common errors & fixes

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

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'.

Uncaught TypeError: parse is not a function

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

fix

Use import { parse } from 'kdljs';

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

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

fix

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

document.forEach is not a function

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.

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/kdl-org/kdljs ↗

packagehttps://www.npmjs.com/package/kdljs ↗