initial airr-js package

.github/workflows/node.js.yml

@@ -9,15 +9,15 @@ on:
   pull_request:
     branches: [ "master" ]
 
-defaults:
-  run:
-    working-directory: lang/js
-
 jobs:
   build:
 
     runs-on: ubuntu-latest
 
+    defaults:
+      run:
+        working-directory: lang/js
+
     strategy:
       matrix:
         node-version: [18.x, 20.x, 22.x]
@@ -29,7 +29,7 @@ jobs:
       uses: actions/setup-node@v4
       with:
         node-version: ${{ matrix.node-version }}
-        cache: 'npm'
+#        cache: 'npm'
     - run: npm ci
     - run: npm run build --if-present
     - run: npm test

docker/Dockerfile

@@ -18,7 +18,8 @@ RUN export DEBIAN_FRONTEND=noninteractive && apt-get update && apt-get install -
     libfontconfig1-dev \
     libssl-dev \
     libharfbuzz-dev libfribidi-dev \
-    libfreetype6-dev libpng-dev libtiff5-dev libjpeg-dev
+    libfreetype6-dev libpng-dev libtiff5-dev libjpeg-dev \
+    nano
 
 RUN pip3 install \
     pandas \
@@ -33,13 +34,27 @@ RUN pip3 install \
 # Install R devtools
 RUN R -e 'install.packages(c("devtools","knitr","rmarkdown","testthat","readr"),dependencies=T)'
 
+# node
+ENV NODE_VER=v14.21.3
+RUN wget https://nodejs.org/dist/$NODE_VER/node-$NODE_VER-linux-x64.tar.xz
+RUN tar xf node-$NODE_VER-linux-x64.tar.xz
+RUN cp -rf /node-$NODE_VER-linux-x64/bin/* /usr/bin
+RUN cp -rf /node-$NODE_VER-linux-x64/lib/* /usr/lib
+RUN cp -rf /node-$NODE_VER-linux-x64/include/* /usr/include
+RUN cp -rf /node-$NODE_VER-linux-x64/share/* /usr/share
+
 # Copy source
 RUN mkdir /airr-standards
 COPY . /airr-standards
 
 # Install python package
 RUN cd /airr-standards/lang/python && pip3 install .
 
+# nodejs package
+RUN cd /airr-standards/lang/js && npm install
+RUN cd /airr-standards/lang/js && npm run eslint
+RUN cd /airr-standards/lang/js && npm run test
+
 # Generate the documentation
 RUN cd /airr-standards && pip3 install -r docs/requirements.txt
 RUN cd /airr-standards && sphinx-build -a -E -b html docs docs/_build/html

docs/packages/airr-js/news.rst

@@ -0,0 +1,6 @@
+.. _JavaScriptNews:
+
+JavaScript Library Release Notes
+=================================
+
+.. include:: ../../../lang/js/NEWS.rst

docs/packages/airr-js/overview.rst

@@ -0,0 +1,17 @@
+.. _JavaScriptOverview:
+
+AIRR JavaScript Reference Library
+===============================================================================
+
+The ``airr-js`` reference library provides basic functions and classes for
+interacting with AIRR Community Data Representation Standards, including tools
+for read, write and validation. The library can be used in the browser or nodejs.
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Table of Contents
+
+    Release Notes <news>
+
+.. include:: ../../../lang/js/README.rst
+

docs/software.rst

@@ -10,6 +10,7 @@ AIRR Standards Reference Implementations
 
     Python Library <packages/airr-python/overview>
     R Library <packages/airr-R/overview>
+    JavaScript Library <packages/airr-js/overview>
     ADC API Reference Implementation <api/reference>
 
 Resources and Tools Supporting AIRR Standards

lang/R/inst/extdata/airr-schema.yaml

@@ -1665,7 +1665,6 @@ DeletedGene:
                 Chromosomal phasing indicator. Alleles with the same value are inferred to be located on the 
                 same chromosome.
 
-
 # List of MHCGenotypes describing a subject's genotype
 MHCGenotypeSet:
     type: object

lang/js/.eslintrc.json

@@ -0,0 +1,16 @@
+{
+    "env": {
+        "es2021": true,
+        "node": true
+    },
+    "extends": "eslint:recommended",
+    "parserOptions": {
+        "ecmaVersion": 12,
+        "sourceType": "module"
+    },
+    "rules": {
+        "no-unused-vars": 0,
+        "no-redeclare": 0,
+        "no-prototype-builtins": 1
+    }
+}

lang/js/NEWS.rst

@@ -0,0 +1,4 @@
+Version 2.0.0:  DATE
+--------------------------------------------------------------------------------
+
+Initial release.

lang/js/README.rst

@@ -0,0 +1,162 @@
+Installation
+------------------------------------------------------------------------------
+
+Install in the usual manner from npm::
+
+    > npm install airr-js
+
+Or from the `downloaded <https://github.com/airr-community/airr-standards>`__
+source code directory::
+
+    > npm install file:lang/js
+
+
+Quick Start
+------------------------------------------------------------------------------
+
+The ``airr-js`` package supports use in the browser or in nodejs. In the browser, the
+file system is not available, so the read/write functions are not implemented but template
+objects can be created, objects can be validated, and the OpenAPI V3 specification can be
+accessed. For nodejs, the full functionality is available including the read/write functions.
+
+For nodejs, need to await the loading of the schema before using any functions::
+
+    var airr = require('airr-js');
+
+    // await schema to be loaded and dereferenced
+    var spec = await airr.load_schema();
+
+For the browser, the schema also needs to be loaded but the package cannot do it itself,
+instead you must provide the Open API V3 specification file as part of your packaging
+of the website. When using webpack, a resolve alias in ``webpack.config.js`` can be used
+to point to the dereferenced yaml file::
+
+    resolve: {
+        alias: {
+            'airr-schema': path.resolve(__dirname,'node_modules') + '/airr-js/airr-schema-openapi3-deref.yaml'
+        }
+    }
+
+The ``package.json`` utilizes the ``browser`` setting supported by website packaging tools
+like webpack to provide an alternative entry point, and browser code can import like so::
+
+    import { airr } from 'airr-js';
+
+The read and write functions for AIRR Rearrangement TSV files support gzip compressed
+data. File names that end with ``.gz`` extension will automatically be uncompressed
+when reading or automatically compressed when writing.
+
+Create Blank Template Schema Objects (browser, nodejs)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Import the ``airr-js`` package correctly depending upon browser or nodejs usage as
+described above, and then blank template objects can be created::
+
+    // Get the schema definition for an AIRR Object
+    var repertoire_schema = new airr.SchemaDefinition('Repertoire');
+    // Create a template object
+    var blank_repertoire = repertoire_schema.template();
+
+Validate Objects (browser, nodejs)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Import the ``airr-js`` package correctly depending upon browser or nodejs usage as
+described above, and then an object can be validated to its schema::
+
+    // Get the schema definition for an AIRR Object
+    var repertoire_schema = new airr.SchemaDefinition('Repertoire');
+    // Validate a repertoire object
+    var is_valid = repertoire_schema.validate_object(obj);
+
+Reading AIRR Data Files (nodejs)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``airr-js`` package contains functions to read and write AIRR Data
+Model files. The file format is either YAML or JSON, and the package provides a
+light wrapper over the standard parsers. The file needs a ``json``, ``yaml``, or ``yml``
+file extension so that the proper parser is utilized. All of the AIRR objects
+are loaded into memory at once and no streaming interface is provided::
+
+    var airr = require('airr-js');
+    await airr.load_schema();
+
+    // read AIRR DataFile
+    var data = await airr.read_airr('input.airr.json');
+
+Writing AIRR Data Files (nodejs)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Writing an AIRR Data File is also a light wrapper over standard YAML or JSON
+parsers. Multiple AIRR objects, such as Repertoire, GermlineSet, and etc., can be
+written together into the same file. In this example, we create some blank
+Repertoire objects, and write them to a file.
+As with the read function, the complete list of repertoires are written at once,
+there is no streaming interface::
+
+    var airr = require('airr-js');
+    await airr.load_schema();
+
+    // Create some blank repertoire objects in a list
+    var repertoire_schema = new airr.SchemaDefinition('Repertoire');
+    var data = { 'Repertoire': [] };
+    for (let i = 0; i < 5; ++i)
+        data['Repertoire'].push(repertoire_schema.template());
+
+    // Write the AIRR Data
+    await airr.write_airr('output.airr.json', data);
+
+Reading AIRR Rearrangement TSV files (nodejs)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``airr-js`` package contains functions to read AIRR Rearrangement
+TSV files as either a stream or the complete file. The streaming interface requires
+two callback functions to be provided; one for the header and another for each
+row as it is read. The callback functions can be synchronous or they can
+return a Promise::
+
+    var airr = require('airr-js');
+    await airr.load_schema();
+
+    // read file completely
+    var data = await airr.load_rearrangement('input.airr.tsv');
+
+    // for streaming, need two callback functions
+    var header_callback = function(headers) { console.log('got headers:', headers); }
+    var row_callback = function(row) { console.log('got row:', row); }
+    // read the file
+    await airr.read_rearrangement('input.airr.tsv', header_callback, row_callback);
+
+Writing AIRR Rearrangement TSV files (nodejs)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``airr-js`` package contains functions to write AIRR Rearrangement
+TSV files as either a stream or the complete file. The streaming interface requires
+a callback function which provides the data for each row or returns ``null`` to indicate
+no more data. The callback function can be synchronous or it can return a Promise::
+
+    var airr = require('airr-js');
+    await airr.load_schema();
+
+    // read some data
+    var data = await airr.load_rearrangement('input.airr.tsv');
+
+    // write file completely
+    var data = await airr.load_rearrangement(data, 'output.airr.tsv');
+
+    // for streaming, need a callback function to provide the row data
+    var idx = 0;
+    var row_callback = function(fields) {
+        if (idx >= data.length) return null;
+        else return data[idx++];
+    };
+    // write the file
+    await airr.create_rearrangement('output.airr.tsv', row_callback)
+
+    // callback function which returns a promise
+    var row_callback = function(fields) {
+        return new Promise(function(resolve, reject) {
+            // acquire some data asynchronously, e.g. from a database
+            row = await read_from_database();
+            return resolve(row);
+        });
+    };

lang/js/airr-browser.js

@@ -0,0 +1,23 @@
+'use strict';
+
+//
+// airr-browser.js
+// AIRR Standards reference library for antibody and TCR sequencing data
+// browser edition
+//
+// Copyright (C) 2023 The AIRR Community
+//
+// Author: Scott Christley <[email protected]>
+//
+
+// The I/O file routines are not provided with the browser edition.
+
+// For webpack, we are utilizing the browser entry in package.json
+// Are we assuming Webpack?
+
+export var airr = {};
+
+// the specification, resolved by webpack
+import AIRRSchema from 'airr-schema';
+// schema functions
+var schema = require('./schema')(airr, AIRRSchema);