@johnmorrisdotca/kumimoji 1.2.2 → 1.3.1

package/dist/partyKept.js

@@ -1,5 +1,5 @@
 import { decodeGrid, encodeGrid, lettersOf, sameLetters } from "./grid.js";
-import { KUMIMOJI_PARTY, KUMIMOJI_HANDS } from "./tiles.constants.js";
+import { KUMIMOJI_HANDS, KUMIMOJI_PARTY } from "./tiles.constants.js";
 /**
  * A PASS-AND-PLAY GAME KEPT IN THE BROWSER, as one string of JSON: the
  * settings, the whole bag in its order, what was traded back and taken, whose
@@ -18,7 +18,20 @@ import { KUMIMOJI_PARTY, KUMIMOJI_HANDS } from "./tiles.constants.js";
  * nothing to check, and the names in it are the players' own business.
  */
 const VERSION = 1;
-/** A table of players as text to keep. `decodeParty` reads it back, and given the word list's `familyKey` checks every tile held against the bag. */
+/** A table of players as text to keep. `decodeParty` reads it back, and given the word list's `familyKey` checks every tile held against the bag.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns A table of players as text to keep. `decodeParty` reads it back, and given the word list's `familyKey` checks every tile held against the bag.
+ * @example
+ * ```ts
+ * import { encodeParty, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(encodeParty(game));
+ * ```
+ */
 export function encodeParty(game) {
     const kept = {
         v: VERSION,
@@ -37,13 +50,29 @@ export function encodeParty(game) {
         traded: game.traded,
         passedBy: game.passedBy,
         ...(game.dealt === game.players.length ? {} : { dealt: game.dealt }),
-        players: game.players.map((player) => ({ name: player.name, hand: player.hand.join(""), grid: encodeGrid(player.tiles), ...(player.computer === true ? { computer: true } : {}) })),
+        players: game.players.map((player) => ({
+            name: player.name,
+            hand: player.hand.join(""),
+            grid: encodeGrid(player.tiles),
+            ...(player.computer === true ? { computer: true } : {}),
+        })),
     };
     return JSON.stringify(kept);
 }
 const isCount = (value, most) => Number.isInteger(value) && value >= 0 && value <= most;
 const isTiles = (value) => typeof value === "string" && /^[a-zA-Z*-]*$/.test(value);
-/** A game's settings as something outside this browser sent them — a table on several devices, a kept game — checked, or null. */
+/** A game's settings as something outside this browser sent them — a table on several devices, a kept game — checked, or null.
+ *
+ * @param value - The unknown setup value to interpret.
+ * @returns A game's settings as something outside this browser sent them — a table on several devices, a kept game — checked, or null.
+ * @example
+ * ```ts
+ * import { readSettings } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * console.log(readSettings(settings));
+ * ```
+ */
 export function readSettings(value) {
     if (typeof value !== "object" || value === null)
         return null;
@@ -64,7 +93,16 @@ export function readSettings(value) {
     // A game kept before Diagonals existed has no word for it, and was played without.
     if (s.diagonals !== undefined && typeof s.diagonals !== "boolean")
         return null;
-    return { size: s.size, level: s.level, seed: s.seed, gameLength: s.gameLength, language: s.language, doubleSet: s.doubleSet, diagonals: s.diagonals === true, hints: s.hints };
+    return {
+        size: s.size,
+        level: s.level,
+        seed: s.seed,
+        gameLength: s.gameLength,
+        language: s.language,
+        doubleSet: s.doubleSet,
+        diagonals: s.diagonals === true,
+        hints: s.hints,
+    };
 }
 /**
  * A kept game read back, or null for anything that is not one. With
@@ -73,6 +111,21 @@ export function readSettings(value) {
  * it and not given back, as the solo game checks a kept run
  * (`decodeTileProgress`). Without, its shape alone, which is enough to offer
  * it on the set-up screen.
+ *
+ * @param code - The encoded grid or progress text.
+ * @param familyKey - The function identifying physical tile families, or null for invalid codes.
+ * @returns A kept game read back, or null for anything that is not one. With `familyKey` (the loaded word list's), it is also checked against its own bag: every tile held by anybody — hand and table — must be one taken out of it and not given back, as the solo game checks a kept run (`decodeTileProgress`). Without, its shape alone, which is enough to offer it on the set-up screen.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { decodeParty, encodeParty, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(decodeParty(encodeParty(game),words.familyKey)?.players.length);
+ * ```
  */
 export function decodeParty(code, familyKey) {
     if (code === null)
@@ -99,28 +152,75 @@ export function decodeParty(code, familyKey) {
     const dealt = kept.dealt ?? count;
     if (!Number.isInteger(dealt) || dealt < KUMIMOJI_PARTY.least || dealt > KUMIMOJI_PARTY.most)
         return null;
-    if (!isCount(kept.turn, count - 1) || !isCount(kept.turns, 1000000) || (kept.ending !== null && kept.ending !== "out" && kept.ending !== "standing" && kept.ending !== "tied") || typeof kept.traded !== "boolean" || !isTiles(kept.startTable) || (kept.passedBy !== null && !isCount(kept.passedBy, count - 1)))
+    if (!isCount(kept.turn, count - 1) ||
+        !isCount(kept.turns, 1_000_000) ||
+        (kept.ending !== null && kept.ending !== "out" && kept.ending !== "standing" && kept.ending !== "tied") ||
+        typeof kept.traded !== "boolean" ||
+        !isTiles(kept.startTable) ||
+        (kept.passedBy !== null && !isCount(kept.passedBy, count - 1)))
         return null;
     const seats = (list) => Array.isArray(list) && list.every((at) => isCount(at, count - 1)) && new Set(list).size === list.length;
-    if (!seats(kept.out) || (kept.lastTurns !== null && !seats(kept.lastTurns)) || !seats(kept.resigned) || !seats(kept.resignRun))
+    if (!seats(kept.out) ||
+        (kept.lastTurns !== null && !seats(kept.lastTurns)) ||
+        !seats(kept.resigned) ||
+        !seats(kept.resignRun))
         return null;
     const players = [];
     for (const player of kept.players) {
-        if (typeof player !== "object" || player === null || typeof player.name !== "string" || player.name.length > KUMIMOJI_PARTY.nameMost || !isTiles(player.hand))
+        if (typeof player !== "object" ||
+            player === null ||
+            typeof player.name !== "string" ||
+            player.name.length > KUMIMOJI_PARTY.nameMost ||
+            !isTiles(player.hand))
             return null;
         if (player.computer !== undefined && player.computer !== true)
             return null;
         const tiles = decodeGrid(player.grid);
         if (tiles === null)
             return null;
-        players.push(player.computer === true ? { name: player.name, hand: [...player.hand], tiles, computer: true } : { name: player.name, hand: [...player.hand], tiles });
+        players.push(player.computer === true
+            ? { name: player.name, hand: [...player.hand], tiles, computer: true }
+            : { name: player.name, hand: [...player.hand], tiles });
     }
-    const game = { settings, bag: kept.bag, returned: kept.returned, taken: kept.taken, players, dealt, turn: kept.turn, turns: kept.turns, out: kept.out, lastTurns: kept.lastTurns, resigned: kept.resigned, resignRun: kept.resignRun, ending: kept.ending, startTable: kept.startTable, traded: kept.traded, passedBy: kept.passedBy };
+    const game = {
+        settings,
+        bag: kept.bag,
+        returned: kept.returned,
+        taken: kept.taken,
+        players,
+        dealt,
+        turn: kept.turn,
+        turns: kept.turns,
+        out: kept.out,
+        lastTurns: kept.lastTurns,
+        resigned: kept.resigned,
+        resignRun: kept.resignRun,
+        ending: kept.ending,
+        startTable: kept.startTable,
+        traded: kept.traded,
+        passedBy: kept.passedBy,
+    };
     if (familyKey !== undefined && !holdsItsBag(game, familyKey))
         return null;
     return game;
 }
-/** Whether what everybody holds is exactly what was taken from the bag, less what was given back. */
+/** Whether what everybody holds is exactly what was taken from the bag, less what was given back.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param familyKey - The function identifying physical tile families, or null for invalid codes.
+ * @returns Whether what everybody holds is exactly what was taken from the bag, less what was given back.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { holdsItsBag, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(holdsItsBag(game,words.familyKey));
+ * ```
+ */
 export function holdsItsBag(game, familyKey) {
     const taken = [...(game.bag + game.returned).slice(0, game.taken)].map(familyKey);
     const back = [...game.returned].map(familyKey);
@@ -135,7 +235,22 @@ export function holdsItsBag(game, familyKey) {
             tally.delete(tile);
     return sameLetters(tally, lettersOf(held));
 }
-/** Whether a kept game is the one an address asks for: the same settings, and dealt to as many players, whoever has joined or left since. */
+/** Whether a kept game is the one an address asks for: the same settings, and dealt to as many players, whoever has joined or left since.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param settings - The native party setup settings.
+ * @param players - The requested player count or current player rows.
+ * @returns Whether a kept game is the one an address asks for: the same settings, and dealt to as many players, whoever has joined or left since.
+ * @example
+ * ```ts
+ * import { isPartyFor, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(isPartyFor(game,settings,2));
+ * ```
+ */
 export function isPartyFor(game, settings, players) {
     const a = game.settings;
     return (game.dealt === players &&

package/dist/partySeats.d.ts

@@ -24,17 +24,90 @@ import type { PartyGame, PartySeat } from "./party.types.ts";
  * standing (`lastStanding`), and wins by laying a tile on a sound grid, as
  * when everybody else resigns — unless somebody joins first.
  */
-/** Why nobody can join now, or null when a hand can be dealt. */
+/** Why nobody can join now, or null when a hand can be dealt.
+ *
+ * @example
+ * ```ts
+ * import type { JoinRefusal } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: JoinRefusal = "full";
+ * console.log(value);
+ * ```
+ */
 export type JoinRefusal = "over" | "full" | "lastRound" | "bag";
-/** Why nobody can join the table now, or null when a hand can be dealt. */
+/** Why nobody can join the table now, or null when a hand can be dealt.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns Why nobody can join the table now, or null when a hand can be dealt.
+ * @example
+ * ```ts
+ * import { joinRefused, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(joinRefused(game));
+ * ```
+ */
 export declare function joinRefused(game: PartyGame): JoinRefusal | null;
-/** A player, or a computer, sat down after the last seat with the next hand out of the bag. */
+/** A player, or a computer, sat down after the last seat with the next hand out of the bag.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param seat - The local name and computer flag for the joining player.
+ * @returns A player, or a computer, sat down after the last seat with the next hand out of the bag.
+ * @example
+ * ```ts
+ * import { joinParty, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(joinParty(game,{name:"Seat 3"}).players.length);
+ * ```
+ */
 export declare function joinParty(game: PartyGame, seat: PartySeat): PartyGame;
-/** Why this player cannot leave now, or null when they can. */
+/** Why this player cannot leave now, or null when they can.
+ *
+ * @example
+ * ```ts
+ * import type { LeaveRefusal } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: LeaveRefusal = "lastPerson";
+ * console.log(value);
+ * ```
+ */
 export type LeaveRefusal = "over" | "out" | "lastPerson";
-/** Why the player at seat `at` cannot leave now, or null when they can. */
+/** Why the player at seat `at` cannot leave now, or null when they can.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @returns Why the player at seat `at` cannot leave now, or null when they can.
+ * @example
+ * ```ts
+ * import { leaveRefused, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(leaveRefused(game,0));
+ * ```
+ */
 export declare function leaveRefused(game: PartyGame, at: number): LeaveRefusal | null;
-/** How many tiles a player would put back in the bag by leaving: their hand and their table. */
+/** How many tiles a player would put back in the bag by leaving: their hand and their table.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @returns How many tiles a player would put back in the bag by leaving: their hand and their table.
+ * @example
+ * ```ts
+ * import { startParty, tilesHeldBy } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(tilesHeldBy(game,0));
+ * ```
+ */
 export declare function tilesHeldBy(game: PartyGame, at: number): number;
 /**
  * A PLAYER LEAVES. Their tiles go back into the bag and the bag is shuffled
@@ -51,5 +124,18 @@ export declare function tilesHeldBy(game: PartyGame, at: number): number;
  * round to the next still to have their last turn; a last round with nobody
  * left to play ends. With nobody still in — everybody left has resigned —
  * the game ends tied between them.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @returns A PLAYER LEAVES. Their tiles go back into the bag and the bag is shuffled — with the game's own seed and how far it has gone, so the same game left the same way deals the same tiles after a reload. A wild goes back blank.
+ * @example
+ * ```ts
+ * import { leaveParty, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(leaveParty(game,0).players.length);
+ * ```
  */
 export declare function leaveParty(game: PartyGame, at: number): PartyGame;

package/dist/partySeats.js

@@ -1,8 +1,21 @@
-import { seededRandom, shuffled } from "./random.js";
 import { computerName, isComputer, nextIn, partyTilesLeft, stillIn, tableTally, tidyName } from "./party.js";
+import { seededRandom, shuffled } from "./random.js";
 import { tileFace } from "./tileFace.js";
 import { KUMIMOJI_PARTY } from "./tiles.constants.js";
-/** Why nobody can join the table now, or null when a hand can be dealt. */
+/** Why nobody can join the table now, or null when a hand can be dealt.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns Why nobody can join the table now, or null when a hand can be dealt.
+ * @example
+ * ```ts
+ * import { joinRefused, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(joinRefused(game));
+ * ```
+ */
 export function joinRefused(game) {
     if (game.ending !== null)
         return "over";
@@ -14,13 +27,29 @@ export function joinRefused(game) {
         return "bag";
     return null;
 }
-/** A player, or a computer, sat down after the last seat with the next hand out of the bag. */
+/** A player, or a computer, sat down after the last seat with the next hand out of the bag.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param seat - The local name and computer flag for the joining player.
+ * @returns A player, or a computer, sat down after the last seat with the next hand out of the bag.
+ * @example
+ * ```ts
+ * import { joinParty, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(joinParty(game,{name:"Seat 3"}).players.length);
+ * ```
+ */
 export function joinParty(game, seat) {
     if (joinRefused(game) !== null)
         return game;
     const hand = [...(game.bag + game.returned).slice(game.taken, game.taken + game.settings.size)];
     const tiles = new Map();
-    const player = seat.computer === true ? { name: computerName(game.players), computer: true, hand, tiles } : { name: tidyName(seat.name) || freePlayerName(game.players), hand, tiles };
+    const player = seat.computer === true
+        ? { name: computerName(game.players), computer: true, hand, tiles }
+        : { name: tidyName(seat.name) || freePlayerName(game.players), hand, tiles };
     return { ...game, players: [...game.players, player], taken: game.taken + hand.length };
 }
 /** "Player" and the next seat's number, or the lowest number nobody at the table goes by. */
@@ -33,7 +62,21 @@ function freePlayerName(players) {
         if (!taken.has(`Player ${number}`))
             return `Player ${number}`;
 }
-/** Why the player at seat `at` cannot leave now, or null when they can. */
+/** Why the player at seat `at` cannot leave now, or null when they can.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @returns Why the player at seat `at` cannot leave now, or null when they can.
+ * @example
+ * ```ts
+ * import { leaveRefused, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(leaveRefused(game,0));
+ * ```
+ */
 export function leaveRefused(game, at) {
     if (game.ending !== null || game.players[at] === undefined)
         return "over";
@@ -43,7 +86,21 @@ export function leaveRefused(game, at) {
         return "lastPerson";
     return null;
 }
-/** How many tiles a player would put back in the bag by leaving: their hand and their table. */
+/** How many tiles a player would put back in the bag by leaving: their hand and their table.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @returns How many tiles a player would put back in the bag by leaving: their hand and their table.
+ * @example
+ * ```ts
+ * import { startParty, tilesHeldBy } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(tilesHeldBy(game,0));
+ * ```
+ */
 export function tilesHeldBy(game, at) {
     const player = game.players[at];
     return player === undefined ? 0 : player.hand.length + player.tiles.size;
@@ -63,13 +120,26 @@ export function tilesHeldBy(game, at) {
  * round to the next still to have their last turn; a last round with nobody
  * left to play ends. With nobody still in — everybody left has resigned —
  * the game ends tied between them.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @returns A PLAYER LEAVES. Their tiles go back into the bag and the bag is shuffled — with the game's own seed and how far it has gone, so the same game left the same way deals the same tiles after a reload. A wild goes back blank.
+ * @example
+ * ```ts
+ * import { leaveParty, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(leaveParty(game,0).players.length);
+ * ```
  */
 export function leaveParty(game, at) {
     if (leaveRefused(game, at) !== null)
         return game;
     const leaver = game.players[at];
     const back = [...leaver.hand, ...leaver.tiles.values()].map((tile) => (tileFace(tile).wild ? "*" : tile));
-    const players = game.players.flatMap((player, seat) => (seat === at ? [] : [{ ...player, name: player.name || `Player ${seat + 1}` }]));
+    const players = game.players.flatMap((player, seat) => seat === at ? [] : [{ ...player, name: player.name || `Player ${seat + 1}` }]);
     const seatOf = (seat) => (seat > at ? seat - 1 : seat);
     const without = (seats) => seats.filter((seat) => seat !== at).map(seatOf);
     const held = players.flatMap((player) => [...player.hand, ...player.tiles.values()]);
@@ -111,7 +181,12 @@ export function leaveParty(game, at) {
     const moved = at === game.turn ? { startTable: tableTally(players[turn].tiles), traded: false } : {};
     if (ending === null && lastTurns === null && stillIn(after).length === 0) {
         // Only players who resigned are left: tied, the last run of them, or all of them where that run has left.
-        return { ...after, ...moved, ending: "tied", resignRun: after.resignRun.length > 0 ? after.resignRun : after.resigned };
+        return {
+            ...after,
+            ...moved,
+            ending: "tied",
+            resignRun: after.resignRun.length > 0 ? after.resignRun : after.resigned,
+        };
     }
     return { ...after, ...moved };
 }