higlass 1.12.4 → 1.13.1

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) {

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

@@ -1,10 +1,20 @@
+// @ts-check
+
 /**
- * Return an array of values that are present in this dictionary
+ * Return an array of keys that are present in this dictionary
+ *
+ * TODO(Trevor): Replace with `Object.keys`?
+ *
+ * @template T
+ * @param {T} dictionary
+ * @returns {Array<keyof T>}
  */
 export default function dictKeys(dictionary) {
+  /** @type {Array<keyof T>} */
   const keys = [];
 
   for (const key in dictionary) {
+    // @ts-expect-error - TS inference not good enough to infer the correct type
     if (dictionary.hasOwnProperty(key)) {
       keys.push(key);
     }

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

@@ -1,7 +1,14 @@
+// @ts-check
+
 /**
  * Return an array of values that are present in this dictionary
+ *
+ * @template {object} T
+ * @param {T} dictionary
+ * @returns {Array<T[keyof T]>}
  */
 export default function dictValues(dictionary) {
+  /** @type {Array<T[keyof T]>} */
   const values = [];
 
   for (const key in dictionary) {

package/app/scripts/utils/download.js

@@ -1,3 +1,10 @@
+// @ts-check
+
+/**
+ * Download a file to the user's computer.
+ * @param {string} filename - Name of the file to download
+ * @param {string | Blob} stringOrBlob - Contents of the file to download
+ */
 export function download(filename, stringOrBlob) {
   // yanked from here
   // https://stackoverflow.com/questions/3665115/create-a-file-in-memory-for-user-to-download-not-through-server
@@ -6,17 +13,13 @@ export function download(filename, stringOrBlob) {
     typeof stringOrBlob === 'string'
       ? new Blob([stringOrBlob], { type: 'application/octet-stream' })
       : stringOrBlob;
-  if (window.navigator.msSaveOrOpenBlob) {
-    window.navigator.msSaveBlob(blob, filename);
-  } else {
-    const elem = window.document.createElement('a');
-    elem.href = window.URL.createObjectURL(blob);
-    elem.download = filename;
-    document.body.appendChild(elem);
-    elem.click();
-    document.body.removeChild(elem);
-    URL.revokeObjectURL(elem.href);
-  }
+  const elem = window.document.createElement('a');
+  elem.href = window.URL.createObjectURL(blob);
+  elem.download = filename;
+  document.body.appendChild(elem);
+  elem.click();
+  document.body.removeChild(elem);
+  URL.revokeObjectURL(elem.href);
 }
 
 export default download;

package/app/scripts/utils/flatten.js

@@ -2,9 +2,12 @@ import reduce from './reduce';
 
 /**
  * Function for flattening a nested array. It returns a curried reducer.
- * @param   {array}  Nested array
- * @return  {array}  Flatt array
+ *
+ * @template T
+ * @param {Array<Array<T>>} Nested array
+ * @return {Array<T>} Flat array
  */
 const flatten = reduce((a, b) => a.concat(b), []);
 
+// TODO(Trevor): Not referenced anywhere. Remove?
 export default flatten;

package/app/scripts/utils/for-each.js

@@ -1,10 +1,12 @@
+// @ts-check
 /**
- * Functional version of `Array.forEach`. More flexible and applicable to
- *   other array-like data types.
- * @param   {function}  f  Modifier function applied on every item of the
- *   array.
- * @return  {*}  Modified array-like variable.
+ * Functional version of `Array.forEach`. More flexible and applicable to other array-like data types.
+ *
+ * @template T
+ * @param {<T>(item: T) => void} f - Modifier function applied on every item of the array.
+ * @return {(arr: ArrayLike<T>) => void} Modified array-like variable.
  */
 const forEach = (f) => (x) => Array.prototype.forEach.call(x, f);
 
+// TODO(Trevor): Not referenced anywhere. Remove?
 export default forEach;

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

@@ -1,9 +1,10 @@
+// @ts-check
 import cloneEvent from './clone-event';
 
 /**
  * Forward an event by cloning and dispatching it.
- * @param   {object}  event  Event to be forwarded.
- * @param   {object}  target  Target HTML element for the event.
+ * @param {Event} event - Event to be forwarded.
+ * @param {HTMLElement} target - Target HTML element for the event.
  */
 const forwardEvent = (event, target) => {
   target.dispatchEvent(cloneEvent(event));

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

@@ -1,5 +1,13 @@
+// @ts-check
 import chrToAbs from './chr-to-abs';
 
+/**
+ * Convert a genome locus to an absolute genome position.
+ * @template {string} Name
+ * @param {[Name, number, Name, number]} genomeLoci - Genome locus
+ * @param {import('../types').ChromInfo<Name>} chromInfo - Chromosome info object
+ * @return {[start: number, end: number]} The absolute genome position.
+ */
 const genomeLociToPixels = (genomeLoci, chromInfo) => [
   chrToAbs(genomeLoci[0], genomeLoci[1], chromInfo),
   chrToAbs(genomeLoci[2], genomeLoci[3], chromInfo),

package/app/scripts/utils/genomic-range-to-chromosome-chunks.js

@@ -1,13 +1,17 @@
+// @ts-check
+
 /**
  * Using the [genomicStart, genomicEnd] range, get an array of "chromosome chunks",
  * where each chunk range starts and ends with the same chromosome.
  * Start a new chromosome chunk at each chromosome boundary.
- * @param {array} chromSizes Array of [chrName, chrLen] tuples.
- * @param {object} genomicStart A genomic position object returned from abs2genomic { chr, pos }.
- * @param {object} genomicEnd A genomic position object returned from abs2genomic { chr, pos }.
- * @param {number} binSize The resolution / bin size.
- * @param {number} tileSize The tile size (probably 256).
- * @returns {array} Returns array of [chrName, zStart, zEnd] tuples.
+ *
+ * @template {string} Name
+ * @param {Array<[charName: Name, chrLen: number]>} chromSizes - Array of [chrName, chrLen] tuples.
+ * @param {{ chr: Name, pos: number }} genomicStart - A genomic position object returned from abs2genomic { chr, pos }.
+ * @param {{ chr: Name, pos: number }} genomicEnd - A genomic position object returned from abs2genomic { chr, pos }.
+ * @param {number} binSize - The resolution / bin size.
+ * @param {number} tileSize - The tile size (probably 256).
+ * @returns {Array<[chrName: Name, zStart: number, zEnd: number]>} Returns array of [chrName, zStart, zEnd] tuples.
  */
 function genomicRangeToChromosomeChunks(
   chromSizes,
@@ -19,6 +23,7 @@ function genomicRangeToChromosomeChunks(
   const { chr: chrStart, pos: chrStartPos } = genomicStart;
   const { chr: chrEnd, pos: chrEndPos } = genomicEnd;
 
+  /** @type {Array<[chrName: Name, zStart: number, zEnd: number]>} */
   const chrChunks = [];
   if (chrStart === chrEnd) {
     // This tile does _not_ cross a chromosome boundary.
@@ -37,7 +42,9 @@ function genomicRangeToChromosomeChunks(
 
     // Create a separate chunk for each chromosome that lies within the range.
     for (let chrIndex = chrStartIndex; chrIndex <= chrEndIndex; chrIndex++) {
+      /** @type {number} */
       let chrChunkStart;
+      /** @type {number} */
       let chrChunkEnd;
 
       const [currChrName, currChrLen] = chromSizes[chrIndex];

package/app/scripts/utils/get-aggregation-function.js

@@ -1,11 +1,18 @@
+// @ts-check
 import { mean, sum, variance, deviation } from 'd3-array';
 
 /**
  * Get an aggregation function from a function name.
- * @param {string} name The name of an aggregation function
+ * @template {'mean' | 'sum' | 'variance' | 'deviation'} Type
+ * @param {Type} name - The name of an aggregation function
  * ('mean', 'sum', 'variance', 'deviation'). If an unknown string is passed,
  * the mean function will be used, and a console warning will be thrown.
- * @returns {function} The function of interest as determined by the string,
+ * @returns {{
+ *  mean: typeof mean,
+ *  sum: typeof sum,
+ *  variance: typeof variance,
+ *  deviation: typeof deviation,
+ * }[Type]} The function of interest as determined by the string,
  */
 const getAggregationFunction = (name) => {
   let aggFunc;
@@ -29,6 +36,7 @@ const getAggregationFunction = (name) => {
         'Encountered an unsupported selectedRowsAggregationMode option.',
       );
   }
+  // @ts-expect-error - TS can't infer type-mapping
   return aggFunc;
 };
 

package/app/scripts/utils/get-element-dim.js

@@ -1,5 +1,11 @@
+// @ts-check
 import { ElementResizeListener } from '../services';
 
+/**
+ * Get the dimensions of an element
+ * @param {HTMLElement} element - DOM element to get dimensions of.
+ * @return {[width: number, height: number]} The width and height of the element.
+ */
 const getElementDim = (element) => {
   ElementResizeListener.listen();
 

package/app/scripts/utils/gradient.js

@@ -1,3 +1,14 @@
+// @ts-check
+
+/**
+ * @param {{ from: number, color: string }[]} steps
+ * @param {number} width
+ * @param {number} height
+ * @param {number} fromX
+ * @param {number} fromY
+ * @param {number} toX
+ * @param {number} toY
+ */
 const gradient = (
   steps,
   width = 1,
@@ -12,6 +23,9 @@ const gradient = (
   canvas.height = height;
 
   const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    throw new Error('Could not get canvas context');
+  }
   const grd = ctx.createLinearGradient(fromX, fromY, toX, toY);
 
   steps.forEach((step) => {

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

@@ -1,15 +1,17 @@
+// @ts-check
+
 const XMLNS = 'http://www.w3.org/2000/svg';
 
 /**
  * Check if an HTML or SVG element has a certain class
- * @param   {object}  el  HTML or SVG element to be checked.
- * @param   {string}  className  Class name to be checked for.
- * @return  {boolean}  If `true` `el` has the class name.
+ * @param {Element} el - HTML or SVG element to be checked.
+ * @param {string} className - Class name to be checked for.
+ * @return {boolean} If `true` `el` has the class name.
  */
 const hasClass = (el, className) => {
   if (el.namespaceURI === XMLNS) {
     const _class = el.getAttribute('class');
-    return _class && !!_class.match(new RegExp(`(\\s|^)${className}(\\s|$)`));
+    return !!_class && !!_class.match(new RegExp(`(\\s|^)${className}(\\s|$)`));
   }
 
   if (el.classList) return el.classList.contains(className);

package/app/scripts/utils/hex-string-to-int.js

@@ -1,8 +1,15 @@
+// @ts-check
 /**
- * Convert a HEX string into a HEX integer. E.g., #FF0000 is translated to
- *   16711680.
- * @param   {string}  str  HEX string
- * @return  {integer}  HEX number
+ * Convert a HEX string into a HEX integer.
+ *
+ * @example
+ * ```js
+ * // returns 16711680
+ * hexStrToInt("#FF0000");
+ * ```
+ *
+ * @param {string} str - HEX string
+ * @return {number} An (integer) HEX number
  */
 const hexStrToInt = (str) => parseInt(str.replace(/^#/, ''), 16);
 

package/app/scripts/utils/index.js

@@ -1,3 +1,4 @@
+// @ts-check
 export { default as absToChr } from './abs-to-chr';
 export { default as accessorTransposition } from './accessor-transposition';
 export { default as addArrays } from './add-arrays';

package/app/scripts/utils/into-the-void.js

@@ -1,6 +1,7 @@
+// @ts-check
 /**
  * An adventure into the abyss of void!
- * @return  {undefined}  The explorers find nothing but void.
+ * @type {(...args: any[]) => void}  The explorers find nothing but void.
  */
 const intoTheVoid = () => {};
 

package/app/scripts/utils/is-track-or-child-track.js

@@ -1,5 +1,11 @@
+// @ts-check
 import CombinedTrack from '../CombinedTrack';
 
+/**
+ * @param {import('../types').TrackObject} testTrack
+ * @param {import('../types').TrackObject} track
+ * @returns {boolean}
+ */
 const isTrackOrChildTrack = (testTrack, track) => {
   if (track === testTrack) return true;
   if (track instanceof CombinedTrack) {

package/app/scripts/utils/is-track-range-selectable.js

@@ -1,5 +1,11 @@
+// @ts-check
 import or from './or';
 
+/**
+ * Return true if this track is selectable by range.
+ * @param {import('../types').TrackConfig} track
+ * @returns {boolean}
+ */
 export const IS_TRACK_RANGE_SELECTABLE = (track) => {
   switch (track.type) {
     case 'heatmap':
@@ -24,7 +30,10 @@ export const IS_TRACK_RANGE_SELECTABLE = (track) => {
       return true;
 
     case 'combined': {
-      return track.contents
+      /** @type {import('../types').TrackConfig[]} */
+      // @ts-expect-error - TS should be able to narrow the type but isn't smart enough
+      const contents = track.contents;
+      return contents
         .map((t) => IS_TRACK_RANGE_SELECTABLE(t))
         .reduce(or, false);
     }

package/app/scripts/utils/is-within.js

@@ -1,12 +1,14 @@
+// @ts-check
+
 /**
  * Check if a 2D or 1D point is within a rectangle or range
- * @param   {number}  x  The point's X coordinate.
- * @param   {number}  y  The point's Y coordinate.
- * @param   {number}  minX  The rectangle's start X coordinate.
- * @param   {number}  maxX  The rectangle's start X coordinate.
- * @param   {number}  minY  The rectangle's start X coordinate.
- * @param   {number}  maxY  The rectangle's start X coordinate.
- * @return  {boolean}  If `true` the [x,y] point is in the rectangle.
+ * @param {number} x - The point's X coordinate.
+ * @param {number} y - The point's Y coordinate.
+ * @param {number} minX - The rectangle's start X coordinate.
+ * @param {number} maxX - The rectangle's start X coordinate.
+ * @param {number} minY - The rectangle's start X coordinate.
+ * @param {number} maxY - The rectangle's start X coordinate.
+ * @return {boolean} If `true` the [x,y] point is in the rectangle.
  */
 const isWithin = (x, y, minX, maxX, minY, maxY, is1d = false) =>
   is1d

package/app/scripts/utils/lat-to-y.js

@@ -1,10 +1,13 @@
+// @ts-check
+
+/** @param {number} y */
 export const invGudermannian = (y) => Math.log(Math.tan((y + Math.PI / 2) / 2));
 
 /**
  * Translate latitude to Y in the Mercator projection
- * @param   {number}  lat  Latitude.
- * @param   {number}  zoom  Zoom level
- * @return  {number}  Y coordinate in the Mercator projection.
+ * @param {number} lat - Latitude.
+ * @param {number} zoom - Zoom level
+ * @return {number} Y coordinate in the Mercator projection.
  */
 const latToY = (lat, zoom) => {
   let latRad = (lat * Math.PI) / 180.0;

package/app/scripts/utils/lng-to-x.js

@@ -1,8 +1,9 @@
+// @ts-check
 /**
  * Convert longitude to the X coordinate in the Mercator projection.
- * @param   {number}  lng  Longitude
- * @param   {number}  zoom  Zoom level
- * @return  {number}  X coordinate in the Mercator projection.
+ * @param {number} lng - Longitude
+ * @param {number} zoom - Zoom level
+ * @return {number} X coordinate in the Mercator projection.
  */
 const lngToX = (lng, zoom) => (2 ** zoom * (lng + 180.0)) / 360.0;
 

package/app/scripts/utils/map.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * Exposed map function. You can do cool stuff with that!
  *
@@ -5,9 +6,11 @@
  * The pure map function is more powerful because it can be used on data types
  * other than Array too.
  *
- * @param {Function}  f  Mapping function.
- * @return {Array}  Mapped array.
+ * @template T, B
+ * @param {(item: T, idx?: number) => B} f - Mapping function.
+ * @return {(x: Array<T>) => Array<B>} Mapped array.
  */
+// @ts-expect-error - TS can't infer the type of the returned function.
 const map = (f) => (x) => Array.prototype.map.call(x, f);
 
 export default map;

package/app/scripts/utils/max-non-zero.js

@@ -1,5 +1,11 @@
+// @ts-check
 const epsilon = 0.0000001;
 
+/**
+ * Calculate the maximum non-zero value in the data
+ * @param {ArrayLike<number>} data - An array of values
+ * @returns {number} The maximum non-zero value in the array
+ */
 export default function maxNonZero(data) {
   /**
    * Calculate the minimum non-zero value in the data

package/app/scripts/utils/max.js

@@ -1,10 +1,11 @@
+// @ts-check
 /**
  * Fast version of `Math.max`. Based on
  *   https://jsperf.com/math-min-max-vs-ternary-vs-if/24 `Math.max` is not
  *   very fast
- * @param   {number}  a  Value A
- * @param   {number}  b  Value B
- * @return  {boolean}  If `true` A is greater than B.
+ * @param {number} a - Value A
+ * @param {number} b - Value B
+ * @return {number} If `true` A is greater than B.
  */
 const max = (a, b) => (a > b ? a : b);
 

package/app/scripts/utils/min-non-zero.js

@@ -1,5 +1,11 @@
+// @ts-check
 const epsilon = 0.0000001;
 
+/**
+ * Calculate the minimum non-zero value in the data
+ * @param {ArrayLike<number>} data - An array of values
+ * @returns {number} The minimum non-zero value in the array
+ */
 export default function minNonZero(data) {
   /**
    * Calculate the minimum non-zero value in the data

package/app/scripts/utils/min.js

@@ -1,10 +1,11 @@
+// @ts-check
 /**
  * Fast version of `Math.min`. Based on
  *   https://jsperf.com/math-min-max-vs-ternary-vs-if/24 `Math.max` is not
  *   very fast
- * @param   {number}  a  Value A
- * @param   {number}  b  Value B
- * @return  {boolean}  If `true` A is smaller than B.
+ * @param {number} a - Value A
+ * @param {number} b - Value B
+ * @return {number} If `true` A is smaller than B.
  */
 const min = (a, b) => (a < b ? a : b);
 

package/app/scripts/utils/mod.js

@@ -1,9 +1,10 @@
+// @ts-check
 /**
  * Non-negative modulo function. E.g., `mod(-1, 5) === 4` while `-1 % 5 === -1`.
  *
- * @param  {Integer}  n  Dividend
- * @param  {Integer}  m  Divisor
- * @return  {Integer}  Remainder
+ * @param {number} n - Dividend (integer)
+ * @param {number} m - Divisor (integer)
+ * @return {number} Remainder (integer)
  */
 const mod = (n, m) => ((n % m) + m) % m;
 

package/app/scripts/utils/numericify-version.js

@@ -1,3 +1,8 @@
+// @ts-check
+/**
+ * @param {string} version
+ * @returns {number}
+ */
 const numericifyVersion = (version) => {
   const parts = version.split('.');
   const tailLen = parts.slice(1).join('').length;

package/app/scripts/utils/obj-vals.js

@@ -3,9 +3,10 @@ import map from './map';
 /**
  * Convert an object into array which entries are the prop values of the object
  *
- * @param {Object}  obj  Object to be arrayified
- * @return {Array}  Array of the object.
+ * @param {Object} obj - Object to be arrayified
+ * @return {Array} Array of the object.
  */
 const objVals = (obj) => map((key) => obj[key])(Object.keys(obj));
 
+// TODO(Trevor): We already have dictValues and `Object.values`? Can we get rid of this?
 export default objVals;

package/app/scripts/utils/or.js

@@ -1,8 +1,9 @@
+// @ts-check
 /**
  * Logical or operator for convenience.
- * @param   {*}  a  Value A
- * @param   {*}  b  Value B
- * @return  {boolean}  If `true` one of the two or both values are truthy.
+ * @param {boolean} a - Value A
+ * @param {boolean} b - Value B
+ * @return {boolean} If `true` one of the two or both values are truthy.
  */
 const or = (a, b) => a || b;
 

package/app/scripts/utils/parse-chromsizes-rows.js

@@ -1,13 +1,34 @@
+// @ts-check
+
+/** @typedef {[string, number]} ChromsizeRow */
+
+/**
+ * @typedef CumulativeChromsizeEntry
+ * @property {number} id
+ * @property {string} chr
+ * @property {number} pos
+ */
+
+/**
+ * @typedef ParsedChromsizes
+ * @property {CumulativeChromsizeEntry[]} cumPositions
+ * @property {Record<string, CumulativeChromsizeEntry>} chrPositions
+ * @property {number} totalLength
+ * @property {Record<string, number>} chromLengths
+ */
+
 /**
- * Parse an array of chromsizes, for example that result
- * from reading rows of a chromsizes CSV file.
- * @param {array} data Array of [chrName, chrLen] "tuples".
- * @returns {object} Object containing properties
- * { cumPositions, chrPositions, totalLength, chromLengths }.
+ * Parse an array of chromsizes, for example that result from reading rows of a chromsizes CSV file.
+ *
+ * @param {ArrayLike<ChromsizeRow>} data - Array of [chrName, chrLen] "tuples".
+ * @returns {ParsedChromsizes}
  */
 function parseChromsizesRows(data) {
+  /** @type {Array<CumulativeChromsizeEntry>} */
   const cumValues = [];
+  /** @type {Record<string, number>} */
   const chromLengths = {};
+  /** @type {Record<string, CumulativeChromsizeEntry>} */
   const chrPositions = {};
 
   let totalLength = 0;

package/app/scripts/utils/q.js

@@ -11,8 +11,8 @@
  *   console.log(myFancyQuery(myFancyObj)) ==> 'Sweet!'
  *   console.log(myFancyQuery(myNotSoFancyObj)) ==> undefined
  *   ```
- * @param   {[type]}  queryStr  [description]
- * @return  {[type]}  [description]
+ * @param {string} queryStr - dot-notation query string
+ * @return {unknown}
  */
 const q = (queryStr) => {
   try {
@@ -29,4 +29,5 @@ const q = (queryStr) => {
   }
 };
 
+// TODO(Trevor): This is not referenced anywhere in the codebase, but it is exported. Remove?
 export default q;

package/app/scripts/utils/rad-to-deg.js

@@ -1,7 +1,8 @@
+// @ts-check
 /**
  * Convert radiance to degree
- * @param   {number}  rad  Radiance
- * @return  {number}  Degree
+ * @param {number} rad - Radiance
+ * @return {number} Degree
  */
 const radToDeg = (rad) => (rad * 180) / Math.PI;
 

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;