Convert "Hebrew frequency list: 10,000 most commonly used words" into Anki cards

ankiHebrewParse.js

/*
 * Convert "Hebrew frequency list: 10,000 most commonly used words" into Anki cards.
 *
 * https://www.teachmehebrew.com/hebrew-frequency-list.html
 * http://web.archive.org/web/20230320182549/https://www.teachmehebrew.com/hebrew-frequency-list.html
 *
 * Go to the page and run this script in the developer console.
 */

/*
Copyright (c) 2023 Johan Kiviniemi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/

await (async () => {
  /**
   * @returns {Promise<void>}
   */
  async function main() {
    const { englishToHebrew, hebrewToEnglish } = parseDictionaries();

    if (englishToHebrew.size === 0 || hebrewToEnglish.size === 0) {
      throw new Error(
        "Failed to find words. Are you on <https://www.teachmehebrew.com/hebrew-frequency-list.html>?"
      );
    }

    await downloadDictionary(englishToHebrew, "english-to-hebrew.csv");
    await downloadDictionary(hebrewToEnglish, "hebrew-to-english.csv");

    alert(
      [
        "1. Create the following decks in Anki:",
        "  • English to Hebrew",
        "  • Hebrew to English",
        "2. Import each file. Enable “Allow HTML in fields” and make sure to choose the correct deck for each import.",
      ].join("\n")
    );
  }

  /**
   * @typedef {Object} ParseDictionariesResult
   * @property {Map<string, Set<string>>} englishToHebrew
   * @property {Map<string, Set<string>>} hebrewToEnglish
   */

  /**
   * @returns {ParseDictionariesResult}
   */
  function parseDictionaries() {
    /** @type {Map<string, Set<string>>} */
    const englishToHebrew = new Map();
    /** @type {Map<string, Set<string>>} */
    const hebrewToEnglish = new Map();

    /** All rows. */
    let englishRowCount = 0;
    /** Rows with a word in Hebrew. */
    let hebrewRowCount = 0;

    // There are multiple tables with id="words".
    for (const table of document.querySelectorAll("table[id='words']")) {
      if (!(table instanceof HTMLTableElement)) {
        console.debug("Expected a table:", table);
        throw new Error("Expected a table, please see the console");
      }

      /** @type {string | null} */
      let prevHebrew = null;

      for (const row of table.rows) {
        if (row.cells.length !== 4) {
          console.warn("Expected 4 cells:", row);
          continue;
        }

        if (row.cells[0].tagName === "TH") {
          const expectedHeadings = [
            "Rank",
            "English",
            "Transliteration",
            "Hebrew",
          ];
          const headings = Array.from(row.cells).map((c) =>
            (c.textContent ?? "").trim()
          );
          if (JSON.stringify(headings) !== JSON.stringify(expectedHeadings)) {
            const message = `Unexpected headings: ${JSON.stringify(headings)}`;
            throw new Error(message);
          }

          // Skip header row.
          continue;
        }

        const english = row.cells[1].innerHTML.trim();
        const transliteration = row.cells[2].innerHTML.trim();
        const currHebrew = row.cells[3].innerHTML.trim();

        if (
          english.length === 0 &&
          transliteration.length === 0 &&
          currHebrew.length === 0
        ) {
          console.info("Skipping empty row:", row.cells);
          continue;
        }

        ++englishRowCount;
        if (currHebrew.length !== 0) ++hebrewRowCount;

        // TS doesn't figure out the type automatically?
        /** @type{string} */
        const hebrew =
          currHebrew.length === 0 && prevHebrew != null
            ? prevHebrew
            : currHebrew;
        prevHebrew = hebrew;

        const hebrewWithTransliteration = `${hebrew} (${transliteration})`;

        mapGetOrSetDefault(englishToHebrew, english, () => new Set()).add(
          hebrewWithTransliteration
        );

        mapGetOrSetDefault(
          hebrewToEnglish,
          hebrewWithTransliteration,
          () => new Set()
        ).add(english);
      }
    }

    console.info(`English count: ${englishRowCount} rows`);
    console.info(`Hebrew count: ${hebrewRowCount} rows`);
    console.info(`English to Hebrew: ${englishToHebrew.size} entries`);
    console.info(`Hebrew to English: ${hebrewToEnglish.size} entries`);

    return { englishToHebrew, hebrewToEnglish };
  }

  /**
   * @template K, V
   * @param {Map<K, V>} map
   * @param {K} key
   * @param {() => V} defaultCB
   * @returns V
   */
  function mapGetOrSetDefault(map, key, defaultCB) {
    const value = map.get(key);
    if (value !== undefined) {
      return value;
    }

    const defValue = defaultCB();
    map.set(key, defValue);
    return defValue;
  }

  /**
   * @param {Map<string, Set<string>>} dictionaryMap
   * @param {string} filename
   * @returns {Promise<void>}
   */
  async function downloadDictionary(dictionaryMap, filename) {
    const stream = dictionaryCSVStream(dictionaryMap);

    await downloadReadableStream(stream, filename, "text/csv");
  }

  /**
   * @param {Map<string, Set<string>>} dictionaryMap
   * @returns {ReadableStream<Uint8Array>}
   */
  function dictionaryCSVStream(dictionaryMap) {
    const entries = dictionaryMap.entries();
    const enc = new TextEncoder();

    const stream = new ReadableStream({
      // A cursed way to make the parent ReadableStream have <Uint8Array> in JSDoc.
      /** @param {ReadableStreamDefaultController<Uint8Array>} controller */
      pull(controller) {
        const { value, done } = entries.next();

        if (done) {
          controller.close();
          return;
        }

        const [from, toSet] = value;

        const ul = document.createElement("ul");
        ul.style.display = "inline-block";
        ul.style.margin = "0";
        ul.style.padding = "0";
        ul.style.listStyle = "inside";

        for (const word of toSet) {
          const li = document.createElement("li");
          li.innerHTML = word;
          ul.appendChild(li);
        }

        const to =
          toSet.size === 1 ? toSet.values().next().value : ul.outerHTML;

        const row = csvEscapeRow([from, to]);
        controller.enqueue(enc.encode(row));
      },
    });

    return stream;
  }

  /**
   * @param {string[]} strArray
   * @returns string
   */
  function csvEscapeRow(strArray) {
    return strArray.map(csvEscapeString).join(";") + "\r\n";
  }

  /**
   * @param {string} str
   * @returns string
   */
  function csvEscapeString(str) {
    return str.length === 0 ? "" : `"${str.replaceAll('"', '""')}"`;
  }

  /**
   * @param {ReadableStream<Uint8Array>} stream
   * @param {string} filename
   * @param {string} contentType
   * @returns {Promise<void>}
   */
  async function downloadReadableStream(stream, filename, contentType) {
    const resp = new Response(stream, {
      headers: { "Content-Type": contentType },
    });
    const blob = await resp.blob();
    const blobURL = window.URL.createObjectURL(blob);

    try {
      const elem = document.createElement("a");
      elem.href = blobURL;
      elem.setAttribute("download", filename);
      elem.style.display = "none";

      document.body.appendChild(elem);

      try {
        elem.click();
      } finally {
        elem.parentNode?.removeChild(elem);
      }
    } finally {
      window.URL.revokeObjectURL(blobURL);
    }
  }

  try {
    await main();
  } catch (e) {
    console.error(e);
    alert(e.message);
    throw e;
  }
})();