Gradual Typing of HiGlass Codebase

[manzt]

This issue will serve as a tracker for our gradual transition toward a typed codebase.

Motivation

We want to introduce type safety into HiGlass code base for improved maintainability and static error-checking. Adding types will make it easier to make planned refactors (#1150) as well provide types to end users #1108 and libraries using HiGlass (e.g. Gosling).

Approach

We have chosen to adopt TypeScript via JSDoc. Rather than using TypeScript syntax, you annotation your code with types via comments:

// index.ts (TypeScript)
const person: Person = { name: "Trevor" };

// index.js (JavaScript with comments)
/** @type {Person} */
const person = { name: "Trevor" };

The TypeScript compiler can type-check both of these files the same way. Since HiGlass already includes some JSDoc annotations, using TypeScript via JSDoc seems to be the most minimal path forward in gradually introducing type-checking to the code base. In the future this could change, but currently this is the outlined approach.

Contributing

Adding types is an excellent way for newcomers to contribute to HiGlass. Right now, we are prioritizing typing the Track files. Steps to contribute:

• Familiarize yourself with TypeScript and specifically TypeScript via JSDoc
• Pick an unannotated file from below
• Remove // @ts-nocheck to the top of the file
• Address TypeScript errors (red squiggly lines)
• Run npm run typecheck without any errors

In order to get the most value out of this migration, it's essential to maximize the strictness of types. This helps us have greater confidence when making changes to the codebase in the future. While TypeScript offers "escape hatches" to opt-out of strict type-checking, it's rare that these should be used.

Best Practices:

1. Avoid any, Use unknown: The use of any type should be avoided. Instead, prefer the use of unknown if you really don't know the type.

2. Custom Type Guards: Employ custom type guards to narrow down complex types and make them more understandable and manageable.

3. Use of // @ts-expect-error - COMMENT WHY: This should only be a last resort. If used, always accompany it with a comment explaining why the strict type-checking is being bypassed. @ts-expect-error is preferred over @ts-ignore or any because TypeScript will tell you if it's no longer needed in the future (i.e., there is no longer a TS error). The other mechanisms of turning off the type-checker will likely stay in the codebase forever.

You can refer to #1161 for examples of this type of adding types.

Progress (priority for Gosling.js)

If you are looking to contribute, we are currently prioritizing typing the files including interfaces used by Gosling.js.

• ☂️ Typing Gosling related code (Priority) #1172

Remaining

Tracks

• ☂️ Type annotations for Pixi Tracks #1175

app/scripts/configs

• configs/available-track-types.js
• configs/colormaps.js
• configs/datatype-to-track-type.js
• configs/default-tracks-for-datatype.js
• configs/dense-data-extrema-config.js
• configs/globals.js
• configs/index.js
• configs/positions-by-datatype.js
• configs/primitives.js
• configs/themes.js
• configs/tracks-info-by-type.js
• configs/tracks-info.js

app/scripts/data-fetchers

• data-fetchers/genbank-fetcher.js
• data-fetchers/index.js
• data-fetchers/local-tile-fetcher.js

app/scripts/hocs

• hocs/with-modal.jsx
• hocs/with-pub-sub.jsx
• hocs/with-theme.jsx

app/scripts/plugins

• plugins/get-data-fetcher.js
• plugins/index.js

app/scripts/services

• services/chrom-info.js
• services/dom-event.js
• services/element-resize-listener.js
• services/index.js
• services/tile-proxy.js
• services/worker.js

app/scripts/test-helpers

• test-helpers/index.jsx

app/scripts/utils

• ☂️ Type annotations for app/scripts/utils #1174

app/scripts

• AddTrackDialog.jsx
• AddTrackPositionMenu.jsx
• api.js
• Autocomplete.jsx
• Button.jsx
• CenterTiledPlot.jsx
• CenterTrack.jsx
• Chromosome2DAnnotations.js
• Chromosome2DLabels.js
• ChromosomeGrid.js
• ChromosomeInfo.js
• CloseTrackMenu.jsx
• ConfigTrackMenu.jsx
• ConfigureSeriesMenu.jsx
• ConfigViewMenu.jsx
• ContextMenuContainer.jsx
• ContextMenuItem.jsx
• Cross.jsx
• CustomTrackDialog.jsx
• d3-context-menu.js
• Dialog.jsx
• DraggableDiv.jsx
• DragListeningDiv.jsx
• ExportLinkDialog.jsx
• FixedTrack.jsx
• GalleryTracks.jsx
• GenomePositionSearchBox.jsx
• HeatmapOptions.jsx
• hglib.jsx
• HiGlassComponent.jsx
• HiGlassTrackComponent.jsx
• HorizontalItem.jsx
• HorizontalTiledPlot.jsx
• HorizontalTrack.jsx
• icons.jsx
• ListWrapper.jsx
• mixwith.js
• Modal.jsx
• MoveableTrack.jsx
• NestedContextMenu.jsx
• options-info.js
• PlotTypeChooser.jsx
• PopupMenu.jsx
• RuleMixin.js
• SearchField.js
• SeriesListItems.jsx
• SeriesListMenu.jsx
• SeriesListSubmenuMixin.jsx
• SketchInlinePicker.jsx
• SortableList.jsx
• symbol.js
• TiledPlot.jsx
• TilesetFinder.jsx
• TrackArea.jsx
• TrackControl.jsx
• TrackRenderer.jsx
• VerticalItem.jsx
• VerticalTiledPlot.jsx
• ViewConfigEditor.jsx
• ViewContextMenu.jsx
• ViewHeader.jsx