@gramio/callback-data
Version:
Library for easily manage callback-data
177 lines (173 loc) • 8.38 kB
TypeScript
type Prettify<T> = {
[Key in keyof T]: T[Key];
} & {};
type AllowedTypes = "string" | "number" | "boolean" | "enum" | "uuid" | "data";
interface FieldTypeToTsType<Enum extends unknown[] | readonly unknown[], Data extends CallbackData = never> {
string: string;
number: number;
boolean: boolean;
enum: Enum;
uuid: string;
data: InferDataPack<Data>;
}
type AddFieldOutput<T extends AllowedTypes, Key extends string, Optional extends boolean = false, Enum extends unknown[] = never, Default extends FieldTypeToTsType<Enum, Data>[T] = never, Data extends CallbackData = never> = [Default] extends [never] ? Optional extends true ? {
[K in Key]?: FieldTypeToTsType<Enum, Data>[T];
} : {
[K in Key]: FieldTypeToTsType<Enum, Data>[T];
} : {
[K in Key]: FieldTypeToTsType<Enum, Data>[T];
};
type AddFieldInput<T extends AllowedTypes, Key extends string, Optional extends boolean = false, Enum extends unknown[] = never, Default extends FieldTypeToTsType<Enum, Data>[T] = never, Data extends CallbackData = never> = [Default] extends [never] ? Optional extends true ? {
[K in Key]?: FieldTypeToTsType<Enum, Data>[T];
} : {
[K in Key]: FieldTypeToTsType<Enum, Data>[T];
} : {
[K in Key]?: FieldTypeToTsType<Enum, Data>[T];
};
interface FieldOptions<T extends AllowedTypes, Optional extends boolean = false, Enum extends unknown[] | readonly unknown[] = never, Default extends FieldTypeToTsType<Enum>[T] = never> {
optional?: [Default] extends [never] ? Optional : true;
default?: Default;
}
type Schema = {
required: {
key: string;
type: AllowedTypes;
enumValues?: string[] | readonly string[];
data?: CallbackData;
}[];
optional: {
key: string;
type: AllowedTypes;
enumValues?: string[] | readonly string[];
data?: CallbackData;
default?: any;
}[];
};
type IsOptionalType<T> = {
[K in keyof T]-?: undefined extends T[K] ? true : false;
}[keyof T] extends true ? true : false;
type SafeUnpackResult<T> = {
success: true;
data: T;
} | {
success: false;
error: Error;
};
type InferDataPack<T extends CallbackData> = T extends CallbackData<infer SchemaType, infer SchemaTypeInput> ? SchemaTypeInput : never;
type InferDataUnpack<T extends CallbackData> = T extends CallbackData<infer SchemaType, infer SchemaTypeInput> ? SchemaType : never;
/**
* @module
*
* Library for easily manage callback-data
*/
/**
* Class-helper that construct schema and serialize/deserialize with {@link CallbackData.pack} and {@link CallbackData.unpack} methods
*
* @example
* ```typescript
* const someData = new CallbackData("example").number("id");
*
* new Bot()
* .command("start", (context) =>
* context.send("some", {
* reply_markup: new InlineKeyboard().text(
* "example",
* someData.pack({
* id: 1,
* })
* ),
* })
* )
* .callbackQuery(someData, (context) => {
* context.queryData; // is type-safe
* });
* ```
*/
declare class CallbackData<SchemaType extends Record<string, any> = Record<never, never>, SchemaTypeInput extends Record<string, any> = Record<never, never>> {
nameId: string;
/** `id` for identify the CallbackData */
id: string;
private legacyId;
protected schema: Schema;
/** Pass the `id` with which you can identify the CallbackData */
constructor(nameId: string);
/**
* Add `string` property to schema
* @param key Name of property
*/
string<Key extends string, Optional extends boolean = false, const Default extends string = never>(key: Key, options?: FieldOptions<"string", Optional, never, Default>): CallbackData<Prettify<SchemaType & AddFieldOutput<"string", Key, Optional, never, Default>>, Prettify<SchemaTypeInput & AddFieldInput<"string", Key, Optional, never, Default>>>;
/**
* Add `number` property to schema
* @param key Name of property
*/
number<Key extends string, Optional extends boolean = false, const Default extends number = never>(key: Key, options?: FieldOptions<"number", Optional, never, Default>): CallbackData<Prettify<SchemaType & AddFieldOutput<"number", Key, Optional, never, Default>>, Prettify<SchemaTypeInput & AddFieldInput<"number", Key, Optional, never, Default>>>;
/**
* Add `boolean` property to schema
* @param key Name of property
*/
boolean<Key extends string, Optional extends boolean = false, const Default extends boolean = never>(key: Key, options?: FieldOptions<"boolean", Optional, never, Default>): CallbackData<Prettify<SchemaType & AddFieldOutput<"boolean", Key, Optional, never, Default>>, Prettify<SchemaTypeInput & AddFieldInput<"boolean", Key, Optional, never, Default>>>;
/**
* Add `enum` property to schema
* @param key Name of property
* @param enumValues Enum values
*/
enum<Key extends string, Optional extends boolean = false, const T extends any[] | readonly any[] = never, const Default extends T[number] = never>(key: Key, enumValues: T, options?: FieldOptions<"enum", Optional, T, Default>): CallbackData<Prettify<SchemaType & AddFieldOutput<"enum", Key, Optional, T[number], Default>>, Prettify<SchemaTypeInput & AddFieldInput<"enum", Key, Optional, T[number], Default>>>;
/**
* Add `uuid` property to schema
* @param key Name of property
*/
uuid<Key extends string, Optional extends boolean = false, const Default extends string = never>(key: Key, options?: FieldOptions<"uuid", Optional, never, Default>): CallbackData<Prettify<SchemaType & AddFieldOutput<"uuid", Key, Optional, never, Default>>, Prettify<SchemaTypeInput & AddFieldInput<"uuid", Key, Optional, never, Default>>>;
data<Key extends string, Optional extends boolean = false, const Data extends CallbackData = never>(key: Key, data: Data, options?: FieldOptions<"data", Optional, never>): CallbackData<Prettify<SchemaType & AddFieldOutput<"data", Key, Optional, never, never, Data>>, Prettify<SchemaTypeInput & AddFieldInput<"data", Key, Optional, never, never, Data>>>;
/**
* Method that return {@link RegExp} to match this {@link CallbackData}
*/
regexp(): RegExp;
/**
* Method that return `true` if data is this {@link CallbackData}
* @param data String with data
*/
filter(data: string): boolean;
/**
* A method for [`serializing`](https://developer.mozilla.org/en-US/docs/Glossary/Serialization) **object data** defined by **schema** into a **string**
* @param data Object defined by schema
*
* @example
* ```ts
* const someData = new CallbackData("example").number("id");
*
* context.send("some", {
* reply_markup: new InlineKeyboard().text(
* "example",
* someData.pack({
* id: 1,
* }),
* ),
* });
* ```
*/
pack<const T extends SchemaTypeInput>(...args: IsOptionalType<SchemaTypeInput> extends true ? [data?: T | undefined] : [data: T]): string;
/**
* A method for [`deserializing`](https://developer.mozilla.org/en-US/docs/Glossary/Deserialization) data **object** by **schema** from a **string**
* @param data String with data (please check that this string matched by {@link CallbackData.regexp})
*/
unpack(data: string): SchemaType;
/**
* Safe version of {@link CallbackData.unpack} that never throws.
* Returns `{ success: true, data }` on success or `{ success: false, error }` on failure.
*
* Useful for handling outdated callback data from old inline keyboards after schema changes.
*
* @example
* ```ts
* const result = someData.safeUnpack(data);
* if (result.success) {
* console.log(result.data);
* } else {
* context.answerCallbackQuery("This button is outdated!");
* }
* ```
*/
safeUnpack(data: string): SafeUnpackResult<SchemaType>;
extend<OtherSchemaType extends Record<string, unknown>, OtherSchemaTypeInput extends Record<string, unknown>>(other: CallbackData<OtherSchemaType, OtherSchemaTypeInput>): CallbackData<Prettify<SchemaType & OtherSchemaType>, Prettify<SchemaTypeInput & OtherSchemaTypeInput>>;
}
export { CallbackData, type InferDataPack, type InferDataUnpack, type SafeUnpackResult };