Refactor code-style

*   Add more docs to JSDoc
*   Add support for `null` in input of API types

Author: wooorm

lib/index.js

@@ -5,27 +5,52 @@
  * @typedef {import('vfile').VFileValue} VFileValue
  */
 
+/**
+ * @typedef NodeLike
+ * @property {string} type
+ * @property {PositionLike | null | undefined} [position]
+ *
+ * @typedef PositionLike
+ * @property {PointLike | null | undefined} [start]
+ * @property {PointLike | null | undefined} [end]
+ *
+ * @typedef PointLike
+ * @property {number | null | undefined} [line]
+ * @property {number | null | undefined} [column]
+ * @property {number | null | undefined} [offset]
+ */
+
 import {location} from 'vfile-location'
 
 const search = /\r?\n|\r/g
 
 /**
  * Get the source of a node or at a position.
  *
- * @param {Node|Position} value
+ * @param {Node | NodeLike | Position | PositionLike | null | undefined} value
  *   Value to get.
- * @param {VFile|VFileValue} file
+ * @param {VFile | VFileValue} file
  *   File in which `value` exists.
- * @returns {string|null}
+ * @returns {string | null}
  *   Source of `value` in `doc`, if available.
  */
 export function source(value, file) {
   const doc = String(file)
   const loc = location(file)
-  /** @type {import('unist').Position} */
-  // @ts-expect-error Looks like a node.
-  const position = (value && value.position) || value || {}
+  const position =
+    value && typeof value === 'object'
+      ? 'type' in value
+        ? value.position
+        : value
+      : undefined
+
+  if (!position || !position.start || !position.end) {
+    return null
+  }
+
+  // @ts-expect-error: To do: add `PointLike` to `vfile-location`
   const endOffset = loc.toOffset(position.end)
+  // @ts-expect-error: To do: add `PointLike` to `vfile-location`
   let startOffset = loc.toOffset(position.start)
 
   if (endOffset === -1 || startOffset === -1) {

test.js

@@ -50,13 +50,27 @@ test('unist-util-source', (t) => {
   assert(node.type === 'text')
   t.equal(source(node, file), 'Hello', 'text')
 
+  t.equal(source(node.position, file), 'Hello', 'position')
+
+  t.equal(
+    source(
+      /** @type {Text} */ ({
+        type: 'text',
+        value: 'qwe',
+        position: {start: {line: 0, column: 0}, end: {line: 0, column: 0}}
+      }),
+      file
+    ),
+    null,
+    'out of bounds data'
+  )
+
   t.equal(
-    source(/** @type {Text} */ ({type: node.type, value: node.value}), file),
+    source(/** @type {Text} */ ({type: 'text', value: 'qwe'}), file),
     null,
     'generated'
   )
 
-  // @ts-expect-error: runtime.
   t.equal(source(null, file), null, 'missing')
 
   file = new VFile('a\r\nb')