type TestFunction is a type predicate, not a generic predicate about unist-util-is HOT 4 CLOSED

@chmac predicate is a narrower type than boolean, which is why TS is erroring in this case.
https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates

Using a TS Predicate ensures that when used with a conditional, inside the if scope, TypeScript knows that the variable passed, is the type defined by the generic in is.
For example:

coming into this function, TypeScript only knows heading is some variable, within the if scope, TypeScript knows that is must be type Node and more specifically a Heading node and allows safe access to all properties provided by that type.
Using a boolean would only safely allow narrowing the type to Node, because we'd have no way to determine what more specific type is wanted.
Allowing a fully generic type without a predicate would allow for a runtime exception such as the one in the example here: #16 (comment)

In your example try:

import { Node, Parent } from "unist";
import visit from "unist-util-visit";

export const insertBefore = (
  tree: Parent,
  predicate: (node: Node, index?: number, parent?: Parent) => node is Node,
  transform: (node: Node) => Node
) => {
  visit(tree, predicate, (node, index, parent) => {});
};

or even better

import { Node, Parent } from "unist";
import { Test } from "unist-util-is";
import visit from "unist-util-visit";

export const insertBefore = <T extends Node>(
  tree: Parent,
  predicate: Test<T>,
  transform: (node: T) => Node
) => {
  visit(tree, predicate, (node, index, parent) => {});
};

Also reference the type tests in https://github.com/syntax-tree/unist-util-visit/blob/master/types/unist-util-visit-tests.ts for more examples.

from unist-util-is.

@ChristianMurphy I don't think I've 100% grok'd this yet, but will spend some more time on it. Thanks for the detailed explanation.

It seems like you made a reasoned decision which I misunderstood. What about adding something to the docs sharing how to use this package in TypeScript? I'd be happy to have a go at submitting a PR to that effect if that would be helpful.

from unist-util-is.

More documentation is welcome.
Rather than making it repository specific, it could be good to add it to a guide about using Unified with TypeScript. See unifiedjs/unifiedjs.github.io#7 for more information on guides.

Types like Test, Plugin, and Transformer are used in many packages, having a central guide could be helpful to point folks in the right direction.

from unist-util-is.

If I understand this conversation correctly, I believe I can close this.
If that is a mistake, please comment here and we can open this again.

from unist-util-is.