@tma.js/sdk 1.5.3 → 2.0.1

package/dist/dts/misc/createComponentInitFn/types.d.ts

@@ -0,0 +1,47 @@
+import { PostEvent } from '../../bridge/methods/postEvent.js';
+import { LaunchParamName, PickLaunchParams } from '../../launch-params/types.js';
+import { CreateRequestIdFn } from '../../request-id/types.js';
+import { StorageKey, StorageValue } from '../../storage/storage.js';
+import { If, IsNever } from '../../types/index.js';
+
+/**
+ * Object, which supports tracking its state changes.
+ */
+export interface WithOnChange<State> {
+    on(event: 'change', listener: (state: State) => void): void;
+}
+type LaunchParamsWithState<LP extends LaunchParamName, State> = PickLaunchParams<LP> & If<IsNever<State>, {}, {
+    state?: State;
+}>;
+export type SSROptions<LP extends LaunchParamName, State> = LaunchParamsWithState<LP, State>;
+/**
+ * Options passed to a component factory.
+ */
+export type FactoryOptions<LP extends LaunchParamName, State> = LaunchParamsWithState<LP, State> & {
+    postEvent: PostEvent;
+    createRequestId: CreateRequestIdFn;
+};
+export interface Factory<LP extends LaunchParamName, R, State> {
+    /**
+     * Creates new component instance.
+     * @param options - factory options.
+     */
+    (options: FactoryOptions<LP, State>): R;
+}
+export interface FactoryStatic<LP extends LaunchParamName, R> extends Factory<LP, R, never> {
+}
+export interface FactoryDynamic<LP extends LaunchParamName, R, SK extends StorageKey> extends Factory<LP, R, StorageValue<SK>> {
+}
+export interface InitComponentFn<LP extends LaunchParamName, Result, State> {
+    /**
+     * Initializes new component instance.
+     * @param options - initialization options.
+     */
+    (options?: {
+        /**
+         * Options, applicable only to SSR mode.
+         */
+        ssr?: SSROptions<LP, State>;
+    }): Result;
+}
+export {};

package/dist/dts/misc/createSingleton.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Creates resettable singleton. We mostly need it for test purposes.
+ * @param create - function which creates singleton entity.
+ * @param onReset - function which will be called in case, singleton was reset.
+ */
+export declare function createSingleton<T>(create: (reset: () => void) => T, onReset?: (entity: T) => void): [
+    /**
+     * Returns singleton entity.
+     */
+    get: () => T,
+    /**
+     * Resets last stored entity.
+     */
+    reset: () => void
+];

package/dist/dts/misc/objectFromKeys.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Creates object with specified keys and value.
+ * @param keys - object keys.
+ * @param value - keys value.
+ */
+export declare function objectFromKeys<K extends string, V>(keys: K[], value: V): Record<K, V>;

package/dist/dts/navigation/BasicNavigator/BasicNavigator.d.ts

@@ -0,0 +1,118 @@
+import { PostEvent } from '../../bridge/methods/postEvent.js';
+import { EventEmitter } from '../../events/event-emitter/EventEmitter.js';
+import { BasicNavigatorAnyHistoryItem, BasicNavigatorEvents, BasicNavigatorHistoryItem } from './types.js';
+
+type Emitter<Params> = EventEmitter<BasicNavigatorEvents<Params>>;
+export declare class BasicNavigator<Params = {}> {
+    /**
+     * Currently active history item.
+     */
+    private _index;
+    /**
+     * Function to call Mini Apps methods.
+     * @default Global `postEvent` function.
+     */
+    private readonly postEvent;
+    /**
+     * Navigation history.
+     */
+    readonly history: Readonly<BasicNavigatorHistoryItem<Params>>[];
+    private readonly ee;
+    constructor(
+    /**
+     * Navigation history.
+     */
+    history: readonly BasicNavigatorAnyHistoryItem<Params>[], 
+    /**
+     * Currently active history item.
+     */
+    _index: number, 
+    /**
+     * Function to call Mini Apps methods.
+     * @default Global `postEvent` function.
+     */
+    postEvent?: PostEvent);
+    /**
+     * True, if current navigator is currently attached.
+     */
+    private attached;
+    /**
+     * Allows this navigator to control the `BackButton` visibility state. It also tracks the
+     * `BackButton` clicks and calls the `back` method.
+     */
+    attach(): void;
+    /**
+     * Goes to the previous history item.
+     */
+    back: () => void;
+    /**
+     * Currently active history item.
+     */
+    get current(): Readonly<BasicNavigatorHistoryItem<Params>>;
+    /**
+     * Prevents current navigator from controlling the BackButton visibility state.
+     */
+    detach(): void;
+    /**
+     * Goes to the next history item.
+     */
+    forward(): void;
+    /**
+     * Changes currently active history item index by the specified delta. This method doesn't
+     * change index in case, the updated index points to the non-existing history item. This behavior
+     * is preserved until the `fit` argument is specified.
+     * @param delta - index delta.
+     * @param fit - cuts the delta argument to fit the bounds `[0, history.length - 1]`.
+     */
+    go(delta: number, fit?: boolean): void;
+    /**
+     * Goes to the specified index. Method does nothing in case, passed index is out of bounds.
+     *
+     * If "fit" option was specified and index is out of bounds, it will be cut to the nearest
+     * bound.
+     * @param index - target index.
+     * @param fit - cuts the index argument to fit the bounds `[0, history.length - 1]`.
+     */
+    goTo(index: number, fit?: boolean): void;
+    /**
+     * True if navigator has items before the current item.
+     */
+    get hasPrev(): boolean;
+    /**
+     * True if navigator has items after the current item.
+     */
+    get hasNext(): boolean;
+    /**
+     * Currently active history item index.
+     */
+    get index(): number;
+    /**
+     * Adds new event listener.
+     */
+    on: Emitter<Params>['on'];
+    /**
+     * Removes event listener.
+     */
+    off: Emitter<Params>['off'];
+    /**
+     * Adds a new history item removing all after the current one.
+     * @param item - item to add.
+     */
+    push(item: BasicNavigatorAnyHistoryItem<Params>): void;
+    /**
+     * Replaces the current history item.
+     * @param item - item to replace the current item with.
+     */
+    replace(item: BasicNavigatorAnyHistoryItem<Params>): void;
+    /**
+     * Sets history item by the specified index.
+     * @param index - history item index to replace.
+     * @param historyItem - history item to set.
+     */
+    private replaceAndMove;
+    /**
+     * Actualizes the `BackButton` visibility state.
+     */
+    private sync;
+}
+export {};

package/dist/dts/navigation/BasicNavigator/prepareItem.d.ts

@@ -0,0 +1,8 @@
+import { BasicNavigatorAnyHistoryItem, BasicNavigatorHistoryItem } from './types.js';
+
+/**
+ * Converts any known history item type to the local one.
+ * @param item - history item presented as a string or an object.
+ * @param relativePathname - relative pathname.
+ */
+export declare function prepareItem<Params>(item: BasicNavigatorAnyHistoryItem<Params>, relativePathname: string): Readonly<BasicNavigatorHistoryItem<Params>>;

package/dist/dts/navigation/BasicNavigator/types.d.ts

@@ -0,0 +1,37 @@
+import { BasicNavigator } from './BasicNavigator.js';
+
+/**
+ * History item used by the `BasicNavigator`.
+ */
+export interface BasicNavigatorHistoryItem<Params> {
+    id: string;
+    pathname: string;
+    params?: Params;
+}
+/**
+ * History item used by the `BasicNavigator` methods.
+ */
+export type BasicNavigatorAnyHistoryItem<Params> = string | Partial<BasicNavigatorHistoryItem<Params>>;
+/**
+ * Events supported by `BasicNavigator`.
+ */
+export interface BasicNavigatorEvents<Params> {
+    change: {
+        /**
+         * Navigator instance.
+         */
+        navigator: BasicNavigator<Params>;
+        /**
+         * Navigator cursor delta.
+         */
+        delta: number;
+        /**
+         * Previous active history item.
+         */
+        from: BasicNavigatorHistoryItem<Params>;
+        /**
+         * Currently active history item.
+         */
+        to: BasicNavigatorHistoryItem<Params>;
+    };
+}

package/dist/dts/navigation/BrowserNavigator/BrowserNavigator.d.ts

@@ -0,0 +1,198 @@
+import { EventEmitter } from '../../events/event-emitter/EventEmitter.js';
+import { BrowserNavigatorAnyHistoryItem, BrowserNavigatorConOptions, BrowserNavigatorEvents, BrowserNavigatorHashMode, BrowserNavigatorHistoryItem, URLLike } from './types.js';
+
+type Emitter<State> = EventEmitter<BrowserNavigatorEvents<State>>;
+export declare class BrowserNavigator<State = {}> {
+    private readonly navigator;
+    private readonly ee;
+    readonly hashMode?: BrowserNavigatorHashMode;
+    readonly base: string;
+    constructor(
+    /**
+     * Navigation history.
+     */
+    history: readonly BrowserNavigatorAnyHistoryItem<State>[], 
+    /**
+     * Currently active history item index.
+     */
+    index: number, { postEvent, hashMode, base }?: BrowserNavigatorConOptions);
+    /**
+     * Shows whether the navigator is currently attached to the browser history.
+     */
+    private attached;
+    /**
+     * Attaches current navigator to the browser history allowing navigator to manipulate it.
+     */
+    attach(): Promise<void>;
+    /**
+     * Goes back in history by 1.
+     */
+    back(): void;
+    /**
+     * Detaches current navigator from the browser history.
+     */
+    detach(): void;
+    /**
+     * Goes forward in history.
+     */
+    forward(): void;
+    /**
+     * Current history cursor.
+     */
+    get index(): number;
+    /**
+     * Current history item identifier.
+     */
+    get id(): string;
+    /**
+     * Changes currently active history item index by the specified delta. This method doesn't
+     * change index in case, the updated index points to the non-existing history item. This behavior
+     * is preserved until the `fit` argument is specified.
+     * @param delta - index delta.
+     * @param fit - cuts the delta argument to fit the bounds `[0, history.length - 1]`.
+     */
+    go(delta: number, fit?: boolean): void;
+    /**
+     * Goes to the specified index. Method does nothing in case, passed index is out of bounds.
+     *
+     * If "fit" option was specified and index is out of bounds, it will be cut to the nearest
+     * bound.
+     * @param index - target index.
+     * @param fit - cuts the index argument to fit the bounds `[0, history.length - 1]`.
+     */
+    goTo(index: number, fit?: boolean): void;
+    /**
+     * Current history item hash.
+     * @see URL.hash
+     * @example
+     * "", "#my-hash"
+     */
+    get hash(): string;
+    /**
+     * True if navigator has items before the current item.
+     */
+    get hasPrev(): boolean;
+    /**
+     * True if navigator has items after the current item.
+     */
+    get hasNext(): boolean;
+    /**
+     * Navigation history.
+     */
+    get history(): BrowserNavigatorHistoryItem<State>[];
+    /**
+     * Handles the window "popstate" event.
+     * @param state - event state.
+     */
+    private onPopState;
+    /**
+     * Underlying navigator change event listener.
+     */
+    private onNavigatorChange;
+    /**
+     * Adds new event listener.
+     */
+    on: Emitter<State>['on'];
+    /**
+     * Removes event listener.
+     */
+    off: Emitter<State>['off'];
+    /**
+     * Path, including pathname, search and hash.
+     * @example Pathname only.
+     * "/pathname"
+     * @example Pathname + search.
+     * "/pathname?search"
+     * @example Pathname + hash.
+     * "/pathname#hash"
+     * @example Pathname + search + hash.
+     * "/pathname?search#hash"
+     */
+    get path(): string;
+    /**
+     * Current pathname. Always starts with the slash.
+     * @see URL.pathname
+     * @example
+     * "/", "/abc"
+     */
+    get pathname(): string;
+    /**
+     * Depending on the current navigation type, parses incoming path and returns it presented as
+     * an object. In other words, this method parses the passed path and returns object, describing
+     * how the navigator "sees" it.
+     *
+     * @example Hash mode is omitted.
+     * parsePath('/abc?a=1#hash');
+     * // { pathname: '/abc', search: '?a=1', hash: '#hash' }
+     * parsePath('http://example.com/abc?a=1#hash');
+     * // { pathname: '/abc', search: '?a=1', hash: '#hash' }
+     *
+     * @example Hash mode is enabled.
+     * parsePath('/abc?a=1#tma?is=cool#yeah');
+     * // { pathname: '/tma', search: '?is=cool', hash: '#yeah' }
+     * parsePath('http://example.com/abc?a=1#tma?is=cool#yeah');
+     * // { pathname: '/tma', search: '?is=cool', hash: '#yeah' }
+     */
+    parsePath(path: string | URL): URLLike;
+    /**
+     * Pushes new history item. Method replaces all entries after the current one with the one
+     * being pushed. Take a note, that passed item is always relative. In case, you want to use
+     * it as an absolute one, use the "/" prefix. Example: "/absolute", { pathname: "/absolute" }.
+     *
+     * To create a final path, navigator uses a method, used in the URL class constructor, resolving
+     * a path based on the current one.
+     * @param path - entry path.
+     * @param state - entry state.
+     *
+     * @example Pushing an absolute path.
+     * push("/absolute"); // "/absolute"
+     *
+     * @example Pushing a relative path.
+     * push("relative"); // "/home/root" -> "/home/relative"
+     *
+     * @example Pushing query parameters.
+     * push("/absolute?my-param=1"); // "/home/root" -> "/absolute?my-param=1"
+     * push("relative?my-param=1"); // "/home/root" -> "/home/relative?my-param=1"
+     * push("?my-param=1"); // "/home" -> "/home?my-param=1"
+     *
+     * @example Pushing hash.
+     * push("#my-hash"); // "/home" -> "/home#my-hash"
+     * push("relative#my-hash"); // "/home/root" -> "/home/relative#my-hash"
+     *
+     * @example Pushing state.
+     * push("", { state: 'my-state' }); "/home/root" -> "/home/root"
+     * push({ state: 'my-state' }); "/home/root" -> "/home/root"
+     */
+    push(path: string, state?: State): void;
+    push(item: BrowserNavigatorAnyHistoryItem<State>): void;
+    /**
+     * Replaces the current history item. Has the same logic as the `push` method.
+     * @param path - entry path.
+     * @param state - entry state.
+     * @see push
+     */
+    replace(path: string, state?: State): void;
+    replace(item: BrowserNavigatorAnyHistoryItem<State>): void;
+    /**
+     * Combines the navigator `base` property with the passed path data applying the navigator
+     * navigation mode.
+     * @param value - path presented as string or URLLike.
+     */
+    renderPath(value: string | URLLike): string;
+    /**
+     * Synchronizes current navigator state with browser history.
+     */
+    private syncHistory;
+    /**
+     * Current query parameters.
+     * @see URL.search
+     * @example
+     * "", "?", "?a=1"
+     */
+    get search(): string;
+    /**
+     * Current history item state.
+     */
+    get state(): State | undefined;
+}
+export {};

package/dist/dts/navigation/BrowserNavigator/basicItemToBrowser.d.ts

@@ -0,0 +1,7 @@
+import { BasicNavigatorHistoryItem } from '../BasicNavigator/types.js';
+import { BrowserNavigatorHistoryItem, BrowserNavigatorHistoryItemParams } from './types.js';
+
+/**
+ * Converts basic navigator entry to browser navigator entry.
+ */
+export declare function basicItemToBrowser<State>({ params, ...rest }: BasicNavigatorHistoryItem<BrowserNavigatorHistoryItemParams<State>>): BrowserNavigatorHistoryItem<State>;

package/dist/dts/navigation/BrowserNavigator/createBrowserNavigatorFromLocation.d.ts

@@ -0,0 +1,4 @@
+import { BrowserNavigator } from './BrowserNavigator.js';
+import { BrowserNavigatorConOptions } from './types.js';
+
+export declare function createBrowserNavigatorFromLocation<State>(options?: BrowserNavigatorConOptions): BrowserNavigator<State>;

package/dist/dts/navigation/BrowserNavigator/prepareItem.d.ts

@@ -0,0 +1,25 @@
+import { BrowserNavigatorAnyHistoryItem } from './types.js';
+
+interface PrepareItemResult<State> {
+    id?: string;
+    pathname: string;
+    params: {
+        hash: string;
+        search: string;
+        state?: State;
+    };
+}
+/**
+ * Converts a path, presented as a string to a basic navigator appropriate form.
+ * @param path - full path.
+ * @param relativePath - relative path.
+ * @param state - history item state.
+ */
+export declare function prepareItem<State>(path: string, relativePath: string, state?: State): PrepareItemResult<State>;
+/**
+ * Converts a path, presented as an object to a basic navigator appropriate form.
+ * @param item - history item data.
+ * @param relativePath - relative path.
+ */
+export declare function prepareItem<State>(item: BrowserNavigatorAnyHistoryItem<State>, relativePath: string): PrepareItemResult<State>;
+export {};

package/dist/dts/navigation/BrowserNavigator/types.d.ts

@@ -0,0 +1,63 @@
+import { PostEvent } from '../../bridge/methods/postEvent.js';
+import { BrowserNavigator } from './BrowserNavigator.js';
+
+/**
+ * Minimal set of properties we are working with in this library.
+ */
+export interface URLLike extends Pick<URL, 'pathname' | 'search' | 'hash'> {
+}
+export interface BrowserNavigatorConOptions {
+    /**
+     * Base navigator URL.
+     * @default ""
+     */
+    base?: string;
+    /**
+     * Hash navigation mode. Omit, if non-hash mode is required.
+     */
+    hashMode?: BrowserNavigatorHashMode;
+    /**
+     * Function to call Mini Apps methods.
+     * @default Global postEvent function.
+     */
+    postEvent?: PostEvent;
+}
+export interface BrowserNavigatorHistoryItemParams<State> extends Pick<URLLike, 'search' | 'hash'> {
+    state?: State;
+}
+export interface BrowserNavigatorHistoryItem<State> extends URLLike {
+    id: string;
+    state?: State;
+}
+export type BrowserNavigatorAnyHistoryItem<State> = string | Partial<BrowserNavigatorHistoryItem<State>>;
+/**
+ * Hash navigation mode.
+ * @example 'default'
+ * '#pathname?search'
+ * @example 'slash'
+ * '#/pathname?search'
+ */
+export type BrowserNavigatorHashMode = 'default' | 'slash';
+/**
+ * Events supported by `BrowserNavigator`.
+ */
+export interface BrowserNavigatorEvents<State> {
+    change: {
+        /**
+         * Navigator instance.
+         */
+        navigator: BrowserNavigator<State>;
+        /**
+         * Navigator cursor delta.
+         */
+        delta: number;
+        /**
+         * Previous active history item.
+         */
+        from: BrowserNavigatorHistoryItem<State>;
+        /**
+         * Currently active history item.
+         */
+        to: BrowserNavigatorHistoryItem<State>;
+    };
+}

package/dist/dts/navigation/createSafeURL.d.ts

@@ -0,0 +1,7 @@
+import { URLLike } from './BrowserNavigator/types.js';
+
+/**
+ * Safely creates new instance of URL with some predefined protocol and hostname.
+ * @param urlOrPath - URL instance or path.
+ */
+export declare function createSafeURL(urlOrPath: string | Partial<URLLike>): URL;

package/dist/dts/navigation/getHash.d.ts

@@ -1,6 +1,7 @@
 /**
- * Returns string after first met "#" symbol.
  * @param value - string to take hash part from.
+ * @returns String after the first met "#" symbol. In case, value doesn't contain hashtag, the
+ * function will return null.
  *
  * @example No hash.
  * getHash('/path'); // null

package/dist/dts/navigation/getPathname.d.ts

@@ -0,0 +1,7 @@
+import { URLLike } from './BrowserNavigator/types.js';
+
+/**
+ * Extracts pathname from the value.
+ * @param value - source value.
+ */
+export declare function getPathname(value: string | Partial<URLLike>): string;

package/dist/dts/navigation/initNavigator.d.ts

@@ -0,0 +1,9 @@
+import { BrowserNavigatorConOptions } from './BrowserNavigator/types.js';
+import { BrowserNavigator } from './BrowserNavigator/BrowserNavigator.js';
+
+/**
+ * Initializes a standard Mini Apps navigator.
+ * @param sessionStorageKey - session storage key, containing the navigator state.
+ * @param options - additional BrowserNavigator options.
+ */
+export declare function initNavigator<State>(sessionStorageKey: string, options?: BrowserNavigatorConOptions): BrowserNavigator<State>;

package/dist/dts/navigation/urlToPath.d.ts

@@ -0,0 +1,7 @@
+import { URLLike } from './BrowserNavigator/types.js';
+
+/**
+ * Extracts path part from a URL.
+ * @param urlOrPath - URL instance or path.
+ */
+export declare function urlToPath(urlOrPath: string | Partial<URLLike>): string;

package/dist/dts/parsing/ArrayParser/ArrayParser.d.ts

@@ -0,0 +1,17 @@
+import { ValueParser } from '../ValueParser/ValueParser.js';
+import { ArrayParserOfResult } from '../ArrayParser/types.js';
+import { AnyParser } from '../types.js';
+import { ValueParserParseResult } from '../ValueParser/types.js';
+
+export declare class ArrayParser<ItemType, IsOptional extends boolean> extends ValueParser<unknown[], IsOptional> {
+    private itemParser;
+    constructor(itemParser: AnyParser<ItemType>, isOptional: IsOptional, type?: string);
+    /**
+     * Attempts to parse passed value
+     * @param value - value to parse.
+     * @throws {SDKError} ERR_PARSE
+     * @see ERR_PARSE
+     */
+    parse(value: unknown): ValueParserParseResult<ItemType[], IsOptional>;
+    of<Item>(itemParser: AnyParser<Item>): ArrayParserOfResult<this, Item, IsOptional>;
+}

package/dist/dts/parsing/ArrayParser/types.d.ts

@@ -0,0 +1,12 @@
+import { AnyParser } from '../types.js';
+import { ValueParserOverrides } from '../ValueParser/types.js';
+
+export type ArrayParserOfResult<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>): ArrayParserOfResult<BaseClass, Item, IsOptional>;
+}
+export type ArrayParserType<BaseClass, ItemType, IsOptional extends boolean> = Omit<BaseClass, keyof ArrayParserOverrides<any, any, any>> & ArrayParserOverrides<BaseClass, ItemType, IsOptional>;

package/dist/dts/parsing/ValueParser/ValueParser.d.ts

@@ -0,0 +1,17 @@
+import { Parser } from '../types.js';
+import { ValueParserOptionalResult, ValueParserParseResult } from './types.js';
+
+export declare class ValueParser<ResultType, IsOptional extends boolean> {
+    protected parser: Parser<ResultType>;
+    protected isOptional: IsOptional;
+    protected type?: string | undefined;
+    constructor(parser: Parser<ResultType>, isOptional: IsOptional, type?: string | undefined);
+    /**
+     * Attempts to parse passed value
+     * @param value - value to parse.
+     * @throws {SDKError} ERR_PARSE
+     * @see ERR_PARSE
+     */
+    parse(value: unknown): ValueParserParseResult<ResultType, IsOptional>;
+    optional(): ValueParserOptionalResult<this, ResultType>;
+}