# ucsc-hub-js

Read and write UCSC track and assembly hub files in Node or the browser.

[![NPM version](https://img.shields.io/npm/v/@gmod/ucsc-hub.svg?logo=npm&style=flat-square)](https://npmjs.org/package/@gmod/ucsc-hub)
![Build Status](https://img.shields.io/github/actions/workflow/status/GMOD/ucsc-hub-js/publish.yml?branch=main)

## Install

```sh
npm install @gmod/ucsc-hub
```

## Usage

See the
[UCSC track hub documentation](https://genome.ucsc.edu/goldenpath/help/hgTrackHubHelp.html)
for the hub.txt, genomes.txt, and trackDb.txt file formats.

```js
import {
  HubFile,
  GenomesFile,
  TrackDbFile,
  SingleFileHub,
} from '@gmod/ucsc-hub'

const hub = new HubFile(hubText)
console.log(hub.data.shortLabel)

const genomes = new GenomesFile(genomesText)
console.log(genomes.data['hg38'].data.trackDb)

const trackDb = new TrackDbFile(trackDbText)
console.log(trackDb.settings('myTrack'))

const singleHub = new SingleFileHub(hubText)
console.log(singleHub.hubData, singleHub.genome, singleHub.tracks)
```

## API

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

#### Table of Contents

- [GenomesFile](#genomesfile)
  - [Parameters](#parameters)
- [HubFile](#hubfile)
  - [Parameters](#parameters-1)
- [RaFile](#rafile)
  - [Parameters](#parameters-2)
  - [Properties](#properties)
- [RaStanza](#rastanza)
  - [Parameters](#parameters-3)
- [SingleFileHub](#singlefilehub)
  - [Parameters](#parameters-4)
- [TrackDbFile](#trackdbfile)
  - [Parameters](#parameters-5)
  - [settings](#settings)
    - [Parameters](#parameters-6)

### GenomesFile

**Extends RaFile**

Class representing a genomes.txt file.

#### Parameters

- `genomesFile`
  **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
  |
  [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)**
  A genomes.txt file as a string (optional, default `[]`)

<!---->

- Throws
  **[Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error)**
  Throws if the first line of the genomes.txt file doesn't start with "genome
  \<genome_name>" or if it has invalid entries

### HubFile

**Extends RaStanza**

Class representing a hub.txt file.

#### Parameters

- `hubFile`
  **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
  |
  [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)**
  A hub.txt file as a string (optional, default `[]`)

<!---->

- Throws
  **[Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error)**
  Throws if the first line of the hub.txt file doesn't start with "hub
  \<hub_name>", if it has invalid entries, or is missing required entries

### RaFile

Class representing an ra file. Each file is composed of multiple stanzas, and
each stanza is separated by one or more blank lines. Each stanza is stored in a
Map with the key being the value of the first key-value pair in the stanza. The
usual Map methods can be used on the file. An additional method `add()` is
available to take a raw line of text and break it up into a key and value and
add them to the class. This should be favored over `set()` when possible, as it
performs more validity checks than using `set()`.

#### Parameters

- `raFile`
  **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
  |
  [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)**
  An ra file, either as a single string or an array of strings with one stanza
  per entry. Supports both LF and CRLF line terminators. (optional, default
  `[]`)
- `options`
  **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**&#x20;
  - `options.checkIndent`
    **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)**
    \[true] - Check if a the stanzas within the file are indented consistently
    and keep track of the indentation

#### Properties

- `nameKey`
  **([undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)
  |
  [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))**
  The key of the first line of all the stanzas (`undefined` if the stanza has no
  lines yet).

<!---->

- Throws
  **[Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error)**
  Throws if an empty stanza is added, if the key in the first key-value pair of
  each stanza isn't the same, or if two stanzas have the same value for the
  key-value pair in their first lines.

### RaStanza

Class representing an ra file stanza. Each stanza line is split into its key and
value and stored as a Map, so the usual Map methods can be used on the stanza.

#### Parameters

- `stanza`
  **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
  |
  [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)**
  (optional, default `[]`)
- `options` **{checkIndent:
  [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?,
  skipValidation:
  [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?}?**&#x20;

### SingleFileHub

Class representing a "single-file" hub.txt file that contains all the sections
of a hub in a single file.

#### Parameters

- `hubText`
  **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;

### TrackDbFile

**Extends RaFile**

Class representing a trackDb.txt file.

#### Parameters

- `trackDbFile`
  **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)
  |
  [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)**
  A trackDb.txt file as a string (optional, default `[]`)
- `options` **any?**&#x20;

<!---->

- Throws
  **[Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error)**
  Throws if "track" is not the first key in each track or if a track is missing
  required keys

#### settings

Gets all track entries including those of parent tracks, with closer entries
overriding more distant ones

##### Parameters

- `trackName`
  **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
  The name of a track

<!---->

- Throws
  **[Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error)**
  Throws if track name does not exist in the trackDb

## License

MIT © [Generic Model Organism Database Project](http://gmod.org/wiki/Main_Page)

## Publishing

[Trusted publishing](https://docs.npmjs.com/about-trusted-publishing) via GitHub
Actions.

```bash
pnpm version patch  # or minor/major
```