@rilong/grammyjs-conversations-esm 2.0.2

package/out/state.d.ts

@@ -0,0 +1,147 @@
+/**
+ * A replay state.
+ *
+ * A replay state consists of two logs of operations.
+ *
+ * 1. A send log which records send operations in the shape of {@link SendOp}
+ * 2. A receive log which records receive operations in the shape of
+ *    {@link ReceiveOp}
+ *
+ * Note that each receive op links to a specific send op. A valid replay state
+ * should only contain receive ops that point to send ops contained in the same
+ * replay state.
+ *
+ * A replay state can be created using {@link create}.
+ */
+export interface ReplayState {
+    /** The send log of the replay state */
+    send: SendOp[];
+    /** The receive log of the replay state */
+    receive: ReceiveOp[];
+}
+/** A send operation */
+export interface SendOp {
+    /** Any string payload for the send operation */
+    payload: string;
+}
+/** A receive operation */
+export interface ReceiveOp {
+    /** The identifier (index in a send log) of a send op */
+    send: number;
+    /** The received value */
+    returnValue: unknown;
+}
+/** A checkpoint in a replay log */
+export type Checkpoint = [number, number];
+/**
+ * Creates and returns an empty {@link ReplayState} object.
+ *
+ * The returned replay state can be inspected via {@link inspect}, mutated via
+ * {@link mutate}, and replayed via {@link cursor}.
+ */
+export declare function create(): ReplayState;
+/**
+ * Holds a number of tools that can be used to inspect a replay state.
+ *
+ * This object is typically created via {@link inspect}.
+ */
+export interface InspectTools {
+    /** Gets the number of send ops */
+    opCount(): number;
+    /** Gets the number of receive ops */
+    doneCount(): number;
+    /** Looks up the payload of a send op */
+    payload(op: number): string;
+    /** Creates a checkpoint for the current replay state */
+    checkpoint(): Checkpoint;
+}
+/**
+ * Provides inspections tools for a given replay state.
+ *
+ * @param state The replay state to inspect
+ */
+export declare function inspect(state: ReplayState): InspectTools;
+/**
+ * Holds a number of tools that can be used to mutate a replay state.
+ *
+ * This object is typically created via {@link mutate}.
+ */
+export interface MutateTools {
+    /**
+     * Begins an op by recording a send op. Returns the send op identifier.
+     *
+     * @param payload A payload to send
+     */
+    op(payload: string): number;
+    /**
+     * Completes an op by recording a receive op for a given send op.
+     *
+     * @param op The identifier of the send op to complete.
+     * @param result The result of the op
+     */
+    done(op: number, result: unknown): void;
+    /**
+     * Resets the replay state to a given checkpoint that was obtained
+     * previously through {@link inspect}ion of the replay state.
+     *
+     * @param checkpoint The known checkpoint
+     */
+    reset([op, done]: Checkpoint): void;
+}
+/**
+ * Provides tools to mutate a given replay state.
+ *
+ * @param state The replay state to mutate
+ */
+export declare function mutate(state: ReplayState): MutateTools;
+/**
+ * Can be used to iterate a given replay state.
+ *
+ * This object is typically created via {@link cursor}.
+ *
+ * Note that this object holds state outside of the replay state itself, namely
+ * the current position of the cursor.
+ */
+export interface ReplayCursor {
+    /**
+     * Performs an action at the current position of the replay cursor, records
+     * its result in the replay state, and advances the cursor.
+     *
+     * Note that if the cursor has not reached the end of the replay state yet,
+     * the action will be replayed from the log.
+     *
+     * @param action The action to perform, receiving a send op identifer
+     * @param payload The payload to assign to this action
+     */
+    perform(action: (op: number) => unknown | Promise<unknown>, payload: string): Promise<unknown>;
+    /**
+     * Begins a new op at the current position of the replay cursor, and
+     * advances the cursor.
+     *
+     * Note that if the cursor has not reached the end of the replay state yet,
+     * the op will be taken from the log.
+     *
+     * @param payload The payload to assign to this op
+     */
+    op(payload: string): number;
+    /**
+     * Completes a given op with the result obtained from a callback function,
+     * and advances the cursor.
+     *
+     * Note that if the cursor has not reached the end of the replay state yet,
+     * the callback function will not be invoked. Instead, the result will be
+     * replayed from the log.
+     *
+     * @param op The op to complete
+     * @param result The result to record
+     */
+    done(op: number, result: () => unknown | Promise<unknown>): Promise<unknown>;
+    /** Creates a checkpoint at the current state of the cursor */
+    checkpoint(): Checkpoint;
+}
+/**
+ * Provides tools to iterate a given replay state.
+ *
+ * @param state The replay state to iterate
+ */
+export declare function cursor(state: ReplayState): ReplayCursor;

package/out/state.js

@@ -0,0 +1,125 @@
+import { resolver } from "./resolve.js";
+/**
+ * Creates and returns an empty {@link ReplayState} object.
+ *
+ * The returned replay state can be inspected via {@link inspect}, mutated via
+ * {@link mutate}, and replayed via {@link cursor}.
+ */
+export function create() {
+    return { send: [], receive: [] };
+}
+/**
+ * Provides inspections tools for a given replay state.
+ *
+ * @param state The replay state to inspect
+ */
+export function inspect(state) {
+    function opCount() {
+        return state.send.length;
+    }
+    function doneCount() {
+        return state.receive.length;
+    }
+    function payload(op) {
+        if (op < 0)
+            throw new Error(`Op ${op} is invalid`);
+        if (op >= state.send.length)
+            throw new Error(`No op ${op} in state`);
+        return state.send[op].payload;
+    }
+    function checkpoint() {
+        return [opCount(), doneCount()];
+    }
+    return { opCount, doneCount, payload, checkpoint };
+}
+/**
+ * Provides tools to mutate a given replay state.
+ *
+ * @param state The replay state to mutate
+ */
+export function mutate(state) {
+    function op(payload) {
+        const index = state.send.length;
+        state.send.push({ payload });
+        return index;
+    }
+    function done(op, result) {
+        if (op < 0)
+            throw new Error(`Op ${op} is invalid`);
+        if (op >= state.send.length)
+            throw new Error(`No op ${op} in state`);
+        state.receive.push({ send: op, returnValue: result });
+    }
+    function reset([op, done]) {
+        if (op < 0 || done < 0)
+            throw new Error("Invalid checkpoint");
+        state.send.splice(op);
+        state.receive.splice(done);
+    }
+    return { op, done, reset };
+}
+/**
+ * Provides tools to iterate a given replay state.
+ *
+ * @param state The replay state to iterate
+ */
+export function cursor(state) {
+    let changes = resolver();
+    function notify() {
+        changes.resolve();
+        changes = resolver();
+    }
+    let send = 0; // 0 <= send <= state.send.length
+    let receive = 0; // 0 <= receive <= state.receive.length
+    function op(payload) {
+        if (send < state.send.length) {
+            // replay existing data (do nothing)
+            const expected = state.send[send].payload;
+            if (expected !== payload) {
+                throw new Error(`Bad replay, expected op '${expected}'`);
+            }
+        }
+        else { // send === state.send.length
+            // log new data
+            state.send.push({ payload });
+        }
+        const index = send++;
+        notify();
+        return index;
+    }
+    async function done(op, result) {
+        if (op < 0)
+            throw new Error(`Op ${op} is invalid`);
+        if (op >= state.send.length)
+            throw new Error(`No op ${op} in state`);
+        let data;
+        if (receive < state.receive.length) {
+            // replay existing data (do nothing)
+            while (state.receive[receive].send !== op) {
+                // make sure we resolve only when it is our turn
+                await changes.promise;
+                if (receive === state.receive.length) {
+                    // It will never be our turn, because the replay completed
+                    // and we are still here. We will have to call `result`.
+                    return await done(op, result);
+                }
+            } // state.receive[receive].send === op
+            data = state.receive[receive].returnValue;
+        }
+        else { // receive === state.receive.length
+            data = await result();
+            state.receive.push({ send: op, returnValue: data });
+        }
+        receive++;
+        notify();
+        return data;
+    }
+    async function perform(action, payload) {
+        const index = op(payload);
+        return await done(index, () => action(index));
+    }
+    function checkpoint() {
+        return [send, receive];
+    }
+    return { perform, op, done, checkpoint };
+}

package/out/storage.d.ts

@@ -0,0 +1,169 @@
+import type { Context } from "./deps.node.js";
+/** Current data version of this plugin */
+export declare const PLUGIN_DATA_VERSION = 0;
+/**
+ * A value with a version.
+ *
+ * The version consists of two pieces.
+ *
+ * The first piece is a number that is defined by the plugin internally and
+ * cannot be changed. When the plugin is updated and it changes its internal
+ * data format, then it can use this part of the version to detect and
+ * automatically migrate the versioned state as necessary.
+ *
+ * The second piece is a number or a string and can be set by the developer. It
+ * should be changed whenever the application code changes in a way that
+ * invalidates the state. The plugin can then discard and re-create the state as
+ * necesarry.
+ *
+ * Versioned states are typically created via the {@link pinVersion} function.
+ *
+ * @typeParam S The type of the state to be versioned
+ */
+export interface VersionedState<S> {
+    /** The version of the state */
+    version: [typeof PLUGIN_DATA_VERSION, string | number];
+    /** The state to be versioned */
+    state: S;
+}
+/**
+ * A container for two functions that are pinned to a specific version. The two
+ * functions can be used to add the bound version to data, and to unpack the
+ * data again. This container is typically created using {@link pinVersion}.
+ */
+export interface PinnedVersion {
+    /**
+     * Adds a version to some data.
+     *
+     * @param state Some data
+     */
+    versionify<S>(state: S): VersionedState<S>;
+    /**
+     * Unpacks some versioned data. Returns the original data if the data is
+     * correct, and `undefined` otherwise. If `undefined` is passed, then
+     * `undefined` will be returned.
+     *
+     * @param data Some versioned data or `undefined`
+     */
+    unpack<S>(data?: VersionedState<S>): S | undefined;
+}
+/**
+ * Takes a version number and state management functions that are pinned to this
+ * version.
+ *
+ * The two functions it returns are `versionify` and `unpack`. The former can be
+ * used to add a version to some data. The latter can be used to unpack the data
+ * again, validating the version on the fly.
+ *
+ * ```ts
+ * import { assert } from "jsr:@std/assert";
+ *
+ * const { versionify, unpack } = pinVersion(42);
+ *
+ * const data = { prop: "pizza" };
+ * const versioned = versionify(data);
+ * const unpacked = unpack(versioned);
+ * assert(data === unpacked);
+ * ```
+ *
+ * @param version the version to use for pinning
+ */
+export declare function pinVersion(version: string | number): PinnedVersion;
+/**
+ * A value or a promise of a value.
+ *
+ * @typeParam T The type of value
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * A storage for versioned state.
+ *
+ * Specify this to define how to persist data.
+ *
+ * This type is a union of three types, each representing a different way to
+ * store data.
+ *
+ * 1. A {@link VersionedStateStorage} directly provides definitions for reading,
+ *    writing, and deleting data based on `ctx.chatId`. No versions can be
+ *    specified and the storage key function cannot be changed.
+ * 2. A {@link ConversationKeyStorage}, disambiguated via `{ type: "key" }`, is
+ *    more general. It supports versioning the data and changing the storage key
+ *    function.
+ * 3. A {@link ConversationContextStorage}, disambiguated via `{ type: "context"
+ *    }`, is even more general. It no longer needs a storage key function.
+ *    Instead, it provides read, write, and delete operations for data based on
+ *    the context object directly. It also supports versioning data.
+ *
+ * @typeParam C A custom context type
+ * @typeParam S A type for the state to version and store
+ */
+export type ConversationStorage<C extends Context, S> = {
+    type?: never;
+    version?: never;
+} & VersionedStateStorage<string, S> | ConversationContextStorage<C, S> | ConversationKeyStorage<C, S>;
+/**
+ * An object that defines how to read, write, and delete versioned data based on
+ * a key.
+ *
+ * @typeParam K The type of key to use
+ * @typeParam S The type of data to store
+ */
+export interface VersionedStateStorage<K, S> {
+    /**
+     * Reads the data for a given key.
+     *
+     * @param key A key to identify the data
+     */
+    read(key: K): MaybePromise<VersionedState<S> | undefined>;
+    /**
+     * Writes some data to the storage for a given key.
+     *
+     * @param key A key to identify the data
+     * @param state The data to write
+     */
+    write(key: K, state: VersionedState<S>): MaybePromise<void>;
+    /**
+     * Deletes some data from the storage for a given key.
+     *
+     * @param key A key to identify the data
+     */
+    delete(key: K): MaybePromise<void>;
+}
+/**
+ * An object that defines how to read, write, or delete versioned data based on
+ * a context object.
+ */
+export interface ConversationContextStorage<C extends Context, S> {
+    /** The type of storage, always `"context"` */
+    type: "context";
+    /** An optional version for the data, defaults to `0` */
+    version?: string | number;
+    /** The underlying storage that defines how to read and write raw data */
+    adapter: VersionedStateStorage<C, S>;
+}
+export interface ConversationKeyStorage<C extends Context, S> {
+    /** The type of storage, always `"key"` */
+    type: "key";
+    /** An optional version for the data, defaults to `0` */
+    version?: string | number;
+    /** An optional prefix to prepend to the storage key */
+    prefix?: string;
+    /** An optional storage key function, defaults to `ctx.chatId` */
+    getStorageKey?(ctx: C): string | undefined;
+    /** The underlying storage that defines how to read and write raw data */
+    adapter: VersionedStateStorage<string, S>;
+}
+/**
+ * Coerces different storages to a single uniform abstraction.
+ *
+ * This function takes a {@link ConversationStorage} object and unifies its
+ * union members behind a common abstraction that simply exposes a read, write,
+ * and delete method for a given context object.
+ *
+ * @param storage An object defining how to store data
+ */
+export declare function uniformStorage<C extends Context, S>(storage?: ConversationStorage<C, S>): (ctx: C) => {
+    read: () => MaybePromise<S | undefined>;
+    write: (state: S) => MaybePromise<void>;
+    delete: () => MaybePromise<void>;
+};

package/out/storage.js

@@ -0,0 +1,105 @@
+/** Current data version of this plugin */
+export const PLUGIN_DATA_VERSION = 0;
+/**
+ * Takes a version number and state management functions that are pinned to this
+ * version.
+ *
+ * The two functions it returns are `versionify` and `unpack`. The former can be
+ * used to add a version to some data. The latter can be used to unpack the data
+ * again, validating the version on the fly.
+ *
+ * ```ts
+ * import { assert } from "jsr:@std/assert";
+ *
+ * const { versionify, unpack } = pinVersion(42);
+ *
+ * const data = { prop: "pizza" };
+ * const versioned = versionify(data);
+ * const unpacked = unpack(versioned);
+ * assert(data === unpacked);
+ * ```
+ *
+ * @param version the version to use for pinning
+ */
+export function pinVersion(version) {
+    function versionify(state) {
+        return { version: [PLUGIN_DATA_VERSION, version], state };
+    }
+    function unpack(data) {
+        if (data === undefined)
+            return undefined;
+        if (!Array.isArray(data.version)) {
+            throw new Error("Unknown data format, cannot parse version");
+        }
+        const [pluginVersion, dataVersion] = data.version;
+        if (dataVersion !== version)
+            return undefined;
+        if (pluginVersion !== PLUGIN_DATA_VERSION) {
+            // In the future, we might want to migrate the data from an old
+            // plugin version to a new one here.
+            return undefined;
+        }
+        return data.state;
+    }
+    return { versionify, unpack };
+}
+function defaultStorageKey(ctx) {
+    var _a;
+    return (_a = ctx.chatId) === null || _a === void 0 ? void 0 : _a.toString();
+}
+function defaultStorage() {
+    const store = new Map();
+    return {
+        type: "key",
+        adapter: {
+            read: (key) => store.get(key),
+            write: (key, state) => void store.set(key, state),
+            delete: (key) => void store.delete(key),
+        },
+    };
+}
+/**
+ * Coerces different storages to a single uniform abstraction.
+ *
+ * This function takes a {@link ConversationStorage} object and unifies its
+ * union members behind a common abstraction that simply exposes a read, write,
+ * and delete method for a given context object.
+ *
+ * @param storage An object defining how to store data
+ */
+export function uniformStorage(storage) {
+    var _a;
+    storage !== null && storage !== void 0 ? storage : (storage = defaultStorage());
+    if (storage.type === undefined) {
+        return uniformStorage({ type: "key", adapter: storage });
+    }
+    const version = (_a = storage.version) !== null && _a !== void 0 ? _a : 0;
+    const { versionify, unpack } = pinVersion(version);
+    if (storage.type === "key") {
+        const { getStorageKey = defaultStorageKey, prefix = "", adapter } = storage;
+        return (ctx) => {
+            const key = prefix + getStorageKey(ctx);
+            return key === undefined
+                ? {
+                    read: () => undefined,
+                    write: () => undefined,
+                    delete: () => undefined,
+                }
+                : {
+                    read: async () => unpack(await adapter.read(key)),
+                    write: (state) => adapter.write(key, versionify(state)),
+                    delete: () => adapter.delete(key),
+                };
+        };
+    }
+    else {
+        const { adapter } = storage;
+        return (ctx) => {
+            return {
+                read: async () => unpack(await adapter.read(ctx)),
+                write: (state) => adapter.write(ctx, versionify(state)),
+                delete: () => adapter.delete(ctx),
+            };
+        };
+    }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "@rilong/grammyjs-conversations-esm",
+    "description": "Conversational interfaces for grammY",
+    "version": "2.0.2",
+    "author": "KnorpelSenf",
+    "license": "MIT",
+    "engines": {
+        "node": "^12.20.0 || >=14.13.1"
+    },
+    "homepage": "https://grammy.dev/",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/grammyjs/grammY"
+    },
+    "scripts": {
+        "prepare": "npm run backport",
+        "backport": "deno2node tsconfig.json"
+    },
+    "peerDependencies": {
+        "grammy": "^1.20.1"
+    },
+    "devDependencies": {
+        "@types/node": "^12.20.55",
+        "deno2node": "^1.14.0"
+    },
+    "files": [
+        "out/"
+    ],
+    "main": "./out/mod.js",
+    "types": "./out/mod.d.ts",
+    "keywords": [
+        "telegram",
+        "bot",
+        "api",
+        "client",
+        "framework",
+        "library",
+        "grammy",
+        "conversations",
+        "scenes",
+        "wizards"
+    ]
+}