@tinkoff/perfume 0.0.0-stage → 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,256 @@
+import { ReportOpts } from "web-vitals";
+//#region src/types.d.ts
+export interface Metric {
+  /**
+   * The name of the metric (in acronym form).
+   */
+  name: 'CLS' | 'FCP' | 'FID' | 'LCP' | 'TTFB' | 'RT' | 'TBT' | 'NTBT' | 'ET' | 'INP';
+  /**
+   * The current value of the metric.
+   */
+  value: number;
+  /**
+   * The rating as to whether the metric value is within the "good",
+   * "needs improvement", or "poor" thresholds of the metric.
+   */
+  rating: IVitalsScore;
+  /**
+   * The delta between the current value and the last-reported value.
+   * On the first report, `delta` and `value` will always be the same.
+   */
+  delta?: number;
+  /**
+   * A unique ID representing this particular metric instance. This ID can
+   * be used by an analytics tool to dedupe multiple values sent for the same
+   * metric instance, or to group multiple deltas together and calculate a
+   * total. It can also be used to differentiate multiple different metric
+   * instances sent from the same page, which can happen if the page is
+   * restored from the back/forward cache (in that case new metrics object
+   * get created).
+   */
+  id?: string;
+  /**
+   * Any performance entries relevant to the metric value calculation.
+   * The array may also be empty if the metric value was not based on any
+   * entries (e.g. a CLS value of 0 given no layout shifts).
+   */
+  entries?: PerformanceEntry[];
+  /**
+   * The type of navigation
+   *
+   * Navigation Timing API (or `undefined` if the browser doesn't
+   * support that API). For pages that are restored from the bfcache, this
+   * value will be 'back-forward-cache'.
+   */
+  navigationType?: INavigationType;
+  /**
+   * An object containing potentially-helpful debugging information that
+   * can be sent along with the metric value for the current page visit in
+   * order to help identify issues happening to real-users in the field.
+   */
+  attribution: {
+    [key: string]: unknown;
+  };
+}
+export interface IAnalyticsTrackerOptions {
+  attribution: object;
+  data: IPerfumeData;
+  metricName: string;
+  navigatorInformation: INavigatorInfo;
+  rating: IVitalsScore;
+  navigationType?: INavigationType;
+}
+interface WebVitalsReportOptions {
+  ttfb?: ReportOpts;
+  cls?: ReportOpts;
+  fcp?: ReportOpts;
+  fid?: ReportOpts;
+  lcp?: ReportOpts;
+  inp?: ReportOpts;
+}
+export interface IPerfumeConfig {
+  isResourceTiming: boolean;
+  isElementTiming: boolean;
+  analyticsTracker?: (options: IAnalyticsTrackerOptions) => void;
+  maxTime: number;
+  reportOptions: WebVitalsReportOptions;
+  steps?: IStepsConfig;
+  onMarkStep?: (mark: string, steps: string[]) => void;
+}
+export interface IPerfumeOptions {
+  resourceTiming?: boolean;
+  elementTiming?: boolean;
+  analyticsTracker?: (options: IAnalyticsTrackerOptions) => void;
+  maxMeasureTime?: number;
+  reportOptions?: WebVitalsReportOptions;
+  steps?: IStepsConfig;
+  onMarkStep?: (mark: string, steps: string[]) => void;
+}
+export interface IMetricMap {
+  [measureName: string]: boolean;
+}
+export interface INavigatorInfo {
+  deviceMemory?: number;
+  hardwareConcurrency?: number;
+  isLowEndDevice?: boolean;
+  isLowEndExperience?: boolean;
+  serviceWorkerStatus?: 'controlled' | 'supported' | 'unsupported';
+}
+export interface IPerfObservers {
+  [measureName: string]: any;
+}
+export type IPerformanceObserverType = 'first-input' | 'largest-contentful-paint' | 'layout-shift' | 'longtask' | 'measure' | 'navigation' | 'paint' | 'element' | 'resource';
+export type IPerformanceEntryInitiatorType = 'beacon' | 'css' | 'fetch' | 'img' | 'other' | 'script' | 'xmlhttprequest';
+export declare interface IPerformanceEntry {
+  decodedBodySize?: number;
+  duration: number;
+  entryType: IPerformanceObserverType;
+  initiatorType?: IPerformanceEntryInitiatorType;
+  loadTime: number;
+  name: string;
+  renderTime: number;
+  startTime: number;
+  hadRecentInput?: boolean;
+  value?: number;
+  identifier?: string;
+}
+export interface PerformanceEventTiming extends PerformanceEntry {
+  processingStart: DOMHighResTimeStamp;
+  target?: Node;
+}
+export interface IPerformancePaintTiming {
+  name: string;
+  entryType: string;
+  startTime: number;
+  duration: number;
+}
+export interface IPerfumeNavigationTiming {
+  fetchTime?: number;
+  workerTime?: number;
+  totalTime?: number;
+  downloadTime?: number;
+  timeToFirstByte?: number;
+  headerSize?: number;
+  dnsLookupTime?: number;
+  redirectTime?: number;
+}
+export type EffectiveConnectionType = '2g' | '3g' | '4g' | 'slow-2g' | 'lte';
+export interface IPerfumeNetworkInformation {
+  downlink?: number;
+  effectiveType?: EffectiveConnectionType;
+  onchange?: () => void;
+  rtt?: number;
+  saveData?: boolean;
+}
+export interface IPerfumeDataConsumption {
+  beacon: number;
+  css: number;
+  fetch: number;
+  img: number;
+  other: number;
+  script: number;
+  total: number;
+  xmlhttprequest: number;
+}
+export type IPerfumeData = number | IPerfumeNavigationTiming | IPerfumeNetworkInformation;
+export type IVitalsScore = 'good' | 'needsImprovement' | 'poor' | null;
+export type INavigationType = 'navigate' | 'reload' | 'back-forward' | 'back-forward-cache' | 'prerender';
+export interface IVitalsThresholds {
+  vitalsThresholds: [number, number];
+}
+export interface IOutlierThreshold {
+  maxOutlierThreshold: number;
+}
+export declare enum IThresholdTier {
+  instant = "instant",
+  quick = "quick",
+  moderate = "moderate",
+  slow = "slow",
+  unavoidable = "unavoidable"
+}
+export type IStepsThresholdConfig = IVitalsThresholds & IOutlierThreshold;
+export type IStepsThresholds = { [key in IThresholdTier]: IStepsThresholdConfig; };
+export type ISteps<Steps extends string> = {
+  steps: Steps[];
+} & Partial<IOutlierThreshold>;
+export interface IStepMarks<Marks extends string> {
+  marks: [Marks | 'launch', Marks];
+}
+export type IStepConfig<Marks extends string> = {
+  threshold: IThresholdTier;
+} & IStepMarks<Marks>;
+export type IStepsConfig = Record<string, IStepConfig<string>>;
+//#endregion
+//#region src/initPerfume.d.ts
+export declare const initPerfume: (options?: IPerfumeOptions) => void;
+//#endregion
+//#region src/steps/markStep.d.ts
+/**
+ * Function which creates a step mark with a name generated
+ * from the provided mark when called.
+ *
+ * The generated mark name has the following format:
+ * `mark.${mark}`
+ *
+ */
+export declare const markStep: (mark: string) => void;
+/**
+ * Start performance measurement
+ */
+export declare const start: (markName: string) => void;
+/**
+ * End performance measurement
+ */
+export declare const end: (markName: string, customProperties?: {}, doLogData?: boolean) => void;
+/**
+ * Removes the named mark from the browser's performance entry buffer.
+ */
+export declare const clear: (markName: string) => void;
+//#endregion
+//#region src/steps/markStepOnce.d.ts
+/**
+ * Function which creates a step mark with a name generated
+ * from the provided mark if a mark with the same name does not
+ * already exist when called.
+ *
+ * The generated mark name has the following format:
+ * `mark.${mark}`
+ *
+ */
+export declare const markStepOnce: (mark: string) => void;
+//#endregion
+//#region src/steps/navigationSteps.d.ts
+/**
+ * An API consumers must use to update internal state based on page/screen navigations.
+ * Internal state must be updated when the following are true
+ * 1. Journey marks are hit
+ * 2. Page navigations occur
+ * This function ensures the 2nd case is covered to help prevent "stale"
+ * steps that don't hit their final mark because the users navigates
+ * backwards in journey.
+ */
+export declare const trackUJNavigation: () => void;
+//#endregion
+//#region src/markNTBT.d.ts
+/**
+ * NTBT = Navigation Total Blocking Time
+ *
+ * This metric measures the amount of time the application may be blocked
+ * from processing code during the 2s window after a user navigates
+ * from page A to page B.
+ *
+ * Because this library is navigation agnostic, we have this method
+ * to mark when the navigation starts.
+ *
+ * The NTBT metric is the summation of the blocking time of all long tasks
+ * in the 2s window after this method is invoked.
+ *
+ * If this method is called before the 2s window ends; it will trigger a new
+ * NTBT measurement and interrupt the previous one.
+ *
+ * Credit: Thank you Steven Lam for helping with this!
+ */
+export declare const markNTBT: () => void;
+//#endregion
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/initPerfume.ts","../src/steps/markStep.ts","../src/steps/markStepOnce.ts","../src/steps/navigationSteps.ts","../src/markNTBT.ts"],"mappings":";;iBAEiB;;;;EAIf;;;;EAcA;;;;;EAKA,QAAQ;;;;;EAKR;;;;;;;;;;EAUA;;;;;;EAMA,UAAU;;;;;;;;EAQV,iBAAiB;;;;;;EAOjB;KACG;;;iBAIY;EACf;EACA,MAAM;EACN;EACA,sBAAsB;EACtB,QAAQ;EACR,iBAAiB;;UAGT;EACR,OAAO;EACP,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;EACN,MAAM;;iBAGS;EAEf;EACA;EAEA,oBAAoB,SAAS;EAE7B;EAEA,eAAe;EAEf,QAAQ;EAER,cAAc,cAAc;;iBAGb;EAEf;EACA;EAEA,oBAAoB,SAAS;EAE7B;EAEA,gBAAgB;EAEhB,QAAQ;EAER,cAAc,cAAc;;iBAGb;GACd;;iBAGc;EACf;EACA;EACA;EACA;EACA;;iBAGe;GACd;;YAGS;YAWA;yBAGa;EACvB;EACA;EACA,WAAW;EACX,gBAAgB;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;;iBAIe,+BAA+B;EAC9C,iBAAiB;EACjB,SAAS;;iBAGM;EACf;EACA;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;YAGU;iBAEK;EACf;EACA,gBAAgB;EAChB;EACA;EACA;;iBAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;YAGU,wBACD,2BAA2B;YAE1B;YAEA;iBAGK;EACf;;iBAEe;EACf;;oBAGU;EACV;EACA;EACA;EACA;EACA;;YAGU,wBAAwB,oBAAoB;YAC5C,sBACT,OAAO,iBAAiB;YAGf,OAAO;EACjB,OAAO;IACL,QAAQ;iBAEK,WAAW;EAC1B,QAAQ,kBAAkB;;YAGhB,YAAY;EACtB,WAAW;IACT,WAAW;YAEH,eAAe,eAAe;;;qBCjO7B,cAAe,UAAS;;;;;;;;;;;qBCHxB,WAAY;;;;qBAcZ,QAAS;;;;qBAYT,MACX,kBACA,uBACA;;;;qBAiBW,QAAS;;;;;;;;;;;;qBClDT,eAAgB;;;;;;;;;;;;qBC0GhB;;;;;;;;;;;;;;;;;;;;;qBC7FA"}