@pretty-chitty/core 1.1.1

package/dist/game/Turn.d.ts

@@ -0,0 +1,169 @@
+import { Chit } from "./Chit";
+import { Match } from "./Match";
+import { TurnState } from "./TurnState";
+import { ButtonPick, Pick } from "./Pick";
+import { GameButton } from "./GameButton";
+import { PlayerChit } from "./PlayerChit";
+import { RootChit } from "./RootChit";
+type ValidPick = undefined | false | Pick | Pick[] | ButtonPick | ButtonPick[] | GameButton | GameButton[];
+export type Picks = ValidPick | ValidPick[];
+/**
+ *
+ * A `Turn` is the heart of pretty-chitty.  It represents multiple actions or sequences of events from a
+ * single player (or possibly not player).
+ *
+ * The core of a `Turn` is the async `fn` provided.  This `fn` will run all of this logic for that turn,
+ * prompt the user for actions, take random number draws and possibly create one or more sub-turns.
+ *
+ * The general pattern will look something like this:
+ *
+ * ```
+ * setup.createTurn([rootChit, playerChit], playerChit, async (turn) => {
+ *
+ *   // take a random number
+ *   const randomDraw = await turn.rng();
+ *
+ *   // ask the turn's player to make a decision.
+ *   await turn.pick([Chit.pick([chit1,chit2], async chosenChit => {
+ *     // do something with chosen chit
+ *   })]);
+ * });
+ * ```
+ *
+ * There are a couple of VERY important details here:
+ *
+ * 1) Your turn implemention should persist no state itself.
+ * 2) Your turn is going to "lock" one or more chits.  Those chits will only be editable by this turn (until the turn is done or a sub-turn briefly locks those same chits)
+ * 3) If a user needs to "undo" something, it will automatically reset all of the locked chits to their original locked state and re-evaluate the turn from its beginning to easily handle a single "step back".
+ * 4) As a result, all random numbers need to go through this turn's rng() so they are persisted correctly.
+ * 5) All state should be either ephemeral or stored on the chits themselves.  Remember that your turn's function may re-evaluate at any point!
+ * 6) It will automatically handle prompting a user for confirmation before drawing a random number OR before changing the active player.
+ *
+ * @group Core Game Elements
+ */
+export declare class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
+    id: string;
+    player?: P | undefined;
+    private pass;
+    private clockSteps;
+    private decisionIndex;
+    private newChitCounter;
+    private chitLookup;
+    private lockedChitStates;
+    private lastChitStates;
+    /**
+     * The root chit instance of the game.  All chits in the game have this chit somewhere in its hierarchy
+     */
+    get rootChit(): R;
+    private _playerIds;
+    constructor(id: string, 
+    /** @internal */
+    match: Match<P, R>, 
+    /** @internal */
+    state: TurnState, 
+    /** @internal */
+    fn: (turn: Turn<T, P, R>) => Promise<T>, 
+    /** @internal */
+    chitsToLock: Chit[], player?: P | undefined, 
+    /** @internal */
+    parent?: Turn<any, P, R> | undefined);
+    /**
+     * Generates a random number from 0 to 1.  This number will persisted in state and will be consistent if the
+     * turn needs to be re-run.  Drawing a random number prevents normal resets.
+     *
+     * If the player can perform a reset, this will confirm with them first.
+     *
+     * @returns A number from 0-1
+     */
+    rng(message?: string): Promise<number>;
+    /**
+     * Generates a series of random numbers from 0 to 1.  This is a helper method to help batch up a lot of random draws
+     * since each rng() call must be awaited.
+     * @param count
+     * @returns A parameterless function that will return the next random number in the list.  If you try to select too many random numbers, that method will throw.
+     */
+    takeRng(count: number, message?: string): Promise<() => number>;
+    /**
+     * Add a game log message to the last flush step
+     * @param message
+     */
+    log(message: string): void;
+    /**
+     * Append a game log message to the last flush step that has a game log message
+     * @param message
+     * @returns
+     */
+    amendLog(message: string | ((previous: string) => string)): void;
+    /**
+     * Scan all of the chits managed by this turn.  If any of them have changed, group them together into a
+     * "ClockStep".  If any new chits appear, then add them to our lookup.  If any chits are deleted (orphaned),
+     * then we have to identify those as well.
+     */
+    flush(force?: boolean): void;
+    /**
+     * Creates a sub-turn.  This is useful for a few reasons:
+     *  1) It is the only way to change game control flow from our current player to a different player
+     *  2) It creates a new "reset" point for backing out turns
+     *
+     * It takes an async function which it will execute.  For simplicity, the result of that function will be the result of
+     * this function.
+     *
+     * It is okay to have multiple turns going at once, but there are some rules:
+     *  1) If there is an ongoing sub turn that hasn't resolved, you cannot prompt or change chits in this turn.
+     *  2) There is only one ongoing subturn allowed per player.
+     *
+     * @param chits The chits to lock.  These are the only chits that will be allowed to be modified by this turn.  If there are never any concurrent turns, this can safely be the root chit (although there maybe minor performance implications)
+     * @param player The player who will be prompted for choices during this turn.
+     * @param cb The async function that will be the logic of this turn.  The function takes a new turn instance
+     * @returns Whatever the final result of cb() is
+     */
+    createTurn<A>(chits: Chit[], player: P, cb: (turn: Turn<A, P, R>) => Promise<A>): Promise<A>;
+    runParallelTurns<A>(players: P[], chits: (p: P) => Chit[], action: (p: P, turn: Turn<A, P, R>) => Promise<A>): Promise<A[]>;
+    /**
+     * Basic selection prompt.  All chits will appear as "selected" on the respective client.
+     * Upon clicking one, the prompt will resolve itself.
+     *
+     * @param chits The list of chits that can be selected from
+     * @returns The chit that the player selected
+     */
+    select(chits: Chit[]): Promise<Chit>;
+    /**
+     * If a player has gotten themselves into a corner - i.e. no valid moves - this prompt will
+     * simply inform them of that and allow them to undo.
+     * @param message
+     * @param help
+     */
+    noValidMoves(message?: string, help?: string): Promise<void>;
+    /**
+     * More complex selection prompt.  Useful in Typescript when you want to handle a response to multiple
+     * types of chits.  This will allow a different typed callback per set of chits.  This also allows
+     * the insertion of "buttons"
+     * @param message (optional) The message to show describing the prompt in a few words
+     * @param help (optional) A detailed help message to show
+     * @param picks An array of "picks" - each of which can have its own typesafe callback
+     */
+    pick(message?: string | Picks, help?: string | Picks, picks?: Picks): Promise<void>;
+    private isProcessingSavedState;
+    private findIndexOfLastFlushStepBefore;
+    private findIndexOfLastFlushStepWithLogMessageBefore;
+    private prepareForPrompt;
+    private waitForPromptResolution;
+    execute(): Promise<T>;
+    private cleanUp;
+    private restartExecution;
+}
+export declare class StepBackError extends Error {
+}
+export declare class RollBackError extends Error {
+}
+export declare class DestroyError extends Error {
+}
+export declare class RerunError extends Error {
+    turn: Turn<any, any, any>;
+    constructor(turn: Turn<any, any, any>);
+}
+export declare class MismatchError extends Error {
+    constructor();
+}
+export {};
+//# sourceMappingURL=Turn.d.ts.map

package/dist/game/Turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Turn.d.ts","sourceRoot":"","sources":["../../src/library/game/Turn.ts"],"names":[],"mappings":"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"}