292 lines
8.2 KiB
Plaintext
292 lines
8.2 KiB
Plaintext
|
/**
|
|||
|
|
* @typedef {import('unist').Node} Node
|
|||
|
|
* @typedef {import('unist').Parent} Parent
|
|||
|
|
*/
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* @template Fn
|
|||
|
|
* @template Fallback
|
|||
|
|
* @typedef {Fn extends (value: any) => value is infer Thing ? Thing : Fallback} Predicate
|
|||
|
|
*/
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* @callback Check
|
|||
|
|
* Check that an arbitrary value is a node.
|
|||
|
|
* @param {unknown} this
|
|||
|
|
* The given context.
|
|||
|
|
* @param {unknown} [node]
|
|||
|
|
* Anything (typically a node).
|
|||
|
|
* @param {number | null | undefined} [index]
|
|||
|
|
* The node’s position in its parent.
|
|||
|
|
* @param {Parent | null | undefined} [parent]
|
|||
|
|
* The node’s parent.
|
|||
|
|
* @returns {boolean}
|
|||
|
|
* Whether this is a node and passes a test.
|
|||
|
|
*
|
|||
|
|
* @typedef {Record<string, unknown> | Node} Props
|
|||
|
|
* Object to check for equivalence.
|
|||
|
|
*
|
|||
|
|
* Note: `Node` is included as it is common but is not indexable.
|
|||
|
|
*
|
|||
|
|
* @typedef {Array<Props | TestFunction | string> | Props | TestFunction | string | null | undefined} Test
|
|||
|
|
* Check for an arbitrary node.
|
|||
|
|
*
|
|||
|
|
* @callback TestFunction
|
|||
|
|
* Check if a node passes a test.
|
|||
|
|
* @param {unknown} this
|
|||
|
|
* The given context.
|
|||
|
|
* @param {Node} node
|
|||
|
|
* A node.
|
|||
|
|
* @param {number | undefined} [index]
|
|||
|
|
* The node’s position in its parent.
|
|||
|
|
* @param {Parent | undefined} [parent]
|
|||
|
|
* The node’s parent.
|
|||
|
|
* @returns {boolean | undefined | void}
|
|||
|
|
* Whether this node passes the test.
|
|||
|
|
*
|
|||
|
|
* Note: `void` is included until TS sees no return as `undefined`.
|
|||
|
|
*/
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* Check if `node` is a `Node` and whether it passes the given test.
|
|||
|
|
*
|
|||
|
|
* @param {unknown} node
|
|||
|
|
* Thing to check, typically `Node`.
|
|||
|
|
* @param {Test} test
|
|||
|
|
* A check for a specific node.
|
|||
|
|
* @param {number | null | undefined} index
|
|||
|
|
* The node’s position in its parent.
|
|||
|
|
* @param {Parent | null | undefined} parent
|
|||
|
|
* The node’s parent.
|
|||
|
|
* @param {unknown} context
|
|||
|
|
* Context object (`this`) to pass to `test` functions.
|
|||
|
|
* @returns {boolean}
|
|||
|
|
* Whether `node` is a node and passes a test.
|
|||
|
|
*/
|
|||
|
|
export const is =
|
|||
|
|
// Note: overloads in JSDoc can’t yet use different `@template`s.
|
|||
|
|
/**
|
|||
|
|
* @type {(
|
|||
|
|
* (<Condition extends string>(node: unknown, test: Condition, index?: number | null | undefined, parent?: Parent | null | undefined, context?: unknown) => node is Node & {type: Condition}) &
|
|||
|
|
* (<Condition extends Props>(node: unknown, test: Condition, index?: number | null | undefined, parent?: Parent | null | undefined, context?: unknown) => node is Node & Condition) &
|
|||
|
|
* (<Condition extends TestFunction>(node: unknown, test: Condition, index?: number | null | undefined, parent?: Parent | null | undefined, context?: unknown) => node is Node & Predicate<Condition, Node>) &
|
|||
|
|
* ((node?: null | undefined) => false) &
|
|||
|
|
* ((node: unknown, test?: null | undefined, index?: number | null | undefined, parent?: Parent | null | undefined, context?: unknown) => node is Node) &
|
|||
|
|
* ((node: unknown, test?: Test, index?: number | null | undefined, parent?: Parent | null | undefined, context?: unknown) => boolean)
|
|||
|
|
* )}
|
|||
|
|
*/
|
|||
|
|
(
|
|||
|
|
/**
|
|||
|
|
* @param {unknown} [node]
|
|||
|
|
* @param {Test} [test]
|
|||
|
|
* @param {number | null | undefined} [index]
|
|||
|
|
* @param {Parent | null | undefined} [parent]
|
|||
|
|
* @param {unknown} [context]
|
|||
|
|
* @returns {boolean}
|
|||
|
|
*/
|
|||
|
|
// eslint-disable-next-line max-params
|
|||
|
|
function (node, test, index, parent, context) {
|
|||
|
|
const check = convert(test)
|
|||
|
|
|
|||
|
|
if (
|
|||
|
|
index !== undefined &&
|
|||
|
|
index !== null &&
|
|||
|
|
(typeof index !== 'number' ||
|
|||
|
|
index < 0 ||
|
|||
|
|
index === Number.POSITIVE_INFINITY)
|
|||
|
|
) {
|
|||
|
|
throw new Error('Expected positive finite index')
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (
|
|||
|
|
parent !== undefined &&
|
|||
|
|
parent !== null &&
|
|||
|
|
(!is(parent) || !parent.children)
|
|||
|
|
) {
|
|||
|
|
throw new Error('Expected parent node')
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (
|
|||
|
|
(parent === undefined || parent === null) !==
|
|||
|
|
(index === undefined || index === null)
|
|||
|
|
) {
|
|||
|
|
throw new Error('Expected both parent and index')
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
return looksLikeANode(node)
|
|||
|
|
? check.call(context, node, index, parent)
|
|||
|
|
: false
|
|||
|
|
}
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* Generate an assertion from a test.
|
|||
|
|
*
|
|||
|
|
* Useful if you’re going to test many nodes, for example when creating a
|
|||
|
|
* utility where something else passes a compatible test.
|
|||
|
|
*
|
|||
|
|
* The created function is a bit faster because it expects valid input only:
|
|||
|
|
* a `node`, `index`, and `parent`.
|
|||
|
|
*
|
|||
|
|
* @param {Test} test
|
|||
|
|
* * when nullish, checks if `node` is a `Node`.
|
|||
|
|
* * when `string`, works like passing `(node) => node.type === test`.
|
|||
|
|
* * when `function` checks if function passed the node is true.
|
|||
|
|
* * when `object`, checks that all keys in test are in node, and that they have (strictly) equal values.
|
|||
|
|
* * when `array`, checks if any one of the subtests pass.
|
|||
|
|
* @returns {Check}
|
|||
|
|
* An assertion.
|
|||
|
|
*/
|
|||
|
|
export const convert =
|
|||
|
|
// Note: overloads in JSDoc can’t yet use different `@template`s.
|
|||
|
|
/**
|
|||
|
|
* @type {(
|
|||
|
|
* (<Condition extends string>(test: Condition) => (node: unknown, index?: number | null | undefined, parent?: Parent | null | undefined, context?: unknown) => node is Node & {type: Condition}) &
|
|||
|
|
* (<Condition extends Props>(test: Condition) => (node: unknown, index?: number | null | undefined, parent?: Parent | null | undefined, context?: unknown) => node is Node & Condition) &
|
|||
|
|
* (<Condition extends TestFunction>(test: Condition) => (node: unknown, index?: number | null | undefined, parent?: Parent | null | undefined, context?: unknown) => node is Node & Predicate<Condition, Node>) &
|
|||
|
|
* ((test?: null | undefined) => (node?: unknown, index?: number | null | undefined, parent?: Parent | null | undefined, context?: unknown) => node is Node) &
|
|||
|
|
* ((test?: Test) => Check)
|
|||
|
|
* )}
|
|||
|
|
*/
|
|||
|
|
(
|
|||
|
|
/**
|
|||
|
|
* @param {Test} [test]
|
|||
|
|
* @returns {Check}
|
|||
|
|
*/
|
|||
|
|
function (test) {
|
|||
|
|
if (test === null || test === undefined) {
|
|||
|
|
return ok
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (typeof test === 'function') {
|
|||
|
|
return castFactory(test)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (typeof test === 'object') {
|
|||
|
|
return Array.isArray(test) ? anyFactory(test) : propsFactory(test)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (typeof test === 'string') {
|
|||
|
|
return typeFactory(test)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
throw new Error('Expected function, string, or object as test')
|
|||
|
|
}
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* @param {Array<Props | TestFunction | string>} tests
|
|||
|
|
* @returns {Check}
|
|||
|
|
*/
|
|||
|
|
function anyFactory(tests) {
|
|||
|
|
/** @type {Array<Check>} */
|
|||
|
|
const checks = []
|
|||
|
|
let index = -1
|
|||
|
|
|
|||
|
|
while (++index < tests.length) {
|
|||
|
|
checks[index] = convert(tests[index])
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
return castFactory(any)
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* @this {unknown}
|
|||
|
|
* @type {TestFunction}
|
|||
|
|
*/
|
|||
|
|
function any(...parameters) {
|
|||
|
|
let index = -1
|
|||
|
|
|
|||
|
|
while (++index < checks.length) {
|
|||
|
|
if (checks[index].apply(this, parameters)) return true
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
return false
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* Turn an object into a test for a node with a certain fields.
|
|||
|
|
*
|
|||
|
|
* @param {Props} check
|
|||
|
|
* @returns {Check}
|
|||
|
|
*/
|
|||
|
|
function propsFactory(check) {
|
|||
|
|
const checkAsRecord = /** @type {Record<string, unknown>} */ (check)
|
|||
|
|
|
|||
|
|
return castFactory(all)
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* @param {Node} node
|
|||
|
|
* @returns {boolean}
|
|||
|
|
*/
|
|||
|
|
function all(node) {
|
|||
|
|
const nodeAsRecord = /** @type {Record<string, unknown>} */ (
|
|||
|
|
/** @type {unknown} */ (node)
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
/** @type {string} */
|
|||
|
|
let key
|
|||
|
|
|
|||
|
|
for (key in check) {
|
|||
|
|
if (nodeAsRecord[key] !== checkAsRecord[key]) return false
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
return true
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* Turn a string into a test for a node with a certain type.
|
|||
|
|
*
|
|||
|
|
* @param {string} check
|
|||
|
|
* @returns {Check}
|
|||
|
|
*/
|
|||
|
|
function typeFactory(check) {
|
|||
|
|
return castFactory(type)
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* @param {Node} node
|
|||
|
|
*/
|
|||
|
|
function type(node) {
|
|||
|
|
return node && node.type === check
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* Turn a custom test into a test for a node that passes that test.
|
|||
|
|
*
|
|||
|
|
* @param {TestFunction} testFunction
|
|||
|
|
* @returns {Check}
|
|||
|
|
*/
|
|||
|
|
function castFactory(testFunction) {
|
|||
|
|
return check
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* @this {unknown}
|
|||
|
|
* @type {Check}
|
|||
|
|
*/
|
|||
|
|
function check(value, index, parent) {
|
|||
|
|
return Boolean(
|
|||
|
|
looksLikeANode(value) &&
|
|||
|
|
testFunction.call(
|
|||
|
|
this,
|
|||
|
|
value,
|
|||
|
|
typeof index === 'number' ? index : undefined,
|
|||
|
|
parent || undefined
|
|||
|
|
)
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function ok() {
|
|||
|
|
return true
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* @param {unknown} value
|
|||
|
|
* @returns {value is Node}
|
|||
|
|
*/
|
|||
|
|
function looksLikeANode(value) {
|
|||
|
|
return value !== null && typeof value === 'object' && 'type' in value
|
|||
|
|
}
|