path: ts-check

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];
 }