cubing 0.22.0 → 0.24.0-pre2

package/src/cubing/alg/Alg.ts

@@ -1,290 +0,0 @@
-import { AlgCommon, Comparable } from "./common";
-import { experimentalIs, experimentalIsUnit } from "./is";
-import { direct, IterationDirection, reverse } from "./iteration";
-import { parseAlg } from "./parse";
-import { simplify, SimplifyOptions } from "./traversal";
-import { LineComment } from "./units/leaves/LineComment";
-import { Move } from "./units/leaves/Move";
-import { Newline } from "./units/leaves/Newline";
-import type { LeafUnit, Unit } from "./units/Unit";
-import { warnOnce } from "./warnOnce";
-
-export type FlexibleAlgSource = string | Iterable<Unit> | Alg;
-
-// TODO: validate
-function toIterable(input?: FlexibleAlgSource): Iterable<Unit> {
-  if (!input) {
-    return [];
-  }
-
-  if (experimentalIs(input, Alg)) {
-    return (input as Alg).units();
-  }
-
-  if (typeof input === "string") {
-    return parseAlg(input).units(); // TODO: something more direct?
-  }
-
-  // const seq = inputUnits as Sequence;
-  // if (seq.type === "sequence" && seq.nestedUnits) {
-  //   throw new Error("unimplemented");
-  //   // return seq.nestedUnits;
-  // }
-
-  const iter = input as Iterable<Unit>;
-  if (typeof iter[Symbol.iterator] === "function") {
-    return iter; // TODO: avoid allocations
-  }
-
-  throw "Invalid unit";
-}
-
-// Preserves the alg if it's already an `Alg`.
-export function experimentalEnsureAlg(alg: FlexibleAlgSource): Alg {
-  if (experimentalIs(alg, Alg)) {
-    return alg as Alg;
-  }
-  return new Alg(alg);
-}
-
-/**
- * Alg is a class that encapsulated a structured alg. To create an alg from a string, use:
- *
- *     new Alg("R U R'"); // Convenient
- *     Alg.fromString(dynamicString); // Recommended when handling dynamic input.
- *
- * Once you have an Alg, you can call methods to transform it:
- *
- *     new Alg("[[R: U], R U R2']").expand().simplify().invert();
- *
- * To convert an Alg to a string, use .toString():
- *
- *     new Alg("R U F").invert().toString();
- *
- * If you need to debug, you may also find it convenient to use .log():
- *
- *     if (alg.isIdentical(alg.invert())) {
- *       alg.log("A self-inverse!")
- *     }
- *
- * For more information, see: {@link https://js.cubing.net/cubing/alg/}
- *
- */
-export class Alg extends AlgCommon<Alg> {
-  // #debugString: string;
-  #units: Iterable<Unit>; // TODO: freeze?
-  constructor(alg?: FlexibleAlgSource) {
-    super();
-    this.#units = Array.from(toIterable(alg)); // TODO: can we avoid array-casting?
-    // this.#debugString = this.toString();
-
-    for (const unit of this.#units) {
-      if (!experimentalIsUnit(unit)) {
-        throw new Error("An alg can only contain units.");
-      }
-    }
-  }
-
-  /**
-   * 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 take 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: Comparable): boolean {
-    const otherAsAlg = other as Alg;
-    if (!other.is(Alg)) {
-      return false;
-    }
-
-    // TODO: avoid converting to array
-    const l1 = Array.from(this.#units);
-    const l2 = Array.from(otherAsAlg.#units);
-    if (l1.length !== l2.length) {
-      return false;
-    }
-    for (let i = 0; i < l1.length; i++) {
-      if (!l1[i].isIdentical(l2[i])) {
-        return false;
-      }
-    }
-    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(): Alg {
-    // TODO: Handle newLines and comments correctly
-    // TODO: Make more efficient.
-    return new Alg(reverse(Array.from(this.#units).map((u) => u.invert())));
-  }
-
-  /** @deprecated Use {@link Alg.expand} instead. */
-  *experimentalExpand(
-    iterDir: IterationDirection = IterationDirection.Forwards,
-    depth?: number,
-  ): Generator<LeafUnit> {
-    depth ??= Infinity;
-    for (const unit of direct(this.#units, iterDir)) {
-      yield* unit.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?: { depth?: number }): Alg {
-    return new Alg(
-      this.experimentalExpand(
-        IterationDirection.Forwards,
-        options?.depth ?? Infinity,
-      ),
-    );
-  }
-
-  /** @deprecated */
-  *experimentalLeafMoves(): Generator<Move> {
-    for (const leaf of this.experimentalExpand()) {
-      if (leaf.is(Move)) {
-        yield leaf as Move;
-      }
-    }
-  }
-
-  concat(input: FlexibleAlgSource): Alg {
-    return new Alg(
-      Array.from(this.#units).concat(Array.from(toIterable(input))),
-    );
-  }
-
-  /** @deprecated */
-  experimentalIsEmpty(): boolean {
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    for (const _ of this.#units) {
-      return false;
-    }
-    return true;
-  }
-
-  static fromString(s: string): Alg {
-    return parseAlg(s);
-  }
-
-  *units(): Generator<Unit> {
-    for (const unit of this.#units) {
-      yield unit;
-    }
-  }
-
-  experimentalNumUnits(): number {
-    return Array.from(this.#units).length;
-  }
-
-  /** @deprecated */
-  get type(): string {
-    warnOnce("deprecated: type");
-    return "sequence";
-  }
-
-  // toJSON(): AlgJSON {
-  //   return {
-  //     type: "alg",
-  //     units: Array.from(this.#units) as UnitJSON[],
-  //   };
-  // }
-
-  /**
-   * 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(): string {
-    let output = "";
-    let previousUnit: Unit | null = null;
-    for (const unit of this.#units) {
-      if (previousUnit) {
-        output += spaceBetween(previousUnit, unit);
-        // console.log("l", previousUnit.toString(), unit.toString(), output);
-      }
-      output += unit.toString();
-      previousUnit = unit;
-    }
-    return output;
-  }
-
-  // *experimentalExpand(options: ExperimentalExpandOptions): Generator<Unit> {
-  //   // if (options.depth === 0) {
-  //   //   yield* this.units();
-  //   //   return;
-  //   // }
-  //   // const newOptions = {
-  //   //   depth: options.depth ? options.depth - 1 : null,
-  //   // }; // TODO: avoid allocations?
-  //   // for (const unit of this.#units) {
-  //   //   yield* unit.experimentalExpandIntoAlg(newOptions);
-  //   // }
-  // }
-
-  simplify(options?: SimplifyOptions): Alg {
-    return new Alg(simplify(this, options ?? {}));
-  }
-}
-
-function spaceBetween(u1: Unit, u2: Unit): string {
-  if (u1.is(Newline) || u2.is(Newline)) {
-    return "";
-  }
-  if (u1.is(LineComment) && !u2.is(Newline)) {
-    return "\n"; /// TODO
-  }
-  return " ";
-}

package/src/cubing/alg/AlgBuilder.ts

@@ -1,33 +0,0 @@
-import { Alg } from "./Alg";
-import type { Unit } from "./units/Unit";
-
-export class AlgBuilder {
-  #units: Unit[] = [];
-
-  push(u: Unit): void {
-    this.#units.push(u);
-  }
-
-  // TODO: Allow FlexibleAlgSource?
-  /** @deprecated */
-  experimentalPushAlg(alg: Alg): void {
-    // TODO: Optimize?
-    for (const u of alg.units()) {
-      this.push(u);
-    }
-  }
-
-  // TODO: can we guarantee this to be fast in the permanent API?
-  experimentalNumUnits(): number {
-    return this.#units.length;
-  }
-
-  // can be called multiple times, even if you push units inbetween.
-  toAlg(): Alg {
-    return new Alg(this.#units);
-  }
-
-  reset(): void {
-    this.#units = [];
-  }
-}

package/src/cubing/alg/Serializable.ts

@@ -1,29 +0,0 @@
-// export interface MoveJSON {
-//   type: "move";
-//   family: string;
-//   innerLayer?: number;
-//   outerLayer?: number;
-// }
-
-// export interface GroupingJSON {
-//   type: "grouping";
-//   alg: AlgJSON;
-// }
-
-// export interface LineCommentJSON {
-//   type: "comment";
-//   text: string;
-// }
-
-// export interface CommutatorJSON {
-//   type: "commutator";
-//   A: AlgJSON;
-//   B: AlgJSON;
-// }
-
-// export type UnitJSON = MoveJSON | GroupingJSON;
-
-// export interface AlgJSON {
-//   type: "alg";
-//   units: UnitJSON[];
-// }

package/src/cubing/alg/common.ts

@@ -1,59 +0,0 @@
-import type { Alg } from "./Alg";
-import type { IterationDirection } from "./iteration";
-import type { LeafUnit, Unit } from "./units/Unit";
-
-let writeAlgDebugField = false;
-export function setAlgDebugField(debug: boolean): void {
-  writeAlgDebugField = debug;
-}
-
-export abstract class Comparable {
-  // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
-  is(c: any): boolean {
-    return this instanceof c;
-  }
-
-  as<T>(c: new (...args: any) => T): T | null {
-    return this instanceof c ? this : null;
-  }
-
-  abstract isIdentical(other: Comparable): boolean;
-}
-
-export interface Repeatable extends Comparable {
-  experimentalExpand(
-    iterDir?: IterationDirection,
-    depth?: number,
-  ): Generator<LeafUnit>;
-}
-
-// Common to algs or units
-export abstract class AlgCommon<T extends Alg | Unit>
-  extends Comparable
-  implements Repeatable
-{
-  constructor() {
-    super();
-    if (writeAlgDebugField) {
-      Object.defineProperty(this, "_debugStr", {
-        get: () => {
-          return this.toString();
-        },
-      });
-    }
-  }
-
-  get log(): (message?: any) => void {
-    // By returning a (bound) version of `console.log`, we ensure that DevTools
-    // logs the call site instead of this function.
-    return console.log.bind(console, this, this.toString()) as (
-      message?: any,
-    ) => void;
-  }
-
-  abstract toString(): string;
-
-  abstract invert(): T;
-
-  abstract experimentalExpand(iterDir: IterationDirection): Generator<LeafUnit>;
-}

package/src/cubing/alg/debug.ts

@@ -1,27 +0,0 @@
-type ReportingLevel = "none" | "warn" | "error";
-let currentReportingLevel = "warn";
-
-const MAX_NUMBER_OF_TIMES_TO_WARN = 10;
-let numWarned = 0;
-
-// TODO: Avoid creating the string message if it won't be used (e.g. by taking a function?).
-export function reportTypeMismatch(msg: string): void {
-  switch (currentReportingLevel) {
-    case "error":
-      throw new Error(msg);
-    case "warn":
-      numWarned++;
-      if (numWarned < MAX_NUMBER_OF_TIMES_TO_WARN) {
-        if (numWarned + 1 === MAX_NUMBER_OF_TIMES_TO_WARN) {
-          console.warn(msg);
-        }
-      }
-      return;
-  }
-}
-
-export function setAlgPartTypeMismatchReportingLevel(
-  level: ReportingLevel,
-): void {
-  currentReportingLevel = level;
-}

package/src/cubing/alg/example.ts

@@ -1,152 +0,0 @@
-// tslint:disable-next-line no-namespace // TODO: nested module
-
-import { Alg } from "./Alg";
-import { Grouping } from "./units";
-import { Commutator } from "./units/containers/Commutator";
-import { Conjugate } from "./units/containers/Conjugate";
-import { Move } from "./units/leaves/Move";
-import { Pause } from "./units/leaves/Pause";
-
-// eslint-disable-next-line @typescript-eslint/no-namespace
-export const Example = {
-  Sune: new Alg([
-    new Move("R", 1),
-    new Move("U", 1),
-    new Move("R", -1),
-    new Move("U", 1),
-    new Move("R", 1),
-    new Move("U", -2),
-    new Move("R", -1),
-  ]),
-
-  AntiSune: new Alg([
-    new Move("R", 1),
-    new Move("U", 2),
-    new Move("R", -1),
-    new Move("U", -1),
-    new Move("R", 1),
-    new Move("U", -1),
-    new Move("R", -1),
-  ]),
-
-  SuneCommutator: new Alg([
-    new Commutator(
-      new Alg([new Move("R", 1), new Move("U", 1), new Move("R", -2)]),
-      new Alg([
-        new Conjugate(new Alg([new Move("R", 1)]), new Alg([new Move("U", 1)])),
-      ]),
-    ),
-  ]),
-
-  Niklas: new Alg([
-    new Move("R", 1),
-    new Move("U", -1),
-    new Move("L", -1),
-    new Move("U", 1),
-    new Move("R", -1),
-    new Move("U", -1),
-    new Move("L", 1),
-    new Move("U", 1),
-  ]),
-
-  EPerm: new Alg([
-    new Move("x", -1),
-    new Commutator(
-      new Alg([
-        new Conjugate(
-          new Alg([new Move("R", 1)]),
-          new Alg([new Move("U", -1)]),
-        ),
-      ]),
-      new Alg([new Move("D", 1)]),
-    ),
-    new Commutator(
-      new Alg([
-        new Conjugate(new Alg([new Move("R", 1)]), new Alg([new Move("U", 1)])),
-      ]),
-      new Alg([new Move("D", 1)]),
-    ),
-    new Move("x", 1),
-  ]),
-
-  FURURFCompact: new Alg([
-    new Conjugate(
-      new Alg([new Move("F", 1)]),
-      new Alg([
-        new Commutator(
-          new Alg([new Move("U", 1)]),
-          new Alg([new Move("R", 1)]),
-        ),
-      ]),
-    ),
-  ]),
-
-  APermCompact: new Alg([
-    new Conjugate(
-      new Alg([new Move("R", 2)]),
-      new Alg([
-        new Commutator(
-          new Alg([new Move("F", 2)]),
-          new Alg([new Move("R", -1), new Move("B", -1), new Move("R", 1)]),
-        ),
-      ]),
-    ),
-  ]),
-
-  FURURFMoves: new Alg([
-    new Move("F", 1),
-    new Move("U", 1),
-    new Move("R", 1),
-    new Move("U", -1),
-    new Move("R", -1),
-    new Move("F", -1),
-  ]),
-
-  TPerm: new Alg([
-    new Move("R", 1),
-    new Move("U", 1),
-    new Move("R", -1),
-    new Move("U", -1),
-    new Move("R", -1),
-    new Move("F", 1),
-    new Move("R", 2),
-    new Move("U", -1),
-    new Move("R", -1),
-    new Move("U", -1),
-    new Move("R", 1),
-    new Move("U", 1),
-    new Move("R", -1),
-    new Move("F", -1),
-  ]),
-
-  HeadlightSwaps: new Alg([
-    new Conjugate(
-      new Alg([new Move("F", 1)]),
-      new Alg([
-        new Grouping(
-          new Alg([
-            new Commutator(
-              new Alg([new Move("R", 1)]),
-              new Alg([new Move("U", 1)]),
-            ),
-          ]),
-          3,
-        ),
-      ]),
-    ),
-  ]),
-
-  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"),
-  // ],
-};

package/src/cubing/alg/index.ts

@@ -1,21 +0,0 @@
-export { Alg } from "./Alg";
-export { AlgBuilder } from "./AlgBuilder";
-export { TraversalDownUp, TraversalUp } from "./traversal";
-export { Example } from "./example";
-export { keyToMove } from "./keyboard";
-export * from "./units";
-export { MoveModifications } from "./units/leaves/Move";
-
-export { algCubingNetLink } from "./url";
-export type { AlgCubingNetOptions } from "./url";
-
-export { experimentalAppendMove } from "./operation";
-export { experimentalIs } from "./is";
-export {
-  directedGenerator as experimentalDirectedGenerator,
-  direct as experimentalDirect,
-  IterationDirection as ExperimentalIterationDirection,
-} from "./iteration";
-
-// TODO: Find a better way to track parsed algs.
-export type { Parsed as ExperimentalParsed } from "./parse";

package/src/cubing/alg/is.ts

@@ -1,38 +0,0 @@
-import type { Alg } from "./Alg";
-import {
-  Commutator,
-  Conjugate,
-  Grouping,
-  LineComment,
-  Move,
-  Newline,
-  Pause,
-} from "./units";
-
-export function experimentalIs(
-  // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
-  v: any,
-  c:
-    | typeof Alg
-    | typeof Grouping
-    | typeof LineComment
-    | typeof Commutator
-    | typeof Conjugate
-    | typeof Move
-    | typeof Newline
-    | typeof Pause,
-): boolean {
-  return v instanceof c;
-}
-// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
-export function experimentalIsUnit(v: any): boolean {
-  return (
-    experimentalIs(v, Grouping) ||
-    experimentalIs(v, LineComment) ||
-    experimentalIs(v, Commutator) ||
-    experimentalIs(v, Conjugate) ||
-    experimentalIs(v, Move) ||
-    experimentalIs(v, Newline) ||
-    experimentalIs(v, Pause)
-  );
-}

package/src/cubing/alg/iteration.ts

@@ -1,45 +0,0 @@
-export enum IterationDirection {
-  Forwards = 1,
-  Backwards = -1,
-}
-
-export function toggleDirection(
-  iterationDirection: IterationDirection,
-  flip: boolean = true,
-): IterationDirection {
-  if (!flip) {
-    return iterationDirection;
-  }
-  switch (iterationDirection) {
-    case IterationDirection.Forwards:
-      return IterationDirection.Backwards;
-    case IterationDirection.Backwards:
-      return IterationDirection.Forwards;
-  }
-}
-
-export function direct<T>(
-  g: Iterable<T>,
-  iterDir: IterationDirection,
-): Iterable<T> {
-  return iterDir === IterationDirection.Backwards ? Array.from(g).reverse() : g;
-}
-
-export function reverse<T>(g: Iterable<T>): Iterable<T> {
-  return Array.from(g).reverse();
-}
-
-export function* directedGenerator<T>(
-  g: Generator<T>,
-  direction: IterationDirection,
-): Generator<T> {
-  direction === IterationDirection.Backwards
-    ? yield* reverseGenerator(g)
-    : yield* g;
-}
-
-export function* reverseGenerator<T>(g: Generator<T>): Generator<T> {
-  for (const t of Array.from(g).reverse()) {
-    yield t;
-  }
-}