@johnmorrisdotca/kumimoji 1.2.2 → 1.3.1

package/dist/export.d.ts

@@ -14,9 +14,31 @@ import { type KumimojiStrings } from "./strings.ts";
  * the game only if every tile in the hand and on the table is one that came
  * out of that bag and was not given back.
  */
-/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one. */
+/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_EXPORT_FORMAT } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_EXPORT_FORMAT);
+ * ```
+ */
 export declare const KUMIMOJI_EXPORT_FORMAT = 1;
-/** A game alone as it is kept: the deal, where the player has got to, and the time spent so far. */
+/** A game alone as it is kept: the deal, where the player has got to, and the time spent so far.
+ *
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji } from "@johnmorrisdotca/kumimoji";
+ * import type { KumimojiSaved } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * const value: KumimojiSaved = saved;
+ * console.log(value);
+ * ```
+ */
 export type KumimojiSaved = {
     /** The game as dealt: `generateKumimoji`'s. */
     deal: KumimojiDeal;
@@ -25,7 +47,22 @@ export type KumimojiSaved = {
     /** Milliseconds spent on it so far. */
     elapsedMs: number;
 };
-/** A whole JSON export of one game: what `kumimojiToJSON` writes and `kumimojiFromJSON` reads. */
+/** A whole JSON export of one game: what `kumimojiToJSON` writes and `kumimojiFromJSON` reads.
+ *
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiExported } from "@johnmorrisdotca/kumimoji";
+ * import type { KumimojiExported } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * const value: KumimojiExported = kumimojiExported(saved);
+ * console.log(value);
+ * ```
+ */
 export type KumimojiExported = {
     /** The shape's number: `KUMIMOJI_EXPORT_FORMAT`. */
     format: typeof KUMIMOJI_EXPORT_FORMAT;
@@ -52,9 +89,39 @@ export type KumimojiExported = {
     /** Milliseconds spent so far. */
     elapsedMs: number;
 };
-/** A game as the JSON export's object. */
+/** A game as the JSON export's object.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @returns A game as the JSON export's object.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiExported } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiExported(saved).format);
+ * ```
+ */
 export declare function kumimojiExported(saved: KumimojiSaved): KumimojiExported;
-/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back. */
+/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @returns A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiToJSON } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiToJSON(saved));
+ * ```
+ */
 export declare function kumimojiToJSON(saved: KumimojiSaved): string;
 /**
  * A game from JSON that `kumimojiToJSON` wrote. Nothing in it is trusted: the
@@ -66,15 +133,50 @@ export declare function kumimojiToJSON(saved: KumimojiSaved): string;
  * The word list of the game's language is loaded first, since dealing needs
  * it; where there is no browser, import `@johnmorrisdotca/kumimoji/words`
  * once, or the promise is rejected as `loadTileWords` rejects it.
+ *
+ * @param text - The saved JSON text to validate.
+ * @returns A game from JSON that `kumimojiToJSON` wrote. Nothing in it is trusted: the bag is dealt again from the seed, and the game opens only if every tile held is one that came out of that bag. Resolves to null when the text is not JSON, is of a later format than this version reads, is another game's, or holds a hand or a grid that this bag never dealt.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiFromJSON, kumimojiToJSON } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log((await kumimojiFromJSON(kumimojiToJSON(saved)))?.deal.seed);
+ * ```
  */
 export declare function kumimojiFromJSON(text: string): Promise<KumimojiSaved | null>;
-/** A time as minutes and seconds: `1:05`. */
+/** A time as minutes and seconds: `1:05`.
+ *
+ * @param ms - The duration in milliseconds.
+ * @returns A time as minutes and seconds: `1:05`.
+ * @example
+ * ```ts
+ * import { kumimojiClock } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiClock(65000));
+ * ```
+ */
 export declare function kumimojiClock(ms: number): string;
 /**
  * A grid as lines of text, the way it lies on the table: English letters in
  * capitals with a space between squares and a dot for an empty one, kana side
  * by side with a full-width dot for an empty one, so that either lines up in a
  * fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param language - The English or Japanese tile language.
+ * @returns A grid as lines of text, the way it lies on the table: English letters in capitals with a space between squares and a dot for an empty one, kana side by side with a full-width dot for an empty one, so that either lines up in a fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ * @example
+ * ```ts
+ * import { gridToText } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(gridToText(tiles));
+ * ```
  */
 export declare function gridToText(tiles: Tiles, language?: KumimojiLanguage): string;
 /**
@@ -83,5 +185,20 @@ export declare function gridToText(tiles: Tiles, language?: KumimojiLanguage): s
  * English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The
  * word list of the game's language must have been loaded, as for any judging.
  * Lines end with a line feed.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @param strings - The localized words for readable export.
+ * @returns A game as plain text, for a chat or a note: how it was set up, the crossword as it lies, the hand, how many tiles are left, and the time. In English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The word list of the game's language must have been loaded, as for any judging. Lines end with a line feed.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiToText } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiToText(saved));
+ * ```
  */
 export declare function kumimojiToText(saved: KumimojiSaved, strings?: KumimojiStrings): string;

package/dist/export.js

@@ -1,5 +1,5 @@
-import { boundsOf, squareAt } from "./grid.js";
 import { generateKumimoji } from "./generate.js";
+import { boundsOf, squareAt } from "./grid.js";
 import { judgeWithWords } from "./judge.js";
 import { decodeTileProgress, encodeTileProgress, isFinished, tilesLeft } from "./play.js";
 import { KUMIMOJI_STRINGS, kumimojiSay } from "./strings.js";
@@ -19,9 +19,31 @@ import { KUMIMOJI_VERSION } from "./version.js";
  * the game only if every tile in the hand and on the table is one that came
  * out of that bag and was not given back.
  */
-/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one. */
+/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_EXPORT_FORMAT } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_EXPORT_FORMAT);
+ * ```
+ */
 export const KUMIMOJI_EXPORT_FORMAT = 1;
-/** A game as the JSON export's object. */
+/** A game as the JSON export's object.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @returns A game as the JSON export's object.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiExported } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiExported(saved).format);
+ * ```
+ */
 export function kumimojiExported(saved) {
     const { deal, play } = saved;
     return {
@@ -39,7 +61,22 @@ export function kumimojiExported(saved) {
         elapsedMs: Math.max(0, Math.round(saved.elapsedMs)),
     };
 }
-/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back. */
+/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @returns A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiToJSON } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiToJSON(saved));
+ * ```
+ */
 export function kumimojiToJSON(saved) {
     return `${JSON.stringify(kumimojiExported(saved), null, 2)}\n`;
 }
@@ -57,6 +94,20 @@ const PROGRESS_MOST = 4000;
  * The word list of the game's language is loaded first, since dealing needs
  * it; where there is no browser, import `@johnmorrisdotca/kumimoji/words`
  * once, or the promise is rejected as `loadTileWords` rejects it.
+ *
+ * @param text - The saved JSON text to validate.
+ * @returns A game from JSON that `kumimojiToJSON` wrote. Nothing in it is trusted: the bag is dealt again from the seed, and the game opens only if every tile held is one that came out of that bag. Resolves to null when the text is not JSON, is of a later format than this version reads, is another game's, or holds a hand or a grid that this bag never dealt.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiFromJSON, kumimojiToJSON } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log((await kumimojiFromJSON(kumimojiToJSON(saved)))?.deal.seed);
+ * ```
  */
 export async function kumimojiFromJSON(text) {
     let data;
@@ -94,7 +145,12 @@ export async function kumimojiFromJSON(text) {
     await loadTileWords(language);
     let deal;
     try {
-        deal = generateKumimoji(size, level, seed, { language, gameLength: gameLength, doubleSet, diagonals });
+        deal = generateKumimoji(size, level, seed, {
+            language,
+            gameLength: gameLength,
+            doubleSet,
+            diagonals,
+        });
     }
     catch {
         return null;
@@ -102,7 +158,17 @@ export async function kumimojiFromJSON(text) {
     const play = decodeTileProgress(progress, deal.givens, language);
     return play === null ? null : { deal, play, elapsedMs: spent };
 }
-/** A time as minutes and seconds: `1:05`. */
+/** A time as minutes and seconds: `1:05`.
+ *
+ * @param ms - The duration in milliseconds.
+ * @returns A time as minutes and seconds: `1:05`.
+ * @example
+ * ```ts
+ * import { kumimojiClock } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiClock(65000));
+ * ```
+ */
 export function kumimojiClock(ms) {
     const seconds = Math.max(0, Math.floor(ms / 1000));
     return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
@@ -112,6 +178,17 @@ export function kumimojiClock(ms) {
  * capitals with a space between squares and a dot for an empty one, kana side
  * by side with a full-width dot for an empty one, so that either lines up in a
  * fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param language - The English or Japanese tile language.
+ * @returns A grid as lines of text, the way it lies on the table: English letters in capitals with a space between squares and a dot for an empty one, kana side by side with a full-width dot for an empty one, so that either lines up in a fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ * @example
+ * ```ts
+ * import { gridToText } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(gridToText(tiles));
+ * ```
  */
 export function gridToText(tiles, language = "english") {
     const bounds = boundsOf(tiles);
@@ -140,17 +217,40 @@ export function gridToText(tiles, language = "english") {
  * English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The
  * word list of the game's language must have been loaded, as for any judging.
  * Lines end with a line feed.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @param strings - The localized words for readable export.
+ * @returns A game as plain text, for a chat or a note: how it was set up, the crossword as it lies, the hand, how many tiles are left, and the time. In English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The word list of the game's language must have been loaded, as for any judging. Lines end with a line feed.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiToText } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiToText(saved));
+ * ```
  */
 export function kumimojiToText(saved, strings = KUMIMOJI_STRINGS.en) {
     const { deal, play } = saved;
     const words = tileWords(deal.language);
-    const face = (tile) => (tileFace(tile).blank ? "*" : deal.language === "japanese" ? words.glyphOf(tile) : words.glyphOf(tile).toUpperCase());
-    const lines = [kumimojiSay(strings.textTitle, { language: deal.language === "japanese" ? strings.japanese : strings.english, hand: deal.size, seed: deal.seed })];
+    const face = (tile) => tileFace(tile).blank ? "*" : deal.language === "japanese" ? words.glyphOf(tile) : words.glyphOf(tile).toUpperCase();
+    const lines = [
+        kumimojiSay(strings.textTitle, {
+            language: deal.language === "japanese" ? strings.japanese : strings.english,
+            hand: deal.size,
+            seed: deal.seed,
+        }),
+    ];
     lines.push(play.tiles.size === 0 ? strings.textEmpty : gridToText(play.tiles, deal.language));
     if (isFinished(play, judgeWithWords(play.tiles, words, { diagonals: deal.diagonals === true })))
         lines.push(strings.textFinished);
     else {
-        lines.push(play.hand.length === 0 ? strings.textHandEmpty : kumimojiSay(strings.textHand, { tiles: play.hand.map(face).join(" ") }));
+        lines.push(play.hand.length === 0
+            ? strings.textHandEmpty
+            : kumimojiSay(strings.textHand, { tiles: play.hand.map(face).join(" ") }));
         lines.push(kumimojiSay(strings.textLeft, { n: tilesLeft(play) }));
     }
     lines.push(kumimojiSay(strings.textTime, { time: kumimojiClock(saved.elapsedMs) }));

package/dist/generate.d.ts

@@ -25,5 +25,19 @@ import type { KumimojiDeal, KumimojiLevel, KumimojiOptions } from "./kumimoji.ty
  *
  * Deterministic in the seed, like every generator here: two browsers in a
  * race, or one tomorrow, deal the same bag in the same order.
+ *
+ * @param size - The supported initial hand size.
+ * @param level - The difficulty that determines the wildcard allowance.
+ * @param seed - The numeric seed for deterministic deals or random draws.
+ * @param options - Native game, component or presentation options.
+ * @returns MAKING A KUMIMOJI, in the browser, from a seed: the bag the game is played from, in the order its tiles come out.
+ * @example
+ * ```ts
+ * import { generateKumimoji } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log(generateKumimoji(3,"hard",44).givens);
+ * ```
  */
 export declare function generateKumimoji(size: number, level: KumimojiLevel, seed: number, options?: KumimojiOptions): KumimojiDeal;

package/dist/generate.js

@@ -1,6 +1,6 @@
-import { seededRandom, shuffled } from "./random.js";
 import { encodeGrid, squareAt } from "./grid.js";
 import { crossingFit } from "./placement.js";
+import { seededRandom, shuffled } from "./random.js";
 import { kumimojiTileCount, kumimojiWildCount, TILE_MIX_TOTAL } from "./tiles.constants.js";
 import { tileWords } from "./tileWords.js";
 /**
@@ -29,6 +29,20 @@ import { tileWords } from "./tileWords.js";
  *
  * Deterministic in the seed, like every generator here: two browsers in a
  * race, or one tomorrow, deal the same bag in the same order.
+ *
+ * @param size - The supported initial hand size.
+ * @param level - The difficulty that determines the wildcard allowance.
+ * @param seed - The numeric seed for deterministic deals or random draws.
+ * @param options - Native game, component or presentation options.
+ * @returns MAKING A KUMIMOJI, in the browser, from a seed: the bag the game is played from, in the order its tiles come out.
+ * @example
+ * ```ts
+ * import { generateKumimoji } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log(generateKumimoji(3,"hard",44).givens);
+ * ```
  */
 export function generateKumimoji(size, level, seed, options = {}) {
     const gameLength = options.gameLength ?? "short";
@@ -44,10 +58,12 @@ export function generateKumimoji(size, level, seed, options = {}) {
     const side = layingSideFor(tiles);
     let bestProgress = 0;
     for (let attempt = 0; attempt < 50; attempt += 1) {
-        const squares = layCrossword(tiles, random, words, side, multiplier, words.mix, (laid) => { bestProgress = Math.max(bestProgress, laid); }, diagonals);
+        const squares = layCrossword(tiles, random, words, side, multiplier, words.mix, (laid) => {
+            bestProgress = Math.max(bestProgress, laid);
+        }, diagonals);
         if (squares === null)
             continue;
-        const positions = shuffled(squares.flatMap((tile, at) => tile === "" ? [] : [at]), random);
+        const positions = shuffled(squares.flatMap((tile, at) => (tile === "" ? [] : [at])), random);
         const wildAt = new Set(positions.slice(0, wilds));
         const bag = squares.flatMap((tile, at) => {
             if (tile === "")
@@ -60,7 +76,18 @@ export function generateKumimoji(size, level, seed, options = {}) {
             squares[at] = assigned;
             return ["*"];
         });
-        return { kind: "kumimoji", size, level, seed, givens: shuffled(bag, random).join(""), solution: encodeGrid(tilesOf(squares, side)), gameLength, doubleSet, language, ...(diagonals ? { diagonals } : {}) };
+        return {
+            kind: "kumimoji",
+            size,
+            level,
+            seed,
+            givens: shuffled(bag, random).join(""),
+            solution: encodeGrid(tilesOf(squares, side)),
+            gameLength,
+            doubleSet,
+            language,
+            ...(diagonals ? { diagonals } : {}),
+        };
     }
     throw new Error(`Could not lay a Kumimoji of ${tiles} tiles from seed ${seed}; furthest attempt laid ${bestProgress}.`);
 }
@@ -88,7 +115,7 @@ const LONGEST_LAID = 7;
 const ANCHORS_TRIED = 8;
 const WORDS_READ = 60;
 const FINISH_BRANCHES = 40;
-const FINISH_NODES = 2000;
+const FINISH_NODES = 2_000;
 /**
  * With Diagonals the last tiles are placed from every tile but a sample of
  * words, and a try that cannot finish is given up sooner: a crossword read