Change to return undefined, not null

wooorm · wooorm · commit 2e3ff5b51608 · 2023-07-08T10:46:11.000+02:00
diff --git a/lib/contents.js b/lib/contents.js
@@ -30,7 +30,7 @@ import extend from 'extend'
  * @param {ContentsOptions} settings
  */
 export function contents(map, settings) {
-  const {ordered = false, tight = false, prefix = null} = settings
+  const {ordered = false, tight = false, prefix} = settings
   /** @type {List} */
   const table = {type: 'list', ordered, spread: false, children: []}
   let minDepth = Number.POSITIVE_INFINITY
diff --git a/lib/index.js b/lib/index.js
@@ -16,18 +16,18 @@
  *
  * @typedef Result
  *   Results.
- * @property {number | null} index
+ * @property {number | undefined} index
  *   Index of the node right after the table of contents heading, `-1` if no
- *   heading was found, `null` if no `heading` was given.
- * @property {number | null} endIndex
+ *   heading was found, `undefined` if no `heading` was given.
+ * @property {number | undefined} endIndex
  *   Index of the first node after `heading` that is not part of its section,
- *   `-1` if no heading was found, `null` if no `heading` was given, same as
- *   `index` if there are no nodes between `heading` and the first heading in
- *   the table of contents.
- * @property {List | null} map
- *   List representing the generated table of contents, `null` if no table of
- *   contents could be created, either because no heading was found or because
- *   no following headings were found.
+ *   `-1` if no heading was found, `undefined` if no `heading` was given, same
+ *   as `index` if there are no nodes between `heading` and the first heading
+ *   in the table of contents.
+ * @property {List | undefined} map
+ *   List representing the generated table of contents, `undefined` if no table
+ *   of contents could be created, either because no heading was found or
+ *   because no following headings were found.
  */
 
 import {search} from './search.js'
@@ -60,8 +60,8 @@ export function toc(tree, options) {
   const result = search(tree, heading, settings)
 
   return {
-    index: heading ? result.index : null,
-    endIndex: heading ? result.endIndex : null,
-    map: result.map.length > 0 ? contents(result.map, settings) : null
+    index: heading ? result.index : undefined,
+    endIndex: heading ? result.endIndex : undefined,
+    map: result.map.length > 0 ? contents(result.map, settings) : undefined
   }
 }
diff --git a/readme.md b/readme.md
@@ -95,8 +95,8 @@ Yields:
 
 ```javascript
 {
-  index: null,
-  endIndex: null,
+  index: undefined,
+  endIndex: undefined,
   map: {
     type: 'list',
     ordered: false,
@@ -171,18 +171,18 @@ Results (TypeScript type).
 
 ###### Fields
 
-*   `index` (`number` or `null`)
+*   `index` (`number` or `undefined`)
     — index of the node right after the table of contents heading, `-1` if no
-    heading was found, `null` if no `heading` was given
-*   `endIndex` (`number` or `null`)
+    heading was found, `undefined` if no `heading` was given
+*   `endIndex` (`number` or `undefined`)
     — index of the first node after `heading` that is not part of its section,
-    `-1` if no heading was found, `null` if no `heading` was given, same as
+    `-1` if no heading was found, `undefined` if no `heading` was given, same as
     `index` if there are no nodes between `heading` and the first heading in
     the table of contents
-*   `map` ([`List`][list] or `null`)
-    — list representing the generated table of contents, `null` if no table of
-    contents could be created, either because no heading was found or because
-    no following headings were found
+*   `map` ([`List`][list] or `undefined`)
+    — list representing the generated table of contents, `undefined` if no
+    table of contents could be created, either because no heading was found or
+    because no following headings were found
 
 ## Types
 
diff --git a/test/fixtures/deep-headings-with-config/output.json b/test/fixtures/deep-headings-with-config/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/deep-headings/output.json b/test/fixtures/deep-headings/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/empty-headings/output.json b/test/fixtures/empty-headings/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/heading-no-contents/output.json b/test/fixtures/heading-no-contents/output.json
@@ -1,5 +1,4 @@
 {
   "index": 2,
-  "endIndex": 2,
-  "map": null
+  "endIndex": 2
 }
diff --git a/test/fixtures/headings-ordered/output.json b/test/fixtures/headings-ordered/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": true,
@@ -110,4 +108,4 @@
       }
     ]
   }
-}
+}
diff --git a/test/fixtures/image-in-link-in-heading/output.json b/test/fixtures/image-in-link-in-heading/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/maximum-depth-1/output.json b/test/fixtures/maximum-depth-1/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/maximum-depth-3/output.json b/test/fixtures/maximum-depth-3/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/maximum-depth-6/output.json b/test/fixtures/maximum-depth-6/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/missing-content/output.json b/test/fixtures/missing-content/output.json
@@ -1,5 +1 @@
-{
-  "index": null,
-  "endIndex": null,
-  "map": null
-}
+{}
diff --git a/test/fixtures/missing-heading/output.json b/test/fixtures/missing-heading/output.json
@@ -1,5 +1,4 @@
 {
   "index": -1,
-  "endIndex": -1,
-  "map": null
+  "endIndex": -1
 }
diff --git a/test/fixtures/normal-attr/output.json b/test/fixtures/normal-attr/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/normal-literal-dashes/output.json b/test/fixtures/normal-literal-dashes/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/normal-nesting-inverted/output.json b/test/fixtures/normal-nesting-inverted/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/normal-singular/output.json b/test/fixtures/normal-singular/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/normal-toc/output.json b/test/fixtures/normal-toc/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/normal/output.json b/test/fixtures/normal/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/phrasing-content/output.json b/test/fixtures/phrasing-content/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/prefix/output.json b/test/fixtures/prefix/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/skip/output.json b/test/fixtures/skip/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/slug-for-images-and-links/output.json b/test/fixtures/slug-for-images-and-links/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/tight/output.json b/test/fixtures/tight/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/fixtures/unicode/output.json b/test/fixtures/unicode/output.json
@@ -1,6 +1,4 @@
 {
-  "index": null,
-  "endIndex": null,
   "map": {
     "type": "list",
     "ordered": false,
diff --git a/test/index.js b/test/index.js
@@ -35,7 +35,11 @@ test('toc', async function (t) {
 
   await t.test('should work on a non-parent', async function () {
     const result = toc({type: 'inlineCode', value: 'a'})
-    assert.deepEqual(result, {index: null, endIndex: null, map: null})
+    assert.deepEqual(result, {
+      index: undefined,
+      endIndex: undefined,
+      map: undefined
+    })
   })
 
   /** @type {Array<BlockContent>} */
@@ -96,16 +100,16 @@ test('toc', async function (t) {
 
   await t.test('should process root nodes', async function () {
     assert.deepEqual(toc({type: 'root', children: fragment}), {
-      index: null,
-      endIndex: null,
+      index: undefined,
+      endIndex: undefined,
       map: expectedRootMap
     })
   })
 
   await t.test('should process non-root nodes', async function () {
     assert.deepEqual(toc({type: 'blockquote', children: fragment}), {
-      index: null,
-      endIndex: null,
+      index: undefined,
+      endIndex: undefined,
       map: expectedRootMap
     })
   })
@@ -132,8 +136,8 @@ test('toc', async function (t) {
         {parents: 'blockquote'}
       ),
       {
-        index: null,
-        endIndex: null,
+        index: undefined,
+        endIndex: undefined,
         map: expectedRootMap
       }
     )
@@ -177,7 +181,9 @@ test('fixtures', async function (t) {
         })
       }
 
-      const actual = toc(tree, options)
+      // Drop `undefined`s.
+      /** @type {Root} */
+      const actual = JSON.parse(JSON.stringify(toc(tree, options)))
 
       /** @type {Root} */
       const expected = JSON.parse(

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,4 @@`
`1`	`1`	`{`
`2`		`- "index": null,`
`3`		`- "endIndex": null,`
`4`	`2`	`"map": {`
`5`	`3`	`"type": "list",`
`6`	`4`	`"ordered": false,`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`{`
`2`	`2`	`"index": 2,`
`3`		`- "endIndex": 2,`
`4`		`- "map": null`
	`3`	`+ "endIndex": 2`
`5`	`4`	`}`