feat(internal): utilities

Signed-off-by: Lexus Drumgold <[email protected]>

.dictionary.txt

@@ -31,4 +31,5 @@ unstub
 vates
 vfile
 vitest
+xast
 yarnrc

package.json

@@ -93,11 +93,13 @@
     "@html-eslint/parser": "0.24.0",
     "@types/chai": "4.3.12",
     "@types/eslint": "8.56.5",
+    "@types/hast": "3.0.4",
     "@types/is-ci": "3.0.4",
     "@types/mdast": "4.0.3",
     "@types/node": "20.11.28",
     "@types/node-notifier": "8.0.5",
     "@types/unist": "3.0.2",
+    "@types/xast": "2.0.4",
     "@typescript-eslint/eslint-plugin": "7.2.0",
     "@typescript-eslint/parser": "7.2.0",
     "@vates/toggle-scripts": "1.0.0",
@@ -155,6 +157,7 @@
     }
   },
   "resolutions": {
+    "@types/hast": "3.0.4",
     "@types/unist": "3.0.2",
     "chai": "5.1.0"
   },

src/utils/__tests__/nodelike.spec.ts

@@ -0,0 +1,20 @@
+/**
+ * @file Unit Tests - nodelike
+ * @module unist-util-visit/utils/tests/unit/nodelike
+ */
+
+import testSubject from '../nodelike'
+
+describe('unit:utils/nodelike', () => {
+  it('should return false if value is not curly-braced object', () => {
+    expect(testSubject([])).to.be.false
+  })
+
+  it('should return false if value.type is invalid', () => {
+    expect(testSubject({ type: '' })).to.be.false
+  })
+
+  it('should return true if value is shaped like a node', () => {
+    expect(testSubject({ type: 'nothing' })).to.be.true
+  })
+})

src/utils/__tests__/nodename.spec.ts

@@ -0,0 +1,55 @@
+/**
+ * @file Unit Tests - nodename
+ * @module unist-util-visit/utils/tests/unit/nodename
+ */
+
+import type * as hast from 'hast'
+import type * as xast from 'xast'
+import testSubject from '../nodename'
+
+describe('unit:utils/nodename', () => {
+  it('should return null if node does not have display name', () => {
+    expect(testSubject({ type: 'break' })).to.be.null
+  })
+
+  describe('node.name', () => {
+    let node: xast.Instruction
+
+    beforeAll(() => {
+      node = {
+        name: 'xml',
+        type: 'instruction',
+        value: 'version="1.0" encoding="UTF-8"'
+      }
+    })
+
+    it('should return node.name if node.name is a string', () => {
+      expect(testSubject(node)).to.equal(node.name)
+    })
+
+    it('should return null if node.name is not a string', () => {
+      expect(testSubject({ ...node, name: { id: node.name } })).to.be.null
+    })
+  })
+
+  describe('node.tagName', () => {
+    let node: hast.Element
+
+    beforeAll(() => {
+      node = {
+        children: [],
+        properties: {},
+        tagName: 'div',
+        type: 'element'
+      }
+    })
+
+    it('should return node.tagName if node.tagName is a string', () => {
+      expect(testSubject(node)).to.equal(node.tagName)
+    })
+
+    it('should return null if node.tagName is not a string', () => {
+      expect(testSubject({ ...node, tagName: { id: node.tagName } })).to.be.null
+    })
+  })
+})

src/utils/__tests__/parentlike.spec.ts

@@ -0,0 +1,27 @@
+/**
+ * @file Unit Tests - parentlike
+ * @module unist-util-visit/utils/tests/unit/parentlike
+ */
+
+import type { Type } from '@flex-development/unist-util-types'
+import testSubject from '../parentlike'
+
+describe('unit:utils/parentlike', () => {
+  let type: Type
+
+  beforeAll(() => {
+    type = 'root'
+  })
+
+  it('should return false if value is not nodelike', () => {
+    expect(testSubject('root')).to.be.false
+  })
+
+  it('should return false if value.children is invalid', () => {
+    expect(testSubject({ children: new Set(), type })).to.be.false
+  })
+
+  it('should return true if value is shaped like a parent', () => {
+    expect(testSubject({ children: [], type })).to.be.true
+  })
+})

src/utils/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @file Entry Point - Utilities
+ * @module unist-util-visit/utils
+ */
+
+export { default as nodelike } from './nodelike'
+export { default as nodename } from './nodename'
+export { default as parentlike } from './parentlike'

src/utils/nodelike.ts

@@ -0,0 +1,24 @@
+/**
+ * @file Utilities - nodelike
+ * @module unist-util-visit/nodelike
+ */
+
+import { isObjectCurly, isString } from '@flex-development/tutils'
+import type { Node } from 'unist'
+
+/**
+ * Check if something looks like a {@linkcode Node}.
+ *
+ * @internal
+ *
+ * @this {void}
+ *
+ * @param {unknown} value - Thing to check
+ * @return {value is Node} `true` if `value` looks like a node
+ */
+function nodelike(this: void, value: unknown): value is Node {
+  if (!isObjectCurly(value)) return false
+  return 'type' in value && isString(value.type) && !!value.type.length
+}
+
+export default nodelike

src/utils/nodename.ts

@@ -0,0 +1,37 @@
+/**
+ * @file Utilities - nodename
+ * @module unist-util-visit/nodename
+ */
+
+import { isString, type Nullable } from '@flex-development/tutils'
+import type { Node } from 'unist'
+
+/**
+ * Get a display name for `node`.
+ *
+ * The following properties will be used as display names if found:
+ *
+ * - `tagName`
+ * - `name`
+ *
+ * @internal
+ *
+ * @template {Node} [T=Node] - Node to check
+ *
+ * @this {void}
+ *
+ * @param {T} node - Node to check
+ * @return {Nullable<string>} Display name or `null`
+ */
+function nodename<T extends Node = Node>(
+  this: void,
+  node: T
+): Nullable<string> {
+  return 'tagName' in node && isString(node.tagName) // hast
+    ? node.tagName
+    : 'name' in node && isString(node.name) // xast
+    ? node.name
+    : null
+}
+
+export default nodename

src/utils/parentlike.ts

@@ -0,0 +1,24 @@
+/**
+ * @file Utilities - parentlike
+ * @module unist-util-visit/parentlike
+ */
+
+import { isArray } from '@flex-development/tutils'
+import type { Parent } from 'unist'
+import nodelike from './nodelike'
+
+/**
+ * Check if something looks like a {@linkcode Parent}.
+ *
+ * @internal
+ *
+ * @this {void}
+ *
+ * @param {unknown} value - Thing to check
+ * @return {value is Parent} `true` if `value` looks like a parent
+ */
+function parentlike(this: void, value: unknown): value is Parent {
+  return nodelike(value) && 'children' in value && isArray(value.children)
+}
+
+export default parentlike

yarn.lock

@@ -1827,11 +1827,13 @@ __metadata:
     "@html-eslint/parser": "npm:0.24.0"
     "@types/chai": "npm:4.3.12"
     "@types/eslint": "npm:8.56.5"
+    "@types/hast": "npm:3.0.4"
     "@types/is-ci": "npm:3.0.4"
     "@types/mdast": "npm:4.0.3"
     "@types/node": "npm:20.11.28"
     "@types/node-notifier": "npm:8.0.5"
     "@types/unist": "npm:3.0.2"
+    "@types/xast": "npm:2.0.4"
     "@typescript-eslint/eslint-plugin": "npm:7.2.0"
     "@typescript-eslint/parser": "npm:7.2.0"
     "@vates/toggle-scripts": "npm:1.0.0"
@@ -2396,7 +2398,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/hast@npm:^3.0.0":
+"@types/hast@npm:3.0.4":
   version: 3.0.4
   resolution: "@types/hast@npm:3.0.4"
   dependencies:
@@ -2536,6 +2538,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/xast@npm:2.0.4":
+  version: 2.0.4
+  resolution: "@types/xast@npm:2.0.4"
+  dependencies:
+    "@types/unist": "npm:*"
+  checksum: 10/41ed740a3deaa8c6aedf3d175ae2291d0bfaa5d56b0fa9d237e972e442364920e21dd63b4a3bfd078027752e681d643145c3e70c1aa02d96ddb20a9a4fc547dc
+  languageName: node
+  linkType: hard
+
 "@typescript-eslint/eslint-plugin@npm:7.2.0":
   version: 7.2.0
   resolution: "@typescript-eslint/eslint-plugin@npm:7.2.0"