Skip to content

callback-data

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

callback-data

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
src
src
 
 
README.md
README.md
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 

README.md


@puregram/callback-data

basic callback data validation and serialization for puregram package

introduction

i'm tired of people using json objects as their callback data payload. this is NOT okay, you should NOT do that. at least because it's not safe when it comes to amount of bytes (JSON.stringify your ass), at most because at the end you have zero types, zero validation, zero anything

@puregram/callback-data provides those mentioned things. yeah, you can write callback data payload that will be validated and will have correct types! incredible.

example

let's create a keyboard that will automatically ban the user!

const { Telegram, InlineKeyboard } = require('puregram')

const { CallbackDataBuilder } = require('@puregram/callback-data')

const telegram = Telegram.fromToken(process.env.TOKEN)

// we create a 'ban' callback data...
const BanPayload = CallbackDataBuilder.create('ban')
  // ... with a number field 'user_id'
  .number('user_id')

const createBanKeyboard = (userId: number) => (
  InlineKeyboard.keyboard([
    InlineKeyboard.textButton({
      text: 'Ban',
      // here we pack our callback data into a small parseable string
      // with all our needed payload
      payload: BanPayload.pack({ user_id: userId })
    })
  ])
)

// let's create our handler
telegram.updates.on('message', (context) => {
  return context.send('User sent a message!', {
    chat_id: process.env.ADMIN_ID,
    reply_markup: createBanKeyboard(context.senderId)
  })
})

// let's handle our 'ban' callback queries!
telegram.updates.use(
  BanPayload.handle((context) => {
    // for convenience
    const payload = context.unpackedPayload
    //    payload: { user_id: number }

    // you can now do whatever you want with `payload.user_id`!
  })
)

telegram.updates.startPolling()

installation

$ yarn add @puregram/callback-data
$ npm i -S @puregram/callback-data

optional or defaulted values

it's possible that you will need a value that may not be present at all times (basically an optional value, right?)

@puregram/callback-data has tools for handling optional values and values that have a default value

optional
const BanPayload = CallbackDataBuilder.create('...')
  .number('user_id')
  .string('reason', { optional: true })

telegram.updates.use(
  BanPayload.handle((context) => {
    const payload = context.unpackedPayload
    //    payload: { user_id: number, reason?: string | undefined }
  })
)

you can also use filtering and literally filters to handle specific cases like when you have the reason for ban and when you dont

telegram.updates.use(
  BanPayload.filter({ reason: filters.exists() }).handle((context) => {
    const payload = context.unpackedPayload
    //    payload: { user_id: number, reason: string }
    // reason will always be present in this case!
  })
)

telegram.updates.use(
  BanPayload.filter({ reason: filters.exists(false) }).handle((context) => {
    const payload = context.unpackedPayload
    //    payload: { user_id: number, reason: undefined }
    // reason will always be undefined here no matter what
  })
)
default

yeah so

const CounterPayload = CallbackDataBuilder.create('counter')
  .number('clicks', { default: 0 })

const counterKeyboard = InlineKeyboard.keyboard([
  InlineKeyboard.textButton({
    text: 'click!',
    payload: CounterPayload.pack({}) // no need to provide `clicks` value!
  })
])

ez stuff $$$

filtering

sometimes you will need to process updates in more detail. that's why CallbackDataBuilder has its own filter function (that is also type-safe! as far as i know). it can accept those values:

  • raw values (string, boolean, number);
  • a function that takes the value and returns non-false value;
  • an array of those above;
  • or a filter.
raw value
telegram.updates.use(
  BanPayload.filter({ user_id: 1337 }).handle((context) => {
    // will be called only if `user_id` is exactly `1337`
  })
)
function
const ADMIN_IDS = [1, 2, 3]

telegram.updates.use(
  BanPayload.filter({ user_id: (userId) => !ADMIN_IDS.includes(userId) }).handle((context) => {
    // this will not be called if `user_id` is either `1`, `2` or `3`
    // will be called otherwise though
  })
)
an array
telegram.updates.use(
  BanPayload.filter({ user_id: [42, (userId) => userId % 2 !== 0 ] }).handle((context) => {
    // will be called EITHER if `user_id` is `42` OR if `user_id` is even
    // because who wants people with odd user IDs be banned? ¯\_(ツ)_/¯
  })
)

literally filters

@puregram/callback-data also has filters for filters. they're called... filters.

currently there aren't much of those: only filters.exists(exists?: boolean) and that's it. it will probably be expanded in the future...

const { filters } = require('@puregram/callback-data')

const FooPayload = CallbackDataBuilder.create('foo')
  .string('bar')
  .boolean('baz', { optional: true })
  .number('quix', { default: 42 })

telegram.updates.use(
  FooPayload.filter({ baz: filters.exists() }).handle((context) => {
    // this will be called only if `baz` iz provided (not `undefined`)
  })
)

not sure what to describe here, filters act like filters: they filter out values

typescript usage

@puregram/callback-data's updates are based on puregram's CallbackQueryContext so CallbackQueryContext will have a new unpackedPayload: Record<never, never> property by default, but you definitely won't use that in your ordinary 'callback_query' updates, so don't worry about that. everything you need is already packed into handles logic under the hood

import { CallbackDataBuilder } from '@puregram/callback-data'

const BanPayload = CallbackDataBuilder.create('ban')
  .number('user_id')

// ...

telegram.updates.use(
  BanPayload.handle((context) => {
    const payload = context.unpackedPayload
    //    payload: { user_id: number }
  })
)

but in case you really need to extend your own contexts with that juicy types you can always import CallbackLayer:

import type { Context } from 'puregram'
import type { CallbackLayer } from '@puregram/callback-data'

type MyContext<C extends Context> = C & CallbackLayer<typeof BanPayload>

that's it!