chrome-devtools-frontend/front_end/models/trace/handlers/types.ts

Chrome DevTools UI

// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
import type * as Types from './../types/types.js';
import type * as ModelHandlers from './ModelHandlers.js';

export type FinalizeOptions = Types.Configuration.ParseOptions&{
  allTraceEvents: readonly Types.Events.Event[],
};

export interface Handler {
  reset(): void;
  handleEvent(data: object): void;
  finalize(options?: FinalizeOptions): Promise<void>;
  data(): unknown;
  deps?(): HandlerName[];
  handleUserConfig?(config: Types.Configuration.Configuration): void;
}

export type HandlerName = keyof typeof ModelHandlers;

/**
 * This type maps Handler names to the return type of their data
 * function. So, for example, if we are given an object with a key of 'foo'
 * and a value which is a TraceHandler containing a data() function that
 * returns a string, this type will be { foo: string }.
 *
 * This allows us to model the behavior of the TraceProcessor in the model,
 * which takes an object with Handlers as part of its config, and
 * which ultimately returns an object keyed off the names of the
 * Handlers, and with values that are derived from each
 * Handler's data function.
 *
 * So, concretely, we provide a Handler for calculating the #time
 * bounds of a trace called TraceBounds, whose data() function returns a
 * TraceWindow. The HandlerData, therefore, would determine that the
 * TraceProcessor would contain a key called 'TraceBounds' whose value is
 * a TraceWindow.
 **/
export type EnabledHandlerDataWithMeta<T extends Record<string, Handler>> = {
  // We allow the user to configure which handlers are created by passing them
  // in when constructing a model instance. However, we then ensure that the
  // Meta handler is added to that, as the Model relies on some of the data
  // from the Meta handler when creating the file. Therefore, this type
  // explicitly defines that the Meta data is present, before then extending it
  // with the index type to represent all the other handlers.
  // eslint-disable-next-line @typescript-eslint/naming-convention
  Meta: Readonly<ReturnType<typeof ModelHandlers['Meta']['data']>>,
}&{
  // For every key in the object, look up the Handler's data function
  // and use its return type as the value for the object.
  [K in keyof T]: Readonly<ReturnType<T[K]['data']>>;
};

export type HandlersWithMeta<T extends Record<string, Handler>> = {
  // eslint-disable-next-line @typescript-eslint/naming-convention
  Meta: typeof ModelHandlers.Meta,
}&{
  [K in keyof T]: T[K];
};

/**
 * Represents the final data from all of the handlers. If you instantiate a
 * TraceProcessor with a subset of handlers, you should instead use
 * `EnabledHandlerDataWithMeta<>`.
 **/
export type HandlerData = Readonly<EnabledHandlerDataWithMeta<typeof ModelHandlers>>;

type DeepWriteable<T> = {
  -readonly[P in keyof T]: DeepWriteable<T[P]>
};
export type HandlerDataMutable = DeepWriteable<HandlerData>;

export type Handlers = typeof ModelHandlers;