{"id":20731684,"url":"https://github.com/bgotink/kdl","last_synced_at":"2025-04-23T22:06:24.047Z","repository":{"id":45808129,"uuid":"507570852","full_name":"bgotink/kdl","owner":"bgotink","description":"A parser and stringifier for the KDL Document Language","archived":false,"fork":false,"pushed_at":"2025-04-05T20:21:19.000Z","size":3794,"stargazers_count":19,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-23T22:06:09.183Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://github.bram.dev/kdl/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bgotink.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-26T12:40:05.000Z","updated_at":"2025-04-05T20:21:23.000Z","dependencies_parsed_at":"2024-12-16T15:34:34.655Z","dependency_job_id":"11e4e59e-abf8-44f4-a7c7-9d644bd86f7a","html_url":"https://github.com/bgotink/kdl","commit_stats":{"total_commits":54,"total_committers":1,"mean_commits":54.0,"dds":0.0,"last_synced_commit":"d0875a960dd761546c0d4516313f735283912d7f"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgotink%2Fkdl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgotink%2Fkdl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgotink%2Fkdl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgotink%2Fkdl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bgotink","download_url":"https://codeload.github.com/bgotink/kdl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250522298,"owners_count":21444511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-17T05:16:24.353Z","updated_at":"2025-04-23T22:06:22.875Z","avatar_url":"https://github.com/bgotink.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `@bgotink/kdl`\n\nThis package contains a parser and stringifier for the [KDL Document Language][kdl-site], a node-based, human-friendly configuration and serialization format.\n\nThe parser in this package focuses on parsing documents in a way that allows for format-preserving modifications. This is most useful when working with KDL files maintained by humans.\n\n## Install\n\n```sh\nyarn add @bgotink/kdl\n# or\nnpm install @bgotink/kdl\n# or\npnpm add @bgotink/kdl\n# or ...\n```\n\n## Usage\n\nThe examples below assume a Node.js environment.\nThe `@bgotink/kdl` package works in any javascript runtime, including browsers, as long as it supports relatively modern browser standards.\nIf you're trying to run these samples in a non-Node.js runtime, replace the import for `assert` with something equivalent in your runtime.\n\n```js\nimport {parse, format} from \"@bgotink/kdl\";\nimport assert from \"node:assert/strict\";\n\nconst doc = parse(String.raw`\n\tnode \"value\" #\"other value\"# 2.0 4 #false \\\n\t\t\t#null -0 {\n\t\tchild; \"child too\"\n\t}\n`);\n\ndoc.nodes[0].children.nodes[0].entries.push(\n\tparse(\n\t\tString.raw`/-lorem=\"ipsum\" \\\n\t\t\tdolor=#true`,\n\t\t{as: \"entry\"},\n\t),\n);\n\nassert.equal(\n\tformat(doc),\n\tString.raw`\n\tnode \"value\" #\"other value\"# 2.0 4 #false \\\n\t\t\t#null -0 {\n\t\tchild /-lorem=\"ipsum\" \\\n\t\t\tdolor=#true; \"child too\"\n\t}\n`,\n);\n```\n\n## JSON-in-KDL (JiK)\n\nThis package exports function from `@bgotink/kdl/json` to parse and stringify KDL documents as JSON-in-KDL (JiK) 4.0.0. For information on the format, see [the JiK 4.0.0 specification][jik-spec].\n\n```js\nimport {parse} from \"@bgotink/kdl/json\";\nimport assert from \"node:assert/strict\";\n\nassert.deepEqual(\n\tparse(\n\t\tString.raw`\n\t\t\t- {\n\t\t\t\tprop #false\n\t\t\t\totherProp {\n\t\t\t\t\t- 0\n\t\t\t\t\t- 2\n\t\t\t\t\t- 4\n\t\t\t\t}\n\t\t\t}\n\t\t`,\n\t),\n\t{\n\t\tprop: false,\n\t\totherProp: [0, 2, 4],\n\t},\n);\n```\n\nThere are four functions:\n\n- `parse` and `stringify` turn text into the encoded JSON value and back. These functions are useful for encoding/decoding entire JiK files.\n- `toJson` and `fromJson` turn KDL nodes into the encoded JSON value and back. These functions give more fine-grained control over the output, and can be used for e.g. encoding/decoding a JiK node embedded in a KDL document.\n\n## (De)Serialization\n\nThe package contains utilities for (de)serialization in `@bgotink/kdl/dessert`.\n\n```js\nimport {parse} from \"@bgotink/kdl/dessert\";\nimport assert from \"node:assert/strict\";\n\nassert.deepEqual(\n\tparse(\n\t\tString.raw`\n\t\t\tname \"my-package\"\n\t\t\t\n\t\t\tdependency \"@bgotink/kdl\" range=\"^0.2.0\"\n\t\t\tdependency \"prettier\" range=\"^3\" dev=#true\n\t\t`,\n\t\t(ctx) =\u003e {\n\t\t\tconst dependencies = {};\n\t\t\tconst devDependencies = {};\n\n\t\t\tconst name = ctx.child.single.required(\"name\", (ctx) =\u003e\n\t\t\t\tctx.argument.required(\"string\"),\n\t\t\t);\n\n\t\t\tfor (const dependency of ctx.children(\"dependency\", (ctx) =\u003e ({\n\t\t\t\tname: ctx.argument.required(\"string\"),\n\t\t\t\trange: ctx.property(\"range\", \"string\") ?? \"*\",\n\t\t\t\tdev: ctx.property(\"dev\", \"boolean\") ?? false,\n\t\t\t}))) {\n\t\t\t\t(dependency.dev ? devDependencies : dependencies)[dependency.name] =\n\t\t\t\t\tdependency.range;\n\t\t\t}\n\n\t\t\treturn {name, dependencies, devDependencies};\n\t\t},\n\t),\n\t{\n\t\tname: \"my-package\",\n\t\tdependencies: {\n\t\t\t\"@bgotink/kdl\": \"^0.2.0\",\n\t\t},\n\t\tdevDependencies: {\n\t\t\tprettier: \"^3\",\n\t\t},\n\t},\n);\n```\n\n## KDL v1\n\nThe package exports two functions from `@bgotink/kdl/v1-compat` to support documents written in KDL v1:\n\n- `parse` parses a KDL v1 document and transforms all linked formatting information to turn it into a valid KDL v2 document.\n  If the resulting document is passed to `format()`, the resulting string will be the same document but in KDL v2 syntax. It will include all comments and formatting applied by the original document's author.\n- `parseCompat` parses a document that's either KDL v2 or KDL v1 and returns a valid KDL v2 document.\n  This is a helper function that combines the regular `parse` function with the v1-compat `parse` function into a single function that supports both formats.\n\n## Quirks\n\nThis package turns KDL documents into JavaScript objects and vice versa. It is therefore limited by the JavaScript language.\n\n### Properties\n\nMultiple properties with the same name are allowed. All duplicated will be preserved, meaning those documents will correctly round-trip. When using `node.getProperty()`/`node.getProperties()`/`node.getPropertyEntry()`, the last property with that name's value will be returned, effectively shadowing any earlier duplicates. Using `node.getPropertyEntries()`/`node.entries` does expose the shadowed duplicates, leaving it up to the caller to handle these. Passing the node through `clearFormat()` removes these shadowed duplicates.\n\n### Numbers\n\nJavaScript stores all numbers as 64-bit [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754) floating point numbers. This limits what integer values can be used safely. These limits are lower than you might expect if you're used to working in environments that have a separate 64-bit integer data type.\n\nThe original representation of parsed numbers is retained, unless `clearFormat` is called on the value or any entry/node/document containing the value.\n\n## License\n\nThis package is licensed under the MIT license, which can be found in `LICENSE.md`.\n\nThe test suite at `test/upstream` is part of the [KDL specification][kdl-spec-repo] and is available under the Creative Commons Attribution-ShareAlike 4.0 International License.\n\n[kdl-site]: https://kdl.dev/\n[kdl-spec-repo]: https://github.com/kdl-org/kdl\n[kdl-rs]: https://github.com/kdl-org/kdl-rs\n[kdljs]: https://github.com/kdl-org/kdljs\n[jik-spec]: https://github.com/kdl-org/kdl/blob/76d5dd542a9043257bc65476c0a70b94667052a7/JSON-IN-KDL.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgotink%2Fkdl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbgotink%2Fkdl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgotink%2Fkdl/lists"}