higlass 1.12.4 → 1.13.0

package/app/scripts/VerticalTiledPlot.jsx

@@ -1,4 +1,3 @@
-// @ts-check
 import PropTypes from 'prop-types';
 import React from 'react';
 

package/app/scripts/configs/default-tracks-for-datatype.js

@@ -1,4 +1,5 @@
-export const DEFAULT_TRACKS_FOR_DATATYPE = {
+// @ts-check
+export const DEFAULT_TRACKS_FOR_DATATYPE = /** @type {const} */ ({
   chromsizes: {
     center: '2d-chromosome-grid',
     top: 'chromosome-labels',
@@ -34,6 +35,6 @@ export const DEFAULT_TRACKS_FOR_DATATYPE = {
     left: 'vertical-bedlike',
     right: 'vertical-bedlike',
   },
-};
+});
 
 export default DEFAULT_TRACKS_FOR_DATATYPE;

package/app/scripts/configs/primitives.js

@@ -1,3 +1,4 @@
+// @ts-check
 export const DEFAULT_VIEW_MARGIN = 0;
 
 export const DEFAULT_VIEW_PADDING = 5;
@@ -32,7 +33,7 @@ export const VIEW_HEADER_MED_WIDTH_SEARCH_BAR = 400;
 
 export const VIEW_HEADER_MIN_WIDTH_SEARCH_BAR = 300;
 
-export const TRACK_LOCATIONS = [
+export const TRACK_LOCATIONS = /** @type {const} */ ([
   'top',
   'left',
   'right',
@@ -40,7 +41,7 @@ export const TRACK_LOCATIONS = [
   'center',
   'whole',
   'gallery',
-];
+]);
 
 export const MIN_HORIZONTAL_HEIGHT = 20;
 

package/app/scripts/configs/tracks-info-by-type.js

@@ -1,5 +1,8 @@
+// @ts-check
 import { TRACKS_INFO } from './tracks-info';
 
+/** @typedef {Record<string, import('./tracks-info').TrackInfo>} TracksInfoByType */
+
 export const TRACKS_INFO_BY_TYPE = TRACKS_INFO.reduce((tracksByType, track) => {
   tracksByType[track.type] = track;
   if (track.aliases) {
@@ -8,6 +11,6 @@ export const TRACKS_INFO_BY_TYPE = TRACKS_INFO.reduce((tracksByType, track) => {
     }
   }
   return tracksByType;
-}, {});
+}, /** @type {TracksInfoByType} */ ({}));
 
 export default TRACKS_INFO_BY_TYPE;

package/app/scripts/configs/tracks-info.js

@@ -1,3 +1,4 @@
+// @ts-check
 import { THEME_DARK } from './themes';
 
 import {
@@ -14,6 +15,28 @@ import {
   svgGeoMapIcon,
 } from '../icons';
 
+/**
+ * @typedef TrackInfo
+ * @property {string} type
+ * @property {string | string[]} datatype
+ * @property {string} orientation
+ * @property {string[]=} aliases
+ * @property {boolean=} local
+ * @property {boolean=} rotatable
+ * @property {boolean=} hidden
+ * @property {string=} name
+ * @property {HTMLElement | null | string=} thumbnail
+ * @property {string[]=} availableOptions
+ * @property {Record<string, unknown>=} defaultOptions
+ * @property {boolean=} exportable
+ * @property {Record<string, Record<string, unknown>>=} defaultOptionsByTheme
+ * @property {number=} minHeight
+ * @property {number=} defaultHeight
+ * @property {number=} defaultWidth
+ * @property {string=} chromInfoPath
+ * @property {boolean=} projection
+ */
+
 const osm = {
   type: 'osm-tiles',
   datatype: ['map-tiles'],
@@ -72,6 +95,7 @@ const mapbox = {
   },
 };
 
+/** @type {TrackInfo[]} */
 export const TRACKS_INFO = [
   osm,
   { ...osm, type: 'osm' },
@@ -682,7 +706,7 @@ export const TRACKS_INFO = [
     aliases: ['horizontal-1d-value-interval', 'vertical-1d-value-interval'],
     datatype: ['bed-value'],
     local: false,
-    orientation: ['1d-horizontal'],
+    orientation: '1d-horizontal',
     rotatable: true,
     name: '1D Rectangles',
     availableOptions: [

package/app/scripts/types.ts

@@ -0,0 +1,79 @@
+/* eslint-disable */
+
+export type Scale = import("d3-scale").ScaleContinuousNumeric<number, number>;
+
+export type TrackPosition = typeof import('./configs/primitives').TRACK_LOCATIONS[number];
+
+export type ChromInfo<Name extends string = string> = {
+    cumPositions: { id?: number; pos: number; chr: Name }[];
+    chrPositions: Record<Name, { pos: number }>;
+    chromLengths: Record<Name, number>;
+    totalLength: number;
+};
+
+export type UnknownTrackConfig = {
+  uid: string;
+  options: Record<string, unknown>;
+  type: string;
+  position: TrackPosition;
+  data?: Record<string, unknown>;
+  server: string;
+  tilesetUid: string;
+  coordSystem?: unknown;
+  x?: number;
+  y?: number;
+  chromInfoPath: string;
+  projectionXDomain?: [number, number];
+  projectionYDomain?: [number, number];
+  registerViewportChanged?: unknown;
+  removeViewportChanged?: unknown;
+  setDomainsCallback?: unknown;
+}
+
+export type CombinedTrackConfig = {
+  uid: string;
+  options: Record<string, unknown>;
+  contents: TrackConfig[];
+  type: 'combined';
+  position: TrackPosition;
+  data?: Record<string, unknown>;
+  server: string;
+  tilesetUid: string;
+  coordSystem?: unknown;
+  x?: number;
+  y?: number;
+  chromInfoPath: string;
+  projectionXDomain?: [number, number];
+  projectionYDomain?: [number, number];
+  registerViewportChanged?: unknown;
+  removeViewportChanged?: unknown;
+  setDomainsCallback?: unknown;
+}
+
+export type TrackConfig = UnknownTrackConfig | CombinedTrackConfig;
+
+export type TrackVisitor = {
+  (track: TrackConfig, position: null | TrackPosition): void;
+}
+
+type ZoomedFunction = {
+  (xScale: Scale, yScale: Scale, k?: number, x?: number, y?: number, xPosition?: number, yPosition?: number): void;
+}
+
+export interface TrackObject {
+  draw(): void;
+  rerender(options: unknown): void;
+  delayDrawing: boolean;
+  childTracks?: TrackObject[];
+  createdTracks: Record<string, TrackObject>;
+  refScalesChanged(x: Scale, y: Scale): void;
+  position: [number, number];
+  dimensions: [number, number];
+  updateContents(contents: TrackConfig[], x: unknown): TrackObject;
+  zoomed: ZoomedFunction;
+  setPosition(position: [number, number]): void;
+  setDimensions(dimensions: [number, number]): void;
+  remove(): void;
+  movedY(extent: number): void;
+  zoomedY(yPosition: number, wheelDelta: number): void;
+}

package/app/scripts/utils/abs-to-chr.js

@@ -1,5 +1,18 @@
+// @ts-check
 import chromInfoBisector from './chrom-info-bisector';
 
+/**
+ * @template {string} Name
+ * @typedef {[name: Name, pos: number, offset: number, insertPoint: number ]} ChromosomePosition
+ */
+
+/**
+ * Convert an absolute genome position to a chromosome position.
+ * @template {string} Name
+ * @param {number} absPosition - Absolute genome position.
+ * @param {import('../types').ChromInfo<Name>} chromInfo - Chromosome info object.
+ * @return {ChromosomePosition<Name> | null} The chromosome position.
+ */
 const absToChr = (absPosition, chromInfo) => {
   if (!chromInfo || !chromInfo.cumPositions || !chromInfo.cumPositions.length) {
     return null;
@@ -9,7 +22,9 @@ const absToChr = (absPosition, chromInfo) => {
   const lastChr = chromInfo.cumPositions[chromInfo.cumPositions.length - 1].chr;
   const lastLength = chromInfo.chromLengths[lastChr];
 
-  insertPoint -= insertPoint > 0 && 1;
+  if (insertPoint > 0) {
+    insertPoint -= 1;
+  }
 
   let chrPosition = Math.floor(
     absPosition - chromInfo.cumPositions[insertPoint].pos,

package/app/scripts/utils/accessor-transposition.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * Factory function for a transposition accessor for a 2D matrix in form of a 1D
  * array.
@@ -6,10 +8,9 @@
  * i^T = column * i + row
  * where column: `Math.floor(i / x)` and row: `Math.floor(i / x)`
  *
- * @param  {Integer}  x  X dimension of the 2D matrix
- * @param  {Integer}  y  Y dimension of the 2D matrix
- * @return  {Function}   Acessor function converting the orignal 1D index into
- *   the transposed index
+ * @param {number} x - X dimension of the 2D matrix
+ * @param {number} y - Y dimension of the 2D matrix
+ * @return {(index: number) => number} Accessor function converting the orignal 1D index into the transposed index
  */
 const accessorTransposition = (x, y) => (i) => (i % x) * y + Math.floor(i / x);
 

package/app/scripts/utils/add-arrays.js

@@ -1,4 +1,7 @@
-const STD_ACC = (i) => i;
+// @ts-check
+
+/** @type {<T>(index: T) => T} */
+const identity = (i) => i;
 
 /**
  * Add two 1D arrays
@@ -11,13 +14,12 @@ const STD_ACC = (i) => i;
  * addArrays([1,2,3], [2,3,4,5]) === [3,5,7]
  * ```
  *
- * @param  {Array}  a1  First array of numbers
- * @param  {Array}  a2  Second array of numbers
- * @param  {Function}  accessor  Allows to use custom accessors. This can be
- *   useful when a2 represents a transformed (e.g., transposed matrix).
- * @return  {Array}  Combination of both arrays.
+ * @param {Array<number>} a1 - First array of numbers
+ * @param {Array<number>} a2 - Second array of numbers
+ * @param {(index: number) => number} accessor - Allows to use custom accessors. This can be useful when a2 represents a transformed (e.g., transposed matrix).
+ * @return {Array<number>} - Combination of both arrays.
  */
-const addArrays = (a1, a2, accessor = STD_ACC) =>
+const addArrays = (a1, a2, accessor = identity) =>
   a1.map((val, i) => val + a2[accessor(i)]);
 
 export default addArrays;

package/app/scripts/utils/add-class.js

@@ -1,11 +1,13 @@
+// @ts-check
 import hasClass from './has-class';
 
 const XMLNS = 'http://www.w3.org/2000/svg';
 
 /**
  * Method to add a class name to an HTML or SVG element.
- * @param  {object}  el  HTML or SVG element to add a class to.
- * @param  {string}  className  The class name to be added.
+ * @param {Element} el - HTML or SVG element to add a class to.
+ * @param {string} className - The class name to be added.
+ * @returns {void}
  */
 const addClass = (el, className) => {
   if (el.namespaceURI === XMLNS) {

package/app/scripts/utils/add-event-listener-once.js

@@ -1,10 +1,16 @@
+// @ts-check
+
 /**
  * Add an event listener that fires only once and auto-removes itself
- * @param   {object}  element  DOM element to assign listener to.
- * @param   {string}  eventName  Event name to listen to.
- * @param   {function}  f  Event callback function.
+ *
+ * @template {keyof HTMLElementEventMap} K
+ *
+ * @param {HTMLElement} element - DOM element to assign listener to.
+ * @param {K} eventName - Event name to listen to.
+ * @param {(event: HTMLElementEventMap[K]) => void} f - Event callback function.
  */
 const addEventListenerOnce = (element, eventName, f) => {
+  /** @type {(event: HTMLElementEventMap[K]) => void} */
   const callback = (event) => {
     f(event);
     element.removeEventListener(eventName, callback);

package/app/scripts/utils/background-task-scheduler.js

@@ -1,10 +1,63 @@
+// @ts-check
+
+/**
+ * @template T
+ * @typedef DataTask
+ * @property {T} data
+ * @property {(data: T) => void} handler
+ * @property {string=} trackId
+ */
+
+/**
+ * @typedef NullDataTask
+ * @property {null} data
+ * @property {() => void} handler
+ * @property {string=} trackId
+ */
+
+/** @typedef {DataTask<any> | NullDataTask} Task */
+
+/**
+ * @param {Task} task
+ * @return {task is NullDataTask}
+ */
+function isNullDataTask(task) {
+  return task.data === null;
+}
+
+/**
+ */
 class BackgroundTaskScheduler {
   constructor() {
+    /** @type {Task[]} */
     this.taskList = [];
     this.taskHandle = null;
     this.requestIdleCallbackTimeout = 300;
   }
 
+  /**
+   * @template T
+   * @overload
+   * @param {(data: T) => void} taskHandler
+   * @param {T} taskData
+   * @param {string | null=} trackId
+   * @return {void}
+   */
+  /**
+   * If `taskData` is `null` the `taskHandler` will eventaully be called without any arguments.
+   *
+   * @overload
+   * @param {() => void} taskHandler
+   * @param {null} taskData
+   * @param {string | null=} trackId
+   * @return {void}
+   */
+  /**
+   * @param {(data: any) => void} taskHandler
+   * @param {any} taskData
+   * @param {string | null} trackId
+   * @return {void}
+   */
   enqueueTask(taskHandler, taskData, trackId = null) {
     if (trackId === null) {
       this.taskList.push({
@@ -30,6 +83,9 @@ class BackgroundTaskScheduler {
     }
   }
 
+  /**
+   * @param {{ timeRemaining(): number, didTimeout: boolean }} deadline
+   */
   runTaskQueue(deadline) {
     while (
       (deadline.timeRemaining() > 0 || deadline.didTimeout) &&
@@ -37,9 +93,9 @@ class BackgroundTaskScheduler {
     ) {
       const task = this.taskList.shift();
 
-      if (task.data === null) {
+      if (task && isNullDataTask(task)) {
         task.handler();
-      } else {
+      } else if (task) {
         task.handler(task.data);
       }
     }

package/app/scripts/utils/base64-to-canvas.js

@@ -1,9 +1,11 @@
+// @ts-check
+
 /**
  * Convert a base64 encoded image into a canvas object.
- * @param   {string}  base64  Base64 string encoding the image.
- * @param   {number}  width  Custom width for the canvas object.
- * @param   {number}  height  Custom height for the canvas object.
- * @return  {object}  The converted canvas object
+ * @param {string} base64 - Base64 string encoding the image.
+ * @param {number} width - Custom width for the canvas object.
+ * @param {number} height - Custom height for the canvas object.
+ * @return {Promise<HTMLCanvasElement>} The converted canvas object
  */
 const base64ToCanvas = (base64, width, height) => {
   const canvas = document.createElement('canvas');
@@ -13,7 +15,12 @@ const base64ToCanvas = (base64, width, height) => {
     img.onload = () => {
       canvas.width = width || img.width;
       canvas.height = height || img.height;
-      canvas.getContext('2d').drawImage(img, 0, 0);
+      const context = canvas.getContext('2d');
+      if (!context) {
+        reject(new Error('Could not get canvas context'));
+        return;
+      }
+      context.drawImage(img, 0, 0);
       resolve(canvas);
     };
 

package/app/scripts/utils/chr-to-abs.js

@@ -1,3 +1,13 @@
+// @ts-check
+
+/**
+ * Convert a chromosome position to an absolute genome position.
+ *
+ * @template {string} Name
+ * @param {Name} chrom - Chromosome name
+ * @param {number} chromPos - Chromosome position
+ * @param {import('../types').ChromInfo<Name>} chromInfo - Chromosome info object
+ */
 const chrToAbs = (chrom, chromPos, chromInfo) =>
   chromInfo.chrPositions[chrom].pos + chromPos;
 

package/app/scripts/utils/chrom-info-bisector.js

@@ -1,5 +1,8 @@
+// @ts-check
 import { bisector } from 'd3-array';
 
-const chromInfoBisector = bisector((d) => d.pos).left;
+const chromInfoBisector = bisector(
+  (/** @type {{ pos: number }} */ d) => d.pos,
+).left;
 
 export default chromInfoBisector;

package/app/scripts/utils/clone-event.js

@@ -1,10 +1,17 @@
+// @ts-check
+
 /**
- * Clone an event by invoking the source event's constructor and passing in
- *   the source event.
- * @param   {object}  event  Source event to be cloned.
- * @return  {object}  Cloned event
+ * Clone an event by invoking the source event's constructor and passing in the source event.
+ *
+ * @template {Event & { sourceUid?: string, forwarded?: boolean }} TEvent
+ * @param {TEvent} event - Source event to be cloned.
+ * @return {TEvent} Cloned event
  */
 const cloneEvent = (event) => {
+  if (!(event instanceof Event)) {
+    throw new Error('Event must be an instance of Event');
+  }
+  // @ts-expect-error - TS doesn't know about the constructor property.
   const newEvent = new event.constructor(event.type, event);
   newEvent.sourceUid = event.sourceUid;
   newEvent.forwarded = event.forwarded;

package/app/scripts/utils/color-to-hex.js

@@ -1,3 +1,4 @@
+// @ts-check
 import { color } from 'd3-color';
 
 // Configs
@@ -6,8 +7,15 @@ import { GLOBALS } from '../configs';
 /**
  * Convert a regular color value (e.g. 'red', '#FF0000', 'rgb(255,0,0)') to a
  * hex value which is legible by PIXI
+ *
+ * @param {string} colorValue - Color value to convert
+ * @return {number} Hex value
  */
 const colorToHex = (colorValue) => {
+  /** @type {import('d3-color').RGBColor} */
+  // @ts-expect-error - FIXME: `color` can return many different types
+  // depending on the string input. We should probably use a different
+  // the more strict `rgb` function instead?
   const c = color(colorValue);
   const hex = GLOBALS.PIXI.utils.rgb2hex([
     c.r / 255.0,

package/app/scripts/utils/color-to-rgba.js

@@ -1,13 +1,21 @@
+// @ts-check
 import { color } from 'd3-color';
 
 /**
  * Convert a regular color value (e.g. 'red', '#FF0000', 'rgb(255,0,0)') to a
  * RGBA array, with support for the value "transparent".
+ *
+ * @param {string} colorValue - An RGB(A) color value to convert.
+ * @return {[r: number, g: number, b: number, a: number]} An RGBA array.
  */
 const colorToRgba = (colorValue) => {
   if (colorValue === 'transparent') {
     return [255, 255, 255, 0];
   }
+  /** @type {import('d3-color').RGBColor} */
+  // @ts-expect-error - FIXME: `color` can return many different types
+  // depending on the string input. We should probably use a different
+  // the more strict `rgb` function instead?
   const c = color(colorValue);
   return [c.r, c.g, c.b, 255];
 };

package/app/scripts/utils/data-to-genomic-loci.js

@@ -1,9 +1,21 @@
+// @ts-check
 import absToChr from './abs-to-chr';
 
+/** @typedef {[startChromName: string, startChromPos: number, endChromName: string, endChromPos: number]} GenomicLoci */
+
+/**
+ * Convert a pair of data coordinates to genomic coordinates.
+ * @param {number} x0 - The first data coordinate.
+ * @param {number} x1 - The second data coordinate.
+ * @param {import('../types').ChromInfo} chromInfo - The chromosome info object.
+ * @returns {GenomicLoci} The genomic coordinates.
+ */
 const dataToGenomicLoci = (x0, x1, chromInfo) => {
   const gX0 = absToChr(x0, chromInfo);
   const gX1 = absToChr(x1, chromInfo);
-
+  if (!gX0 || !gX1) {
+    throw new Error("Couldn't convert data to genomic coordinates");
+  }
   return [gX0[0], Math.round(gX0[1]), gX1[0], Math.round(gX1[1])];
 };
 

package/app/scripts/utils/debounce.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * Debounce a function call
  *
@@ -9,21 +11,24 @@
  * Once webpack 2 with tree-shaking is supported I'd advocate to use lodash's
  * debounce method.
  *
- * @method  debounce
- * @author  Fritz Lekschas
- * @date    2017-01-14
- * @param   {Function}   func       Function to be debounced
- * @param   {Number}     wait       Number of milliseconds to debounce the
- *   function call.
- * @param   {Boolean}    immediate  If `true` function is not debounced.
- * @return  {Functiomn}             Debounced function.
+ * @method debounce
+ * @author Fritz Lekschas
+ * @date   2017-01-14
+ *
+ * @template {any[]} Args
+ * @param {(...args: Args) => void} func - Function to be debounced
+ * @param {number} wait - Number of milliseconds to debounce the function call.
+ * @param {boolean} immediate - If `true` function is not debounced.
+ * @return {{ (...args: Args): void, cancel(): void }} Debounced function.
  */
 export const debounce = (func, wait, immediate) => {
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
   let timeout;
 
+  /** @param {Args} args */
   const debounced = (...args) => {
     const later = () => {
-      timeout = null;
+      timeout = undefined;
       if (!immediate) {
         func(...args);
       }
@@ -38,9 +43,9 @@ export const debounce = (func, wait, immediate) => {
     }
   };
 
-  debounce.cancel = () => {
+  debounced.cancel = () => {
     clearTimeout(timeout);
-    timeout = null;
+    timeout = undefined;
   };
 
   return debounced;

package/app/scripts/utils/dec-to-hex-str.js

@@ -1,3 +1,10 @@
+// @ts-check
+/**
+ * Converts a decimal number to a hex string.
+ *
+ * @param {number} dec - Decimal number
+ * @return {string} Hex string
+ */
 const decToHexStr = (dec) => (dec + 16 ** 6).toString(16).substr(-6);
 
 export default decToHexStr;

package/app/scripts/utils/dict-from-tuples.js

@@ -1,15 +1,23 @@
+// @ts-check
+
 /**
- * Create a dictionary from a list of [key,value] pairs.
- * @param tuples: A list of [key,value] pairs
- * @return: A dictionary
+ * Create a dictionary from a list of [key, value] pairs.
+ *
+ * TODO(Trevor): Replace with Object.fromEntries?
+ *
+ * @template {ReadonlyArray<readonly [PropertyKey, unknown]>} T
+ * @param {T} tuples: A list of [key, value] pairs
+ * @return {{ [Item in T[number] as Item[0]]: Item[1] }} A dictionary
  */
 const dictFromTuples = (tuples) => {
+  /** @type {Record<PropertyKey, unknown>} */
   const dict = {};
 
   tuples.forEach((x) => {
     dict[x[0]] = x[1];
   });
 
+  // @ts-expect-error - TS inference not good enough to infer the correct type
   return dict;
 };
 

package/app/scripts/utils/dict-items.js

@@ -1,8 +1,23 @@
+// @ts-check
+
+/**
+ * @template T
+ * @typedef {Array<{ [Key in keyof T]: [Key, T[Key]] }[keyof T]>} DictItems
+ */
+
 /**
  * Return an array of (key,value) pairs that are present in this
  * dictionary
+ *
+ * TODO(Trevor): Replace with `Object.entries`?
+ *
+ * @template {object} T
+ * @param {T} dictionary
+ *
+ * @returns {DictItems<T>}
  */
 const dictItems = (dictionary) => {
+  /** @type {DictItems<T>} */
   const keyValues = [];
 
   for (const key in dictionary) {