teledzik 1.0.0

package/src/scenes/stage.ts

@@ -0,0 +1,71 @@
+import { isSessionContext, SessionContext } from '../session'
+import SceneContextScene, {
+  SceneContextSceneOptions,
+  SceneSession,
+  SceneSessionData,
+} from './context'
+import { BaseScene } from './base'
+import { Composer } from '../composer'
+import { Context } from '../context'
+
+export class Stage<
+  C extends SessionContext<SceneSession<D>> & {
+    scene: SceneContextScene<C, D>
+  },
+  D extends SceneSessionData = SceneSessionData,
+> extends Composer<C> {
+  options: Partial<SceneContextSceneOptions<D>>
+  scenes: Map<string, BaseScene<C>>
+
+  constructor(
+    scenes: ReadonlyArray<BaseScene<C>> = [],
+    options?: Partial<SceneContextSceneOptions<D>>
+  ) {
+    super()
+    this.options = { ...options }
+    this.scenes = new Map<string, BaseScene<C>>()
+    scenes.forEach((scene) => this.register(scene))
+  }
+
+  register(...scenes: ReadonlyArray<BaseScene<C>>) {
+    scenes.forEach((scene) => {
+      if (scene?.id == null || typeof scene.middleware !== 'function') {
+        throw new Error('telegraf: Unsupported scene')
+      }
+      this.scenes.set(scene.id, scene)
+    })
+    return this
+  }
+
+  middleware() {
+    const handler = Composer.compose<C>([
+      (ctx, next) => {
+        const scenes: Map<string, BaseScene<C>> = this.scenes
+        const scene = new SceneContextScene<C, D>(ctx, scenes, this.options)
+        ctx.scene = scene
+        return next()
+      },
+      super.middleware(),
+      Composer.lazy<C>((ctx) => ctx.scene.current ?? Composer.passThru()),
+    ])
+    return Composer.optional(isSessionContext, handler)
+  }
+
+  static enter<C extends Context & { scene: SceneContextScene<C> }>(
+    ...args: Parameters<SceneContextScene<C>['enter']>
+  ) {
+    return (ctx: C) => ctx.scene.enter(...args)
+  }
+
+  static reenter<C extends Context & { scene: SceneContextScene<C> }>(
+    ...args: Parameters<SceneContextScene<C>['reenter']>
+  ) {
+    return (ctx: C) => ctx.scene.reenter(...args)
+  }
+
+  static leave<C extends Context & { scene: SceneContextScene<C> }>(
+    ...args: Parameters<SceneContextScene<C>['leave']>
+  ) {
+    return (ctx: C) => ctx.scene.leave(...args)
+  }
+}

package/src/scenes/wizard/context.ts

@@ -0,0 +1,58 @@
+import SceneContextScene, { SceneSession, SceneSessionData } from '../context'
+import Context from '../../context'
+import { Middleware } from '../../middleware'
+import { SessionContext } from '../../session'
+
+export interface WizardContext<D extends WizardSessionData = WizardSessionData>
+  extends Context {
+  session: WizardSession<D>
+  scene: SceneContextScene<WizardContext<D>, D>
+  wizard: WizardContextWizard<WizardContext<D>>
+}
+
+export interface WizardSessionData extends SceneSessionData {
+  cursor: number
+}
+
+export interface WizardSession<S extends WizardSessionData = WizardSessionData>
+  extends SceneSession<S> {}
+
+export default class WizardContextWizard<
+  C extends SessionContext<WizardSession> & {
+    scene: SceneContextScene<C, WizardSessionData>
+  },
+> {
+  readonly state: object
+  constructor(
+    private readonly ctx: C,
+    private readonly steps: ReadonlyArray<Middleware<C>>
+  ) {
+    this.state = ctx.scene.state
+    this.cursor = ctx.scene.session.cursor ?? 0
+  }
+
+  get step() {
+    return this.steps[this.cursor]
+  }
+
+  get cursor() {
+    return this.ctx.scene.session.cursor
+  }
+
+  set cursor(cursor: number) {
+    this.ctx.scene.session.cursor = cursor
+  }
+
+  selectStep(index: number) {
+    this.cursor = index
+    return this
+  }
+
+  next() {
+    return this.selectStep(this.cursor + 1)
+  }
+
+  back() {
+    return this.selectStep(this.cursor - 1)
+  }
+}

package/src/scenes/wizard/index.ts

@@ -0,0 +1,63 @@
+import BaseScene, { SceneOptions } from '../base'
+import { Middleware, MiddlewareObj } from '../../middleware'
+import WizardContextWizard, { WizardSessionData } from './context'
+import Composer from '../../composer'
+import Context from '../../context'
+import SceneContextScene from '../context'
+
+export class WizardScene<
+    C extends Context & {
+      scene: SceneContextScene<C, WizardSessionData>
+      wizard: WizardContextWizard<C>
+    },
+  >
+  extends BaseScene<C>
+  implements MiddlewareObj<C>
+{
+  steps: Array<Middleware<C>>
+
+  constructor(id: string, ...steps: Array<Middleware<C>>)
+  constructor(
+    id: string,
+    options: SceneOptions<C>,
+    ...steps: Array<Middleware<C>>
+  )
+  constructor(
+    id: string,
+    options: SceneOptions<C> | Middleware<C>,
+    ...steps: Array<Middleware<C>>
+  ) {
+    let opts: SceneOptions<C> | undefined
+    let s: Array<Middleware<C>>
+    if (typeof options === 'function' || 'middleware' in options) {
+      opts = undefined
+      s = [options, ...steps]
+    } else {
+      opts = options
+      s = steps
+    }
+    super(id, opts)
+    this.steps = s
+  }
+
+  middleware() {
+    return Composer.compose<C>([
+      (ctx, next) => {
+        ctx.wizard = new WizardContextWizard<C>(ctx, this.steps)
+        return next()
+      },
+      super.middleware(),
+      (ctx, next) => {
+        if (ctx.wizard.step === undefined) {
+          ctx.wizard.selectStep(0)
+          return ctx.scene.leave()
+        }
+        return Composer.unwrap(ctx.wizard.step)(ctx, next)
+      },
+    ])
+  }
+
+  enterMiddleware() {
+    return Composer.compose([this.enterHandler, this.middleware()])
+  }
+}

package/src/scenes.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./scenes/index.js"), exports);

package/src/scenes.ts

@@ -0,0 +1 @@
+export * from './scenes/index.js'

package/src/session.js

@@ -0,0 +1,175 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSessionContext = exports.MemorySessionStore = exports.session = void 0;
+const debug_1 = __importDefault(require("debug"));
+const debug = (0, debug_1.default)('telegraf:session');
+/**
+ * Returns middleware that adds `ctx.session` for storing arbitrary state per session key.
+ *
+ * The default `getSessionKey` is `${ctx.from.id}:${ctx.chat.id}`.
+ * If either `ctx.from` or `ctx.chat` is `undefined`, default session key and thus `ctx.session` are also `undefined`.
+ *
+ * > ⚠️ Session data is kept only in memory by default,  which means that all data will be lost when the process is terminated.
+ * >
+ * > If you want to persist data across process restarts, or share it among multiple instances, you should use
+ * [@telegraf/session](https://www.npmjs.com/package/@telegraf/session), or pass custom `storage`.
+ *
+ * @see {@link https://github.com/feathers-studio/telegraf-docs/blob/b694bcc36b4f71fb1cd650a345c2009ab4d2a2a5/guide/session.md Telegraf Docs | Session}
+ * @see {@link https://github.com/feathers-studio/telegraf-docs/blob/master/examples/session-bot.ts Example}
+ */
+function session(options) {
+    var _a, _b, _c;
+    const prop = (_a = options === null || options === void 0 ? void 0 : options.property) !== null && _a !== void 0 ? _a : 'session';
+    const getSessionKey = (_b = options === null || options === void 0 ? void 0 : options.getSessionKey) !== null && _b !== void 0 ? _b : defaultGetSessionKey;
+    const store = (_c = options === null || options === void 0 ? void 0 : options.store) !== null && _c !== void 0 ? _c : new MemorySessionStore();
+    // caches value from store in-memory while simultaneous updates share it
+    // when counter reaches 0, the cached ref will be freed from memory
+    const cache = new Map();
+    // temporarily stores concurrent requests
+    const concurrents = new Map();
+    // this function must be handled with care
+    // read full description on the original PR: https://github.com/telegraf/telegraf/pull/1713
+    // make sure to update the tests in test/session.js if you make any changes or fix bugs here
+    return (ctx, next) => __awaiter(this, void 0, void 0, function* () {
+        var _d;
+        const updId = ctx.update.update_id;
+        let released = false;
+        function releaseChecks() {
+            if (released && process.env.EXPERIMENTAL_SESSION_CHECKS)
+                throw new Error("Session was accessed or assigned to after the middleware chain exhausted. This is a bug in your code. You're probably accessing session asynchronously and missing awaits.");
+        }
+        // because this is async, requests may still race here, but it will get autocorrected at (1)
+        // v5 getSessionKey should probably be synchronous to avoid that
+        const key = yield getSessionKey(ctx);
+        if (!key) {
+            // Leaving this here could be useful to check for `prop in ctx` in future middleware
+            ctx[prop] = undefined;
+            return yield next();
+        }
+        let cached = cache.get(key);
+        if (cached) {
+            debug(`(${updId}) found cached session, reusing from cache`);
+            ++cached.counter;
+        }
+        else {
+            debug(`(${updId}) did not find cached session`);
+            // if another concurrent request has already sent a store request, fetch that instead
+            let promise = concurrents.get(key);
+            if (promise)
+                debug(`(${updId}) found a concurrent request, reusing promise`);
+            else {
+                debug(`(${updId}) fetching from upstream store`);
+                promise = store.get(key);
+            }
+            // synchronously store promise so concurrent requests can share response
+            concurrents.set(key, promise);
+            const upstream = yield promise;
+            // all concurrent awaits will have promise in their closure, safe to remove now
+            concurrents.delete(key);
+            debug(`(${updId}) updating cache`);
+            // another request may have beaten us to the punch
+            const c = cache.get(key);
+            if (c) {
+                // another request did beat us to the punch
+                c.counter++;
+                // (1) preserve cached reference; in-memory reference is always newer than from store
+                cached = c;
+            }
+            else {
+                // we're the first, so we must cache the reference
+                cached = { ref: upstream !== null && upstream !== void 0 ? upstream : (_d = options === null || options === void 0 ? void 0 : options.defaultSession) === null || _d === void 0 ? void 0 : _d.call(options, ctx), counter: 1 };
+                cache.set(key, cached);
+            }
+        }
+        // TS already knows cached is always defined by this point, but does not guard cached.
+        // It will, however, guard `c` here.
+        const c = cached;
+        let touched = false;
+        Object.defineProperty(ctx, prop, {
+            get() {
+                releaseChecks();
+                touched = true;
+                return c.ref;
+            },
+            set(value) {
+                releaseChecks();
+                touched = true;
+                c.ref = value;
+            },
+        });
+        try {
+            yield next();
+            released = true;
+        }
+        finally {
+            if (--c.counter === 0) {
+                // decrement to avoid memory leak
+                debug(`(${updId}) refcounter reached 0, removing cached`);
+                cache.delete(key);
+            }
+            debug(`(${updId}) middlewares completed, checking session`);
+            // only update store if ctx.session was touched
+            if (touched)
+                if (c.ref == null) {
+                    debug(`(${updId}) ctx.${prop} missing, removing from store`);
+                    yield store.delete(key);
+                }
+                else {
+                    debug(`(${updId}) ctx.${prop} found, updating store`);
+                    yield store.set(key, c.ref);
+                }
+        }
+    });
+}
+exports.session = session;
+function defaultGetSessionKey(ctx) {
+    var _a, _b;
+    const fromId = (_a = ctx.from) === null || _a === void 0 ? void 0 : _a.id;
+    const chatId = (_b = ctx.chat) === null || _b === void 0 ? void 0 : _b.id;
+    if (fromId == null || chatId == null)
+        return undefined;
+    return `${fromId}:${chatId}`;
+}
+/** @deprecated Use `Map` */
+class MemorySessionStore {
+    constructor(ttl = Infinity) {
+        this.ttl = ttl;
+        this.store = new Map();
+    }
+    get(name) {
+        const entry = this.store.get(name);
+        if (entry == null) {
+            return undefined;
+        }
+        else if (entry.expires < Date.now()) {
+            this.delete(name);
+            return undefined;
+        }
+        return entry.session;
+    }
+    set(name, value) {
+        const now = Date.now();
+        this.store.set(name, { session: value, expires: now + this.ttl });
+    }
+    delete(name) {
+        this.store.delete(name);
+    }
+}
+exports.MemorySessionStore = MemorySessionStore;
+/** @deprecated session can use custom properties now. Directly use `'session' in ctx` instead */
+function isSessionContext(ctx) {
+    return 'session' in ctx;
+}
+exports.isSessionContext = isSessionContext;

package/src/session.ts

@@ -0,0 +1,204 @@
+import { Context } from './context'
+import { ExclusiveKeys, MaybePromise } from './core/helpers/util'
+import { MiddlewareFn } from './middleware'
+import d from 'debug'
+const debug = d('telegraf:session')
+
+export interface SyncSessionStore<T> {
+  get: (name: string) => T | undefined
+  set: (name: string, value: T) => void
+  delete: (name: string) => void
+}
+
+export interface AsyncSessionStore<T> {
+  get: (name: string) => Promise<T | undefined>
+  set: (name: string, value: T) => Promise<unknown>
+  delete: (name: string) => Promise<unknown>
+}
+
+export type SessionStore<T> = SyncSessionStore<T> | AsyncSessionStore<T>
+
+interface SessionOptions<S, C extends Context, P extends string> {
+  /** Customise the session prop. Defaults to "session" and is available as ctx.session. */
+  property?: P
+  getSessionKey?: (ctx: C) => MaybePromise<string | undefined>
+  store?: SessionStore<S>
+  defaultSession?: (ctx: C) => S
+}
+
+/** @deprecated session can use custom properties now. Construct this type directly. */
+export interface SessionContext<S extends object> extends Context {
+  session?: S
+}
+
+/**
+ * Returns middleware that adds `ctx.session` for storing arbitrary state per session key.
+ *
+ * The default `getSessionKey` is `${ctx.from.id}:${ctx.chat.id}`.
+ * If either `ctx.from` or `ctx.chat` is `undefined`, default session key and thus `ctx.session` are also `undefined`.
+ *
+ * > ⚠️ Session data is kept only in memory by default,  which means that all data will be lost when the process is terminated.
+ * >
+ * > If you want to persist data across process restarts, or share it among multiple instances, you should use
+ * [@telegraf/session](https://www.npmjs.com/package/@telegraf/session), or pass custom `storage`.
+ *
+ * @see {@link https://github.com/feathers-studio/telegraf-docs/blob/b694bcc36b4f71fb1cd650a345c2009ab4d2a2a5/guide/session.md Telegraf Docs | Session}
+ * @see {@link https://github.com/feathers-studio/telegraf-docs/blob/master/examples/session-bot.ts Example}
+ */
+export function session<
+  S extends NonNullable<C[P]>,
+  C extends Context & { [key in P]?: C[P] },
+  P extends (ExclusiveKeys<C, Context> & string) | 'session' = 'session',
+  // ^ Only allow prop names that aren't keys in base Context.
+  // At type level, this is cosmetic. To not get cluttered with all Context keys.
+>(options?: SessionOptions<S, C, P>): MiddlewareFn<C> {
+  const prop = options?.property ?? ('session' as P)
+  const getSessionKey = options?.getSessionKey ?? defaultGetSessionKey
+  const store = options?.store ?? new MemorySessionStore()
+  // caches value from store in-memory while simultaneous updates share it
+  // when counter reaches 0, the cached ref will be freed from memory
+  const cache = new Map<string, { ref?: S; counter: number }>()
+  // temporarily stores concurrent requests
+  const concurrents = new Map<string, MaybePromise<S | undefined>>()
+
+  // this function must be handled with care
+  // read full description on the original PR: https://github.com/telegraf/telegraf/pull/1713
+  // make sure to update the tests in test/session.js if you make any changes or fix bugs here
+  return async (ctx, next) => {
+    const updId = ctx.update.update_id
+
+    let released = false
+
+    function releaseChecks() {
+      if (released && process.env.EXPERIMENTAL_SESSION_CHECKS)
+        throw new Error(
+          "Session was accessed or assigned to after the middleware chain exhausted. This is a bug in your code. You're probably accessing session asynchronously and missing awaits."
+        )
+    }
+
+    // because this is async, requests may still race here, but it will get autocorrected at (1)
+    // v5 getSessionKey should probably be synchronous to avoid that
+    const key = await getSessionKey(ctx)
+    if (!key) {
+      // Leaving this here could be useful to check for `prop in ctx` in future middleware
+      ctx[prop] = undefined as unknown as S
+      return await next()
+    }
+
+    let cached = cache.get(key)
+    if (cached) {
+      debug(`(${updId}) found cached session, reusing from cache`)
+      ++cached.counter
+    } else {
+      debug(`(${updId}) did not find cached session`)
+      // if another concurrent request has already sent a store request, fetch that instead
+      let promise = concurrents.get(key)
+      if (promise)
+        debug(`(${updId}) found a concurrent request, reusing promise`)
+      else {
+        debug(`(${updId}) fetching from upstream store`)
+        promise = store.get(key)
+      }
+      // synchronously store promise so concurrent requests can share response
+      concurrents.set(key, promise)
+      const upstream = await promise
+      // all concurrent awaits will have promise in their closure, safe to remove now
+      concurrents.delete(key)
+      debug(`(${updId}) updating cache`)
+      // another request may have beaten us to the punch
+      const c = cache.get(key)
+      if (c) {
+        // another request did beat us to the punch
+        c.counter++
+        // (1) preserve cached reference; in-memory reference is always newer than from store
+        cached = c
+      } else {
+        // we're the first, so we must cache the reference
+        cached = { ref: upstream ?? options?.defaultSession?.(ctx), counter: 1 }
+        cache.set(key, cached)
+      }
+    }
+
+    // TS already knows cached is always defined by this point, but does not guard cached.
+    // It will, however, guard `c` here.
+    const c = cached
+
+    let touched = false
+
+    Object.defineProperty(ctx, prop, {
+      get() {
+        releaseChecks()
+        touched = true
+        return c.ref
+      },
+      set(value: S) {
+        releaseChecks()
+        touched = true
+        c.ref = value
+      },
+    })
+
+    try {
+      await next()
+      released = true
+    } finally {
+      if (--c.counter === 0) {
+        // decrement to avoid memory leak
+        debug(`(${updId}) refcounter reached 0, removing cached`)
+        cache.delete(key)
+      }
+      debug(`(${updId}) middlewares completed, checking session`)
+
+      // only update store if ctx.session was touched
+      if (touched)
+        if (c.ref == null) {
+          debug(`(${updId}) ctx.${prop} missing, removing from store`)
+          await store.delete(key)
+        } else {
+          debug(`(${updId}) ctx.${prop} found, updating store`)
+          await store.set(key, c.ref)
+        }
+    }
+  }
+}
+
+function defaultGetSessionKey(ctx: Context): string | undefined {
+  const fromId = ctx.from?.id
+  const chatId = ctx.chat?.id
+  if (fromId == null || chatId == null) return undefined
+  return `${fromId}:${chatId}`
+}
+
+/** @deprecated Use `Map` */
+export class MemorySessionStore<T> implements SyncSessionStore<T> {
+  private readonly store = new Map<string, { session: T; expires: number }>()
+
+  constructor(private readonly ttl = Infinity) {}
+
+  get(name: string): T | undefined {
+    const entry = this.store.get(name)
+    if (entry == null) {
+      return undefined
+    } else if (entry.expires < Date.now()) {
+      this.delete(name)
+      return undefined
+    }
+    return entry.session
+  }
+
+  set(name: string, value: T): void {
+    const now = Date.now()
+    this.store.set(name, { session: value, expires: now + this.ttl })
+  }
+
+  delete(name: string): void {
+    this.store.delete(name)
+  }
+}
+
+/** @deprecated session can use custom properties now. Directly use `'session' in ctx` instead */
+export function isSessionContext<S extends object>(
+  ctx: Context
+): ctx is SessionContext<S> {
+  return 'session' in ctx
+}