Finish adding JS API docs.

packages/js/src/parser.ts

@@ -1,6 +1,6 @@
 // Holds the parsed information from each line.
 export type LineData = {
-  // Which character is being used for indentation. Avoids having to specify it on each terrace_parse_line call.
+  // Which character is being used for indentation. Avoids having to specify it on each parseLine call.
   indent: string;
   // How many indent characters are present in the current line before the first non-indent character.
   level: number;
@@ -12,7 +12,7 @@ export type LineData = {
 }
 
 /**
- * Initialize a LineData instance with default values.
+ * Initialize a LineData instance with default values to pass to parseLine()
  * @param {string} indent The character to use for indenting lines. ONLY ONE CHARACTER IS CURRENTLY PERMITTED.
  * @returns {LineData} A LineData instance with the specified indent character and all other values initialized to 0.
  */
@@ -21,10 +21,10 @@ export function createLineData(indent: string = ' '): LineData {
 }
 
 /**
- * Core Terrace parser function, sets level, offsetHead, and offsetTail in a LineData object based on the current line.
+ * Core Terrace parser function, sets level, offsetHead, and offsetTail in a LineData object based on the passed line.
  * Note that this is a C-style function, lineData is treated as a reference and mutated in-place.
  * @param {string} line A string containing a line to parse. Shouldn't end with a newline.
- * @param {LineData} lineData A LineData object to store information about the current line in. **Mutated in-place!**
+ * @param {LineData} lineData A LineData object to store information about the current line, from `createLineData()` **Mutated in-place!**
  */
 export function parseLine(line: string, lineData: LineData) {
   if ((typeof lineData !== 'object' || !lineData) || typeof lineData.level !== 'number') throw new Error(`'lineData' must be an object with string line and numeric level properties`)

packages/js/src/readers/js-string.ts

@@ -1,7 +1,15 @@
 import type { Reader } from './reader'
 
-export function createStringReader(doc: string|string[], index = 0): Reader {
-  const lines = Array.isArray(doc) ? doc : doc.split('\n')
+/**
+ * Get a simple `Reader` function that always returns the next line
+ * from a multiline string or an array of line strings.
+ *
+ * @param {string|string[]} source The lines to iterate over, as a multiline string or an array of line strings.
+ * @param {number} index Optional - which line to start from.
+ * @returns {Reader} A reader function that returns each line from the source document when called sequentially.
+ */
+export function createStringReader(source: string|string[], index: number = 0): Reader {
+  const lines = Array.isArray(source) ? source : source.split('\n')
 
   index--;
 

packages/js/src/readers/node-readline.ts

@@ -2,18 +2,36 @@ import fs from 'node:fs'
 import readline from 'node:readline/promises'
 import type { Reader } from './reader'
 
+
+/**
+ * Get a `Reader` function that always returns the next line from a passed read stream when called sequentially.
+ * @param {NodeJS.ReadStream|fs.ReadStream} stream A ReadStream compatible with Node.js `readline` APIs
+ * @returns {Reader} A reader function that returns each line from the stream when called sequentially
+ */
+export function createStreamReader(stream: NodeJS.ReadStream|fs.ReadStream): Reader {
+  // A bit of a messy way of working with readline, but the most straightforward
+  // way I found that allowed pulling lines with a promise-style interface.
+  const iterator = readline.createInterface({
+    input: stream
+  })[Symbol.asyncIterator]()
+
+  return async () => (await iterator.next()).value
+}
+
+/**
+ * Get a `Reader` function that always returns the next line from the specified file when called sequentially.
+ * @param {string} path A path to the file to read.
+ * @returns {Reader} A reader function that returns each line from the file when called sequentially
+ */
 export function createFileReader(path: string): Reader {
-  const it = readline.createInterface({
-    input: fs.createReadStream(path, 'utf-8'),
-  })[Symbol.asyncIterator]()
-
-  return async () => (await it.next()).value
+  return createStreamReader(fs.createReadStream(path, 'utf-8'))
 }
 
+/**
+ * Get a `Reader` function that always returns the next line from `stdin` when called sequentially.
+ * Does not block stdin to wait for input. If no input is present it returns null immediately.
+ * @returns {Reader} A reader function that returns each line from the stdin when called sequentially.
+ */
 export function createStdinReader(): Reader {
-  const it = readline.createInterface({
-    input: process.stdin
-  })[Symbol.asyncIterator]()
-
-  return async () => (await it.next()).value
+  return createStreamReader(process.stdin)
 }