Change types to work w/o explicit type parameter

Previously, the type parameter of the kind of node that was checked for
needed to be passed.
This node kind had to be matched by the given runtime `test`.
At that point, it was known that node would be of that kind.

Now, the given runtime test is used in the type system to narrow the
given `node` value down.

This means that the types can become much simpler.
Instead of `AssertAnything` and `AssertPredicate`, use the new `Check`.
Instead of `TestFunctionAnything` and `TestFunctionPredicate`, use
`TestFunction`.
Instead of `PredicateTest`, use `Test`.

Author: wooorm

index.js

@@ -1,22 +1,7 @@
 /**
- * @typedef {import('./lib/index.js').AssertAnything} AssertAnything
+ * @typedef {import('./lib/index.js').Check} Check
  * @typedef {import('./lib/index.js').Test} Test
- * @typedef {import('./lib/index.js').TestFunctionAnything} TestFunctionAnything
- */
-
-/**
- * @template {import('hast').Element} T
- * @typedef {import('./lib/index.js').AssertPredicate<T>} AssertPredicate
- */
-
-/**
- * @template {import('hast').Element} T
- * @typedef {import('./lib/index.js').PredicateTest<T>} PredicateTest
- */
-
-/**
- * @template {import('hast').Element} T
- * @typedef {import('./lib/index.js').TestFunctionPredicate<T>} TestFunctionPredicate
+ * @typedef {import('./lib/index.js').TestFunction} TestFunction
  */
 
 export {convertElement, isElement} from './lib/index.js'

index.test-d.ts

@@ -1,173 +1,198 @@
-import type {Element} from 'hast'
-import {expectAssignable, expectError, expectNotType, expectType} from 'tsd'
-import {unified} from 'unified'
-import type {Node} from 'unist'
-import {isElement, convertElement} from './index.js'
+import type {Element, Parents, Root, RootContent} from 'hast'
+import {expectAssignable, expectNotType, expectType} from 'tsd'
+import {convertElement, isElement} from './index.js'
 
-/* Setup. */
-type Section = {
-  tagName: 'section'
-} & Element
+// # Setup
 
-type Article = {
-  tagName: 'article'
-} & Element
+const hastElement = (function (): Root | RootContent {
+  return {type: 'element', tagName: 'a', properties: {}, children: []}
+})()
 
-const section: Element = {
-  type: 'element',
-  tagName: 'section',
-  properties: {},
-  children: [{type: 'text', value: 'x'}]
+const unknownValue = (function (): unknown {
+  return {type: 'something'}
+})()
+
+const someTagName = (function (): string {
+  return 'c'
+})()
+
+// # `isElement`
+
+// No node.
+expectType<false>(isElement())
+
+// No test.
+expectType<boolean>(isElement(hastElement))
+
+if (isElement(unknownValue)) {
+  expectType<Element>(unknownValue)
+}
+
+/* Nullish test. */
+expectType<boolean>(isElement(hastElement, null))
+expectType<boolean>(isElement(hastElement, undefined))
+
+// String test.
+if (isElement(hastElement, 'a')) {
+  expectType<Element & {tagName: 'a'}>(hastElement)
 }
 
-const article: Element = {
-  type: 'element',
-  tagName: 'article',
-  properties: {},
-  children: [{type: 'text', value: 'x'}]
+if (isElement(hastElement, 'b')) {
+  expectType<Element & {tagName: 'b'}>(hastElement)
 }
 
-const isSection = (element: Element): element is Section =>
-  element.tagName === 'section'
+if (isElement(hastElement, someTagName)) {
+  expectType<Element>(hastElement)
+}
 
-expectType<false>(isElement())
+// Function test (with explicit assertion).
+expectType<boolean>(isElement(hastElement, isHeading2))
 
-/* Missing parameters. */
-expectError(isElement<Section>())
+if (isElement(hastElement, isHeading2)) {
+  expectType<Element & {tagName: 'h2'}>(hastElement)
+}
 
-/* Types cannot be narrowed without predicate. */
-expectType<boolean>(isElement(section))
+if (isElement(hastElement, isParagraph)) {
+  expectType<Element & {tagName: 'p'}>(hastElement)
+}
 
-/* Incorrect generic. */
-expectError(isElement<string>(section, 'section'))
-expectError(isElement<boolean>(section, 'section'))
-expectError(isElement<Record<string, unknown>>(section, 'section'))
+if (isElement(hastElement, isParagraph)) {
+  expectNotType<Element & {tagName: 'h2'}>(hastElement)
+}
 
-/* Should be assignable to boolean. */
-expectType<boolean>(isElement<Section>(section, 'section'))
+if (isElement(hastElement, isHeading2)) {
+  expectAssignable<Element>(hastElement)
+  expectType<'h2'>(hastElement.tagName)
+}
 
-/* Test isElement optional */
-expectType<boolean>(isElement(section))
-expectType<boolean>(isElement(section, null))
-expectType<boolean>(isElement(section, undefined))
-/* But not with a type predicate */
-expectError(isElement<Node>(section)) // But not with a type predicate
-expectError(isElement<Node>(section, null))
-expectError(isElement<Node>(section, undefined))
+// Function test (implicit assertion).
+expectType<boolean>(isElement(hastElement, isHeading2Loose))
 
-/* Should support string tests. */
-expectType<boolean>(isElement<Section>(section, 'section'))
-expectType<boolean>(isElement<Section>(article, 'section'))
-expectError(isElement<Section>(section, 'article'))
+if (isElement(hastElement, isHeading2Loose)) {
+  expectNotType<Element & {tagName: 'h2'}>(hastElement)
+}
 
-if (isElement<Section>(section, 'section')) {
-  expectType<Section>(section)
-  expectNotType<Article>(section)
+if (isElement(hastElement, isParagraphLoose)) {
+  expectNotType<Element & {tagName: 'p'}>(hastElement)
 }
 
-expectType<boolean>(isElement<Article>(article, 'article'))
-expectType<boolean>(isElement<Article>(section, 'article'))
-expectError(isElement<Article>(article, 'section'))
-
-if (isElement<Article>(article, 'article')) {
-  expectType<Article>(article)
-  expectNotType<Section>(article)
-}
-
-/* Should support function tests. */
-expectType<boolean>(isElement(section, isSection))
-expectType<boolean>(isElement(article, isSection))
-
-if (isElement(section, isSection)) {
-  expectType<Section>(section)
-  expectNotType<Article>(section)
-}
-
-expectType<boolean>(isElement(article, isSection))
-expectType<boolean>(isElement(section, isSection))
-expectError(isElement<Article>(article, isSection))
-
-if (isElement(section, isSection)) {
-  expectType<Section>(section)
-}
-
-/* Should support array tests. */
-expectType<boolean>(
-  isElement<Article | Section>(section, ['article', isSection])
-)
-
-if (isElement<Article | Section>(section, ['article', isSection])) {
-  switch (section.tagName) {
-    case 'section': {
-      expectType<Section>(section)
-      break
-    }
-
-    case 'article': {
-      expectType<Article>(section)
-      break
-    }
-
-    default: {
-      break
-    }
-  }
-}
-
-/* Should support being used in a unified transform. */
-unified().use(() => (tree) => {
-  if (isElement<Section>(tree, 'section')) {
-    expectAssignable<Section>(tree)
-    // Do something
-  }
-
-  return tree
-})
-
-/* Should support `convert`. */
-convertElement<Section>('section')
-expectError(convertElement<Section>('article'))
-convertElement<Section>(isSection)
-expectError(convertElement<Article>(isSection))
-convertElement()
-convertElement(null)
-convertElement(undefined)
-expectError(convertElement<Article>())
-
-declare const node: unknown
-
-/* Type assertion */
-if (isElement(node)) {
-  expectType<Element>(node)
-}
-
-if (isElement(node, (node): node is Section => node.tagName === 'section')) {
-  expectType<Section>(node)
-}
-
-/**
- * This test demonstrates that, while the test definitely asserts that `node`
- * is an element, it asserts that it is *some* kind of element.
- * If we’d define `node` as an `Element` in the if-branch (which is correct),
- * TypeScript will think `node` is *not* an `Element` in the else-branch (which
- * is incorrect).
- * We can’t solve this in this project, but users can change their code (see
- * next example).
- */
-if (isElement(node, (node) => node.children.length > 0)) {
-  expectType<unknown>(node)
-} else {
-  expectType<unknown>(node)
-}
+if (isElement(hastElement, isHead)) {
+  expectType<Element>(hastElement)
+}
+
+// Array tests.
+// Can’t narrow down.
+expectType<boolean>(isElement(hastElement, ['h2', isHeading2, isHeading2Loose]))
+
+// Can’t narrow down.
+if (isElement(hastElement, ['h2', isHeading2, isHeading2Loose])) {
+  expectNotType<Element & {tagName: 'h2'}>(hastElement)
+}
+
+// # `convertElement`
+
+// No node.
+const checkNone = convertElement()
+expectType<boolean>(checkNone())
+
+// No test.
+expectType<boolean>(checkNone(hastElement))
+
+if (checkNone(unknownValue)) {
+  expectType<Element>(unknownValue)
+}
+
+/* Nullish test. */
+const checkNull = convertElement(null)
+const checkUndefined = convertElement(null)
+expectType<boolean>(checkNull(hastElement))
+expectType<boolean>(checkUndefined(hastElement))
+
+// String test.
+const checkHeading2 = convertElement('h2')
+const checkParagraph = convertElement('p')
+
+if (checkHeading2(hastElement)) {
+  expectType<Element & {tagName: 'h2'}>(hastElement)
+}
+
+if (checkParagraph(hastElement)) {
+  expectType<Element & {tagName: 'p'}>(hastElement)
+}
+
+// Function test (with explicit assertion).
+const checkParagraphFn = convertElement(isParagraph)
+const checkHeading2Fn = convertElement(isHeading2)
+
+expectType<boolean>(checkHeading2Fn(hastElement))
+
+if (checkHeading2Fn(hastElement)) {
+  expectType<Element & {tagName: 'h2'}>(hastElement)
+}
+
+if (checkParagraphFn(hastElement)) {
+  expectType<Element & {tagName: 'p'}>(hastElement)
+}
+
+if (checkParagraphFn(hastElement)) {
+  expectNotType<Element & {tagName: 'h2'}>(hastElement)
+}
+
+if (checkHeading2Fn(hastElement)) {
+  expectAssignable<Element>(hastElement)
+  expectType<'h2'>(hastElement.tagName)
+}
+
+// Function test (implicit assertion).
+const checkHeading2LooseFn = convertElement(isHeading2Loose)
+const checkParagraphLooseFn = convertElement(isParagraphLoose)
+const checkHeadFn = convertElement(isHead)
+
+expectType<boolean>(checkHeading2LooseFn(hastElement))
+
+if (checkHeading2LooseFn(hastElement)) {
+  expectNotType<Element & {tagName: 'h2'}>(hastElement)
+}
+
+if (checkParagraphLooseFn(hastElement)) {
+  expectNotType<Element & {tagName: 'p'}>(hastElement)
+}
+
+if (checkHeadFn(hastElement)) {
+  expectNotType<Element & {tagName: 'h2'}>(hastElement)
+}
+
+// Array tests.
+// Can’t narrow down.
+const isHeadingArray = convertElement(['h2', isHeading2, isHeading2Loose])
+
+expectType<boolean>(isHeadingArray(hastElement))
+
+// Can’t narrow down.
+if (isHeadingArray(hastElement)) {
+  expectNotType<Element & {tagName: 'h2'}>(hastElement)
+}
+
+function isHeading2(element: Element): element is Element & {tagName: 'h2'} {
+  return element.tagName === 'h2'
+}
+
+function isHeading2Loose(element: Element) {
+  return element.tagName === 'h2'
+}
+
+function isParagraph(element: Element): element is Element & {tagName: 'p'} {
+  return element.tagName === 'p'
+}
+
+function isParagraphLoose(element: Element) {
+  return element.tagName === 'p'
+}
 
-/**
- * This is the suggested use of this package so TypeScript can infer what types
- * it’s working with.
- * This way, `node` as an `Element` in the if-branch, and it could still be an
- * element (or something else) in the else-branch.
- */
-if (isElement(node) && node.children.length > 0) {
-  expectType<Element>(node)
-} else {
-  expectType<unknown>(node)
+function isHead(
+  element: Element,
+  index: number | undefined,
+  parent: Parents | undefined
+) {
+  return parent ? index === 0 : false
 }