From cf4b82020a5fdff6ebcc9011da9ea6855eb0f5a0 Mon Sep 17 00:00:00 2001
From: Joshua T Corbin <jcorbin@wunjo.org>
Date: Wed, 3 Mar 2021 16:14:01 -0800
Subject: [PATCH] path: ts-check

---
 path.js | 49 +++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 41 insertions(+), 8 deletions(-)

diff --git a/path.js b/path.js
index f862f87..9f35cd5 100644
--- a/path.js
+++ b/path.js
@@ -1,13 +1,31 @@
+// @ts-check
+
 'use strict';
 
+/** A path is a story label optionally with a variable number of ids.
+ * The label may be a dotted string containing sub-labels within each dotted level.
+ * Any ids count nodes within the grammar subtree under label.
+ *
+ * @typedef {[string, ...number[]]} Path
+ */
+
 exports.start = start;
 
+/** Creates the Path where all stories start from.
+ *
+ * @returns {Path}
+ */
 function start() {
     return ['start'];
 }
 
 exports.toName = pathToName;
 
+/** Converts a path to a dotted string like "lab.el.1.2.3"
+ *
+ * @param {Path} path
+ * @returns {string}
+ */
 function pathToName(path) {
     var name = path[0];
     var i;
@@ -23,24 +41,39 @@ function pathToName(path) {
 
 exports.next = nextPath;
 
+/** Constructs a sibling path, incrementing the last id from the given path.
+ * If the given path is label-only, simply returns the given path unchanged.
+ *
+ * @param {Path} path
+ * @returns {Path}
+ */
 function nextPath(path) {
-    path = path.slice();
-    path[path.length - 1]++;
+    const [label, ...ids] = path;
+    if (ids.length > 0) {
+        ids[ids.length-1]++;
+        return [label, ...ids];
+    }
     return path;
 }
 
 exports.firstChild = firstChildPath;
 
+/** Constructs a child path by appending a 1 id to a copy of the given path.
+ *
+ * @param {Path} path
+ * @returns {Path} -- a copy of path with an added 1 id
+ */
 function firstChildPath(path) {
-    path = path.slice();
-    path.push(1);
-    return path;
+    return [...path, 1];
 }
 
 exports.zerothChild = zerothChildPath;
 
+/** Constructs a child path by appending a 0 id to a copy of the given path.
+ *
+ * @param {Path} path
+ * @returns {Path} -- a copy of path with an added 0 id
+ */
 function zerothChildPath(path) {
-    path = path.slice();
-    path.push(0);
-    return path;
+    return [...path, 0];
 }