readers/ArtifactDB-zipped.js

  1. import * as adb from "./ArtifactDB-abstract.js";
  2. import JSZip from "jszip";
  3. import * as afile from "./abstract/file.js";
  5. class ZippedProjectNavigator {
  6.     #zipfile;
  7.     #ziphandle;
  9.     constructor(zipfile, ziphandle) {
  10.         this.#zipfile = zipfile;
  11.         this.#ziphandle = null;
  12.     }
  14.     async file(path) {
  15.         if (this.#ziphandle == null) {
  16.             this.#ziphandle = await JSZip.loadAsync(this.#zipfile.buffer());
  17.         }
  18.         return await this.#ziphandle.file(path).async("uint8array");
  19.     }
  21.     async metadata(path) {
  22.         if (this.#ziphandle == null) {
  23.             this.#ziphandle = await JSZip.loadAsync(this.#zipfile.buffer());
  24.         }
  26.         while (1) {
  27.             if (!path.endsWith(".json")) { 
  28.                 path += ".json";
  29.             }
  31.             let contents = await this.#ziphandle.file(path).async("string");
  32.             let values = JSON.parse(contents);
  34.             if (values["$schema"].startsWith("redirection/")){
  35.                 path = values.redirection.targets[0].location;
  36.             } else {
  37.                 return values;
  38.             }
  39.         }
  40.     }
  42.     clear() {
  43.         this.#ziphandle = null;
  44.     }
  45. };
  47. /**
  48.  * Search a ZIP file for SummarizedExperiments to use in {@linkplain ZippedArtifactdbDataset} or {@linkplain ZippedArtifactdbResult}.
  49.  *
  50.  * @param {JSZip} handle - A handle into the ZIP file, generated using the [**JSZip**](https://stuk.github.io/jszip/) package.
  51.  * 
  52.  * @return {Map} Object where the keys are the paths/names of possible SummarizedExperiment objects,
  53.  * and each value is a 2-element array of dimensions.
  54.  */
  55. export async function searchZippedArtifactdb(handle) {
  56.     // Sorting by the number of slashes.
  57.     let all_json = [];
  58.     for (const name of Object.keys(handle.files)) {
  59.         if (name.endsWith(".json")) {
  60.             all_json.push({ name: name, path: name.split("/") });
  61.         }
  62.     }
  63.     all_json.sort((a, b) => a.path.length - b.path.length);
  65.     let found_se = new Map;
  66.     let nonchildren = new Map;
  67.     let redirects = new Map;
  69.     for (const x of all_json) {
  70.         // Avoid loading JSONs for files in subdirectories of known SEs.
  71.         let current = found_se;
  72.         let already_found = false;
  74.         for (const comp of x.path) {
  75.             let val = current.get(comp);
  76.             if (typeof val === "undefined") {
  77.                 val = new Map;
  78.                 current.set(comp, val);
  79.             } else if (val === null) {
  80.                 already_found = true;
  81.                 break;
  82.             }
  83.             current = val;
  84.         }
  86.         // Otherwise, we load it in and peel out some information.
  87.         if (!already_found) {
  88.             let contents = await handle.file(x.name).async("string");
  89.             let values = JSON.parse(contents);
  90.             if ("summarized_experiment" in values) {
  91.                 nonchildren.set(values.path, values.summarized_experiment.dimensions);            
  92.             } else if (values["$schema"].startsWith("redirection/")) {
  93.                 redirects.set(values.path, values.redirection.targets[0].location);
  94.             }
  95.         }
  96.     }
  98.     for (const [rr, loc] of redirects) {
  99.         let found = nonchildren.get(loc);
  100.         if (typeof found !== "undefined") {
  101.             nonchildren.delete(loc);
  102.             nonchildren.set(rr, found);
  103.         }
  104.     }
  106.     return nonchildren;
  107. }
  109. /************************
  110.  ******* Dataset ********
  111.  ************************/
  113. /**
  114.  * Dataset as a ZIP file containing a SummarizedExperiment in the **ArtifactDB** representation,
  115.  * e.g., as produced by {@linkcode saveSingleCellExperiment}.
  116.  * Specifically, the ZIP file should contain the contents of an **ArtifactDB** project directory.
  117.  * This project directory may contain multiple objects; the SummarizedExperiment of interest is identified in the constructor.
  118.  *
  119.  * @extends AbstractArtifactdbDataset
  120.  */
  121. export class ZippedArtifactdbDataset extends adb.AbstractArtifactdbDataset {
  122.     #zipfile;
  123.     #name;
  125.     /**
  126.      * @param {string} name - Name of the SummarizedExperiment object inside the project directory.
  127.      * @param {SimpleFile|string|File} zipfile - Contents of the ZIP file containing the project directory.
  128.      * On browsers, this may be a File object.
  129.      * On Node.js, this may also be a string containing a file path.
  130.      * @param {object} [options={}] - Optional parameters. 
  131.      * @param {?JSZip} [options.existingHandle=null] - An existing handle into the ZIP file, generated using the [**JSZip**](https://stuk.github.io/jszip/) package.
  132.      * If an existing handle already exists, passing it in here will allow it to be re-used for greater efficiency.
  133.      * If `null`, a new handle is created for this ZippedArtifactdbDataset instance.
  134.      */
  135.     constructor(name, zipfile, options={}) {
  136.         let ziphandle = null;
  137.         if ("existingHandle" in options) {
  138.             ziphandle = options.existingHandle;
  139.             delete options.existingHandle;
  140.         } else {
  141.             if (!(zipfile instanceof afile.SimpleFile)) {
  142.                 zipfile = new afile.SimpleFile(zipfile);
  143.             }
  144.         }
  146.         let nav = new ZippedProjectNavigator(zipfile, ziphandle);
  147.         super(name, nav);
  148.         this.#zipfile = zipfile;
  149.         this.#name = name;
  150.     }
  152.     /**
  153.      * @return {string} String specifying the format for this dataset.
  154.      */
  155.     static format() {
  156.         return "ArtifactDB-zipped";
  157.     }
  159.     #dump_summary(fun) {
  160.         let files = [ { type: "zip", file: fun(this.#zipfile) } ]; 
  161.         let opt = this.options();
  162.         opt.datasetName = this.#name; // storing the name as a special option... can't be bothered to store it as a separate file.
  163.         return { files: files, options: opt };
  165.     }
  167.     /**
  168.      * @return {object} Object containing the abbreviated details of this dataset.
  169.      */
  170.     abbreviate() {
  171.         return this.#dump_summary(f => { 
  172.             return { size: f.size(), name: f.name() }
  173.         });
  174.     }
  176.     /**
  177.      * @return {object} Object describing this dataset, containing:
  178.      *
  179.      * - `files`: Array of objects representing the files used in this dataset.
  180.      *   Each object corresponds to a single file and contains:
  181.      *   - `type`: a string denoting the type.
  182.      *   - `file`: a {@linkplain SimpleFile} object representing the file contents.
  183.      * - `options`: An object containing additional options to saved.
  184.      */
  185.     serialize() {
  186.         return this.#dump_summary(f => f);
  187.     }
  189.     /**
  190.      * @param {Array} files - Array of objects like that produced by {@linkcode ZippedArtifactdbDataset#serialize serialize}.
  191.      * @param {object} options - Object containing additional options to be passed to the constructor.
  192.      * @return {ZippedArtifactdbDataset} A new instance of this class.
  193.      * @static
  194.      */
  195.     static unserialize(files, options) {
  196.         if (files.length != 1 || files[0].type != "zip") {
  197.             throw new Error("expected exactly one file of type 'zip' for Zipped ArtifactDB unserialization");
  198.         }
  200.         let name = options.datasetName;
  201.         delete options.datasetName;
  203.         let output = new ZippedArtifactdbDataset(name, files[0].file);
  204.         output.setOptions(output);
  205.         return output;
  206.     }
  207. }
  209. /***********************
  210.  ******* Result ********
  211.  ***********************/
  213. /**
  214.  * Result as a ZIP file containing a SummarizedExperiment in the **ArtifactDB** representation,
  215.  * e.g., as produced by {@linkcode saveSingleCellExperiment}.
  216.  * Specifically, the ZIP file should contain the contents of an **ArtifactDB** project directory.
  217.  * This project directory may contain multiple objects; the SummarizedExperiment of interest is identified in the constructor.
  218.  *
  219.  * @extends AbstractArtifactdbResult
  220.  */
  221. export class ZippedArtifactdbResult extends adb.AbstractArtifactdbResult {
  222.     /**
  223.      * @param {string} name - Name of the SummarizedExperiment object inside the project directory.
  224.      * @param {SimpleFile|string|File} zipfile - Contents of the ZIP file containing the project directory.
  225.      * On browsers, this may be a File object.
  226.      * On Node.js, this may also be a string containing a file path.
  227.      * @param {object} [options={}] - Optional parameters. 
  228.      * @param {?JSZip} [options.existingHandle=null] - An existing handle into the ZIP file, generated using the [**JSZip**](https://stuk.github.io/jszip/) package.
  229.      * If an existing handle already exists, passing it in here will allow it to be re-used for greater efficiency.
  230.      * If `null`, a new handle is created for this ZippedArtifactdbDataset instance.
  231.      */
  232.     constructor(name, zipfile, options={}) {
  233.         let ziphandle = null;
  234.         if ("existingHandle" in options) {
  235.             ziphandle = options.existingHandle;
  236.             delete options.existingHandle;
  237.         } else {
  238.             if (!(zipfile instanceof afile.SimpleFile)) {
  239.                 zipfile = new afile.SimpleFile(zipfile);
  240.             }
  241.         }
  243.         let nav = new ZippedProjectNavigator(zipfile, ziphandle);
  244.         super(name, nav);
  245.     }
  246. }