{"id":19584805,"url":"https://github.com/flex-development/unist-util-builder","last_synced_at":"2025-04-27T11:32:51.165Z","repository":{"id":241677832,"uuid":"807405648","full_name":"flex-development/unist-util-builder","owner":"flex-development","description":"unist utility to build trees","archived":false,"fork":false,"pushed_at":"2024-10-24T07:05:35.000Z","size":1749,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-25T01:16:46.979Z","etag":null,"topics":["ast","builder","docast","esast","mdast","syntax","syntax-tree","tree","unist","unist-util","util"],"latest_commit_sha":null,"homepage":"https://github.com/flex-development/unist-util-builder","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flex-development.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/funding.yml","license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","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},"funding":{"github":["flex-development"]}},"created_at":"2024-05-29T03:34:17.000Z","updated_at":"2024-10-24T07:04:09.000Z","dependencies_parsed_at":"2024-08-26T07:48:07.040Z","dependency_job_id":"20ff72cf-d4c0-4bde-998f-547786f9a298","html_url":"https://github.com/flex-development/unist-util-builder","commit_stats":null,"previous_names":["flex-development/unist-util-builder"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Funist-util-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Funist-util-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Funist-util-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Funist-util-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flex-development","download_url":"https://codeload.github.com/flex-development/unist-util-builder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224069554,"owners_count":17250454,"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":["ast","builder","docast","esast","mdast","syntax","syntax-tree","tree","unist","unist-util","util"],"created_at":"2024-11-11T07:49:50.173Z","updated_at":"2024-11-11T07:49:51.452Z","avatar_url":"https://github.com/flex-development.png","language":"JavaScript","funding_links":["https://github.com/sponsors/flex-development"],"categories":[],"sub_categories":[],"readme":"# unist-util-builder\n\n[![github release](https://img.shields.io/github/v/release/flex-development/unist-util-builder.svg?include_prereleases\u0026sort=semver)](https://github.com/flex-development/unist-util-builder/releases/latest)\n[![npm](https://img.shields.io/npm/v/@flex-development/unist-util-builder.svg)](https://npmjs.com/package/@flex-development/unist-util-builder)\n[![codecov](https://codecov.io/gh/flex-development/unist-util-builder/graph/badge.svg?token=qZFDFVZtym)](https://codecov.io/gh/flex-development/unist-util-builder)\n[![module type: esm](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://github.com/voxpelli/badges-cjs-esm)\n[![license](https://img.shields.io/github/license/flex-development/unist-util-builder.svg)](LICENSE.md)\n[![conventional commits](https://img.shields.io/badge/-conventional%20commits-fe5196?logo=conventional-commits\u0026logoColor=ffffff)](https://conventionalcommits.org/)\n[![typescript](https://img.shields.io/badge/-typescript-3178c6?logo=typescript\u0026logoColor=ffffff)](https://typescriptlang.org/)\n[![vitest](https://img.shields.io/badge/-vitest-6e9f18?style=flat\u0026logo=vitest\u0026logoColor=ffffff)](https://vitest.dev/)\n[![yarn](https://img.shields.io/badge/-yarn-2c8ebb?style=flat\u0026logo=yarn\u0026logoColor=ffffff)](https://yarnpkg.com/)\n\n[unist][unist] utility to build trees\n\n## Contents\n\n- [What is this?](#what-is-this)\n- [When should I use this?](#when-should-i-use-this)\n- [Install](#install)\n- [Use](#use)\n- [API](#api)\n  - [`u(type[, builder])`](#utype-builder)\n    - [`u(type, children`](#utype-children)\n    - [`u(type, properties)`](#utype-properties)\n    - [`u(type, value`](#utype-value)\n  - [`AnyBuilder`](#anybuilder)\n  - [`Builder\u003c[T]\u003e`](#buildert)\n  - [`BuilderChildren\u003c[T]\u003e`](#builderchildrent)\n  - [`BuilderProps`](#builderprops)\n  - [`BuilderValue`](#buildervalue)\n- [Types](#types)\n- [Related](#related)\n- [Contribute](#contribute)\n\n## What is this?\n\nThis is a tiny but useful utility for building [*trees*][tree].\n\n## When should I use this?\n\nUse this package when you need to create nodes.\n\n## Install\n\nThis package is [ESM only][esm].\n\nIn Node.js (version 18+) with [yarn][yarn]:\n\n```sh\nyarn add @flex-development/unist-util-builder\n```\n\n\u003cblockquote\u003e\n  \u003csmall\u003e\n    See \u003ca href='https://yarnpkg.com/protocol/git'\u003eGit - Protocols | Yarn\u003c/a\u003e\n    \u0026nbsp;for details regarding installing from Git.\n  \u003c/small\u003e\n\u003c/blockquote\u003e\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```ts\nimport { u } from 'https://esm.sh/@flex-development/unist-util-builder'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import { u } from 'https://esm.sh/@flex-development/unist-util-builder'\n\u003c/script\u003e\n```\n\n## Use\n\n```ts\nimport { u } from '@flex-development/unist-util-builder'\nimport type { Parent } from 'unist'\n\nconst tree: Parent = u('root', [\n  u('subtree', {\n    children: [\n      u('node', [u('leaf', 'leaf 1'), u('leaf', 'leaf 2')]),\n      u('leaf', { value: 'leaf 3' }),\n      u('void')\n    ],\n    data: { id: 1 }\n  })\n])\n\nconsole.dir(tree, { depth: null })\n```\n\n...yields:\n\n```sh\n{\n  type: 'root',\n  children: [\n    {\n      type: 'subtree',\n      children: [\n        {\n          type: 'node',\n          children: [\n            { type: 'leaf', value: 'leaf 1' },\n            { type: 'leaf', value: 'leaf 2' }\n          ]\n        },\n        { type: 'leaf', value: 'leaf 3' },\n        { type: 'void' }\n      ],\n      data: { id: 1 }\n    }\n  ]\n}\n```\n\n## API\n\nThis package exports the identifier [`u`](#utype-builder). There is no default export.\n\n### `u(type[, builder])`\n\nBuild a node using a [child node array](#utype-children), [properties object](#utype-properties), or\n[value](#utype-value).\n\nIf `builder` is omitted, a void node (a node with only a `type` field) will be created.\n\n#### Type Parameters\n\n- `T` ([`Node`][node]) - node to build\n\n##### Parameters\n\n- `type` ([`Type\u003cT\u003e`][type]) - node type\n- `builder` ([`Builder\u003cT\u003e`](#buildert), optional) - node children, properties, or value\n\n##### Returns\n\n`T` new node.\n\n#### `u(type, children)`\n\nCreate a [*parent*][parent].\n\n##### Type Parameters\n\n- `T` ([`Type`][type]) - node type\n- `Children` ([`BuilderChildren`](#builderchildrent)) - node children\n\n##### Parameters\n\n- `type` (`T`) - node type\n- `children` (`Children`) - node children\n\n##### Returns\n\n`{ children: Children; type: T }` new parent node.\n\n#### `u(type, properties)`\n\nBuild a node using a properties object.\n\n\u003e 👉 Properties of a node are all fields except `type`. If a `type` field is on the builder object, it will be ignored.\n\n##### Type Parameters\n\n- `T` ([`Type`][type]) - node type\n- `Properties` ([`BuilderProps`](#builderprops)) - node properties\n\n##### Parameters\n\n- `type` (`T`) - node type\n- `properties` (`Properties`) - node properties\n\n##### Returns\n\n`Properties \u0026 { type: T }` new node.\n\n#### `u(type, value)`\n\nCreate a [*literal*][literal].\n\n- `bigint`\n- `boolean`\n- `number`\n- `string`\n- `null`\n\n\u003e 👉 Undefined literals must be created using a properties object, rather than a value. Passing `undefined` will create\n\u003e a void node (a node with only a `type` field).\n\n##### Type Parameters\n\n- `T` ([`Type`][type]) - node type\n- `Value` ([`BuilderValue`](#buildervalue)) - node value\n\n##### Parameters\n\n- `type` (`T`) - node type\n- `value` (`Value`) - node value\n\n##### Returns\n\n`{ type: T; value: Value }` new literal node.\n\n### `AnyBuilder`\n\nUnion of types that can be used to build any node (TypeScript type).\n\n```ts\ntype AnyBuilder = BuilderChildren | BuilderProps | BuilderValue\n```\n\n### `Builder\u003c[T]\u003e`\n\nUnion of node children, properties, and value (TypeScript type).\n\n**See also**: [`MatchChildren`][matchchildren], [`MatchProperties`][matchproperties]\n\n```ts\ntype Builder\u003cN extends Node = Node\u003e =\n  | Extract\u003cMatchValue\u003cN, Type\u003cN\u003e\u003e, BuilderValue\u003e\n  | MatchChildren\u003cN, Type\u003cN\u003e\u003e\n  | MatchProperties\u003cN, Type\u003cN\u003e\u003e\n```\n\n### `BuilderChildren\u003c[T]\u003e`\n\nList of [*child*][child] nodes used to build a [parent] (TypeScript type).\n\n```ts\ntype BuilderChildren\u003cT extends Node = Node\u003e = T[]\n```\n\n### `BuilderProps`\n\nNode properties object (TypeScript type).\n\n\u003e 👉 Properties of a node are all fields except `type`. If a `type` field is present on a builder object, it will be\n\u003e ignored.\n\n```ts\ntype BuilderProps = { [x: string]: unknown }\n```\n\n### `BuilderValue`\n\nUnion of values that can be used to build a [literal][literal] (TypeScript type).\n\n\u003e 👉 Undefined literals must be created using a properties object, rather than a value. Passing `undefined` will create\n\u003e a void node (a node with only a `type` field).\n\n```ts\ntype BuilderValue = bigint | boolean | number | string | null\n```\n\n## Types\n\nThis package is fully typed with [TypeScript][typescript].\n\n## Related\n\n- [`esast-util-builder`][esast-util-builder] \u0026mdash; build [esast][esast] nodes\n\n## Contribute\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\nThis project has a [code of conduct](CODE_OF_CONDUCT.md). By interacting with this repository, organization, or\ncommunity you agree to abide by its terms.\n\n[child]: https://github.com/syntax-tree/unist#child\n[esast-util-builder]: https://github.com/flex-development/esast-util-builder\n[esast]: https://github.com/flex-development/esast\n[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n[esmsh]: https://esm.sh/\n[literal]: https://github.com/syntax-tree/unist#literal\n[matchchildren]: https://github.com/flex-development/unist-util-types#matchchildrenn-check\n[matchproperties]: https://github.com/flex-development/unist-util-types#matchpropertiesn-check\n[node]: https://github.com/syntax-tree/unist#node\n[parent]: https://github.com/syntax-tree/unist#parent\n[tree]: https://github.com/syntax-tree/unist#tree\n[type]: https://github.com/flex-development/unist-util-types#typet\n[typescript]: https://www.typescriptlang.org\n[unist]: https://github.com/syntax-tree/unist\n[yarn]: https://yarnpkg.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Funist-util-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflex-development%2Funist-util-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Funist-util-builder/lists"}