Refactor code-style

*   Accept `null` as input in types
*   Add more docs to JSDoc

Author: wooorm

index.js

@@ -1,16 +1,23 @@
+// To do next major: use `structuredClone` (or so?) to deep clone `properties`
+// and the like: the return value has to be a clone (not shallow copy) of the
+// passed tree.
+
 /**
  * @typedef {import('hast').Root} Root
  * @typedef {import('hast').Content} Content
  * @typedef {import('hast').Text} Text
- * @typedef {Root|Content} Node
+ */
+
+/**
+ * @typedef {Root | Content} Node
  *
  * @typedef Options
  *   Configuration.
- * @property {number} [size=140]
+ * @property {number | null | undefined} [size=140]
  *   Number of characters to truncate to.
- * @property {string} [ellipsis]
+ * @property {string | null | undefined} [ellipsis]
  *   Value to use at truncation point.
- * @property {number} [maxCharacterStrip=30]
+ * @property {number | null | undefined} [maxCharacterStrip=30]
  *   How far to walk back.
  *   The algorithm attempts to break right after a word rather than the exact
  *   `size`.
@@ -25,27 +32,37 @@
  *   If `maxCharacterStrip` characters are walked back and no nice break point
  *   is found, the bad break point is used.
  *   Set `maxCharacterStrip: 0` to not find a nice break.
- * @property {Array<Content>} [ignore=[]]
+ * @property {Array<Content> | null | undefined} [ignore=[]]
  *   Nodes to exclude from the resulting tree.
  *   These are not counted towards `size`.
  */
 
 import {unicodeWhitespace, unicodePunctuation} from 'micromark-util-character'
 
+/** @type {ReadonlyArray<void>} */
+const empty = []
+
 /**
  * Truncate the tree to a certain number of characters.
  *
  * @template {Node} Tree
  * @param {Tree} tree
- * @param {Options} [options]
+ * @param {Options | null | undefined} [options]
  * @returns {Tree}
+ *   A shallow copy of `tree`, truncated.
  */
-export function truncate(tree, options = {}) {
+export function truncate(tree, options) {
   // To do: support units.
-  const {size = 140, ellipsis, maxCharacterStrip = 30, ignore = []} = options
+  const config = options || {}
+  const size = typeof config.size === 'number' ? config.size : 140
+  const maxCharacterStrip =
+    typeof config.maxCharacterStrip === 'number' ? config.maxCharacterStrip : 30
+  const ignore = config.ignore || empty
+  const ellipsis = config.ellipsis
   let searchSize = 0
-  /** @type {Text|undefined} */
+  /** @type {Text | undefined} */
   let overflowingText
+
   const result = preorder(tree)
 
   if (overflowingText) {
@@ -89,8 +106,12 @@ export function truncate(tree, options = {}) {
   return result
 
   /**
+   * Transform in `preorder`.
+   *
    * @param {Node} node
-   * @returns {Node|undefined}
+   *   Node to truncate.
+   * @returns {Node}
+   *   Shallow copy of `node`.
    */
   function preorder(node) {
     if (node.type === 'text') {
@@ -119,6 +140,7 @@ export function truncate(tree, options = {}) {
           if (result) children.push(result)
         }
 
+        // One of the descendant texts included the breakpoint.
         if (overflowingText) {
           break
         }
@@ -134,7 +156,9 @@ export function truncate(tree, options = {}) {
 
 /**
  * @param {number} code
+ *   Character code.
  * @returns {boolean}
+ *   Whether `code` is not whitespace and not punctuation.
  */
 function unicodeAlphanumeric(code) {
   return !unicodeWhitespace(code) && !unicodePunctuation(code)