feat: u

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>

.codecov.yml

@@ -89,4 +89,5 @@ ignore:
   - '!src/index.ts'
 
 profiling:
-  critical_files_paths: []
+  critical_files_paths:
+    - src/u.ts

.dictionary.txt

@@ -1,5 +1,6 @@
 attw
 cefc
+codecov
 commitlintrc
 dedupe
 deno
@@ -14,6 +15,7 @@ gpgsign
 hmarr
 jchen
 kaisugi
+lcov
 lintstagedrc
 mdast
 mkbuild

.github/infrastructure.yml

@@ -168,7 +168,7 @@ repository:
   automated_security_fixes: true
   default_branch: main
   delete_branch_on_merge: true
-  description: unist utility to create trees
+  description: unist utility to build trees
   has_issues: true
   has_projects: true
   has_wiki: false

README.md

@@ -2,7 +2,7 @@
 
 [![github release](https://img.shields.io/github/v/release/flex-development/unist-util-builder.svg?include_prereleases&sort=semver)](https://github.com/flex-development/unist-util-builder/releases/latest)
 [![npm](https://img.shields.io/npm/v/@flex-development/unist-util-builder.svg)](https://npmjs.com/package/@flex-development/unist-util-builder)
-[![codecov](https://codecov.io/gh/flex-development/unist-util-builder/graph/badge.svg?token=)](https://codecov.io/gh/flex-development/unist-util-builder)
+[![codecov](https://codecov.io/gh/flex-development/unist-util-builder/graph/badge.svg?token=qZFDFVZtym)](https://codecov.io/gh/flex-development/unist-util-builder)
 [![module type: esm](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://github.com/voxpelli/badges-cjs-esm)
 [![license](https://img.shields.io/github/license/flex-development/unist-util-builder.svg)](LICENSE.md)
 [![conventional commits](https://img.shields.io/badge/-conventional%20commits-fe5196?logo=conventional-commits&logoColor=ffffff)](https://conventionalcommits.org/)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flex-development/unist-util-builder",
-  "description": "unist utility to create trees",
+  "description": "unist utility to build trees",
   "version": "1.0.0",
   "keywords": [
     "ast",
@@ -86,6 +86,7 @@
     "@commitlint/types": "19.0.3",
     "@flex-development/commitlint-config": "1.0.1",
     "@flex-development/decorator-regex": "2.0.0",
+    "@flex-development/docast": "1.0.0-alpha.17",
     "@flex-development/esm-types": "2.0.0",
     "@flex-development/grease": "3.0.0-alpha.9",
     "@flex-development/mkbuild": "1.0.0-alpha.23",
@@ -97,6 +98,7 @@
     "@types/chai": "4.3.16",
     "@types/eslint": "8.56.10",
     "@types/is-ci": "3.0.4",
+    "@types/mdast": "4.0.4",
     "@types/node": "20.12.12",
     "@types/node-notifier": "8.0.5",
     "@typescript-eslint/eslint-plugin": "7.11.0",
@@ -144,6 +146,7 @@
     "yaml-eslint-parser": "1.2.3"
   },
   "resolutions": {
+    "@types/mdast": "4.0.4",
     "chai": "5.1.1"
   },
   "engines": {

src/__snapshots__/u.snap

@@ -0,0 +1,63 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`unit:u > children builder > should build parent 1`] = `
+{
+  "children": [],
+  "type": "root",
+}
+`;
+
+exports[`unit:u > properties builder > should build node 1`] = `
+{
+  "type": "undefined",
+  "value": undefined,
+}
+`;
+
+exports[`unit:u > should build leaf if builder is undefined 1`] = `
+{
+  "type": "root",
+}
+`;
+
+exports[`unit:u > value builder > RegExp > should build literal 1`] = `
+{
+  "type": "regexp",
+  "value": /\\^node:/,
+}
+`;
+
+exports[`unit:u > value builder > bigint > should build literal 1`] = `
+{
+  "type": "bigint",
+  "value": 3n,
+}
+`;
+
+exports[`unit:u > value builder > boolean > should build literal 1`] = `
+{
+  "type": "boolean",
+  "value": true,
+}
+`;
+
+exports[`unit:u > value builder > null > should build literal 1`] = `
+{
+  "type": "null",
+  "value": null,
+}
+`;
+
+exports[`unit:u > value builder > number > should build literal 1`] = `
+{
+  "type": "number",
+  "value": 3,
+}
+`;
+
+exports[`unit:u > value builder > string > should build literal 1`] = `
+{
+  "type": "string",
+  "value": "node",
+}
+`;

src/__tests__/index.e2e.spec.ts

@@ -0,0 +1,12 @@
+/**
+ * @file E2E Tests - api
+ * @module unist-util-builder/tests/e2e/api
+ */
+
+import * as testSubject from '../index'
+
+describe('e2e:unist-util-builder', () => {
+  it('should expose public api', () => {
+    expect(testSubject).to.have.keys(['u'])
+  })
+})

src/__tests__/u.spec.ts

@@ -0,0 +1,62 @@
+/**
+ * @file Unit Tests - u
+ * @module unist-util-builder/tests/unit/u
+ */
+
+import testSubject from '../u'
+
+describe('unit:u', () => {
+  it('should build leaf if builder is undefined', () => {
+    expect(testSubject('root')).toMatchSnapshot()
+  })
+
+  describe('children builder', () => {
+    it('should build parent', () => {
+      expect(testSubject('root', [])).toMatchSnapshot()
+    })
+  })
+
+  describe('properties builder', () => {
+    it('should build node', () => {
+      expect(testSubject('undefined', { value: undefined })).toMatchSnapshot()
+    })
+  })
+
+  describe('value builder', () => {
+    describe('RegExp', () => {
+      it('should build literal', () => {
+        expect(testSubject('regexp', /^node:/)).toMatchSnapshot()
+      })
+    })
+
+    describe('bigint', () => {
+      it('should build literal', () => {
+        expect(testSubject('bigint', 3n)).toMatchSnapshot()
+      })
+    })
+
+    describe('boolean', () => {
+      it('should build literal', () => {
+        expect(testSubject('boolean', true)).toMatchSnapshot()
+      })
+    })
+
+    describe('null', () => {
+      it('should build literal', () => {
+        expect(testSubject('null', null)).toMatchSnapshot()
+      })
+    })
+
+    describe('number', () => {
+      it('should build literal', () => {
+        expect(testSubject('number', 3)).toMatchSnapshot()
+      })
+    })
+
+    describe('string', () => {
+      it('should build literal', () => {
+        expect(testSubject('string', 'node')).toMatchSnapshot()
+      })
+    })
+  })
+})

src/index.ts

@@ -3,4 +3,5 @@
  * @module unist-util-builder
  */
 
-export {}
+export type * from './types'
+export { default as u } from './u'

src/types/__tests__/any-builder.spec-d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file Type Tests - AnyBuilder
+ * @module unist-util-builder/tests/types/unit-d/AnyBuilder
+ */
+
+import type TestSubject from '../any-builder'
+import type BuilderChildren from '../builder-children'
+import type BuilderProps from '../builder-props'
+import type BuilderValue from '../builder-value'
+
+describe('unit-d:types/AnyBuilder', () => {
+  it('should extract BuilderChildren', () => {
+    expectTypeOf<TestSubject>().extract<BuilderChildren>().not.toBeNever()
+  })
+
+  it('should extract BuilderProps', () => {
+    expectTypeOf<TestSubject>().extract<BuilderProps>().not.toBeNever()
+  })
+
+  it('should extract BuilderValue', () => {
+    expectTypeOf<TestSubject>().extract<BuilderValue>().not.toBeNever()
+  })
+})

src/types/__tests__/builder-children.spec-d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file Type Tests - BuilderChildren
+ * @module unist-util-builder/tests/types/unit-d/BuilderChildren
+ */
+
+import type * as docast from '@flex-development/docast'
+import type TestSubject from '../builder-children'
+
+describe('unit-d:types/BuilderChildren', () => {
+  it('should equal T[]', () => {
+    // Arrange
+    type T = docast.PhrasingContent
+
+    // Expect
+    expectTypeOf<TestSubject<T>>().toEqualTypeOf<T[]>()
+  })
+})

src/types/__tests__/builder-props.spec-d.ts

@@ -0,0 +1,12 @@
+/**
+ * @file Type Tests - BuilderProps
+ * @module unist-util-builder/tests/types/unit-d/BuilderProps
+ */
+
+import type TestSubject from '../builder-props'
+
+describe('unit-d:types/BuilderProps', () => {
+  it('should equal { [x: string]: unknown }', () => {
+    expectTypeOf<TestSubject>().toEqualTypeOf<{ [x: string]: unknown }>()
+  })
+})

src/types/__tests__/builder-value.spec-d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file Type Tests - BuilderValue
+ * @module unist-util-builder/tests/types/unit-d/BuilderValue
+ */
+
+import type TestSubject from '../builder-value'
+
+describe('unit-d:types/BuilderValue', () => {
+  it('should extract RegExp', () => {
+    expectTypeOf<TestSubject>().extract<RegExp>().not.toBeNever()
+  })
+
+  it('should extract bigint', () => {
+    expectTypeOf<TestSubject>().extract<bigint>().not.toBeNever()
+  })
+
+  it('should extract boolean', () => {
+    expectTypeOf<TestSubject>().extract<boolean>().not.toBeNever()
+  })
+
+  it('should extract number', () => {
+    expectTypeOf<TestSubject>().extract<number>().not.toBeNever()
+  })
+
+  it('should extract null', () => {
+    expectTypeOf<TestSubject>().extract<null>().not.toBeNever()
+  })
+})

src/types/__tests__/builder.spec-d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file Type Tests - Builder
+ * @module unist-util-builder/tests/types/unit-d/Builder
+ */
+
+import type * as docast from '@flex-development/docast'
+import type { Children } from '@flex-development/unist-util-types'
+import type * as mdast from 'mdast'
+import type TestSubject from '../builder'
+import type BuilderValue from '../builder-value'
+
+describe('unit-d:types/Builder', () => {
+  it('should extract Extract<MatchValue<N, Type<N>>, BuilderValue>', () => {
+    // Arrange
+    type N = { type: string; value: BuilderValue | Date }
+
+    // Expect
+    expectTypeOf<TestSubject<N>>().extract<Date>().toBeNever()
+  })
+
+  it('should extract MatchChildren<N, Type<N>>', () => {
+    // Arrange
+    type N = docast.Root
+
+    // Expect
+    expectTypeOf<TestSubject<N>>().extract<Children<N>>().not.toBeNever()
+  })
+
+  it('should extract MatchProperties<N, Type<N>>', () => {
+    // Arrange
+    type N = mdast.Code
+
+    // Expect
+    expectTypeOf<TestSubject<N>>().extract<Omit<N, 'type'>>().not.toBeNever()
+  })
+})

src/types/any-builder.ts

@@ -0,0 +1,19 @@
+/**
+ * @file Type Aliases - AnyBuilder
+ * @module unist-util-builder/types/AnyBuilder
+ */
+
+import type BuilderChildren from './builder-children'
+import type BuilderProps from './builder-props'
+import type BuilderValue from './builder-value'
+
+/**
+ * Union of types used to build any node.
+ *
+ * @see {@linkcode BuilderChildren}
+ * @see {@linkcode BuilderProps}
+ * @see {@linkcode BuilderValue}
+ */
+type AnyBuilder = BuilderChildren | BuilderProps | BuilderValue
+
+export type { AnyBuilder as default }

src/types/builder-children.ts

@@ -0,0 +1,18 @@
+/**
+ * @file Type Aliases - BuilderChildren
+ * @module unist-util-BuilderChildren/types/BuilderChildren
+ */
+
+import type { Node } from 'unist'
+
+/**
+ * List of [*child*][child] nodes used to build a [parent].
+ *
+ * [child]: https://github.com/syntax-tree/unist#child
+ * [parent]: https://github.com/syntax-tree/unist#parent
+ *
+ * @template {Node} [T=Node] - Child node
+ */
+type BuilderChildren<T extends Node = Node> = T[]
+
+export type { BuilderChildren as default }

src/types/builder-props.ts

@@ -0,0 +1,14 @@
+/**
+ * @file Type Aliases - BuilderProps
+ * @module unist-util-BuilderProps/types/BuilderProps
+ */
+
+/**
+ * Node properties object.
+ *
+ * > 👉 Properties of a node are all fields except `type`. If a `type` field is
+ * > present on a builder object, it will be ignored.
+ */
+type BuilderProps = { [x: string]: unknown }
+
+export type { BuilderProps as default }