cubing 0.35.17 → 0.35.19

package/dist/esm/{chunk-VZP3KFTU.js → chunk-CFNRQVBC.js}

@@ -58,23 +58,27 @@ var MIN_INT = -2147483648;
 
 // src/cubing/alg/AlgBuilder.ts
 var AlgBuilder = class {
-  #algNode = [];
+  #algNodes = [];
   push(u) {
-    this.#algNode.push(u);
+    this.#algNodes.push(u);
   }
+  // TODO: Allow FlexibleAlgSource?
+  /** @deprecated */
   experimentalPushAlg(alg) {
     for (const u of alg.childAlgNodes()) {
       this.push(u);
     }
   }
+  // TODO: can we guarantee this to be fast in the permanent API?
   experimentalNumAlgNodes() {
-    return this.#algNode.length;
+    return this.#algNodes.length;
   }
+  // can be called multiple times, even if you push alg nodes inbetween.
   toAlg() {
-    return new Alg(this.#algNode);
+    return new Alg(this.#algNodes);
   }
   reset() {
-    this.#algNode = [];
+    this.#algNodes = [];
   }
 };
 
@@ -220,6 +224,12 @@ var LineComment = class extends AlgCommon {
   toString() {
     return `//${this.#text}`;
   }
+  // toJSON(): LineCommentJSON {
+  //   return {
+  //     type: "comment",
+  //     text: this.#text,
+  //   };
+  // }
 };
 
 // src/cubing/alg/alg-nodes/leaves/Newline.ts
@@ -240,6 +250,7 @@ var Newline = class extends AlgCommon {
 
 // src/cubing/alg/alg-nodes/leaves/Pause.ts
 var Pause = class extends AlgCommon {
+  // TODO: tie this to the alg
   toString() {
     return ".";
   }
@@ -523,11 +534,13 @@ var AlgParser = class {
       if (suffix.startsWith("+")) {
         quantumMove = quantumMove.modified({
           family: `${quantumMove.family}_${suffix === "+" ? "PLUS" : "PLUSPLUS"}_`
+          // TODO
         });
       }
       if (suffix.startsWith("-")) {
         quantumMove = quantumMove.modified({
           family: `${quantumMove.family}_${suffix === "-" ? "PLUS" : "PLUSPLUS"}_`
+          // TODO
         });
         amount *= -1;
       }
@@ -585,6 +598,7 @@ var AlgParser = class {
     this.#idx += arr[0].length;
     return arr;
   }
+  // TOD: can we avoid this?
   tryRegex(regex) {
     const arr = regex.exec(this.remaining());
     if (arr === null) {
@@ -653,6 +667,7 @@ var QuantumWithAmount = class {
   isIdentical(other) {
     return this.quantum.isIdentical(other.quantum) && this.amount === other.amount;
   }
+  // TODO: `Conjugate` and `Commutator` decrement `depth` inside the quantum, `Grouping` has to do it outside the quantum.
   *experimentalExpand(iterDir, depth) {
     const absAmount = Math.abs(this.amount);
     const newIterDir = toggleDirection(iterDir, this.amount < 0);
@@ -697,6 +712,7 @@ var QuantumMove = class extends Comparable {
   static fromString(s) {
     return parseQuantumMove(s);
   }
+  // TODO: `modify`?
   modified(modifications) {
     return new QuantumMove(
       modifications.family ?? this.#family,
@@ -708,12 +724,18 @@ var QuantumMove = class extends Comparable {
     const otherAsQuantumMove = other;
     return other.is(QuantumMove) && this.#family === otherAsQuantumMove.#family && this.#innerLayer === otherAsQuantumMove.#innerLayer && this.#outerLayer === otherAsQuantumMove.#outerLayer;
   }
+  // TODO: provide something more useful on average.
+  /** @deprecated */
   get family() {
     return this.#family;
   }
+  // TODO: provide something more useful on average.
+  /** @deprecated */
   get outerLayer() {
     return this.#outerLayer;
   }
+  // TODO: provide something more useful on average.
+  /** @deprecated */
   get innerLayer() {
     return this.#innerLayer;
   }
@@ -775,6 +797,7 @@ var Move = class extends AlgCommon {
   get quantum() {
     return this.#quantumWithAmount.quantum;
   }
+  // TODO: `modify`?
   modified(modifications) {
     return new Move(
       this.#quantumWithAmount.quantum.modified(modifications),
@@ -787,16 +810,20 @@ var Move = class extends AlgCommon {
   get amount() {
     return this.#quantumWithAmount.amount;
   }
+  /** @deprecated */
   get type() {
     warnOnce("deprecated: type");
     return "blockMove";
   }
+  /** @deprecated */
   get family() {
     return this.#quantumWithAmount.quantum.family ?? void 0;
   }
+  /** @deprecated */
   get outerLayer() {
     return this.#quantumWithAmount.quantum.outerLayer ?? void 0;
   }
+  /** @deprecated */
   get innerLayer() {
     return this.#quantumWithAmount.quantum.innerLayer ?? void 0;
   }
@@ -813,6 +840,15 @@ var Move = class extends AlgCommon {
     }
     return this.#quantumWithAmount.quantum.toString() + this.#quantumWithAmount.suffix();
   }
+  // // TODO: Serialize as a string?
+  // toJSON(): MoveJSON {
+  //   return {
+  //     type: "move",
+  //     family: this.family,
+  //     innerLayer: this.innerLayer,
+  //     outerLayer: this.outerLayer,
+  //   };
+  // }
 };
 
 // src/cubing/alg/alg-nodes/containers/Grouping.ts
@@ -848,6 +884,7 @@ var Square1TupleFormatter = class {
 };
 var square1TupleFormatterInstance = new Square1TupleFormatter();
 var Grouping = class extends AlgCommon {
+  // TODO: tie this to the alg
   constructor(algSource, amount) {
     super();
     const alg = experimentalEnsureAlg(algSource);
@@ -864,6 +901,7 @@ var Grouping = class extends AlgCommon {
   get amount() {
     return this.#quantumWithAmount.amount;
   }
+  /** @deprecated */
   get experimentalRepetitionSuffix() {
     return this.#quantumWithAmount.suffix();
   }
@@ -890,6 +928,12 @@ var Grouping = class extends AlgCommon {
   experimentalAsSquare1Tuple() {
     return square1TupleFormatterInstance.tuple(this);
   }
+  // toJSON(): GroupingJSON {
+  //   return {
+  //     type: "grouping",
+  //     alg: this.#quanta.quantum.toJSON(),
+  //   };
+  // }
 };
 
 // src/cubing/alg/is.ts
@@ -932,6 +976,7 @@ function mustBeAlgNode(t) {
   throw new Error("internal error: expected AlgNode");
 }
 var TraversalDownUp = class {
+  // Immediate subclasses should overwrite this.
   traverseAlgNode(algNode, dataDown) {
     return dispatch(this, algNode, dataDown);
   }
@@ -1067,7 +1112,8 @@ function experimentalAppendMove(alg, addedMove, options) {
       const quantumKey = move.quantum.toString();
       if (sameDirectionOnly) {
         const existingQuantumDirectionOnAxis = quantumDirections.get(quantumKey);
-        if (existingQuantumDirectionOnAxis && !areSameDirection(existingQuantumDirectionOnAxis, move)) {
+        if (existingQuantumDirectionOnAxis && // Short-circuits, but that's actually okay here.
+        !areSameDirection(existingQuantumDirectionOnAxis, move)) {
           break;
         }
         quantumDirections.set(quantumKey, Math.sign(move.amount));
@@ -1110,12 +1156,14 @@ var Simplify = class extends TraversalDownUp {
   #newPlaceholderAssociations() {
     return this.#newPlaceholderAssociationsMap ?? (this.#newPlaceholderAssociationsMap = /* @__PURE__ */ new Map());
   }
+  // TODO: avoid allocations?
   #descendOptions(options) {
     return {
       ...options,
       depth: options.depth ? options.depth - 1 : null
     };
   }
+  // TODO: Handle
   *traverseAlg(alg, options) {
     if (options.depth === 0) {
       yield* alg.childAlgNodes();
@@ -1259,7 +1307,9 @@ function experimentalEnsureAlg(alg) {
   return new Alg(alg);
 }
 var Alg = class extends AlgCommon {
+  // #debugString: string;
   #algNodes;
+  // TODO: freeze?
   constructor(alg) {
     super();
     this.#algNodes = Array.from(toIterable(alg));
@@ -1269,6 +1319,36 @@ var Alg = class extends AlgCommon {
       }
     }
   }
+  /**
+   * Checks whether this Alg is structurally identical to another Alg. This
+   * essentially means that they are written identically apart from whitespace.
+   *
+   *     const alg1 = new Alg("R U L'");
+   *     const alg2 = new Alg("L U' R'").invert();
+   *     // true
+   *     alg1.isIdentical(alg2);
+   *
+   *     // false
+   *     new Alg("[R, U]").isIdentical(new Alg("R U R' U'"));
+   *     // true
+   *     new Alg("[R, U]").expand().isIdentical(new Alg("R U R' U'"));
+   *
+   * Note that .isIdentical() efficiently compares algorithms, but mainly exists
+   * to help optimize code when the structure of an algorithm hasn't changed.
+   * There are many ways to write the "same" alg on most puzzles, but is
+   * *highly* recommended to avoid expanding two Alg instances to compare them,
+   * since that can easily slow your program to a crawl if someone inputs an alg
+   * containing a large repetition. In general, you should use `cubing/kpuzzle`
+   * to compare if two algs have the same effect on a puzzle.
+   *
+   * Also note that parser annotations are not taken into account while comparing
+   * algs:
+   *
+   *     const alg = new Alg([new Move("R"), new Move("U2")]);
+   *     // true, even though one of the algs has parser annotations
+   *     alg.isIdentical(new Alg("R U2"))
+   *
+   */
   isIdentical(other) {
     const otherAsAlg = other;
     if (!other.is(Alg)) {
@@ -1286,15 +1366,44 @@ var Alg = class extends AlgCommon {
     }
     return true;
   }
+  /**
+   * Returns the inverse of the given alg.
+   *
+   * Note that that this does not make any assumptions about what puzzle the alg
+   * is for. For example, U2 is its own inverse on a cube, but U2' has the same
+   * effect U3 (and not U2) on Megaminx:
+   *
+   *     // Outputs: R U2' L'
+   *     new Alg("L U2 R'").invert().log();
+   */
   invert() {
     return new Alg(reverse(Array.from(this.#algNodes).map((u) => u.invert())));
   }
+  /** @deprecated Use {@link Alg.expand} instead. */
   *experimentalExpand(iterDir = 1 /* Forwards */, depth) {
     depth ?? (depth = Infinity);
     for (const algNode of direct(this.#algNodes, iterDir)) {
       yield* algNode.experimentalExpand(iterDir, depth);
     }
   }
+  /**
+   * Expands all Grouping, Commutator, and Conjugate parts nested inside the
+   * alg.
+   *
+   *     // F R U R' U' F'
+   *     new Alg("[F: [R, U]]").expand().log();
+   *
+   *     // F [R, U] F'
+   *     new Alg("[F: [R, U]]").expand(({ depth: 1 }).log();
+   *
+   * Avoid calling this on a user-provided alg unless the user explicitly asks
+   * to see the expanded alg. Otherwise, it's easy to make your program freeze
+   * when someone passes in an alg like: (R U)10000000
+   *
+   * Generally, if you want to perform an operation on an entire alg, you'll
+   * want to use something based on the `Traversal` mechanism, like countMoves()
+   * from `cubing/notation`.
+   */
   expand(options) {
     return new Alg(
       this.experimentalExpand(
@@ -1303,6 +1412,7 @@ var Alg = class extends AlgCommon {
       )
     );
   }
+  /** @deprecated */
   *experimentalLeafMoves() {
     for (const leaf of this.experimentalExpand()) {
       if (leaf.is(Move)) {
@@ -1315,6 +1425,7 @@ var Alg = class extends AlgCommon {
       Array.from(this.#algNodes).concat(Array.from(toIterable(input)))
     );
   }
+  /** @deprecated */
   experimentalIsEmpty() {
     for (const _ of this.#algNodes) {
       return false;
@@ -1324,6 +1435,7 @@ var Alg = class extends AlgCommon {
   static fromString(s) {
     return parseAlg(s);
   }
+  /** @deprecated */
   units() {
     return this.childAlgNodes();
   }
@@ -1332,16 +1444,25 @@ var Alg = class extends AlgCommon {
       yield algNode;
     }
   }
+  /** @deprecated */
   experimentalNumUnits() {
     return this.experimentalNumChildAlgNodes();
   }
   experimentalNumChildAlgNodes() {
     return Array.from(this.#algNodes).length;
   }
+  /** @deprecated */
   get type() {
     warnOnce("deprecated: type");
     return "sequence";
   }
+  /**
+   * Converts the Alg to a string:
+   *
+   *     const alg = new Alg([new Move("R"), new Move("U2"), new Move("L")])
+   *     // R U2 L
+   *     console.log(alg.toString())
+   */
   toString() {
     let output = "";
     let previousVisibleAlgNode = null;
@@ -1363,9 +1484,60 @@ var Alg = class extends AlgCommon {
     }
     return output;
   }
+  /**
+   * `experimentalSimplify` can perform several mostly-syntactic simplifications on an alg:
+   *
+   *     // Logs: R' U3
+   *     import { Alg } from "cubing/alg";
+   *     new Alg("R R2' U U2").experimentalSimplify({ cancel: true }).log()
+   *
+   * You can pass in a `PuzzleLoader` (currently only for 3x3x3) for puzzle-specific simplifications:
+   *
+   *     // Logs: R' U'
+   *     import { Alg } from "cubing/alg";
+   *     import { cube3x3x3 } from "cubing/puzzles";
+   *     new Alg("R R2' U U2").experimentalSimplify({ cancel: true, puzzleLoader: cube3x3x3 }).log()
+   *
+   * You can also cancel only moves that are in the same direction:
+   *
+   *     // Logs: R R2' U'
+   *     import { Alg } from "cubing/alg";
+   *     import { cube3x3x3 } from "cubing/puzzles";
+   *     new Alg("R R2' U U2").experimentalSimplify({
+   *       cancel: { directional: "same-direction" },
+   *       puzzleLoader: cube3x3x3
+   *     }).log()
+   *
+   * Additionally, you can specify how moves are "wrapped":
+   *
+   *     import { Alg } from "cubing/alg";
+   *     import { cube3x3x3 } from "cubing/puzzles";
+   *
+   *     function example(puzzleSpecificModWrap) {
+   *       alg.experimentalSimplify({
+   *         cancel: { puzzleSpecificModWrap },
+   *         puzzleLoader: cube3x3x3
+   *       }).log()
+   *     }
+   *
+   *     const alg = new Alg("R7' . R6' . R5' . R6")
+   *     example("none")               // R7' . R6' . R5' . R6
+   *     example("gravity")            // R . R2' . R' . R2
+   *     example("canonical-centered") // R . R2 . R' . R2
+   *     example("canonical-positive") // R . R2 . R3 . R2
+   *     example("preserve-sign")      // R3' . R2' . R' . R2
+   *
+   * Same-axis and simultaneous move canonicalization is not implemented yet:
+   *
+   *     // Logs: R L R
+   *     import { Alg } from "cubing/alg";
+   *     import { cube3x3x3 } from "cubing/puzzles";
+   *     new Alg("R L R").experimentalSimplify({ cancel: true, puzzleLoader: cube3x3x3 }).log()
+   */
   experimentalSimplify(options) {
     return new Alg(simplify(this, options ?? {}));
   }
+  /** @deprecated See {@link experimentalSimplify} */
   simplify(options) {
     return this.experimentalSimplify(options);
   }
@@ -1503,6 +1675,17 @@ var Example = {
     )
   ]),
   TriplePause: new Alg([new Pause(), new Pause(), new Pause()])
+  // AllAlgParts: [
+  //   new Alg([new Move("R", 1), new Move("U", -1)]),
+  //   new Grouping(new Alg([new Move("F", 1)]), 2),
+  //   // new Rotation("y", -1),
+  //   new Move("R", 2),
+  //   new Commutator(new Alg([new Move("R", 2)]), new Alg([new Move("U", 2)]), 2),
+  //   new Conjugate(new Alg([new Move("L", 2)]), new Alg([new Move("D", -1)]), 2),
+  //   new Pause(),
+  //   new Newline(),
+  //   new LineComment("line comment"),
+  // ],
 };
 
 // src/cubing/alg/keyboard.ts
@@ -1532,6 +1715,7 @@ var cubeKeyMapping = {
   186: new Move("y"),
   59: new Move("y"),
   65: new Move("y'"),
+  // 186 is WebKit, 59 is Mozilla; see http://unixpapa.com/js/key.html
   80: new Move("z"),
   81: new Move("z'"),
   90: new Move("M'"),
@@ -1651,4 +1835,4 @@ export {
   keyToMove,
   experimentalAlgCubingNetLink
 };
-//# sourceMappingURL=chunk-VZP3KFTU.js.map
+//# sourceMappingURL=chunk-CFNRQVBC.js.map