@tma.js/sdk 0.13.3 → 1.0.1

package/src/navigation/HashNavigator/HashNavigator.ts

@@ -0,0 +1,220 @@
+import { off, on, postEvent } from '~/bridge/index.js';
+import { EventEmitter } from '~/event-emitter/index.js';
+
+import { drop } from './drop.js';
+import { go } from './go.js';
+import type {
+  HashNavigatorEventsMap,
+  HashNavigatorOptions,
+} from './types.js';
+import { Navigator } from '../Navigator/index.js';
+import type {
+  NavigationEntry,
+  NavigatorConEntry,
+  PerformGoOptions,
+  PerformPushOptions,
+  PerformReplaceOptions,
+} from '../Navigator/types.js';
+
+const CURSOR_VOID = 0;
+const CURSOR_BACK = 1;
+const CURSOR_FORWARD = 2;
+
+export class HashNavigator extends Navigator<Promise<void>> {
+  /**
+   * Creates navigator from current window location hash.
+   * @param options - options passed to constructor.
+   */
+  static fromLocation(options?: HashNavigatorOptions): HashNavigator {
+    const {
+      search,
+      pathname,
+      hash,
+    } = new URL(
+      window.location.hash.slice(1),
+      window.location.href,
+    );
+
+    return new HashNavigator([{ search, pathname, hash }], 0, options);
+  }
+
+  private readonly ee = new EventEmitter<HashNavigatorEventsMap>();
+
+  private attached = false;
+
+  constructor(
+    entries: NavigatorConEntry[],
+    entriesCursor: number,
+    options: HashNavigatorOptions = {},
+  ) {
+    super(entries, entriesCursor, {
+      ...options,
+      loggerPrefix: 'HashNavigator',
+    });
+  }
+
+  /**
+   * Handles window "popstate" event.
+   * @param state - event state.
+   */
+  private onPopState = async ({ state }: PopStateEvent) => {
+    this.logger.log('"popstate" event received. State:', state);
+
+    // In case state is null, we recognize current event as occurring whenever user clicks
+    // any anchor.
+    // TODO: Should we do it?
+    if (state === null) {
+      return this.push(window.location.hash.slice(1));
+    }
+
+    // There is only one case when state can be CURSOR_VOID - when history contains
+    // only one element. In this case, we should return user to the current history element.
+    if (state === CURSOR_VOID) {
+      this.logger.log('Void reached. Moving history forward');
+      window.history.forward();
+      return;
+    }
+
+    // User pressed Back button.
+    if (state === CURSOR_BACK) {
+      return this.back();
+    }
+
+    // User pressed Forward button.
+    if (state === CURSOR_FORWARD) {
+      return this.forward();
+    }
+  };
+
+  protected async performGo(options: PerformGoOptions): Promise<void> {
+    if (!options.updated) {
+      return;
+    }
+
+    if (this.attached) {
+      await this.syncHistory();
+    }
+
+    this.emitChanged(options.before, options.after);
+  }
+
+  protected async performPush({ before, after }: PerformPushOptions): Promise<void> {
+    if (this.attached) {
+      await this.syncHistory();
+    }
+
+    this.emitChanged(before, after);
+  }
+
+  protected async performReplace(options: PerformReplaceOptions): Promise<void> {
+    if (!options.updated) {
+      return;
+    }
+
+    if (this.attached) {
+      window.history.replaceState(null, '', `#${this.path}`);
+    }
+
+    this.emitChanged(options.before, options.after);
+  }
+
+  /**
+   * Synchronizes current navigator state with browser history.
+   */
+  private async syncHistory(): Promise<void> {
+    // Remove history change event listener to get rid of side effects related to possible
+    // future calls of history.go.
+    window.removeEventListener('popstate', this.onPopState);
+
+    const hash = `#${this.path}`;
+
+    // Drop the browser history and work with the clean one.
+    await drop();
+
+    // Actualize Telegram Mini Apps BackButton state.
+    postEvent('web_app_setup_back_button', { is_visible: this.canGoBack });
+
+    if (this.canGoBack && this.canGoForward) {
+      // We have both previous and next elements. History should be:
+      // [back, *current*, forward]
+      this.logger.log('Setting up history: [<-, *, ->]');
+
+      window.history.replaceState(CURSOR_BACK, '');
+      window.history.pushState(null, '', hash);
+      window.history.pushState(CURSOR_FORWARD, '');
+
+      await go(-1);
+    } else if (this.canGoBack) {
+      // We have only previous element. History should be:
+      // [back, *current*]
+      this.logger.log('Setting up history: [<-, *]');
+
+      window.history.replaceState(CURSOR_BACK, '');
+      window.history.pushState(null, '', hash);
+    } else if (this.canGoForward) {
+      // We have only next element. History should be:
+      // [*current*, forward]
+      this.logger.log('Setting up history: [*, ->]');
+
+      window.history.replaceState(null, hash);
+      window.history.pushState(CURSOR_FORWARD, '');
+
+      await go(-1);
+    } else {
+      // We have no back and next elements. History should be:
+      // [void, *current*]
+      this.logger.log('Setting up history: [~, *]');
+
+      window.history.replaceState(CURSOR_VOID, '');
+      window.history.pushState(null, '', hash);
+    }
+
+    window.addEventListener('popstate', this.onPopState);
+  }
+
+  private emitChanged(from: NavigationEntry, to: NavigationEntry) {
+    this.ee.emit('change', {
+      navigator: this,
+      from,
+      to,
+    });
+  }
+
+  /**
+   * Attaches current navigator to the browser history allowing navigator to manipulate it.
+   */
+  async attach(): Promise<void> {
+    if (this.attached) {
+      return;
+    }
+    this.logger.log('Attaching', this);
+    this.attached = true;
+    on('back_button_pressed', this.back);
+    return this.syncHistory();
+  }
+
+  back = () => super.back();
+
+  /**
+   * Detaches current navigator from the browser history.
+   */
+  detach() {
+    if (!this.attached) {
+      return;
+    }
+    this.logger.log('Detaching', this);
+    this.attached = false;
+    window.removeEventListener('popstate', this.onPopState);
+    off('back_button_pressed', this.back);
+  }
+
+  /**
+   * Adds new event listener.
+   */
+  on = this.ee.on.bind(this.ee);
+
+  /**
+   * Removes event listener.
+   */
+  off = this.ee.off.bind(this.ee);
+}

package/src/navigation/HashNavigator/drop.ts

@@ -0,0 +1,36 @@
+import { go } from './go.js';
+
+/**
+ * Drops current browser history switching browser history cursor to the first one entry.
+ */
+export async function drop(): Promise<void> {
+  if (window.history.length <= 1) {
+    return;
+  }
+
+  // Push empty state to cut states we have no access to.
+  window.history.pushState(null, '');
+
+  // By this line of code we cover the most recent case, when application is opened in WebView,
+  // but not in iframe. Applications opened in WebView have simple browser history containing
+  // only entries belonging to the current web application.
+  const goPerformed = await go(1 - window.history.length);
+  if (goPerformed) {
+    return;
+  }
+
+  // Nevertheless, iframe works a bit different in context of browser history. Calling
+  // window.history.length in iframe will return browser history information related to the
+  // external web environment too (e.g. browser tab). So, iframe shares the browser history with
+  // the external application, but has no access to its history entries. Calling window.history.go
+  // pointing out to the entry belonging to the external application will have no impact, so the
+  // previous idea with go(1 - ...) will not work.
+  //
+  // This is the reason why we iteratively call go(-1) to meet the entry which is recognized as
+  // the initial one for the current iframe.
+  let shouldGoBack = await go(-1);
+  while (shouldGoBack) {
+    // eslint-disable-next-line no-await-in-loop
+    shouldGoBack = await go(-1);
+  }
+}

package/src/navigation/HashNavigator/go.ts

@@ -0,0 +1,28 @@
+/**
+ * Performs window.history.go operation waiting for it to be completed.
+ * @param delta - history change delta.
+ */
+export async function go(delta: number): Promise<boolean> {
+  if (delta === 0) {
+    return true;
+  }
+
+  // We expect popstate event to occur during some time. Yeah, this seems tricky and not stable,
+  // but it seems like we have no other way out. Waiting for Navigation API to be implemented in
+  // browsers.
+  return Promise.race<boolean>([
+    new Promise((res) => {
+      window.addEventListener('popstate', function listener() {
+        window.removeEventListener('popstate', listener);
+        res(true);
+      });
+
+      window.history.go(delta);
+    }),
+
+    // Usually, it takes about 1ms to emit this event, but we use some buffer.
+    new Promise((res) => {
+      setTimeout(res, 50, false);
+    }),
+  ]);
+}

package/src/navigation/HashNavigator/index.ts

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

package/src/navigation/HashNavigator/types.ts

@@ -0,0 +1,41 @@
+import type { HashNavigator } from './HashNavigator.js';
+import type { NavigatorOptions } from '../Navigator/index.js';
+import type { NavigationEntry } from '../Navigator/types.js';
+
+export type HashNavigatorOptions = Omit<NavigatorOptions, 'loggerPrefix'>;
+
+interface ChangeEventPayload {
+  /**
+   * Navigator instance.
+   */
+  navigator: HashNavigator;
+
+  /**
+   * Previous navigation state.
+   */
+  from: NavigationEntry;
+
+  /**
+   * Current navigation state.
+   */
+  to: NavigationEntry;
+}
+
+export interface HashNavigatorEventsMap {
+  /**
+   * Being called whenever current history changes.
+   * @param event - generated event.
+   */
+  change: (event: ChangeEventPayload) => void;
+}
+
+/**
+ * Navigator event name.
+ */
+export type HashNavigatorEventName = keyof HashNavigatorEventsMap;
+
+/**
+ * Navigator event listener.
+ */
+export type HashNavigatorEventListener<E extends HashNavigatorEventName> =
+  HashNavigatorEventsMap[E];

package/src/navigation/Navigator/Navigator.ts

@@ -0,0 +1,282 @@
+import { Logger } from '~/logger/index.js';
+
+import type {
+  AnyEntry,
+  NavigationEntry,
+  NavigatorConEntry,
+  NavigatorOptions,
+  PerformGoOptions,
+  PerformPushOptions,
+  PerformReplaceOptions,
+} from './types.js';
+import { ensurePrefix } from '../ensurePrefix.js';
+
+/**
+ * Represents basic navigator implementation which uses only memory to store and control
+ * navigation state.
+ */
+export abstract class Navigator<T> {
+  protected logger: Logger;
+
+  protected readonly entries: NavigationEntry[];
+
+  constructor(
+    entries: NavigatorConEntry[],
+    protected entriesCursor: number,
+    {
+      debug = false,
+      loggerPrefix = 'Navigator',
+    }: NavigatorOptions,
+  ) {
+    if (entries.length === 0) {
+      throw new Error('Entries list should not be empty.');
+    }
+
+    if (entriesCursor >= entries.length) {
+      throw new Error('Cursor should be less than entries count.');
+    }
+
+    this.entries = entries.map(({ pathname = '', search, hash }) => {
+      if (!pathname.startsWith('/') && pathname.length > 0) {
+        throw new Error('Pathname should start with "/"');
+      }
+
+      return {
+        pathname: ensurePrefix(pathname, '/'),
+        search: search ? ensurePrefix(search, '?') : '',
+        hash: hash ? ensurePrefix(hash, '#') : '',
+      };
+    });
+    this.logger = new Logger(`[${loggerPrefix}]`, debug);
+  }
+
+  protected abstract performGo(options: PerformGoOptions): T;
+
+  protected abstract performPush(options: PerformPushOptions): T;
+
+  protected abstract performReplace(options: PerformReplaceOptions): T;
+
+  /**
+   * Converts entry to the navigation entry.
+   * @param entry - entry data
+   */
+  private formatEntry(entry: AnyEntry): NavigationEntry {
+    let path: string;
+
+    if (typeof entry === 'string') {
+      path = entry;
+    } else {
+      const {
+        pathname = '',
+        search,
+        hash,
+      } = entry;
+
+      path = pathname
+        + (search ? ensurePrefix(search, '?') : '')
+        + (hash ? ensurePrefix(hash, '#') : '');
+    }
+
+    const {
+      pathname,
+      search,
+      hash,
+    } = new URL(path, `https://localhost${this.path}`);
+    return {
+      pathname,
+      search,
+      hash,
+    };
+  }
+
+  /**
+   * Current entry.
+   */
+  protected get entry(): NavigationEntry {
+    return this.entries[this.entriesCursor];
+  }
+
+  /**
+   * Goes back in history.
+   */
+  back(): T {
+    return this.go(-1);
+  }
+
+  /**
+   * Current entries cursor.
+   */
+  get cursor(): number {
+    return this.entriesCursor;
+  }
+
+  /**
+   * True if navigator can go back.
+   */
+  get canGoBack(): boolean {
+    return this.entriesCursor > 0;
+  }
+
+  /**
+   * True if navigator can go forward.
+   */
+  get canGoForward(): boolean {
+    return this.entriesCursor !== this.entries.length - 1;
+  }
+
+  /**
+   * Goes forward in history.
+   */
+  forward(): T {
+    return this.go(1);
+  }
+
+  /**
+   * Moves entries cursor by specified delta.
+   * @param delta - cursor delta.
+   */
+  go(delta: number): T {
+    this.logger.log(`called go(${delta})`);
+
+    // Cursor should be in bounds: [0, this.entries).
+    const cursor = Math.min(
+      this.entries.length - 1,
+      Math.max(this.entriesCursor + delta, 0),
+    );
+
+    if (this.entriesCursor === cursor) {
+      return this.performGo({
+        updated: false,
+        delta,
+      });
+    }
+
+    const before = this.entry;
+    this.entriesCursor = cursor;
+    const after = this.entry;
+
+    this.logger.log('State changed', { before, after });
+
+    return this.performGo({
+      updated: true,
+      delta,
+      before,
+      after,
+    });
+  }
+
+  /**
+   * Returns copy of navigator entries.
+   */
+  getEntries(): NavigationEntry[] {
+    return this.entries.map((entry) => ({ ...entry }));
+  }
+
+  /**
+   * Current hash.
+   * @example
+   * "", "#", "#hash"
+   */
+  get hash(): string {
+    return this.entry.hash;
+  }
+
+  /**
+   * Pushes new entry. Method replaces all entries after the current one with the inserted.
+   * @param entry - entry data.
+   *
+   * @example Pushing absolute pathname.
+   * push("/absolute-path"); // "/absolute-path"
+   *
+   * @example Pushing relative pathname.
+   * // Pushing relative path replaces N last path parts, where N is pushed pathname parts count.
+   * // Pushing empty path is recognized as relative, but not replacing the last pathname part.
+   * push("relative"); // "/home/root" -> "/home/relative"
+   *
+   * @example Pushing query parameters.
+   * push("/absolute?my-param=1"); // "/home" -> "/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("johny#my-hash"); // "/home/root" -> "/home/johny#my-hash"
+   */
+  push(entry: AnyEntry): T {
+    // In case, current cursor refers not to the last one element in the history, we should
+    // remove everything after the cursor.
+    if (this.entriesCursor !== this.entries.length - 1) {
+      this.entries.splice(this.entriesCursor + 1);
+    }
+
+    const formatted = this.formatEntry(entry);
+    const before = this.entry;
+    this.entriesCursor += 1;
+    this.entries[this.entriesCursor] = formatted;
+    const after = this.entry;
+
+    this.logger.log('State changed', { before, after });
+
+    return this.performPush({
+      before,
+      after,
+    });
+  }
+
+  /**
+   * Current full path including pathname, query parameters and hash.
+   */
+  get path(): string {
+    return `${this.pathname}${this.search}${this.hash}`;
+  }
+
+  /**
+   * Current pathname.
+   * @example
+   * "/", "/abc"
+   */
+  get pathname(): string {
+    return this.entry.pathname;
+  }
+
+  /**
+   * Replaces current entry. Has the same logic as `push` method.
+   * @param entry - entry data.
+   * @see push
+   * @returns True if changes were done.
+   */
+  replace(entry: AnyEntry): T {
+    const formattedEntry = this.formatEntry(entry);
+    if (
+      this.search === formattedEntry.search
+      && this.pathname === formattedEntry.pathname
+      && this.hash === formattedEntry.hash
+    ) {
+      return this.performReplace({
+        updated: false,
+        entry: formattedEntry,
+      });
+    }
+
+    const before = this.entry;
+    this.entries[this.entriesCursor] = formattedEntry;
+    const after = this.entry;
+
+    this.logger.log('State changed', { before, after });
+
+    return this.performReplace({
+      updated: true,
+      before,
+      after,
+    });
+  }
+
+  /**
+   * Current query parameters.
+   * @example
+   * "", "?", "?a=1"
+   */
+  get search(): string {
+    return this.entry.search;
+  }
+}

package/src/navigation/Navigator/index.ts

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

package/src/navigation/Navigator/types.ts

@@ -0,0 +1,55 @@
+export interface NavigationEntry {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+export type NavigatorConEntry = Partial<NavigationEntry>;
+
+/**
+ * Entry information is allowed to be used in `push` and `replace` Navigator methods.
+ * Should be either path or object partially describing it.
+ */
+export type AnyEntry = string | Partial<NavigationEntry>;
+
+export type PerformGoOptions =
+  | {
+    updated: false;
+    delta: number;
+  }
+  | {
+    updated: true;
+    delta: number;
+    before: NavigationEntry;
+    after: NavigationEntry;
+  };
+
+export interface PerformPushOptions {
+  before: NavigationEntry;
+  after: NavigationEntry;
+}
+
+export type PerformReplaceOptions =
+  | {
+    updated: false;
+    entry: NavigationEntry;
+  }
+  | {
+    updated: true;
+    before: NavigationEntry;
+    after: NavigationEntry;
+  };
+
+export interface NavigatorOptions {
+  /**
+   * Should navigator display debug messages.
+   * @default false
+   */
+  debug?: boolean;
+
+  /**
+   * Prefix used for logger.
+   * @default 'Navigator'
+   */
+  loggerPrefix?: string;
+}

package/src/navigation/ensurePrefix.ts

@@ -0,0 +1,9 @@
+/**
+ * Ensures, that specified value starts with the specified prefix. If it doesn't, function appends
+ * prefix.
+ * @param value - value to check.
+ * @param prefix - prefix to add.
+ */
+export function ensurePrefix(value: string, prefix: string): string {
+  return value.startsWith(prefix) ? value : `${prefix}${value}`;
+}

package/src/navigation/getHash.ts

@@ -0,0 +1,17 @@
+/**
+ * Returns string after first met "#" symbol.
+ * @param value - string to take hash part from.
+ *
+ * @example No hash.
+ * getHash('/path'); // null
+ *
+ * @example Has hash.
+ * getHash('/path#abc'); // 'abc'
+ *
+ * @example Has double hash.
+ * getHash('/path#abc#another'); // 'abc#another'
+ */
+export function getHash(value: string): string | null {
+  const match = value.match(/#(.+)/);
+  return match ? match[1] : null;
+}

package/src/navigation/index.ts

@@ -0,0 +1,4 @@
+export * from './ensurePrefix.js';
+export * from './getHash.js';
+export * from './HashNavigator/index.js';
+export * from './Navigator/index.js';