From 60a48ca97933428448a90c7fd080bb5c7cff220f Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Sun, 19 Mar 2023 10:05:36 -0400 Subject: [PATCH] Check-in type declaration file This is checked-in to source control include manual revisions documenting overloaded functions, due to a suspected upstream bug in TypeScript. See: https://github.com/microsoft/TypeScript/issues/53350 --- .gitignore | 3 +- es/index.d.ts | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++ package.json | 2 +- src/index.js | 22 +++++++++ 4 files changed, 154 insertions(+), 2 deletions(-) create mode 100644 es/index.d.ts diff --git a/.gitignore b/.gitignore index 2c94565..9d27333 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ -es/ +/es/* +!/es/index.d.ts node_modules/ *.log dist/ diff --git a/es/index.d.ts b/es/index.d.ts new file mode 100644 index 0000000..dbc35b1 --- /dev/null +++ b/es/index.d.ts @@ -0,0 +1,129 @@ +// This is checked-in to source control include manual revisions documenting overloaded functions, +// due to a suspected upstream bug in TypeScript. +// +// See: https://github.com/microsoft/TypeScript/issues/53350 +// +// It is not generated automatically as part of the build process, and must be created manually +// using `npm run build:types`. + +/** + * Given a markup string or DOM element, creates an object aligning with the + * shape of the matchers object, or the value returned by the matcher. + * + * @template T + * @template {MatcherObj} O + * + * @overload + * @param {Element|string} source Source content + * @param {O} matchers Object of matchers + * @return {{[K in keyof O]: ReturnType}} Matched values, shaped by object + * @param source + * @param matchers + */ +export function parse>>( + source: Element | string, + matchers: O +): { [K in keyof O]: ReturnType }; + +/** + * Given a markup string or DOM element, creates an object aligning with the + * shape of the matchers object, or the value returned by the matcher. + * + * @template {any} T + * @template {MatcherFn} F + * + * @overload + * @param {Element|string} source Source content + * @param {F} matchers matcher Matcher function + * @return {ReturnType} Matched value + */ +export function parse>( + source: Element | string, + matchers: F +): ReturnType; + +/** + * Generates a function which matches node of type selector, returning an + * attribute by property if the attribute exists. If no selector is passed, + * returns property of the query element. + * + * @template T + * + * @overload + * @param {string} name Property name + * @return {MatcherFn} Matcher function returning the property value + */ +export function prop(name: string): MatcherFn; + +/** + * Generates a function which matches node of type selector, returning an + * attribute by property if the attribute exists. If no selector is passed, + * returns property of the query element. + * + * @template T + * + * @overload + * @param {string|undefined} selector Optional selector + * @param {string} name Property name + * @return {MatcherFn} Matcher function returning the property value + */ +export function prop(selector: string | undefined, name: string): MatcherFn; + +/** + * Generates a function which matches node of type selector, returning an + * attribute by name if the attribute exists. If no selector is passed, + * returns attribute of the query element. + * + * @overload + * @param {string} name Attribute name + * @return {MatcherFn} Matcher function returning the attribute value + */ +export function attr(name: string): MatcherFn; + +/** + * Generates a function which matches node of type selector, returning an + * attribute by name if the attribute exists. If no selector is passed, + * returns attribute of the query element. + * + * @overload + * @param {string|undefined} selector Optional selector + * @param {string} name Attribute name + * @return {MatcherFn} Matcher function returning the attribute value + */ +export function attr(selector: string | undefined, name: string): MatcherFn; + +/** + * Convenience for `prop( selector, 'innerHTML' )`. + * + * @see prop() + * + * @param {string=} selector Optional selector + * @return {(node: Element) => string} Matcher which returns innerHTML + */ +export function html(selector?: string | undefined): (node: Element) => string; +/** + * Convenience for `prop( selector, 'textContent' )`. + * + * @see prop() + * + * @param {string} selector Optional selector + * @return {(node: Element) => string} Matcher which returns text content + */ +export function text(selector: string): (node: Element) => string; +/** + * Creates a new matching context by first finding elements matching selector + * using querySelectorAll before then running another `parse` on `matchers` + * scoped to the matched elements. + * + * @see parse() + * + * @template T + * + * @param {string} selector Selector to match + * @param {Matcher} matchers Matcher function or object of matchers + * @return Matcher function which returns an array of matched value(s) + */ +export function query(selector: string, matchers: Matcher): (node: Element) => any[]; +export type MatcherFn = (node: Element) => T; +export type MatcherObj = Record>; +export type Matcher = MatcherFn | MatcherObj; diff --git a/package.json b/package.json index c57f5fc..783fb22 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,7 @@ "build:es": "babel src --out-dir es", "build:umd": "rollup -c", "build:types": "tsc -b", - "build": "npm run build:es && npm run build:umd && npm run build:types", + "build": "npm run build:es && npm run build:umd", "dev": "rollup -c -w", "lint": "eslint . --ignore-pattern dist --ignore-pattern es", "unit-test": "NODE_ENV=test mocha --require @babel/register", diff --git a/src/index.js b/src/index.js index 7ed85b8..3bf7bc6 100644 --- a/src/index.js +++ b/src/index.js @@ -37,6 +37,9 @@ const getDocument = (() => { */ /** + * Given a markup string or DOM element, creates an object aligning with the + * shape of the matchers object, or the value returned by the matcher. + * * @template T * @template {MatcherObj} O * @@ -47,6 +50,9 @@ const getDocument = (() => { */ /** + * Given a markup string or DOM element, creates an object aligning with the + * shape of the matchers object, or the value returned by the matcher. + * * @template {any} T * @template {MatcherFn} F * @@ -99,6 +105,10 @@ export function parse(source, matchers) { } /** + * Generates a function which matches node of type selector, returning an + * attribute by property if the attribute exists. If no selector is passed, + * returns property of the query element. + * * @template T * * @overload @@ -107,6 +117,10 @@ export function parse(source, matchers) { */ /** + * Generates a function which matches node of type selector, returning an + * attribute by property if the attribute exists. If no selector is passed, + * returns property of the query element. + * * @template T * * @overload @@ -144,12 +158,20 @@ export function prop(selector, name) { } /** + * Generates a function which matches node of type selector, returning an + * attribute by name if the attribute exists. If no selector is passed, + * returns attribute of the query element. + * * @overload * @param {string} name Attribute name * @return {MatcherFn} Matcher function returning the attribute value */ /** + * Generates a function which matches node of type selector, returning an + * attribute by name if the attribute exists. If no selector is passed, + * returns attribute of the query element. + * * @overload * @param {string|undefined} selector Optional selector * @param {string} name Attribute name