From 15c3395fd286d1925ea8e5adeaf12ace66001160 Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sat, 2 Nov 2019 16:33:54 +1100 Subject: [PATCH 01/14] Add types --- package.json | 28 +++++++----- readme.md | 25 ++++------- test/index.js | 2 +- types/index.d.ts | 54 +++++++++++++++++++++++ types/mdast-util-toc-tests.ts | 80 +++++++++++++++++++++++++++++++++++ types/tsconfig.json | 14 ++++++ types/tslint.json | 14 ++++++ 7 files changed, 188 insertions(+), 29 deletions(-) create mode 100644 types/index.d.ts create mode 100644 types/mdast-util-toc-tests.ts create mode 100644 types/tsconfig.json create mode 100644 types/tslint.json diff --git a/package.json b/package.json index 2b3cb48..beb4a6a 100644 --- a/package.json +++ b/package.json @@ -15,32 +15,37 @@ "Titus Wormer (https://wooorm.com)", "Jonathan Haines (https://barrythepenguin.github.io)" ], + "types": "types/index.d.ts", "files": [ + "types/index.d.ts", "lib", "index.js" ], "dependencies": { + "@types/unist": "^2.0.3", "extend": "^3.0.2", "github-slugger": "^1.2.1", "mdast-util-to-string": "^1.0.5", - "unist-util-is": "^3.0.0", - "unist-util-visit": "^1.1.0" + "unist-util-is": "^4.0.0", + "unist-util-visit": "^2.0.0" }, "devDependencies": { "browserify": "^16.2.3", + "dtslint": "^1.0.2", "nyc": "^14.0.0", "prettier": "^1.15.2", - "remark": "^10.0.0", - "remark-attr": "^0.8.0", - "remark-cli": "^6.0.0", - "remark-parse": "^6.0.3", - "remark-preset-wooorm": "^5.0.0", - "remark-usage": "^6.1.3", + "remark": "^11.0.1", + "remark-attr": "^0.9.0", + "remark-cli": "^7.0.0", + "remark-parse": "^7.0.1", + "remark-preset-wooorm": "^6.0.1", + "remark-usage": "^7.0.1", "tape": "^4.10.1", "tinyify": "^2.5.0", + "typescript": "^3.0.0", "unified": "^8.0.0", - "unist-builder": "^1.0.3", - "xo": "^0.24.0" + "unist-builder": "^2.0.1", + "xo": "^0.25.3" }, "scripts": { "format": "remark . -qfo && prettier --write \"**/*.js\" && xo --fix", @@ -49,7 +54,8 @@ "build": "npm run build-bundle && npm run build-mangle", "test-api": "node test", "test-coverage": "nyc --reporter lcov tape test/index.js", - "test": "npm run format && npm run build && npm run test-coverage" + "test-types": "dtslint types", + "test": "npm run format && npm run build && npm run test-coverage && npm run test-types" }, "nyc": { "check-coverage": true, diff --git a/readme.md b/readme.md index 0312fc8..2dce655 100644 --- a/readme.md +++ b/readme.md @@ -36,30 +36,21 @@ var tree = u('root', [ u('heading', {depth: 3}, [u('text', 'Charlie')]), u('heading', {depth: 2}, [u('text', 'Delta')]) ]) + var table = toc(tree) ``` Yields: ```javascript - -{ - index: null, +{ index: null, endIndex: null, - map: { - type: 'list', - ordered: false, - spread: true, - children: [ - { - type: 'listItem', - loose: true, - spread: true, - children: [Array] - } - ] - } -} + map: + { type: 'list', + ordered: false, + spread: true, + children: + [ { type: 'listItem', loose: true, spread: true, children: [Array] } ] } } ``` ## API diff --git a/test/index.js b/test/index.js index 8f9a74f..4f970da 100644 --- a/test/index.js +++ b/test/index.js @@ -40,7 +40,7 @@ test('Fixtures', function(t) { try { config = JSON.parse(fs.readFileSync(join(root, name, 'config.json'))) - } catch (error) {} + } catch (_) {} processor.use(remarkParse, config.remarkParseOptions) diff --git a/types/index.d.ts b/types/index.d.ts new file mode 100644 index 0000000..1835ea0 --- /dev/null +++ b/types/index.d.ts @@ -0,0 +1,54 @@ +// TypeScript Version: 3.0 + +import {Node, Parent} from 'unist' +import {Test} from 'unist-util-is' + +declare namespace mdastUtilToc { + interface Link extends Parent { + type: 'link' + title: null + url: string + children: Node[] + } + + interface Paragraph extends Parent { + type: 'paragraph' + children: Link[] + } + + interface ListItem extends Parent { + type: 'listItem' + loose: boolean + spread: boolean + children: Node[] + } + + interface List extends Parent { + type: 'list' + ordered: boolean + spread: boolean + children: ListItem[] + } + + interface TOCOptions { + heading?: string + maxDepth?: number + skip?: string + tight?: boolean + prefix?: string + parents?: Test | Array> + } + + interface TOCResult { + index?: number + endIndex?: number + map?: List + } +} + +declare function toc( + node: Node, + options?: mdastUtilToc.TOCOptions +): mdastUtilToc.TOCResult + +export = toc diff --git a/types/mdast-util-toc-tests.ts b/types/mdast-util-toc-tests.ts new file mode 100644 index 0000000..0f36f77 --- /dev/null +++ b/types/mdast-util-toc-tests.ts @@ -0,0 +1,80 @@ +import {Parent} from 'unist' + +import unified = require('unified') +import u = require('unist-builder') +import is = require('unist-util-is') +import toc = require('mdast-util-toc') + +interface Link extends Parent { + type: 'link' +} + +interface Paragraph extends Parent { + type: 'paragraph' +} + +interface List extends Parent { + type: 'list' +} + +interface ListItem extends Parent { + type: 'listItem' +} + +const tree = u('root', [ + u('heading', {depth: 1}, [u('text', 'Alpha')]), + u('heading', {depth: 2}, [u('text', 'Bravo')]), + u('heading', {depth: 3}, [u('text', 'Charlie')]), + u('heading', {depth: 2}, [u('text', 'Delta')]) +]) + +const {map} = toc(tree) + +if (is(map, 'list')) { + const [firstListItem] = map.children + + if (is(firstListItem, 'listItem')) { + const [firstParagraph] = firstListItem.children + + if (is(firstParagraph, 'paragraph')) { + const [firstLink] = firstParagraph.children + + is(firstLink, 'link') + } + } +} + +toc(tree, { + heading: 'Table Of Contents' +}) + +toc(tree, { + maxDepth: 2 +}) + +toc(tree, { + skip: 'skip heading' +}) + +toc(tree, { + tight: true +}) + +toc(tree, { + prefix: '/prefix' +}) + +toc(tree, { + parents: ['root', 'blockquote'] +}) + +/*=== usable in unified transform ===*/ +unified().use(() => tree => { + const table = toc(tree) + + if (is(table.map, 'list')) { + // do something + } + + return tree +}) diff --git a/types/tsconfig.json b/types/tsconfig.json new file mode 100644 index 0000000..6634bdf --- /dev/null +++ b/types/tsconfig.json @@ -0,0 +1,14 @@ +{ + "compilerOptions": { + "lib": ["es2015"], + "strict": true, + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "baseUrl": ".", + "paths": { + "mdast-util-toc": ["index.d.ts"] + } + } +} diff --git a/types/tslint.json b/types/tslint.json new file mode 100644 index 0000000..22174ee --- /dev/null +++ b/types/tslint.json @@ -0,0 +1,14 @@ +{ + "extends": "dtslint/dtslint.json", + "rules": { + "callable-types": false, + "max-line-length": false, + "no-redundant-jsdoc": false, + "no-void-expression": false, + "only-arrow-functions": false, + "semicolon": false, + "unified-signatures": false, + "whitespace": false, + "interface-over-type-literal": false + } +} From d87c6289304731a7152501c0c410f97721550330 Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sat, 2 Nov 2019 16:41:02 +1100 Subject: [PATCH 02/14] export mdastUtilToc namespace --- types/index.d.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/types/index.d.ts b/types/index.d.ts index 1835ea0..9442308 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -46,9 +46,9 @@ declare namespace mdastUtilToc { } } -declare function toc( +declare function mdastUtilToc( node: Node, options?: mdastUtilToc.TOCOptions ): mdastUtilToc.TOCResult -export = toc +export = mdastUtilToc From 12c0abef25b608b2657cba6ed77738f5b3226a7f Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sun, 3 Nov 2019 06:20:19 +1100 Subject: [PATCH 03/14] Update types/index.d.ts Co-Authored-By: Christian Murphy --- types/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/types/index.d.ts b/types/index.d.ts index 9442308..f41f886 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -36,7 +36,7 @@ declare namespace mdastUtilToc { skip?: string tight?: boolean prefix?: string - parents?: Test | Array> + parents?: Test | Array> } interface TOCResult { From 4af1f9ae8d65813471a820ef496252f1c0705a2b Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sun, 3 Nov 2019 06:21:43 +1100 Subject: [PATCH 04/14] Update types/tslint.json Co-Authored-By: Christian Murphy --- types/tslint.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/types/tslint.json b/types/tslint.json index 22174ee..1af086d 100644 --- a/types/tslint.json +++ b/types/tslint.json @@ -9,6 +9,6 @@ "semicolon": false, "unified-signatures": false, "whitespace": false, - "interface-over-type-literal": false + "strict-export-declare-modifiers": false } } From 267dd25f61c36e7baa15fea6b6362a82a751cb91 Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sun, 3 Nov 2019 06:23:35 +1100 Subject: [PATCH 05/14] Update types/index.d.ts Co-Authored-By: Christian Murphy --- types/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/types/index.d.ts b/types/index.d.ts index f41f886..e051ff5 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -32,7 +32,7 @@ declare namespace mdastUtilToc { interface TOCOptions { heading?: string - maxDepth?: number + maxDepth?: Heading['depth'] skip?: string tight?: boolean prefix?: string From 7b0141133c8addfc19d03de23713cebc6c57c31e Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sun, 3 Nov 2019 06:23:56 +1100 Subject: [PATCH 06/14] Update types/index.d.ts Co-Authored-By: Christian Murphy --- types/index.d.ts | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/types/index.d.ts b/types/index.d.ts index e051ff5..d02167f 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -46,6 +46,12 @@ declare namespace mdastUtilToc { } } +/** + * Generate a Table of Contents from a tree. + * + * @param node searched for headings + * @param options configuration and settings + */ declare function mdastUtilToc( node: Node, options?: mdastUtilToc.TOCOptions From 0cd5c121db5ecfe4eeaafaf2df1bbb1b1e3103ed Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sun, 3 Nov 2019 06:45:01 +1100 Subject: [PATCH 07/14] Add mdast typings --- package.json | 1 + 1 file changed, 1 insertion(+) diff --git a/package.json b/package.json index beb4a6a..ed967d2 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,7 @@ "index.js" ], "dependencies": { + "@types/mdast": "^3.0.3", "@types/unist": "^2.0.3", "extend": "^3.0.2", "github-slugger": "^1.2.1", From d8a75ee30feacc458946f56838114d978e620369 Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sun, 3 Nov 2019 06:45:24 +1100 Subject: [PATCH 08/14] Change config feedback --- types/tsconfig.json | 4 ---- types/tslint.json | 2 +- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/types/tsconfig.json b/types/tsconfig.json index 6634bdf..680123a 100644 --- a/types/tsconfig.json +++ b/types/tsconfig.json @@ -2,10 +2,6 @@ "compilerOptions": { "lib": ["es2015"], "strict": true, - "noImplicitAny": true, - "noImplicitThis": true, - "strictNullChecks": true, - "strictFunctionTypes": true, "baseUrl": ".", "paths": { "mdast-util-toc": ["index.d.ts"] diff --git a/types/tslint.json b/types/tslint.json index 1af086d..5ce3dd6 100644 --- a/types/tslint.json +++ b/types/tslint.json @@ -7,7 +7,7 @@ "no-void-expression": false, "only-arrow-functions": false, "semicolon": false, - "unified-signatures": false, + "unified-signatures": true, "whitespace": false, "strict-export-declare-modifiers": false } From 45e0e4c9df908271715fdfc13d910f3845ce5de5 Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sun, 3 Nov 2019 06:46:03 +1100 Subject: [PATCH 09/14] Use mdast typings --- types/index.d.ts | 28 ++-------------------------- types/mdast-util-toc-tests.ts | 18 +----------------- 2 files changed, 3 insertions(+), 43 deletions(-) diff --git a/types/index.d.ts b/types/index.d.ts index d02167f..c4da9bb 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -1,34 +1,10 @@ // TypeScript Version: 3.0 -import {Node, Parent} from 'unist' +import {Node} from 'unist' +import {Parent, Heading, Link, Paragraph, List, ListItem} from 'mdast' import {Test} from 'unist-util-is' declare namespace mdastUtilToc { - interface Link extends Parent { - type: 'link' - title: null - url: string - children: Node[] - } - - interface Paragraph extends Parent { - type: 'paragraph' - children: Link[] - } - - interface ListItem extends Parent { - type: 'listItem' - loose: boolean - spread: boolean - children: Node[] - } - - interface List extends Parent { - type: 'list' - ordered: boolean - spread: boolean - children: ListItem[] - } interface TOCOptions { heading?: string diff --git a/types/mdast-util-toc-tests.ts b/types/mdast-util-toc-tests.ts index 0f36f77..98ac3b9 100644 --- a/types/mdast-util-toc-tests.ts +++ b/types/mdast-util-toc-tests.ts @@ -1,26 +1,10 @@ -import {Parent} from 'unist' +import {Link, Paragraph, List, ListItem} from 'mdast' import unified = require('unified') import u = require('unist-builder') import is = require('unist-util-is') import toc = require('mdast-util-toc') -interface Link extends Parent { - type: 'link' -} - -interface Paragraph extends Parent { - type: 'paragraph' -} - -interface List extends Parent { - type: 'list' -} - -interface ListItem extends Parent { - type: 'listItem' -} - const tree = u('root', [ u('heading', {depth: 1}, [u('text', 'Alpha')]), u('heading', {depth: 2}, [u('text', 'Bravo')]), From 2f4893989da57c1e0072cd4898543469d4317297 Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sun, 3 Nov 2019 06:46:54 +1100 Subject: [PATCH 10/14] Add docs to TOCOptions --- types/index.d.ts | 41 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/types/index.d.ts b/types/index.d.ts index c4da9bb..1a7369d 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -7,18 +7,53 @@ import {Test} from 'unist-util-is' declare namespace mdastUtilToc { interface TOCOptions { + /** + * Heading to look for, wrapped in `new RegExp('^(' + value + ')$', 'i')`. + */ heading?: string + + /** + * Maximum heading depth to include in the table of contents (default: `6`), + * This is inclusive: when set to `3`, + * level three headings are included (those with three hashes, `###`). + */ maxDepth?: Heading['depth'] + + /** + * Headings to skip, wrapped in `new RegExp('^(' + value + ')$', 'i')`. + * Any heading matching this expression will not be present in the table of contents. + */ skip?: string + + /** + * Whether to compile list-items tightly (default: `false`). + */ tight?: boolean + + /** + * Add a prefix to links to headings in the table of contents (default: null). + * Useful for example when later going from mdast to hast and sanitizing with `hast-util-sanitize`. + */ prefix?: string + + /** + * Allows headings to be children of certain node types + * (default: the to `toc` given `tree`, to only allow top-level headings). + * Internally, uses `unist-util-is` to check, so `parents` can be any `is`-compatible test. + * + * For example, this would allow headings under either `root` or `blockquote` to be used: + * + * ```ts + * toc(tree, {parents: ['root', 'blockquote']}) + * ``` + */ parents?: Test | Array> } interface TOCResult { - index?: number - endIndex?: number - map?: List + index: number | null + endIndex: number | null + map: List | null } } From 541eee26749c4f7decae84f7483201dffb2c03fa Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sun, 3 Nov 2019 06:52:20 +1100 Subject: [PATCH 11/14] Enable lint rules --- types/tslint.json | 5 ----- 1 file changed, 5 deletions(-) diff --git a/types/tslint.json b/types/tslint.json index 5ce3dd6..1fded03 100644 --- a/types/tslint.json +++ b/types/tslint.json @@ -1,11 +1,6 @@ { "extends": "dtslint/dtslint.json", "rules": { - "callable-types": false, - "max-line-length": false, - "no-redundant-jsdoc": false, - "no-void-expression": false, - "only-arrow-functions": false, "semicolon": false, "unified-signatures": true, "whitespace": false, From 51b6a54e2a997e08b7914cac8d192904b1e92dc2 Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sun, 3 Nov 2019 06:54:27 +1100 Subject: [PATCH 12/14] Fix padding for dslint --- types/index.d.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/types/index.d.ts b/types/index.d.ts index 1a7369d..3ecd1de 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -5,7 +5,6 @@ import {Parent, Heading, Link, Paragraph, List, ListItem} from 'mdast' import {Test} from 'unist-util-is' declare namespace mdastUtilToc { - interface TOCOptions { /** * Heading to look for, wrapped in `new RegExp('^(' + value + ')$', 'i')`. From b6ce9ef585f94e4aa0df5cd4243f9fc5428de33b Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sun, 3 Nov 2019 07:55:33 +1100 Subject: [PATCH 13/14] Add default hints --- types/index.d.ts | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/types/index.d.ts b/types/index.d.ts index 3ecd1de..7aaf683 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -12,9 +12,11 @@ declare namespace mdastUtilToc { heading?: string /** - * Maximum heading depth to include in the table of contents (default: `6`), + * Maximum heading depth to include in the table of contents, * This is inclusive: when set to `3`, * level three headings are included (those with three hashes, `###`). + * + * @default 6 */ maxDepth?: Heading['depth'] @@ -25,19 +27,22 @@ declare namespace mdastUtilToc { skip?: string /** - * Whether to compile list-items tightly (default: `false`). + * Whether to compile list-items tightly. + * + * @default false */ tight?: boolean /** - * Add a prefix to links to headings in the table of contents (default: null). + * Add a prefix to links to headings in the table of contents. * Useful for example when later going from mdast to hast and sanitizing with `hast-util-sanitize`. + * + * @default null */ prefix?: string /** * Allows headings to be children of certain node types - * (default: the to `toc` given `tree`, to only allow top-level headings). * Internally, uses `unist-util-is` to check, so `parents` can be any `is`-compatible test. * * For example, this would allow headings under either `root` or `blockquote` to be used: @@ -45,6 +50,8 @@ declare namespace mdastUtilToc { * ```ts * toc(tree, {parents: ['root', 'blockquote']}) * ``` + * + * @default the to `toc` given `tree`, to only allow top-level headings */ parents?: Test | Array> } From e077eae47b7fb041d0a554c4d7041d916397733e Mon Sep 17 00:00:00 2001 From: Jonathan Haines Date: Sun, 3 Nov 2019 07:56:21 +1100 Subject: [PATCH 14/14] Disable no redundant jsdoc --- types/tslint.json | 1 + 1 file changed, 1 insertion(+) diff --git a/types/tslint.json b/types/tslint.json index 1fded03..874122f 100644 --- a/types/tslint.json +++ b/types/tslint.json @@ -1,6 +1,7 @@ { "extends": "dtslint/dtslint.json", "rules": { + "no-redundant-jsdoc": false, "semicolon": false, "unified-signatures": true, "whitespace": false,