@tma.js/sdk 0.13.3 → 1.0.1

package/src/parsing/ArrayValueParser.ts

@@ -0,0 +1,79 @@
+import type { AnyParser, Parser } from './types.js';
+import { unexpectedTypeError } from './unexpectedTypeError.js';
+import type { ParseResult, ValueParserOverrides } from './ValueParser.js';
+import { ValueParser } from './ValueParser.js';
+
+export type OfResult<BaseClass, ItemType, IsOptional extends boolean> = ArrayParserType<
+BaseClass,
+ItemType,
+IsOptional
+>;
+
+export interface ArrayParserOverrides<
+  BaseClass,
+  ItemType,
+  IsOptional extends boolean,
+> extends ValueParserOverrides<BaseClass, ItemType[], IsOptional> {
+  /**
+   * Specifies parser for each array item.
+   * @param parser - item parser.
+   */
+  of<Item>(parser: AnyParser<Item>): OfResult<BaseClass, Item, IsOptional>;
+}
+
+export type ArrayParserType<BaseClass, ItemType, IsOptional extends boolean> =
+  Omit<BaseClass, keyof ArrayParserOverrides<any, any, any>>
+  & ArrayParserOverrides<BaseClass, ItemType, IsOptional>;
+
+/**
+ * Parses incoming value as array.
+ * @param value - value to parse.
+ */
+function parseArray(value: unknown): unknown[] {
+  if (Array.isArray(value)) {
+    return value;
+  }
+
+  if (typeof value === 'string') {
+    try {
+      const json = JSON.parse(value);
+
+      if (Array.isArray(json)) {
+        return json;
+      }
+      // eslint-disable-next-line no-empty
+    } catch (e) {
+    }
+  }
+  throw unexpectedTypeError();
+}
+
+export class ArrayValueParser<ItemType, IsOptional extends boolean>
+  extends ValueParser<unknown[], IsOptional> {
+  private itemParser: Parser<any>;
+
+  constructor(
+    itemParser: AnyParser<ItemType>,
+    isOptional: IsOptional,
+    type?: string,
+  ) {
+    super(parseArray, isOptional, type);
+
+    this.itemParser = typeof itemParser === 'function'
+      ? itemParser
+      : itemParser.parse.bind(itemParser);
+  }
+
+  override parse(value: unknown): ParseResult<ItemType[], IsOptional> {
+    const arr = super.parse(value);
+    return arr === undefined ? arr : arr.map(this.itemParser);
+  }
+
+  of<Item>(itemParser: AnyParser<Item>): OfResult<this, Item, IsOptional> {
+    this.itemParser = typeof itemParser === 'function'
+      ? itemParser
+      : itemParser.parse.bind(itemParser);
+
+    return this as OfResult<this, Item, IsOptional>;
+  }
+}

package/src/parsing/ParseError.ts

@@ -0,0 +1,27 @@
+interface Options {
+  /**
+   * Type name.
+   */
+  type?: string;
+
+  /**
+   * Original occurred error.
+   */
+  cause?: unknown;
+}
+
+/**
+ * Error thrown in case, there was an error during parsing.
+ */
+export class ParseError extends Error {
+  /**
+   * Parser name.
+   */
+  public readonly type?: string;
+
+  constructor(public readonly value: unknown, { cause, type }: Options = {}) {
+    super(`Unable to parse value${type ? ` as ${type}` : ''}`, { cause });
+    Object.setPrototypeOf(this, ParseError.prototype);
+    this.type = type;
+  }
+}

package/src/parsing/ParseSchemaFieldError.ts

@@ -0,0 +1,21 @@
+interface Options {
+  /**
+   * Type name.
+   */
+  type?: string;
+
+  /**
+   * Original occurred error.
+   */
+  cause?: unknown;
+}
+
+/**
+ * Error thrown in case, there was an error during parse.
+ */
+export class ParseSchemaFieldError extends Error {
+  constructor(field: string, { cause, type }: Options = {}) {
+    super(`Unable to parse field "${field}"${type ? ` as ${type}` : ''}`, { cause });
+    Object.setPrototypeOf(this, ParseSchemaFieldError.prototype);
+  }
+}

package/src/parsing/ValueParser.ts

@@ -0,0 +1,71 @@
+import type { If } from '~/types/index.js';
+
+import { ParseError } from './ParseError.js';
+import type { Parser } from './types.js';
+
+/**
+ * Result of "parse" function.
+ */
+export type ParseResult<ResultType, IsOptional extends boolean> =
+  | ResultType
+  | If<IsOptional, undefined, never>;
+
+/**
+ * Result of "optional" function in ValueParser.
+ */
+export type OptionalResult<BaseClass, ResultType> = ValueParserType<
+BaseClass,
+ResultType,
+true
+>;
+
+export interface ValueParserOverrides<BaseClass, ResultType, IsOptional extends boolean> {
+  /**
+   * Parses incoming value applying parsing function passed via constructor.
+   * @param value - value to parse.
+   */
+  parse(value: unknown): ParseResult<ResultType, IsOptional>;
+
+  /**
+   * Marks this parser result as optional. This makes the parser to check if passed value
+   * is empty. If so, parser will return undefined value instead of passing it to the actual
+   * parser.
+   */
+  optional(): OptionalResult<BaseClass, ResultType>;
+}
+
+/**
+ * Describes generated ValueParser interface. Shortly saying, this type overrides BaseClass
+ * properties defined in ValueParser.
+ */
+export type ValueParserType<BaseClass, ResultType, IsOptional extends boolean> =
+  Omit<BaseClass, keyof ValueParserOverrides<any, any, any>>
+  & ValueParserOverrides<BaseClass, ResultType, IsOptional>;
+
+export class ValueParser<ResultType, IsOptional extends boolean> {
+  constructor(
+    protected parser: Parser<ResultType>,
+    protected isOptional: IsOptional,
+    protected type?: string,
+  ) {
+  }
+
+  parse(value: unknown): ParseResult<ResultType, IsOptional> {
+    // In case, parsing result is specified as optional, and passed value is considered as empty,
+    // we can return undefined. Otherwise, pass to parser.
+    if (this.isOptional && value === undefined) {
+      return undefined as ParseResult<ResultType, IsOptional>;
+    }
+
+    try {
+      return this.parser(value) as ParseResult<ResultType, IsOptional>;
+    } catch (cause) {
+      throw new ParseError(value, { type: this.type, cause });
+    }
+  }
+
+  optional(): OptionalResult<this, ResultType> {
+    this.isOptional = true as IsOptional;
+    return this as OptionalResult<this, ResultType>;
+  }
+}

package/src/parsing/createValueParserGenerator.ts

@@ -0,0 +1,16 @@
+import type { Parser } from './types.js';
+import { ValueParser } from './ValueParser.js';
+
+export type ValueParserGenerator<T> = () => ValueParser<T, false>;
+
+/**
+ * Creates function which generates new scalar value parser based on the specified one.
+ * @param parser - parser to use as basic.
+ * @param type - type name.
+ */
+export function createValueParserGenerator<T>(
+  parser: Parser<T>,
+  type?: string,
+): ValueParserGenerator<T> {
+  return () => new ValueParser(parser, false, type);
+}

package/src/parsing/index.ts

@@ -0,0 +1,10 @@
+export * from './ArrayValueParser.js';
+export * from './createValueParserGenerator.js';
+export * from './parseBySchema.js';
+export * from './ParseError.js';
+export * from './parsers/index.js';
+export * from './ParseSchemaFieldError.js';
+export * from './toRecord.js';
+export * from './types.js';
+export * from './unexpectedTypeError.js';
+export * from './ValueParser.js';

package/src/parsing/parseBySchema.ts

@@ -0,0 +1,65 @@
+import { ParseError } from './ParseError.js';
+import { ParseSchemaFieldError } from './ParseSchemaFieldError.js';
+import type { Parser, Schema } from './types.js';
+
+/**
+ * Parses external value by specified schema. Functions iterates over each schema field
+ * and uses getField function to get its value from the external source.
+ * @param schema - object schema.
+ * @param getField - function which gets external value by its field name.
+ */
+export function parseBySchema<T>(
+  schema: Schema<T>,
+  getField: (field: string) => unknown,
+): T {
+  const result = {} as T;
+
+  // eslint-disable-next-line guard-for-in,no-restricted-syntax
+  for (const field in schema) {
+    const definition = schema[field];
+    if (!definition) {
+      continue;
+    }
+
+    let from: string;
+    let parser: Parser<any>;
+
+    // In case, definition has "type" property, then SchemaFieldDetailed was passed.
+    if (typeof definition === 'function' || 'parse' in definition) {
+      // Otherwise we are working with either parser function or instance.
+      from = field;
+      parser = typeof definition === 'function' ? definition : definition.parse.bind(definition);
+    } else {
+      const { type } = definition;
+
+      from = definition.from || field;
+      parser = typeof type === 'function' ? type : type.parse.bind(type);
+    }
+
+    let parsedValue: unknown;
+    const originalValue = getField(from);
+
+    try {
+      parsedValue = parser(originalValue);
+    } catch (error) {
+      // If error is not instance of ParseError, we have nothing additional to do with the error.
+      if (!(error instanceof ParseError)) {
+        throw new ParseSchemaFieldError(from, { cause: error });
+      }
+
+      // Otherwise, we are going to rethrow the error with extended data.
+      throw new ParseSchemaFieldError(from, {
+        type: error.type,
+        cause: error,
+      });
+    }
+
+    if (parsedValue === undefined) {
+      continue;
+    }
+
+    (result as any)[field] = parsedValue;
+  }
+
+  return result;
+}

package/src/parsing/parsers/array.ts

@@ -0,0 +1,9 @@
+import { ArrayValueParser } from '../ArrayValueParser.js';
+
+/**
+ * Parses incoming value as an array.
+ * @param type - parser type name.
+ */
+export function array(type?: string): ArrayValueParser<unknown, false> {
+  return new ArrayValueParser((value) => value, false, type);
+}

package/src/parsing/parsers/boolean.ts

@@ -0,0 +1,22 @@
+import { createValueParserGenerator } from '../createValueParserGenerator.js';
+import { unexpectedTypeError } from '../unexpectedTypeError.js';
+
+/**
+ * Returns parser to parse value as boolean.
+ */
+export const boolean = createValueParserGenerator<boolean>((value) => {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  const asString = String(value);
+
+  if (asString === '1' || asString === 'true') {
+    return true;
+  }
+
+  if (asString === '0' || asString === 'false') {
+    return false;
+  }
+
+  throw unexpectedTypeError();
+}, 'boolean');

package/src/parsing/parsers/date.ts

@@ -0,0 +1,13 @@
+import { number } from './number.js';
+import { createValueParserGenerator } from '../createValueParserGenerator.js';
+
+const num = number();
+
+/**
+ * Returns parser to parse value as Date.
+ */
+export const date = createValueParserGenerator<Date>((value) => (
+  value instanceof Date
+    ? value
+    : new Date(num.parse(value) * 1000)
+), 'Date');

package/src/parsing/parsers/index.ts

@@ -0,0 +1,8 @@
+export * from './array.js';
+export * from './boolean.js';
+export * from './date.js';
+export * from './json.js';
+export * from './number.js';
+export * from './rgb.js';
+export * from './searchParams.js';
+export * from './string.js';

package/src/parsing/parsers/json.ts

@@ -0,0 +1,17 @@
+import { parseBySchema } from '../parseBySchema.js';
+import { toRecord } from '../toRecord.js';
+import type { Schema } from '../types.js';
+import { ValueParser } from '../ValueParser.js';
+
+/**
+ * Creates new Json parser according to passed schema.
+ * @param schema - object schema.
+ * @param type - parser type name.
+ */
+export function json<T>(schema: Schema<T>, type?: string): ValueParser<T, false> {
+  return new ValueParser((value) => {
+    const record = toRecord(value);
+
+    return parseBySchema(schema, (field) => record[field]);
+  }, false, type);
+}

package/src/parsing/parsers/number.ts

@@ -0,0 +1,21 @@
+import { createValueParserGenerator } from '../createValueParserGenerator.js';
+import { unexpectedTypeError } from '../unexpectedTypeError.js';
+
+/**
+ * Returns parser to parse value as number.
+ */
+export const number = createValueParserGenerator<number>((value) => {
+  if (typeof value === 'number') {
+    return value;
+  }
+
+  if (typeof value === 'string') {
+    const num = Number(value);
+
+    if (!Number.isNaN(num)) {
+      return num;
+    }
+  }
+
+  throw unexpectedTypeError();
+}, 'number');

package/src/parsing/parsers/rgb.ts

@@ -0,0 +1,12 @@
+import { toRGB } from '~/colors/index.js';
+import type { RGB } from '~/colors/index.js';
+
+import { string } from './string.js';
+import { createValueParserGenerator } from '../createValueParserGenerator.js';
+
+const str = string();
+
+/**
+ * Returns parser to parse value as RGB color.
+ */
+export const rgb = createValueParserGenerator<RGB>((value) => toRGB(str.parse(value)), 'rgb');

package/src/parsing/parsers/searchParams.ts

@@ -0,0 +1,24 @@
+import { parseBySchema } from '../parseBySchema.js';
+import type { Schema } from '../types.js';
+import { unexpectedTypeError } from '../unexpectedTypeError.js';
+import { ValueParser } from '../ValueParser.js';
+
+/**
+ * Creates new search params parser according to passed schema.
+ * @param schema - object schema.
+ * @param type - parser type name.
+ */
+export function searchParams<T>(schema: Schema<T>, type?: string): ValueParser<T, false> {
+  return new ValueParser((value) => {
+    if (typeof value !== 'string' && !(value instanceof URLSearchParams)) {
+      throw unexpectedTypeError();
+    }
+
+    const params = typeof value === 'string' ? new URLSearchParams(value) : value;
+
+    return parseBySchema(schema, (field) => {
+      const paramValue = params.get(field);
+      return paramValue === null ? undefined : paramValue;
+    });
+  }, false, type);
+}

package/src/parsing/parsers/string.ts

@@ -0,0 +1,12 @@
+import { createValueParserGenerator } from '../createValueParserGenerator.js';
+import { unexpectedTypeError } from '../unexpectedTypeError.js';
+
+/**
+ * Returns parser to parse value as string.
+ */
+export const string = createValueParserGenerator<string>((value) => {
+  if (typeof value === 'string' || typeof value === 'number') {
+    return value.toString();
+  }
+  throw unexpectedTypeError();
+}, 'string');

package/src/parsing/toRecord.ts

@@ -0,0 +1,27 @@
+import { unexpectedTypeError } from './unexpectedTypeError.js';
+
+/**
+ * Converts value to record.
+ * @param value - value to convert.
+ * @throws {Error} Value passed as a string does not represent JSON object.
+ * @throws {Error} Value is not convertable.
+ */
+export function toRecord(value: unknown): Record<string, unknown> {
+  let formattedValue: any = value;
+
+  // Convert value to JSON in case, it is string. We expect value to be JSON string.
+  if (typeof formattedValue === 'string') {
+    formattedValue = JSON.parse(formattedValue);
+  }
+
+  // We expect json to be usual object.
+  if (
+    typeof formattedValue !== 'object'
+    || formattedValue === null
+    || Array.isArray(formattedValue)
+  ) {
+    throw unexpectedTypeError();
+  }
+
+  return formattedValue;
+}

package/src/parsing/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Represents any known parser.
+ */
+export type AnyParser<T> = Parser<T> | { parse: Parser<T> };
+
+/**
+ * Detailed schema field options.
+ */
+export interface SchemaFieldDetailed<T> {
+  /**
+   * Source property name.
+   * @default Original property name in schema.
+   */
+  from?: string;
+
+  /**
+   * Function which should parse incoming value and return expected type.
+   */
+  type: AnyParser<T>;
+}
+
+/**
+ * Function which parses incoming value.
+ */
+export type Parser<T> = (value: unknown) => T;
+
+/**
+ * Object schema definition.
+ */
+export type Schema<T> = {
+  [K in keyof T]: AnyParser<T[K]> | SchemaFieldDetailed<T[K]>;
+};

package/src/parsing/unexpectedTypeError.ts

@@ -0,0 +1,6 @@
+/**
+ * Creates instance of TypeError stating, that value has unexpected type.
+ */
+export function unexpectedTypeError(): TypeError {
+  return new TypeError('Value has unexpected type');
+}

package/src/{components/Popup → popup}/Popup.ts

@@ -1,13 +1,18 @@
-import { EventEmitter } from '@tma.js/event-emitter';
-import { postEvent as defaultPostEvent, request, type PostEvent } from '@tma.js/bridge';
+import {
+  type PostEvent,
+  postEvent as defaultPostEvent,
+  request,
+} from '~/bridge/index.js';
+import { EventEmitter } from '~/event-emitter/index.js';
+import { State } from '~/state/index.js';
+import {
+  createSupportsFunc,
+  type SupportsFunc,
+} from '~/supports/index.js';
+import type { Version } from '~/version/index.js';
 
-import type { Version } from '@tma.js/utils';
-
-import { preparePopupParams } from './utils.js';
-import { createSupportsFunc, type SupportsFunc } from '../../supports.js';
-import { State } from '../../state/index.js';
-
-import type { PopupParams, PopupEvents, PopupState } from './types.js';
+import { preparePopupParams } from './preparePopupParams.js';
+import type { OpenPopupOptions, PopupEvents, PopupState } from './types.js';
 
 /**
  * Controls currently displayed application popup. It allows developers to
@@ -18,13 +23,20 @@ export class Popup {
 
   private readonly state: State<PopupState>;
 
-  constructor(version: Version, private readonly postEvent: PostEvent = defaultPostEvent) {
+  constructor(
+    version: Version,
+    private readonly postEvent: PostEvent = defaultPostEvent,
+  ) {
     this.state = new State({ isOpened: false }, this.ee);
     this.supports = createSupportsFunc(version, { open: 'web_app_open_popup' });
   }
 
+  private set isOpened(value) {
+    this.state.set('isOpened', value);
+  }
+
   /**
-   * Shows whether popup is currently opened.
+   * True if popup is currently opened.
    */
   get isOpened(): boolean {
     return this.state.get('isOpened');
@@ -33,12 +45,12 @@ export class Popup {
   /**
    * Adds new event listener.
    */
-  on: typeof this.ee.on = this.ee.on.bind(this.ee);
+  on = this.ee.on.bind(this.ee);
 
   /**
    * Removes event listener.
    */
-  off: typeof this.ee.off = this.ee.off.bind(this.ee);
+  off = this.ee.off.bind(this.ee);
 
   /**
    * A method that shows a native popup described by the `params` argument.
@@ -50,28 +62,26 @@ export class Popup {
    *
    * FIXME: In desktop, this function may work incorrectly.
    *  Issue: https://github.com/Telegram-Mini-Apps/tma.js/issues/7
-   * @param params - popup parameters.
+   * @param options - popup parameters.
    * @throws {Error} Popup is already opened.
    */
-  async open(params: PopupParams): Promise<string | null> {
+  open(options: OpenPopupOptions): Promise<string | null> {
     if (this.isOpened) {
       throw new Error('Popup is already opened.');
     }
 
-    this.state.set('isOpened', true);
-
-    try {
-      const { button_id: buttonId = null } = await request(
-        'web_app_open_popup',
-        preparePopupParams(params),
-        'popup_closed',
-        { postEvent: this.postEvent },
-      );
+    this.isOpened = true;
 
-      return buttonId;
-    } finally {
-      this.state.set('isOpened', false);
-    }
+    return request(
+      'web_app_open_popup',
+      preparePopupParams(options),
+      'popup_closed',
+      { postEvent: this.postEvent },
+    )
+      .then(({ button_id = null }) => button_id)
+      .finally(() => {
+        this.isOpened = false;
+      });
   }
 
   /**

package/src/popup/index.ts

@@ -0,0 +1,2 @@
+export * from './Popup.js';
+export * from './types.js';

package/src/{components/Popup/utils.ts → popup/preparePopupParams.ts}

@@ -1,12 +1,12 @@
-import type { PopupButton, PopupParams as BridgePopupParams } from '@tma.js/bridge';
+import type { PopupButton, PopupParams as BridgePopupParams } from '~/bridge/index.js';
 
-import type { PopupParams } from './types.js';
+import type { OpenPopupOptions } from './types.js';
 
 /**
  * Prepares popup parameters before sending them to native app.
  * @param params - popup parameters.
  */
-export function preparePopupParams(params: PopupParams): BridgePopupParams {
+export function preparePopupParams(params: OpenPopupOptions): BridgePopupParams {
   const message = params.message.trim();
   const title = (params.title || '').trim();
   const buttons = params.buttons || [];

package/src/{components/Popup → popup}/types.ts

@@ -1,4 +1,4 @@
-import type { StateEvents } from '../../state/index.js';
+import type { StateEvents } from '~/state/index.js';
 
 export interface PopupState {
   isOpened: boolean;
@@ -14,7 +14,7 @@ export type PopupEventListener<E extends PopupEventName> = PopupEvents[E];
  * This object describes the native popup.
  * @see https://core.telegram.org/bots/webapps#popupparams
  */
-export interface PopupParams {
+export interface OpenPopupOptions {
   /**
    * The text to be displayed in the popup title, 0-64 characters.
    * @default ""
@@ -30,14 +30,14 @@ export interface PopupParams {
    * List of buttons to be displayed in the popup, 1-3 buttons.
    * @default [{type: 'close'}]
    */
-  buttons?: PopupButton[]
+  buttons?: OpenPopupOptionsButton[];
 }
 
 /**
  * This object describes the native popup button.
  * @see https://core.telegram.org/bots/webapps#popupbutton
  */
-export type PopupButton = {
+export type OpenPopupOptionsButton = {
   /**
    * Identifier of the button, 0-64 characters.
    * @default ""