higlass 1.12.3 → 1.13.0

package/app/scripts/utils/reduce.js

@@ -1,9 +1,9 @@
 /**
- * Pure functional reducer. Can be used for currying stuff. Check out
- *   `flatten.js`.
+ * Pure functional reducer. Can be used for currying stuff. Check out `flatten.js`.
  * @param   {function}  f  Reducer function.
  * @return  {array}  Curried function that accepts an array to be reduced.
  */
 const reduce = (f) => (x) => Array.prototype.reduce.call(x, f);
 
+// TODO(Trevor): Not referenced anywhere. Remove?
 export default reduce;

package/app/scripts/utils/rel-to-abs-chrom-pos.js

@@ -1,3 +1,13 @@
+// @ts-check
+
+/**
+ * @template {string} Name
+ * @param {Name} chrom
+ * @param {number} x
+ * @param {number} y
+ * @param {import('../types').ChromInfo<Name>} chromInfo
+ * @returns {[number, number]}
+ */
 const relToAbsChromPos = (chrom, x, y, chromInfo) => [
   chromInfo.chrPositions[chrom].pos + +x,
   chromInfo.chrPositions[chrom].pos + +y,

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

@@ -1,11 +1,12 @@
+// @ts-check
 import hasClass from './has-class';
 
 const XMLNS = 'http://www.w3.org/2000/svg';
 
 /**
  * Remove a class from an HTML or SVG element.
- * @param   {object}  el  HTML or SVG element.
- * @param   {string}  className  Class name to be removed.
+ * @param {Element} el - HTML or SVG element.
+ * @param {string} className  Class name to be removed.
  */
 const removeClass = (el, className) => {
   const reg = new RegExp(`(\\s|^)${className}(\\s|$)`);

package/app/scripts/utils/reset-d3-brush-style.js

@@ -1,7 +1,12 @@
+// @ts-check
+
+/** @typedef {import('d3-selection').BaseType} BaseType */
+
 /**
  * Unsets the automatically set brush style of D3.
- * @param   {object}  el  Element which is brushed on.
- * @param   {string}  className  New class name to be set.
+ * @template {import('d3-selection').Selection<BaseType, unknown, BaseType, unknown>} Sel
+ * @param {Sel} el - Element which is brushed on.
+ * @param {string} className  New class name to be set.
  */
 const resetD3BrushStyle = (el, className) => {
   el.select('.selection')

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

@@ -1,8 +1,17 @@
+// @ts-check
+
+/** @param {number} c */
 const componentToHex = (c) => {
   const hex = c.toString(16);
   return hex.length === 1 ? `0${hex}` : hex;
 };
 
+/**
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @returns {string}
+ */
 const rgbToHex = (r, g, b) =>
   `#${componentToHex(r)}${componentToHex(g)}${componentToHex(b)}`;
 

package/app/scripts/utils/scales-center-and-k.js

@@ -1,12 +1,14 @@
+// @ts-check
+
 /**
  * Calculate the center of the scale as well as its scale
  * factor
  *
  * Assumes the two scales have the same k
  *
- * @param xScale: A d3 scale.
- * @param yScale: A d3 scale.
- * @return: [domainCenter, k]
+ * @param {import('../types').Scale} xScale - A d3 scale.
+ * @param {import('../types').Scale} yScale - A d3 scale.
+ * @return {[xCenter: number, yCenter: number, k: number]}
  */
 const scalesCenterAndK = (xScale, yScale) => {
   const xCenter = xScale.invert((xScale.range()[0] + xScale.range()[1]) / 2);

package/app/scripts/utils/scales-to-genome-loci.js

@@ -1,5 +1,15 @@
+// @ts-check
 import dataToGenomicLoci from './data-to-genomic-loci';
 
+/** @typedef {import('./data-to-genomic-loci').GenomicLoci} GenomicLoci */
+
+/**
+ * Convert a pair of scales to genomic coordinates.
+ * @param {import('../types').Scale} xScale
+ * @param {import('../types').Scale} yScale
+ * @param {import('../types').ChromInfo} chromInfo
+ * @returns {[...GenomicLoci, ...GenomicLoci] | undefined} The genomic coordinates.
+ */
 export const scalesToGenomeLoci = (xScale, yScale, chromInfo) => {
   if (chromInfo === null || !xScale || !yScale) return undefined;
 

package/app/scripts/utils/selected-items-to-cum-weights.js

@@ -1,7 +1,14 @@
+// @ts-check
 import selectedItemsToSize from './selected-items-to-size';
 
+/**
+ * Compute the cumulative sum of an array of numbers.
+ * @param {Array<number>} values - The array of numbers to sum.
+ * @returns {Float64Array} The array of cumulative sums.
+ */
 function cumsum(values) {
   let sum = 0;
+  /** @type {number[]} */
   const result = [];
   values.forEach((v) => {
     sum += +v || 0;
@@ -13,10 +20,11 @@ function cumsum(values) {
 /**
  * Compute the cumulative normalized weights associated with a
  * potentially 2d array of selected item indices.
- * @param {array} selectedItems The 1d or 2d array of items or groups of items.
- * @param {boolean} withRelativeSize Does a group of indices count as 1 unit size
- * or is its size relative to the group size?
- * @returns {number[]} The array of cumulative weights, one for each item.
+ *
+ * @param {Array<unknown>} selectedItems - The 1d or 2d array of items or groups of items.
+ * @param {boolean} withRelativeSize - Does a group of indices count as 1 unit size or is its size relative to the group size?
+ * @returns {Float64Array} The array of cumulative weights, one for each item.
+ *
  * Sums to 1 before the cumulative sum step (i.e. the final array element will be 1).
  */
 const selectedItemsToCumWeights = (selectedItems, withRelativeSize) => {

package/app/scripts/utils/selected-items-to-size.js

@@ -1,8 +1,10 @@
+// @ts-check
 /**
  * Compute the size associated with a potentially 2d array of selected item indices.
  * For example, this can be used to compute the total height of a `horizontal-multivec` track
  * where rows are selected individually or in aggregation groups.
- * @param {array} selectedItems The 1d or 2d array of items or groups of items.
+ *
+ * @param {Array<unknown>} selectedItems The 1d or 2d array of items or groups of items.
  * @param {boolean} withRelativeSize Does a group of indices count as 1 unit size
  * or is its size relative to the group size?
  * @returns {number} The computed size value.
@@ -10,7 +12,8 @@
  */
 const selectedItemsToSize = (selectedItems, withRelativeSize) =>
   selectedItems.reduce(
-    (a, h) => a + (Array.isArray(h) && withRelativeSize ? h.length : 1),
+    (/** @type {number} */ a, h) =>
+      a + (Array.isArray(h) && withRelativeSize ? h.length : 1),
     0,
   );
 

package/app/scripts/utils/show-mouse-position.js

@@ -1,3 +1,4 @@
+// @ts-check
 import { globalPubSub } from 'pub-sub-es';
 
 import hexStrToInt from './hex-string-to-int';
@@ -8,22 +9,27 @@ import { GLOBALS } from '../configs';
 const COLOR = 0xaaaaaa;
 const ALPHA = 1.0;
 
+/**
+ * @typedef MouseTrackOptions
+ * @property {string=} mousePositionColor - Color of the mouse position.
+ * @property {number=} mousePositionAlpha - Alpha of the mouse position.
+ */
+
 /**
  * Actual interface for initializing to show the mouse location
  *
- * @param  {Object}  pubSubs  PubSub service.
- * @param  {Object}  pubSubs  Subscribed PubSub events.
- * @param  {Object}  options  Track options.
- * @param  {Function}  getScales  Getter for the track's X and Y scales.
- * @param  {Function}  getPosition  Getter for the track's position.
- * @param  {Function}  getDimensions  Getter for the track's dimensions.
- * @param  {Function}  getIsFlipped  Getter determining if a track has been
+ * @param {import('pub-sub-es').PubSub} pubSub - PubSub service.
+ * @param {Array<import('pub-sub-es').Subscription>} pubSubs - Subscribed PubSub events.
+ * @param {MouseTrackOptions} options - Track options.
+ * @param {() => [import('../types').Scale, import('../types').Scale]} getScales - Getter for the track's X and Y scales.
+ * @param {() => [number, number]} getPosition - Getter for the track's position.
+ * @param {() => [number, number]} getDimensions - Getter for the track's dimensions.
+ * @param {() => boolean} getIsFlipped - Getter determining if a track has been
  *   flipped from horizontal to vertical.
- * @param  {Boolean}  is2d  If `true` draw both dimensions of the mouse
- *   location.
- * @param  {Boolean}  isGlobal   If `true` local and global events will trigger
+ * @param {boolean} is2d - If `true` draw both dimensions of the mouse location.
+ * @param {boolean} isGlobal - If `true` local and global events will trigger
  *   the mouse position drawing.
- * @return  {Object}  PIXI graphics the mouse location is drawn on.
+ * @return {import('pixi.js').Graphics} - PIXI graphics the mouse location is drawn on.
  */
 const showMousePosition = (
   pubSub,
@@ -56,10 +62,11 @@ const showMousePosition = (
   /**
    * Draw 1D mouse location (cross) hair onto the PIXI graphics.
    *
-   * @param  {Integer}   mousePos  One dimension of the mouse location
-   * @param  {Boolean}   isHorizontal  If `true` the dimension to be drawn is
+   * @param {number} mousePos - One dimension of the mouse location (integer).
+   * @param {boolean=} isHorizontal - If `true` the dimension to be drawn is
    *   horizontal.
-   * @param  {Boolean}   isNoClear  If `true` do not clear the graphics.
+   * @param  {boolean=}   isNoClear  If `true` do not clear the graphics.
+   * @return {void}
    */
   const drawMousePosition = (mousePos, isHorizontal, isNoClear) => {
     if (!isNoClear) clearGraphics();
@@ -77,10 +84,25 @@ const showMousePosition = (
     }
   };
 
+  /**
+   * @typedef NoHoveredTracksEvent
+   * @property {true} noHoveredTracks - If `true` no tracks are hovered.
+   * @property {false=} isFromVerticalTrack - If `true` the event is from a vertical track.
+   */
+
+  /**
+   * @typedef TrackEvent
+   * @property {false=} noHoveredTracks - If `true` no tracks are hovered.
+   * @property {boolean} isFromVerticalTrack - If `true` the event is from a vertical track.
+   * @property {boolean} isFrom2dTrack - If `true` the event is from a 2D track.
+   * @property {number} dataY - Y position of the mouse.
+   * @property {number} dataX - X position of the mouse.
+   */
+
   /**
    * Mouse move handler
    *
-   * @param  {Object}  e  Event object.
+   * @param {Event & (NoHoveredTracksEvent | TrackEvent)} event - Event object.
    */
   const mouseMoveHandler = (event) => {
     if (event.noHoveredTracks) {
@@ -127,6 +149,21 @@ const showMousePosition = (
   return graphics;
 };
 
+/**
+ * @typedef ClassContext
+ * @property {import('pixi.js').Container=} pForeground
+ * @property {import('pixi.js').Container=} pMasked
+ * @property {import('pixi.js').Container=} pMain
+ * @property {() => import('../types').Scale} xScale
+ * @property {() => import('../types').Scale} yScale
+ * @property {() => [number, number]} getPosition
+ * @property {() => [number, number]} getDimensions
+ * @property {import('pub-sub-es').PubSub} pubSub
+ * @property {Array<import('pub-sub-es').Subscription>} pubSubs
+ * @property {(prop: 'flipText') => () => boolean} getProp
+ * @property {{}} options
+ */
+
 /**
  * Public API for showing the mouse location.
  *
@@ -135,15 +172,21 @@ const showMousePosition = (
  * `showMousePosition` is the actual function and could be called from within
  * each class as well.
  *
- * @param  {Object}  context  Class context, i.e., `this`.
- * @param  {Boolean}  is2d   If `true` both dimensions of the mouse location
+ * @param {ClassContext} context - Class context, i.e., `this`.
+ * @param {Boolean} is2d - If `true` both dimensions of the mouse location
  *   should be shown. E.g., on a central track.
- * @param  {Boolean}  isGlobal   If `true` local and global events will trigger
+ * @param {Boolean} isGlobal - If `true` local and global events will trigger
  *   the mouse position drawing.
- * @return  {Function}  Method to remove graphics showing the mouse location.
+ * @return {Function} - Method to remove graphics showing the mouse location.
  */
 const setupShowMousePosition = (context, is2d = false, isGlobal = false) => {
   const scene = is2d ? context.pMasked : context.pForeground || context.pMain;
+  if (!scene) {
+    throw new Error(
+      'setupShowMousePosition: No scene found. Please make sure to call this method after the scene has been initialized.',
+    );
+  }
+  /** @type {() => [import('../types').Scale, import('../types').Scale]} */
   const getScales = () => [context.xScale(), context.yScale()];
 
   const graphics = showMousePosition(

package/app/scripts/utils/some.js

@@ -1,9 +1,11 @@
+// @ts-check
 /**
  * Functional version of `Array.forEach`. More flexible and applicable to
- *   other array-like data types like `NodeList`.
- * @param   {function}  f  Modifier function applied on every item of the
- *   array.
- * @return  {*}  Modified array-like variable.
+ * other array-like data types like `NodeList`.
+ *
+ * @template T
+ * @param {(item: T, i: number) => boolean} f - Modifier function applied on every item of the array.
+ * @return {(arr: Array<T>) => boolean}  Modified array-like variable.
  */
 const some = (f) => (x) => Array.prototype.some.call(x, f);
 

package/app/scripts/utils/sum.js

@@ -1,8 +1,9 @@
+// @ts-check
 /**
  * Convenience function for a reducer to sum up a numerical array.
- * @param   {number}  a  Value A
- * @param   {number}  b  Value B
- * @return  {number}  Sum of A + B
+ * @param {number} a - Value A
+ * @param {number} b - Value B
+ * @return {number} Sum of A + B
  */
 const sum = (a, b) => a + b;
 

package/app/scripts/utils/throttle-and-debounce.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * Throttle and debounce a function call
  *
@@ -23,19 +24,22 @@
  * 09. nothing
  * 10. y(f, 2, 2)(args_10) => f(args_10) call from debouncing
  *
- * @param   {functon}  func - Function to be throttled and debounced
- * @param   {number}  interval - Throttle intevals in milliseconds
- * @param   {number}  finalWait - Debounce wait time in milliseconds
- * @return  {function} - Throttled and debounced function
+ * @template {any[]} Args
+ * @param {(...args: Args) => void} func - Function to be throttled and debounced
+ * @param {number} interval - Throttle intevals in milliseconds
+ * @param {number} finalWait - Debounce wait time in milliseconds
+ * @return {(request: unknown, ...args: Args) => void} - Throttled and debounced function
  */
 const throttleAndDebounce = (func, interval, finalWait) => {
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
   let timeout;
   let blockedCalls = 0;
 
   const reset = () => {
-    timeout = null;
+    timeout = undefined;
   };
 
+  /** @param {Args} args */
   const debounced = (...args) => {
     const later = () => {
       // Since we throttle and debounce we should check whether there were
@@ -57,12 +61,17 @@ const throttleAndDebounce = (func, interval, finalWait) => {
     reset();
   };
 
+  /** @param {Args} args */
   debounced.immediate = (...args) => {
     func(...args);
   };
 
   let wait = false;
-  const throttled = (request, ...args) => {
+  /**
+   * @param {unknown} _request
+   * @param {Args} args
+   */
+  const throttled = (_request, ...args) => {
     if (!wait) {
       func(...args);
       debounced(...args);

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

@@ -1,9 +1,10 @@
+// @ts-check
 /**
  * Convert a 1D numerical array into a canvas image
- * @param   {Float32Array}  pixData  1D data array
- * @param   {number}  w  Width
- * @param   {number}  h  Height
- * @return  {object}  Canvas object
+ * @param {Uint8ClampedArray} pixData - 1D data array
+ * @param {number} w - Width
+ * @param {number} h - Height
+ * @return {object} Canvas object
  */
 const tileToCanvas = (pixData, w = 256, h = 256) => {
   const canvas = document.createElement('canvas');
@@ -12,6 +13,9 @@ const tileToCanvas = (pixData, w = 256, h = 256) => {
   canvas.height = h;
 
   const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    throw new Error('Could not get canvas context');
+  }
 
   ctx.fillStyle = 'transparent';
   ctx.fillRect(0, 0, canvas.width, canvas.height);

package/app/scripts/utils/timeout.js

@@ -1,3 +1,5 @@
+// @ts-check
+/** @param {number} ms */
 const timeout = (ms) =>
   new Promise((resolve) => {
     setTimeout(resolve, ms);

package/app/scripts/utils/to-void.js

@@ -1,3 +1,5 @@
+// @ts-check
+/** @type {(...args: any[]) => void}  */
 const toVoid = () => {};
 
 export default toVoid;

package/app/scripts/utils/total-track-pixel-height.js

@@ -1,17 +1,16 @@
+// @ts-check
 /**
- * Calculate the total height of the horizontal and center
- * tracks in pixels
- *
- * Parameters
- * -----------
- *
- *  view : view config object
- *    A typical view configuration containing a list of tracks
+ * @typedef Tracks
+ * @prop {{ height: number }[]=} top
+ * @prop {{ height: number }[]=} center
+ * @prop {{ height: number }[]=} bottom
+ */
+
+/**
+ * Calculate the total height of the horizontal and center tracks in pixels
  *
- * Returns
- * -------
- *  int
- *    The total height of the top, center and bottom tracks
+ * @param {{ tracks?: Tracks }} view - A typical view configuration containing a list of tracks
+ * @returns {number} - The total height of the top, center and bottom tracks
  */
 const totalTrackPixelHeight = (view) => {
   // no tracks means no height

package/app/scripts/utils/trim-trailing-slash.js

@@ -1,7 +1,8 @@
+// @ts-check
 /**
  * Trim trailing slash of an URL.
- * @param   {string}  url  URL to be trimmed.
- * @return  {string}  Trimmed URL.
+ * @param {string} url - URL to be trimmed.
+ * @return {string} Trimmed URL.
  */
 const trimTrailingSlash = (url) => (url || '').replace(/\/$/, '');
 

package/app/scripts/utils/type-guards.js

@@ -0,0 +1,17 @@
+// @ts-check
+
+/**
+ * @param {import('../types').TrackConfig} trackConfig
+ * @return {trackConfig is import('../types').CombinedTrackConfig}
+ */
+export function isCombinedTrackConfig(trackConfig) {
+  return trackConfig.type === 'combined';
+}
+
+/**
+ * @param {Event} event
+ * @returns {event is WheelEvent}
+ */
+export function isWheelEvent(event) {
+  return 'deltaY' in event && 'deltaMode' in event;
+}

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

@@ -1,12 +1,13 @@
+// @ts-check
 /**
  * Factory function for a value to RGB color converter
  *
- * @param  {Function}  valueScale  Value scaling function.
- * @param  {Array}  colorScale  Color scale array.
- * @param  {Number}  pseudoCounts  Pseudo counts used as a pseudocount to
- *   prevent taking the log of 0.
- * @param  {Number}  eps  Epsilon.
- * @return  {Array}  RGB color array.
+ * @template T
+ * @param {(value: number) => number} valueScale - Value scaling function.
+ * @param {Array<T>} colorScale - Color scale array.
+ * @param {number} pseudoCounts - Pseudo counts used as a pseudocount to prevent taking the log of 0.
+ * @param {number} eps - Epsilon.
+ * @return {(value: number) => T} RGB color array.
  */
 const valueToColor =
   (valueScale, colorScale, pseudoCounts = 0, eps = 0.000001) =>

package/app/scripts/utils/visit-positioned-tracks.js

@@ -1,26 +1,31 @@
+// @ts-check
 import visitTracks from './visit-tracks';
 
+/** @typedef {{ [Key in import('../types').TrackPosition]: import('../types').TrackConfig[] }} PositionedTracks
+ */
+
 /**
  * Track visitor for positioned tracks, i.e., tracks with a position.
- * @param   {array}  tracks  List of all positioned tracks from the view definition.
- * @param   {function}  visitor  Callback function receiving individual tracks.
- * @param   {boolean}  inclCombinedTracks  If `true` recursively visit combined tracks.
+ * @param {PositionedTracks} positionedTracks - List of all positioned tracks from the view definition.
+ * @param {import('../types').TrackVisitor} visitor - Callback function receiving individual tracks.
+ * @param {boolean} inclCombinedTracks - If `true` recursively visit combined tracks.
  */
 const visitPositionedTracks = (
   positionedTracks,
   visitor,
   inclCombinedTracks = true,
 ) => {
+  /** @type {import('../types').TrackConfig[]} */
   const allTracks = [];
 
-  Object.keys(positionedTracks).forEach((position) => {
-    visitTracks(
-      positionedTracks[position],
-      visitor,
-      inclCombinedTracks,
-      position,
-    );
-  });
+  for (const [stringPosition, tracks] of Object.entries(positionedTracks)) {
+    /** @type {import('../types').TrackPosition} */
+    // @ts-expect-error - Typings for Object#entries don't have strong inference,
+    // might change in the future.
+    const position = stringPosition;
+    visitTracks(tracks, visitor, inclCombinedTracks, position);
+    allTracks.push(...tracks);
+  }
 
   return allTracks;
 };

package/app/scripts/utils/visit-tracks.js

@@ -1,25 +1,24 @@
+// @ts-check
+import { isCombinedTrackConfig } from './type-guards';
+
 /**
  * Track visitor to run code on individual tracks.
- * @param   {array}  tracks  List of all tracks from the view definition.
- * @param   {function}  visitor  Callback function receiving individual tracks.
- * @param   {boolean}  inclCombinedTracks  If `true` recursively visit combined tracks.
- * @param   {function}  position  Can be used to limit the tracks to be visit to a certain position.
+ * @param {import('../types').TrackConfig[]} tracks - List of all tracks from the view definition.
+ * @param {import('../types').TrackVisitor} visit - Callback function receiving individual tracks.
+ * @param {boolean} includeCombinedTracks - If `true` recursively visit combined tracks.
+ * @param {import('../types').TrackPosition | null} position - Can be used to limit the tracks to be visit to a certain position.
  */
 const visitTracks = (
   tracks,
-  visitor,
-  inclCombinedTracks = true,
+  visit,
+  includeCombinedTracks = true,
   position = null,
 ) =>
   tracks.forEach((track) => {
-    if (track.type === 'combined') {
-      if (inclCombinedTracks) {
-        visitTracks(track.contents, visitor, inclCombinedTracks, position);
-        visitor(track, position);
-      }
-    } else {
-      visitor(track, position);
+    if (includeCombinedTracks && isCombinedTrackConfig(track)) {
+      visitTracks(track.contents, visit, includeCombinedTracks, position);
     }
+    visit(track, position);
   });
 
 export default visitTracks;