{"id":18461,"library":"kdljs","title":"KDL-JS","description":"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.","status":"active","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/kdl-org/kdljs","tags":["javascript","kdl","parser","serializer","typescript"],"install":[{"cmd":"npm install kdljs","lang":"bash","label":"npm"},{"cmd":"yarn add kdljs","lang":"bash","label":"yarn"},{"cmd":"pnpm add kdljs","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM import works in Node 14+ with type:module; CommonJS users must destructure require().","wrong":"const kdl = require('kdljs'); kdl.parse(...)","symbol":"parse","correct":"import { parse } from 'kdljs'"},{"note":"Same as parse — named export, not default.","wrong":"const kdl = require('kdljs'); kdl.query(...)","symbol":"query","correct":"import { query } from 'kdljs'"},{"note":"KDLNode is a TypeScript type, only import as type to avoid runtime errors in transpiled code.","wrong":"import { KDLNode } from 'kdljs'","symbol":"KDLNode","correct":"import type { KDLNode } from 'kdljs'"},{"note":"No default export exists; using default import will result in undefined.","wrong":"import kdl from 'kdljs'","symbol":"parse (default)","correct":"import { parse } from 'kdljs'"}],"quickstart":{"code":"import { parse } from 'kdljs';\n\nconst document = parse(`\npackage {\n  name \"my-project\"\n  version \"1.0.0\"\n}\n`);\n\nconsole.log(JSON.stringify(document, null, 2));\n/*\n[\n  {\n    \"name\": \"package\",\n    \"properties\": {},\n    \"values\": [],\n    \"children\": [\n      {\n        \"name\": \"name\",\n        \"properties\": {},\n        \"values\": [\"my-project\"],\n        \"children\": [],\n        \"tags\": {\n          \"name\": undefined,\n          \"properties\": {},\n          \"values\": [undefined]\n        }\n      },\n      {\n        \"name\": \"version\",\n        \"properties\": {},\n        \"values\": [\"1.0.0\"],\n        \"children\": [],\n        \"tags\": {\n          \"name\": undefined,\n          \"properties\": {},\n          \"values\": [undefined]\n        }\n      }\n    ],\n    \"tags\": {\n      \"name\": undefined,\n      \"properties\": {},\n      \"values\": []\n    }\n  }\n]\n*/","lang":"typescript","description":"Demonstrates parsing a simple KDL document with nested nodes and string values, showing the resulting AST structure."},"warnings":[{"fix":"Iterate over the resulting array or access by index; do not assume a single root object.","message":"parse() returns an array of nodes, not a single root node. Each top-level KDL node becomes an element in the array.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Check array length instead of truthiness; handle empty arrays.","message":"query() returns an array of matched nodes, not a node or null. If no matches, returns an empty array.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Use const { parse, query } = require('kdljs');","message":"The use of require('kdljs') with destructuring is the only correct CommonJS pattern; importing via require('kdljs').default is undefined.","severity":"deprecated","affected_versions":">=0.0.0"},{"fix":"Always check array emptiness or use optional chaining; do not rely on undefined for missing fields.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use typeof to differentiate value types; type annotations are only preserved in tags.","message":"Values can be strings, numbers, booleans, or null. The parser returns native JS types, not KDL type annotations.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Install @kdl-org/kdljs-types if separate; ensure tsconfig.json has 'moduleResolution': 'node' or 'bundler'.","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).","error":"Cannot find module 'kdljs' or its corresponding type declarations."},{"fix":"Use import { parse } from 'kdljs';","cause":"Using default import (import kdl from 'kdljs') when there is no default export; parse is a named export.","error":"Uncaught TypeError: parse is not a function"},{"fix":"Ensure correct import: import { query } from 'kdljs';","cause":"Trying to use require('kdljs').query directly after default import confusion, or misspelling.","error":"Property 'query' does not exist on type 'typeof import(\"kdljs\")'"},{"fix":"parse returns an array, so use Array.isArray check or directly iterate.","cause":"Treating parse result as a single node object instead of an array; trying to call forEach on undefined.","error":"document.forEach is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}