From f2b1dd1d9ba4dccdfb0d5216fd1317cc6c1d1893 Mon Sep 17 00:00:00 2001 From: Titus Date: Tue, 1 Jun 2021 10:56:25 +0200 Subject: [PATCH 01/17] Use `pull_request_target` in bb --- .github/workflows/bb.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/bb.yml b/.github/workflows/bb.yml index 291ab09..0198fc3 100644 --- a/.github/workflows/bb.yml +++ b/.github/workflows/bb.yml @@ -2,7 +2,7 @@ name: bb on: issues: types: [opened, reopened, edited, closed, labeled, unlabeled] - pull_request: + pull_request_target: types: [opened, reopened, edited, closed, labeled, unlabeled] jobs: main: From e02b8b798381c80b98b091ab2c9cbef2d5dcacd2 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Mon, 26 Jul 2021 15:21:16 +0200 Subject: [PATCH 02/17] Refactor code-style --- index.js | 8 ++++---- package.json | 6 +----- readme.md | 4 ++-- test.js | 2 +- 4 files changed, 8 insertions(+), 12 deletions(-) diff --git a/index.js b/index.js index 138193a..4f59d74 100644 --- a/index.js +++ b/index.js @@ -12,8 +12,8 @@ * @param {Options} [options] * @returns {string} */ -export function toString(node, options) { - var {includeImageAlt = true} = options || {} +export function toString(node, options = {}) { + const {includeImageAlt = true} = options return one(node, includeImageAlt) } @@ -44,8 +44,8 @@ function one(node, includeImageAlt) { */ function all(values, includeImageAlt) { /** @type {Array.} */ - var result = [] - var index = -1 + const result = [] + let index = -1 while (++index < values.length) { result[index] = one(values[index], includeImageAlt) diff --git a/package.json b/package.json index 03ef400..e389d11 100644 --- a/package.json +++ b/package.json @@ -61,11 +61,7 @@ "trailingComma": "none" }, "xo": { - "prettier": true, - "rules": { - "no-var": "off", - "prefer-arrow-callback": "off" - } + "prettier": true }, "remarkConfig": { "plugins": [ diff --git a/readme.md b/readme.md index 4a77fb9..1aaa8bd 100644 --- a/readme.md +++ b/readme.md @@ -24,11 +24,11 @@ npm install mdast-util-to-string ## Use ```js -import unified from 'unified' +import {unified} from 'unified' import remarkParse from 'remark-parse' import {toString} from 'mdast-util-to-string' -var tree = unified() +const tree = unified() .use(remarkParse) .parse('Some _emphasis_, **importance**, and `code`.') diff --git a/test.js b/test.js index 3a4c6a3..09f8ca3 100644 --- a/test.js +++ b/test.js @@ -1,7 +1,7 @@ import test from 'tape' import {toString} from './index.js' -test('toString', function (t) { +test('toString', (t) => { t.equal(toString(), '', 'should not fail on a missing node') t.equal(toString(null), '', 'should not fail on `null` missing node') From 1232790feace7af91a3d13bb8265b1f25b8a9fd3 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Mon, 26 Jul 2021 15:27:21 +0200 Subject: [PATCH 03/17] Add `strict` to `tsconfig.json` --- index.js | 34 ++++++++++++++++++++-------------- package.json | 3 +++ test.js | 1 + tsconfig.json | 3 ++- 4 files changed, 26 insertions(+), 15 deletions(-) diff --git a/index.js b/index.js index 4f59d74..7918460 100644 --- a/index.js +++ b/index.js @@ -1,4 +1,6 @@ /** + * @typedef {import('mdast').Root|import('mdast').Content} Node + * * @typedef Options * @property {boolean} [includeImageAlt=true] */ @@ -8,31 +10,27 @@ * Prefer the node’s plain-text fields, otherwise serialize its children, * and if the given value is an array, serialize the nodes in it. * - * @param {unknown} node + * @param {unknown} value * @param {Options} [options] * @returns {string} */ -export function toString(node, options = {}) { +export function toString(value, options = {}) { const {includeImageAlt = true} = options - return one(node, includeImageAlt) + return one(value, includeImageAlt) } /** - * @param {unknown} node + * @param {unknown} value * @param {boolean} includeImageAlt * @returns {string} */ -function one(node, includeImageAlt) { +function one(value, includeImageAlt) { return ( - (node && - typeof node === 'object' && - // @ts-ignore looks like a literal. - (node.value || - // @ts-ignore looks like an image. - (includeImageAlt ? node.alt : '') || - // @ts-ignore looks like a parent. - ('children' in node && all(node.children, includeImageAlt)) || - (Array.isArray(node) && all(node, includeImageAlt)))) || + (node(value) && + (('value' in value && value.value) || + (includeImageAlt && 'alt' in value && value.alt) || + ('children' in value && all(value.children, includeImageAlt)))) || + (Array.isArray(value) && all(value, includeImageAlt)) || '' ) } @@ -53,3 +51,11 @@ function all(values, includeImageAlt) { return result.join('') } + +/** + * @param {unknown} value + * @returns {value is Node} + */ +function node(value) { + return Boolean(value && typeof value === 'object') +} diff --git a/package.json b/package.json index e389d11..ec3aa18 100644 --- a/package.json +++ b/package.json @@ -32,6 +32,9 @@ "index.d.ts", "index.js" ], + "dependencies": { + "@types/mdast": "^3.0.0" + }, "devDependencies": { "@types/tape": "^4.0.0", "c8": "^7.0.0", diff --git a/test.js b/test.js index 09f8ca3..7a1d0ec 100644 --- a/test.js +++ b/test.js @@ -2,6 +2,7 @@ import test from 'tape' import {toString} from './index.js' test('toString', (t) => { + // @ts-expect-error: runtime. t.equal(toString(), '', 'should not fail on a missing node') t.equal(toString(null), '', 'should not fail on `null` missing node') diff --git a/tsconfig.json b/tsconfig.json index be08abe..e31adf8 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -10,6 +10,7 @@ "declaration": true, "emitDeclarationOnly": true, "allowSyntheticDefaultImports": true, - "skipLibCheck": true + "skipLibCheck": true, + "strict": true } } From 8c5e180b00ee016a5a715cbd7174514660df3d19 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Mon, 26 Jul 2021 15:28:34 +0200 Subject: [PATCH 04/17] Update `xo` --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index ec3aa18..e6f5def 100644 --- a/package.json +++ b/package.json @@ -45,7 +45,7 @@ "tape": "^5.0.0", "type-coverage": "^2.0.0", "typescript": "^4.0.0", - "xo": "^0.39.0" + "xo": "^0.42.0" }, "scripts": { "prepack": "npm run build && npm run format", From 21e1d78c553e6a411fb41c08e542d84c8913426e Mon Sep 17 00:00:00 2001 From: Christian Murphy Date: Thu, 3 Mar 2022 10:37:24 -0700 Subject: [PATCH 05/17] Add `ignore-scripts` to `.npmrc` --- .npmrc | 1 + 1 file changed, 1 insertion(+) diff --git a/.npmrc b/.npmrc index 43c97e7..9951b11 100644 --- a/.npmrc +++ b/.npmrc @@ -1 +1,2 @@ package-lock=false +ignore-scripts=true From a622cd346fd25ee3b340e58f2aec650b6f49c3c5 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Sat, 21 May 2022 14:11:03 +0200 Subject: [PATCH 06/17] Update dev-dependencies --- package.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/package.json b/package.json index e6f5def..31eae3d 100644 --- a/package.json +++ b/package.json @@ -39,13 +39,13 @@ "@types/tape": "^4.0.0", "c8": "^7.0.0", "prettier": "^2.0.0", - "remark-cli": "^9.0.0", - "remark-preset-wooorm": "^8.0.0", + "remark-cli": "^10.0.0", + "remark-preset-wooorm": "^9.0.0", "rimraf": "^3.0.0", "tape": "^5.0.0", "type-coverage": "^2.0.0", "typescript": "^4.0.0", - "xo": "^0.42.0" + "xo": "^0.49.0" }, "scripts": { "prepack": "npm run build && npm run format", From b03ce2617dd09aeb6b05c6f423a477de3fa4ec03 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Sat, 21 May 2022 14:16:25 +0200 Subject: [PATCH 07/17] Refactor code-style --- index.js | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/index.js b/index.js index 7918460..7f71f7b 100644 --- a/index.js +++ b/index.js @@ -2,12 +2,14 @@ * @typedef {import('mdast').Root|import('mdast').Content} Node * * @typedef Options + * Configuration (optional). * @property {boolean} [includeImageAlt=true] + * Whether to use `alt` for `image`s. */ /** - * Get the text content of a node. - * Prefer the node’s plain-text fields, otherwise serialize its children, + * Get the text content of a node or list of nodes. + * Prefers the node’s plain-text fields, otherwise serializes its children, * and if the given value is an array, serialize the nodes in it. * * @param {unknown} value @@ -36,12 +38,12 @@ function one(value, includeImageAlt) { } /** - * @param {Array.} values + * @param {Array} values * @param {boolean} includeImageAlt * @returns {string} */ function all(values, includeImageAlt) { - /** @type {Array.} */ + /** @type {Array} */ const result = [] let index = -1 From 353622c439ae1e65f8f19837543b347167931fe6 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Sat, 21 May 2022 14:20:45 +0200 Subject: [PATCH 08/17] Add improved docs --- readme.md | 123 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 91 insertions(+), 32 deletions(-) diff --git a/readme.md b/readme.md index 1aaa8bd..5f9ff38 100644 --- a/readme.md +++ b/readme.md @@ -8,52 +8,103 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -**[mdast][]** utility to get the plain text content of a node. +[mdast][] utility to get the text content of a node. -## Install +## Contents + +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`toString(node[, options])`](#tostringnode-options) +* [Types](#types) +* [Compatibility](#compatibility) +* [Security](#security) +* [Related](#related) +* [Contribute](#contribute) +* [License](#license) + +## What is this? + +This package is a tiny utility that gets the textual content of a node. + +## When should I use this? + +This utility is useful when you have a node, say a heading, and want to get the +text inside it. + +This package does not serialize markdown, that’s what +[`mdast-util-to-markdown`][mdast-util-to-markdown] does. + +Similar packages, [`hast-util-to-string`][hast-util-to-string] and +[`hast-util-to-text`][hast-util-to-text], do the same but on [hast][]. -This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c): -Node 12+ is needed to use it and it must be `import`ed instead of `require`d. +## Install -[npm][]: +This package is [ESM only][esm]. +In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: ```sh npm install mdast-util-to-string ``` +In Deno with [`esm.sh`][esmsh]: + +```js +import {toString} from 'https://esm.sh/mdast-util-to-string@3' +``` + +In browsers with [`esm.sh`][esmsh]: + +```html + +``` + ## Use ```js import {unified} from 'unified' -import remarkParse from 'remark-parse' +import {fromMarkdown} from 'mdast-util-from-markdown' import {toString} from 'mdast-util-to-string' -const tree = unified() - .use(remarkParse) - .parse('Some _emphasis_, **importance**, and `code`.') +const tree = fromMarkdown('Some _emphasis_, **importance**, and `code`.') console.log(toString(tree)) // => 'Some emphasis, importance, and code.' ``` ## API -This package exports the following identifiers: `toString`. +This package exports the identifier `toString`. There is no default export. ### `toString(node[, options])` Get the text content of a [node][] or list of nodes. +Prefers the node’s plain-text fields, otherwise serializes its children, and if +the given value is an array, serialize the nodes in it. -The algorithm checks `value` of `node` and then `alt`. -If no value is found, the algorithm checks the children of `node` and joins them -(without spaces or newlines). +##### `options` -> This is not a markdown to plain-text library. -> Use [`strip-markdown`][strip-markdown] for that. +Configuration (optional). ###### `options.includeImageAlt` -Whether to use `alt` (`boolean`, default: `true`) +Whether to use `alt` (`boolean`, default: `true`). + +## Types + +This package is fully typed with [TypeScript][]. +It exports the type `Options`. + +## Compatibility + +Projects maintained by the unified collective are compatible with all maintained +versions of Node.js. +As of now, that is Node.js 12.20+, 14.14+, and 16.0+. +Our projects sometimes work with older versions, but this is not guaranteed. ## Security @@ -63,19 +114,15 @@ attacks. ## Related -* [`nlcst-to-string`](https://github.com/syntax-tree/nlcst-to-string) - — Get text content in nlcst -* [`hast-util-to-string`](https://github.com/wooorm/rehype-minify/tree/HEAD/packages/hast-util-to-string) - — Get text content in hast +* [`hast-util-to-string`](https://github.com/wooorm/rehype-minify/tree/main/packages/hast-util-to-string) + — get text content in hast * [`hast-util-to-text`](https://github.com/syntax-tree/hast-util-to-text) - — Get text content in hast according to the `innerText` algorithm -* [`hast-util-from-string`](https://github.com/wooorm/rehype-minify/tree/HEAD/packages/hast-util-from-string) - — Set text content in hast + — get text content in hast according to the `innerText` algorithm ## Contribute -See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get -started. +See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for +ways to get started. See [`support.md`][support] for ways to get help. This project has a [code of conduct][coc]. @@ -116,22 +163,34 @@ abide by its terms. [npm]: https://docs.npmjs.com/cli/install +[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c + +[esmsh]: https://esm.sh + +[typescript]: https://www.typescriptlang.org + [license]: license [author]: https://wooorm.com -[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md +[health]: https://github.com/syntax-tree/.github + +[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md -[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md +[support]: https://github.com/syntax-tree/.github/blob/main/support.md -[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md +[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md [mdast]: https://github.com/syntax-tree/mdast -[node]: https://github.com/syntax-tree/mdast#nodes +[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown -[strip-markdown]: https://github.com/remarkjs/strip-markdown +[hast]: https://github.com/syntax-tree/hast -[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting +[hast-util-to-string]: https://github.com/rehypejs/rehype-minify/tree/main/packages/hast-util-to-string -[hast]: https://github.com/syntax-tree/hast +[hast-util-to-text]: https://github.com/syntax-tree/hast-util-to-text + +[node]: https://github.com/syntax-tree/mdast#nodes + +[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting From 8065eafe167729d07170cbd029e21182b3a0043b Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 25 Jan 2023 10:58:17 +0100 Subject: [PATCH 09/17] Update dev-dependencies --- package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 31eae3d..7980800 100644 --- a/package.json +++ b/package.json @@ -39,13 +39,13 @@ "@types/tape": "^4.0.0", "c8": "^7.0.0", "prettier": "^2.0.0", - "remark-cli": "^10.0.0", + "remark-cli": "^11.0.0", "remark-preset-wooorm": "^9.0.0", "rimraf": "^3.0.0", "tape": "^5.0.0", "type-coverage": "^2.0.0", "typescript": "^4.0.0", - "xo": "^0.49.0" + "xo": "^0.53.0" }, "scripts": { "prepack": "npm run build && npm run format", From 08ee7ae3a635f379b5c8c048cc24d0e138119123 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 25 Jan 2023 10:58:22 +0100 Subject: [PATCH 10/17] Update Actions --- .github/workflows/main.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index fe284ad..89dc06c 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -7,15 +7,15 @@ jobs: name: ${{matrix.node}} runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - uses: dcodeIO/setup-node-nvm@master + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 with: node-version: ${{matrix.node}} - run: npm install - run: npm test - - uses: codecov/codecov-action@v1 + - uses: codecov/codecov-action@v3 strategy: matrix: node: - - lts/erbium + - lts/fermium - node From ae5234c35122870f6e563c0740a9624ad96ce760 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 25 Jan 2023 10:58:38 +0100 Subject: [PATCH 11/17] Update `tsconfig.json` --- package.json | 7 +++---- tsconfig.json | 17 +++++++++-------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/package.json b/package.json index 7980800..28c1381 100644 --- a/package.json +++ b/package.json @@ -41,7 +41,6 @@ "prettier": "^2.0.0", "remark-cli": "^11.0.0", "remark-preset-wooorm": "^9.0.0", - "rimraf": "^3.0.0", "tape": "^5.0.0", "type-coverage": "^2.0.0", "typescript": "^4.0.0", @@ -49,10 +48,10 @@ }, "scripts": { "prepack": "npm run build && npm run format", - "build": "rimraf \"*.d.ts\" && tsc && type-coverage", + "build": "tsc --build --clean && tsc --build && type-coverage", "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix", - "test-api": "node test.js", - "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test.js", + "test-api": "node --conditions development test.js", + "test-coverage": "c8 --check-coverage --100 --reporter lcov npm run test-api", "test": "npm run build && npm run format && npm run test-coverage" }, "prettier": { diff --git a/tsconfig.json b/tsconfig.json index e31adf8..ebe8889 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,16 +1,17 @@ { - "include": ["*.js"], + "include": ["**/*.js"], + "exclude": ["coverage/", "node_modules/"], "compilerOptions": { - "target": "ES2020", - "lib": ["ES2020"], - "module": "ES2020", - "moduleResolution": "node", - "allowJs": true, "checkJs": true, "declaration": true, "emitDeclarationOnly": true, - "allowSyntheticDefaultImports": true, + "exactOptionalPropertyTypes": true, + "forceConsistentCasingInFileNames": true, + "lib": ["es2020"], + "module": "node16", + "newLine": "lf", "skipLibCheck": true, - "strict": true + "strict": true, + "target": "es2020" } } From 537d210ab08dbb1d0853d653e9d44951657e1f08 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 25 Jan 2023 10:59:07 +0100 Subject: [PATCH 12/17] Refactor to move implementation to `lib/` --- index.js | 62 ++------------------------------------------------- lib/index.js | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++ package.json | 1 + 3 files changed, 66 insertions(+), 60 deletions(-) create mode 100644 lib/index.js diff --git a/index.js b/index.js index 7f71f7b..8674f30 100644 --- a/index.js +++ b/index.js @@ -1,63 +1,5 @@ /** - * @typedef {import('mdast').Root|import('mdast').Content} Node - * - * @typedef Options - * Configuration (optional). - * @property {boolean} [includeImageAlt=true] - * Whether to use `alt` for `image`s. + * @typedef {import('./lib/index.js').Options} Options */ -/** - * Get the text content of a node or list of nodes. - * Prefers the node’s plain-text fields, otherwise serializes its children, - * and if the given value is an array, serialize the nodes in it. - * - * @param {unknown} value - * @param {Options} [options] - * @returns {string} - */ -export function toString(value, options = {}) { - const {includeImageAlt = true} = options - return one(value, includeImageAlt) -} - -/** - * @param {unknown} value - * @param {boolean} includeImageAlt - * @returns {string} - */ -function one(value, includeImageAlt) { - return ( - (node(value) && - (('value' in value && value.value) || - (includeImageAlt && 'alt' in value && value.alt) || - ('children' in value && all(value.children, includeImageAlt)))) || - (Array.isArray(value) && all(value, includeImageAlt)) || - '' - ) -} - -/** - * @param {Array} values - * @param {boolean} includeImageAlt - * @returns {string} - */ -function all(values, includeImageAlt) { - /** @type {Array} */ - const result = [] - let index = -1 - - while (++index < values.length) { - result[index] = one(values[index], includeImageAlt) - } - - return result.join('') -} - -/** - * @param {unknown} value - * @returns {value is Node} - */ -function node(value) { - return Boolean(value && typeof value === 'object') -} +export {toString} from './lib/index.js' diff --git a/lib/index.js b/lib/index.js new file mode 100644 index 0000000..7f71f7b --- /dev/null +++ b/lib/index.js @@ -0,0 +1,63 @@ +/** + * @typedef {import('mdast').Root|import('mdast').Content} Node + * + * @typedef Options + * Configuration (optional). + * @property {boolean} [includeImageAlt=true] + * Whether to use `alt` for `image`s. + */ + +/** + * Get the text content of a node or list of nodes. + * Prefers the node’s plain-text fields, otherwise serializes its children, + * and if the given value is an array, serialize the nodes in it. + * + * @param {unknown} value + * @param {Options} [options] + * @returns {string} + */ +export function toString(value, options = {}) { + const {includeImageAlt = true} = options + return one(value, includeImageAlt) +} + +/** + * @param {unknown} value + * @param {boolean} includeImageAlt + * @returns {string} + */ +function one(value, includeImageAlt) { + return ( + (node(value) && + (('value' in value && value.value) || + (includeImageAlt && 'alt' in value && value.alt) || + ('children' in value && all(value.children, includeImageAlt)))) || + (Array.isArray(value) && all(value, includeImageAlt)) || + '' + ) +} + +/** + * @param {Array} values + * @param {boolean} includeImageAlt + * @returns {string} + */ +function all(values, includeImageAlt) { + /** @type {Array} */ + const result = [] + let index = -1 + + while (++index < values.length) { + result[index] = one(values[index], includeImageAlt) + } + + return result.join('') +} + +/** + * @param {unknown} value + * @returns {value is Node} + */ +function node(value) { + return Boolean(value && typeof value === 'object') +} diff --git a/package.json b/package.json index 28c1381..2f46508 100644 --- a/package.json +++ b/package.json @@ -29,6 +29,7 @@ "main": "index.js", "types": "index.d.ts", "files": [ + "lib/", "index.d.ts", "index.js" ], From eede172386f2cc0e7783c4ac04719696c8994905 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 25 Jan 2023 11:02:56 +0100 Subject: [PATCH 13/17] Refactor code-style * Add more docs to JSDoc * Add support for `null` in input of API types --- lib/index.js | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/lib/index.js b/lib/index.js index 7f71f7b..d0e7314 100644 --- a/lib/index.js +++ b/lib/index.js @@ -3,28 +3,40 @@ * * @typedef Options * Configuration (optional). - * @property {boolean} [includeImageAlt=true] + * @property {boolean | null | undefined} [includeImageAlt=true] * Whether to use `alt` for `image`s. */ /** * Get the text content of a node or list of nodes. + * * Prefers the node’s plain-text fields, otherwise serializes its children, * and if the given value is an array, serialize the nodes in it. * * @param {unknown} value - * @param {Options} [options] + * Thing to serialize, typically `Node`. + * @param {Options | null | undefined} [options] + * Configuration (optional). * @returns {string} + * Serialized `value`. */ -export function toString(value, options = {}) { - const {includeImageAlt = true} = options - return one(value, includeImageAlt) +export function toString(value, options) { + const includeImageAlt = (options || {}).includeImageAlt + return one( + value, + typeof includeImageAlt === 'boolean' ? includeImageAlt : true + ) } /** + * One node or several nodes. + * * @param {unknown} value + * Thing to serialize. * @param {boolean} includeImageAlt + * Include image `alt`s. * @returns {string} + * Serialized node. */ function one(value, includeImageAlt) { return ( @@ -38,9 +50,14 @@ function one(value, includeImageAlt) { } /** + * Serialize a list of nodes. + * * @param {Array} values + * Thing to serialize. * @param {boolean} includeImageAlt + * Include image `alt`s. * @returns {string} + * Serialized nodes. */ function all(values, includeImageAlt) { /** @type {Array} */ @@ -55,8 +72,12 @@ function all(values, includeImageAlt) { } /** + * Check if `value` looks like a node. + * * @param {unknown} value + * Thing. * @returns {value is Node} + * Whether `value` is a node. */ function node(value) { return Boolean(value && typeof value === 'object') From ab7eb0b12fcada270b8b8fa2b4e756e174e3a245 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 25 Jan 2023 11:03:40 +0100 Subject: [PATCH 14/17] Use Node test runner --- .github/workflows/main.yml | 2 +- package.json | 2 +- test.js | 31 +++++++++++++++++-------------- 3 files changed, 19 insertions(+), 16 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 89dc06c..fb63387 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -17,5 +17,5 @@ jobs: strategy: matrix: node: - - lts/fermium + - lts/gallium - node diff --git a/package.json b/package.json index 2f46508..a8a8ea1 100644 --- a/package.json +++ b/package.json @@ -37,7 +37,7 @@ "@types/mdast": "^3.0.0" }, "devDependencies": { - "@types/tape": "^4.0.0", + "@types/node": "^18.0.0", "c8": "^7.0.0", "prettier": "^2.0.0", "remark-cli": "^11.0.0", diff --git a/test.js b/test.js index 7a1d0ec..c7ec9e4 100644 --- a/test.js +++ b/test.js @@ -1,14 +1,19 @@ -import test from 'tape' +import assert from 'node:assert/strict' +import test from 'node:test' import {toString} from './index.js' -test('toString', (t) => { +test('toString', () => { // @ts-expect-error: runtime. - t.equal(toString(), '', 'should not fail on a missing node') - t.equal(toString(null), '', 'should not fail on `null` missing node') + assert.equal(toString(), '', 'should not fail on a missing node') + assert.equal(toString(null), '', 'should not fail on `null` missing node') - t.equal(toString({value: 'foo'}), 'foo', 'should not fail on nodes w/o type') + assert.equal( + toString({value: 'foo'}), + 'foo', + 'should not fail on nodes w/o type' + ) - t.equal( + assert.equal( toString({ value: 'foo', alt: 'bar', @@ -19,37 +24,35 @@ test('toString', (t) => { 'should prefer `value` over all others' ) - t.equal( + assert.equal( toString({alt: 'bar', title: 'baz', children: [{value: 'qux'}]}), 'bar', 'should prefer `alt` over all others' ) - t.equal( + assert.equal( toString({title: 'baz', children: [{value: 'qux'}]}), 'qux', 'should *not* prefer `title` over all others' ) - t.equal( + assert.equal( toString({alt: 'bar'}, {includeImageAlt: false}), '', 'should *not* include `alt` w/ `includeImageAlt: false`' ) - t.equal( + assert.equal( toString({children: [{value: 'foo'}, {alt: 'bar'}, {title: 'baz'}]}), 'foobar', 'should serialize children' ) - t.equal( + assert.equal( toString([{value: 'foo'}, {alt: 'bar'}, {title: 'baz'}]), 'foobar', 'should serialize a list of nodes' ) - t.equal(toString({}), '', 'should produce an empty string otherwise') - - t.end() + assert.equal(toString({}), '', 'should produce an empty string otherwise') }) From 748289f17f93c2ef96b820f5f38c63342f0b8ac4 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 25 Jan 2023 11:03:55 +0100 Subject: [PATCH 15/17] Add tests for exposed identifiers --- test.js | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/test.js b/test.js index c7ec9e4..1096c35 100644 --- a/test.js +++ b/test.js @@ -1,8 +1,15 @@ import assert from 'node:assert/strict' import test from 'node:test' import {toString} from './index.js' +import * as mod from './index.js' test('toString', () => { + assert.deepEqual( + Object.keys(mod).sort(), + ['toString'], + 'should expose the public api' + ) + // @ts-expect-error: runtime. assert.equal(toString(), '', 'should not fail on a missing node') assert.equal(toString(null), '', 'should not fail on `null` missing node') From 7380cd7a50a19d8bceeec96492360e213f669754 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 25 Jan 2023 11:06:31 +0100 Subject: [PATCH 16/17] Add improved docs --- readme.md | 44 +++++++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/readme.md b/readme.md index 5f9ff38..94dac6e 100644 --- a/readme.md +++ b/readme.md @@ -17,7 +17,8 @@ * [Install](#install) * [Use](#use) * [API](#api) - * [`toString(node[, options])`](#tostringnode-options) + * [`toString(value[, options])`](#tostringvalue-options) + * [`Options`](#options) * [Types](#types) * [Compatibility](#compatibility) * [Security](#security) @@ -43,7 +44,7 @@ Similar packages, [`hast-util-to-string`][hast-util-to-string] and ## Install This package is [ESM only][esm]. -In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: +In Node.js (version 14.14+ and 16.0+), install with [npm][]: ```sh npm install mdast-util-to-string @@ -77,33 +78,46 @@ console.log(toString(tree)) // => 'Some emphasis, importance, and code.' ## API -This package exports the identifier `toString`. +This package exports the identifier [`toString`][api-tostring]. There is no default export. -### `toString(node[, options])` +### `toString(value[, options])` -Get the text content of a [node][] or list of nodes. -Prefers the node’s plain-text fields, otherwise serializes its children, and if -the given value is an array, serialize the nodes in it. +Get the text content of a node or list of nodes. -##### `options` +Prefers the node’s plain-text fields, otherwise serializes its children, +and if the given value is an array, serialize the nodes in it. -Configuration (optional). +###### Parameters -###### `options.includeImageAlt` +* `value` (`unknown`) + — thing to serialize, typically [`Node`][node] +* `options` ([`Options`][api-options], optional) + — configuration -Whether to use `alt` (`boolean`, default: `true`). +###### Returns + +Serialized `value` (`string`). + +### `Options` + +Configuration (TypeScript type). + +###### Fields + +* `includeImageAlt` (`boolean`, default: `true`) + — whether to use `alt` for `image`s ## Types This package is fully typed with [TypeScript][]. -It exports the type `Options`. +It exports the additional type [`Options`][api-options]. ## Compatibility Projects maintained by the unified collective are compatible with all maintained versions of Node.js. -As of now, that is Node.js 12.20+, 14.14+, and 16.0+. +As of now, that is Node.js 14.14+ and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed. ## Security @@ -194,3 +208,7 @@ abide by its terms. [node]: https://github.com/syntax-tree/mdast#nodes [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting + +[api-tostring]: #tostringvalue-options + +[api-options]: #options From b13a458d16640512d3820d09d6a96958184d54e3 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 25 Jan 2023 11:07:50 +0100 Subject: [PATCH 17/17] 3.1.1 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index a8a8ea1..10edf20 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "mdast-util-to-string", - "version": "3.1.0", + "version": "3.1.1", "description": "mdast utility to get the plain text content of a node", "license": "MIT", "keywords": [