{"_id":"@databio/gtars-node","_rev":"6-f727862321638ba8545484c1c575b117","name":"@databio/gtars-node","dist-tags":{"latest":"0.8.0"},"versions":{"0.0.1":{"name":"@databio/gtars-node","version":"0.0.1","license":"MIT","_id":"@databio/gtars-node@0.0.1","maintainers":[{"name":"nsheff","email":"nathan@code.databio.org"},{"name":"khoroshevskyi","email":"sasha99250@gmail.com"},{"name":"nleroy917","email":"nleroy917@gmail.com"}],"homepage":"https://github.com/databio/gtars#readme","bugs":{"url":"https://github.com/databio/gtars/issues"},"dist":{"shasum":"f18afaf6f2c7a619ea5b3043dff8a37e87288f3e","tarball":"https://registry.npmjs.org/@databio/gtars-node/-/gtars-node-0.0.1.tgz","fileCount":3,"integrity":"sha512-x1m/0Yy+qKqYFUqudov3S8bm3AR2D+4bHg93NPqKUkvSWOoiDoRIdMZoFZ5wHiWbCpUnn8H9tIqN2j6q1tHk8g==","signatures":[{"sig":"MEUCIBxyDo9Q2CsHhpqr8O6S3LzV7ybovICXjIWn69Do7wSGAiEAhse2iGbnhAR9UmRK2Rku8lVWKH/myPOvL1ZuAy29QYI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":11732},"main":"index.js","napi":{"name":"gtars-node","triples":{"defaults":false,"additional":["x86_64-unknown-linux-gnu","aarch64-apple-darwin"]}},"types":"index.d.ts","gitHead":"d2f8f8821de4fd54c33a9bb369c14d7f84090c01","scripts":{"test":"node --test __test__/index.test.mjs","build":"napi build --platform --release","build:debug":"napi build --platform","prepublishOnly":"napi prepublish -t npm"},"_npmUser":{"name":"nsheff","email":"nathan@code.databio.org"},"repository":{"url":"git+https://github.com/databio/gtars.git","type":"git"},"_npmVersion":"10.7.0","description":"Native Node.js bindings for gtars (genomic tools and region sets)","directories":{},"_nodeVersion":"20.15.0","_hasShrinkwrap":false,"devDependencies":{"@napi-rs/cli":"^2"},"optionalDependencies":{"@databio/gtars-node-darwin-arm64":"0.0.1","@databio/gtars-node-linux-x64-gnu":"0.0.1"},"_npmOperationalInternal":{"tmp":"tmp/gtars-node_0.0.1_1776108307864_0.5665432708241054","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@databio/gtars-node","version":"0.0.2","license":"MIT","_id":"@databio/gtars-node@0.0.2","maintainers":[{"name":"nsheff","email":"nathan@code.databio.org"},{"name":"khoroshevskyi","email":"sasha99250@gmail.com"},{"name":"nleroy917","email":"nleroy917@gmail.com"}],"homepage":"https://github.com/databio/gtars#readme","bugs":{"url":"https://github.com/databio/gtars/issues"},"dist":{"shasum":"3b2ee71a7af17e705caea175b252b5a60b0027bd","tarball":"https://registry.npmjs.org/@databio/gtars-node/-/gtars-node-0.0.2.tgz","fileCount":2,"integrity":"sha512-pCDM3YRbkmjGcNr0Lg76lXz4fwAZ67B5Gdi7vDpBoH6xlwqMZP1J2RaBJXVHDMAvh+fpvE8OBGDMf0/phsvo6A==","signatures":[{"sig":"MEYCIQCBnUs75Hwws5wD6bup0G67hvH08v/DrNHawYUqRPfLXAIhAMm8MjozgKYOM1WsiolEyPrvnrKTZoeB4txxoC4kEGL8","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":6338},"main":"index.js","napi":{"name":"gtars-node","triples":{"defaults":false,"additional":["x86_64-unknown-linux-gnu","aarch64-apple-darwin"]}},"types":"index.d.ts","gitHead":"d55c49cc65a7359682bee984bdf2a8c1c9092e97","scripts":{"test":"node --test __test__/index.test.mjs","build":"napi build --platform --release","build:debug":"napi build --platform","prepublishOnly":"napi prepublish -t npm"},"_npmUser":{"name":"nsheff","email":"nathan@code.databio.org"},"repository":{"url":"git+https://github.com/databio/gtars.git","type":"git"},"_npmVersion":"10.8.2","description":"Native Node.js bindings for gtars (genomic tools and region sets)","directories":{},"_nodeVersion":"20.20.2","_hasShrinkwrap":false,"devDependencies":{"@napi-rs/cli":"^2"},"optionalDependencies":{"@databio/gtars-node-darwin-arm64":"0.0.2","@databio/gtars-node-linux-x64-gnu":"0.0.2"},"_npmOperationalInternal":{"tmp":"tmp/gtars-node_0.0.2_1776110146530_0.3369088267384177","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@databio/gtars-node","version":"0.1.0","license":"MIT","_id":"@databio/gtars-node@0.1.0","maintainers":[{"name":"nsheff","email":"nathan@code.databio.org"},{"name":"khoroshevskyi","email":"sasha99250@gmail.com"},{"name":"nleroy917","email":"nleroy917@gmail.com"}],"homepage":"https://github.com/databio/gtars#readme","bugs":{"url":"https://github.com/databio/gtars/issues"},"dist":{"shasum":"4b4e8f63fa4e1e7494541cb8538006630729598d","tarball":"https://registry.npmjs.org/@databio/gtars-node/-/gtars-node-0.1.0.tgz","fileCount":4,"integrity":"sha512-NW9qGP0Fq7rGCpRqKTBNCZMtKzhV5uHhgUyovMQHISTgp6kSQgnEhUyubwEVO45S1SbJ0efdepEaxBOMg7jjRg==","signatures":[{"sig":"MEQCIF6G742ly6o+3z4IagfZwaQNJ6h7QQwgmxyOsD9JZ9JUAiBSNbhLrjooXsd6/lUeW+4Z2TppYwW/jgfK99kyP/LuYw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":11290},"main":"wrapper.js","napi":{"name":"gtars-node","triples":{"defaults":false,"additional":["x86_64-unknown-linux-gnu","aarch64-apple-darwin"]}},"types":"wrapper.d.ts","gitHead":"566d26bbfae45434ec07b9a4cbbe6a1fd88fc9fb","scripts":{"test":"node --test __test__/","build":"napi build --platform --release","build:debug":"napi build --platform","prepublishOnly":"napi prepublish -t npm"},"_npmUser":{"name":"nsheff","email":"nathan@code.databio.org"},"repository":{"url":"git+https://github.com/databio/gtars.git","type":"git"},"_npmVersion":"10.8.2","description":"Native Node.js bindings for gtars (genomic tools and region sets)","directories":{},"_nodeVersion":"20.20.2","_hasShrinkwrap":false,"devDependencies":{"@napi-rs/cli":"^2"},"optionalDependencies":{"@databio/gtars-node-darwin-arm64":"0.1.0","@databio/gtars-node-linux-x64-gnu":"0.1.0"},"_npmOperationalInternal":{"tmp":"tmp/gtars-node_0.1.0_1776305948868_0.8721293862861548","host":"s3://npm-registry-packages-npm-production"}},"0.7.0":{"name":"@databio/gtars-node","version":"0.7.0","license":"MIT","_id":"@databio/gtars-node@0.7.0","maintainers":[{"name":"nsheff","email":"nathan@code.databio.org"},{"name":"khoroshevskyi","email":"sasha99250@gmail.com"},{"name":"nleroy917","email":"nleroy917@gmail.com"}],"homepage":"https://github.com/databio/gtars#readme","bugs":{"url":"https://github.com/databio/gtars/issues"},"dist":{"shasum":"bad404edf26499e9448750e18649b07d61e997b4","tarball":"https://registry.npmjs.org/@databio/gtars-node/-/gtars-node-0.7.0.tgz","fileCount":4,"integrity":"sha512-4ZgLIIuB54dR2BUOTjTEFJWs5yOfcNgzh2NkiOU7/6frKNI2bp15DpxJCepp/ClHOCz4BxngnSSuseGnvoWm8Q==","signatures":[{"sig":"MEUCICekGRtqp5QwsynFXyZwOlgvY6auupRB0AUlq1QYIRhbAiEAiKNbuLgaC7XWQxAeOyt8ybKfYZc981LN87t3uC2Hqus=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@databio%2fgtars-node@0.7.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":11290},"main":"wrapper.js","napi":{"name":"gtars-node","triples":{"defaults":false,"additional":["x86_64-unknown-linux-gnu","aarch64-apple-darwin"]}},"types":"wrapper.d.ts","gitHead":"8687df3ea80c812ddaaf9bdafe9546ea1a9eb6bf","scripts":{"test":"node --test __test__/","build":"napi build --platform --release","build:debug":"napi build --platform","prepublishOnly":"napi prepublish -t npm"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:70523a43-7395-4194-ad15-1b5849a81d85"}},"repository":{"url":"git+https://github.com/databio/gtars.git","type":"git"},"_npmVersion":"11.17.0","description":"Native Node.js bindings for gtars (genomic tools and region sets)","directories":{},"_nodeVersion":"20.20.2","_hasShrinkwrap":false,"devDependencies":{"@napi-rs/cli":"^2"},"optionalDependencies":{"@databio/gtars-node-darwin-arm64":"0.7.0","@databio/gtars-node-linux-x64-gnu":"0.7.0"},"_npmOperationalInternal":{"tmp":"tmp/gtars-node_0.7.0_1781287424980_0.7846404401402969","host":"s3://npm-registry-packages-npm-production"}},"0.7.1":{"name":"@databio/gtars-node","version":"0.7.1","license":"MIT","_id":"@databio/gtars-node@0.7.1","maintainers":[{"name":"nsheff","email":"nathan@code.databio.org"},{"name":"khoroshevskyi","email":"sasha99250@gmail.com"},{"name":"nleroy917","email":"nleroy917@gmail.com"}],"homepage":"https://github.com/databio/gtars#readme","bugs":{"url":"https://github.com/databio/gtars/issues"},"dist":{"shasum":"857b6b7b9015f0ed2e07a117ff0fbf3c6ccdc4a7","tarball":"https://registry.npmjs.org/@databio/gtars-node/-/gtars-node-0.7.1.tgz","fileCount":4,"integrity":"sha512-XS9uObJiAd2PFBwoD864n9+TcIs+176737LjiQIdWRJCGHqw8RTDRUEA+CfzYQt0ixMtTghTj7EFYCZ/dgVEbA==","signatures":[{"sig":"MEUCIGZ75SK0AyHJDiXu9UMHzqGdlXaTESHhdtCHLp6RIP/9AiEA8qFRRJiC6EthCTlRBAIxEVaz+ayTQ1Uf/q3R5+4mlpA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@databio%2fgtars-node@0.7.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":11300},"main":"wrapper.js","napi":{"name":"gtars-node","triples":{"defaults":false,"additional":["x86_64-unknown-linux-gnu","aarch64-apple-darwin"]}},"types":"wrapper.d.ts","gitHead":"35114cf166afd4d1b94adee1281f75f8f31a4500","scripts":{"test":"node --test __test__/*.test.mjs","build":"napi build --platform --release","build:debug":"napi build --platform","prepublishOnly":"napi prepublish -t npm"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:70523a43-7395-4194-ad15-1b5849a81d85"}},"repository":{"url":"git+https://github.com/databio/gtars.git","type":"git"},"_npmVersion":"11.17.0","description":"Native Node.js bindings for gtars (genomic tools and region sets)","directories":{},"_nodeVersion":"20.20.2","_hasShrinkwrap":false,"devDependencies":{"@napi-rs/cli":"^2"},"optionalDependencies":{"@databio/gtars-node-darwin-arm64":"0.7.1","@databio/gtars-node-linux-x64-gnu":"0.7.1"},"_npmOperationalInternal":{"tmp":"tmp/gtars-node_0.7.1_1781709130659_0.32662333061989535","host":"s3://npm-registry-packages-npm-production"}},"0.8.0":{"name":"@databio/gtars-node","version":"0.8.0","description":"Native Node.js bindings for gtars (genomic tools and region sets)","main":"wrapper.js","types":"wrapper.d.ts","repository":{"type":"git","url":"git+https://github.com/databio/gtars.git"},"license":"MIT","napi":{"name":"gtars-node","triples":{"defaults":false,"additional":["x86_64-unknown-linux-gnu","aarch64-apple-darwin"]}},"scripts":{"build":"napi build --platform --release","build:debug":"napi build --platform","test":"node --test __test__/*.test.mjs","prepublishOnly":"napi prepublish -t npm"},"devDependencies":{"@napi-rs/cli":"^2"},"optionalDependencies":{"@databio/gtars-node-linux-x64-gnu":"0.8.0","@databio/gtars-node-darwin-arm64":"0.8.0"},"gitHead":"5b1643c99cd1fcc3b838be63eb16b327fea06504","_id":"@databio/gtars-node@0.8.0","bugs":{"url":"https://github.com/databio/gtars/issues"},"homepage":"https://github.com/databio/gtars#readme","_nodeVersion":"20.20.2","_npmVersion":"11.19.1","dist":{"integrity":"sha512-QpaNyVuJonAuYFmmwmasqStlCRoeXXtmh0hTPDXGWBea49yTuRgS1Iln/CkcTMv3ozTLf1fTbd2WsR8jm42slA==","shasum":"c5281a21241d8ba9a78d55a1c36cf4a448a5706c","tarball":"https://registry.npmjs.org/@databio/gtars-node/-/gtars-node-0.8.0.tgz","fileCount":4,"unpackedSize":11300,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@databio%2fgtars-node@0.8.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC9bU2p8GnIyd26yl2y0MlxhrcNXG71gKiKEwsEFgrJkwIgH31mtNOxmJtI/n7/Si0qglpiWkSEIqLZWtwEi5ZiZD4="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:70523a43-7395-4194-ad15-1b5849a81d85"}},"directories":{},"maintainers":[{"name":"nsheff","email":"nathan@code.databio.org"},{"name":"khoroshevskyi","email":"sasha99250@gmail.com"},{"name":"nleroy917","email":"nleroy917@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gtars-node_0.8.0_1788642699795_0.10896858696969614"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-13T19:25:07.749Z","modified":"2026-09-05T21:11:40.244Z","0.0.1":"2026-04-13T19:25:08.026Z","0.0.2":"2026-04-13T19:55:46.674Z","0.1.0":"2026-04-16T02:19:08.992Z","0.7.0":"2026-06-12T18:03:45.120Z","0.7.1":"2026-06-17T15:12:10.813Z","0.8.0":"2026-09-05T21:11:39.915Z"},"bugs":{"url":"https://github.com/databio/gtars/issues"},"license":"MIT","homepage":"https://github.com/databio/gtars#readme","repository":{"type":"git","url":"git+https://github.com/databio/gtars.git"},"description":"Native Node.js bindings for gtars (genomic tools and region sets)","maintainers":[{"name":"nsheff","email":"nathan@code.databio.org"},{"name":"khoroshevskyi","email":"sasha99250@gmail.com"},{"name":"nleroy917","email":"nleroy917@gmail.com"}],"readme":"# @databio/gtars-node\n\nNative Node.js bindings for [gtars](https://github.com/databio/gtars) (genomic tools and region sets). Provides a `RefgetStore` class for working with GA4GH refget sequence collections — loading FASTA files, retrieving sequences by digest, and comparing collections.\n\nBuilt with [NAPI-RS](https://napi.rs). The main package auto-detects your platform and loads the correct native binary.\n\n## Supported platforms\n\n- Linux x64 (glibc)\n- macOS ARM64 (Apple Silicon)\n\n## Quick start\n\n```javascript\nconst { RefgetStore } = require(\"@databio/gtars-node\")\nconst store = RefgetStore.openRemote(\"/tmp/rgcache\", \"https://refgenie.s3.us-east-1.amazonaws.com/refget-store/jungle/\")\nconsole.log(store.stats())                // { nSequences: 580742, nCollections: 205, ... }\nconsole.log(store.listCollections(0, 5))  // first 5 collections\nconst seq = store.listCollections(0, 1)[0]\nconsole.log(store.getCollectionMetadata(seq.digest))\n```\n\n## Installation\n\n```bash\nnpm install @databio/gtars-node\n```\n\n## Usage\n\n```javascript\nconst { RefgetStore } = require('@databio/gtars-node')\n\n// Create an in-memory store and load a FASTA file\nconst store = RefgetStore.inMemory()\nstore.addFasta('/path/to/genome.fa.gz')\n\n// Inspect what was loaded\nstore.stats()            // { nSequences, nCollections, storageMode, ... }\nstore.listSequences()    // [{ name, length, sha512T24U, md5 }, ...]\nstore.listCollections()  // [{ digest, nSequences, namesDigest, ... }, ...]\n\n// Retrieve a sequence by its digest\nstore.getSequence('iYtREV555dUFKg2_agSJW6suquUyPpMw')\n\n// Retrieve a substring (0-indexed, exclusive end)\nstore.getSubstring('iYtREV555dUFKg2_agSJW6suquUyPpMw', 2, 7)\n\n// Get metadata for a specific sequence or collection\nstore.getSequenceMetadata(digest)\nstore.getCollectionMetadata(digest)\n\n// Compare two sequence collections (returns a JSON string)\nconst result = JSON.parse(store.compare(digestA, digestB))\n\n// Persist to disk, then reload\nstore.write('/path/to/store')\nconst reloaded = RefgetStore.openLocal('/path/to/store')\n\n// Open a remote store (fetches rgstore.json from the URL, caches locally)\nconst remote = RefgetStore.openRemote('/local/cache', 'https://example.com/path/to/store')\nremote.listCollections()\n```\n\nFor ESM modules, use `createRequire`:\n\n```javascript\nimport { createRequire } from 'node:module'\nconst require = createRequire(import.meta.url)\nconst { RefgetStore } = require('@databio/gtars-node')\n```\n\n## Opening a remote store\n\n`openRemote` lets you load a refget store hosted on any static file server. The remote URL must serve a directory created by `store.write()`, with `rgstore.json` at the root:\n\n```\nhttps://example.com/my-store/\n  rgstore.json        # store manifest\n  sequences/...       # sequence data files\n```\n\nThe first argument is a local cache directory where fetched data is stored:\n\n```javascript\nconst store = RefgetStore.openRemote('/tmp/rgcache', 'https://example.com/my-store')\nstore.listCollections()\nstore.getSequence('iYtREV555dUFKg2_agSJW6suquUyPpMw')\n```\n\nTo publish a store for remote access, build it locally and upload the output directory to any static host (S3, GitHub Pages, nginx, etc.):\n\n```javascript\nconst store = RefgetStore.inMemory()\nstore.addFasta('/path/to/genome.fa.gz')\nstore.write('/path/to/output')   // upload this directory\n```\n\n## API reference\n\n### Factory methods\n\n| Method | Description |\n|--------|-------------|\n| `RefgetStore.inMemory()` | Create an empty in-memory store. Load data with `addFasta()`. |\n| `RefgetStore.openLocal(path)` | Open a store previously saved with `write()`. |\n| `RefgetStore.openRemote(cachePath, url)` | Fetch a store from a remote URL with local caching. |\n\n### Sequence retrieval\n\nSequences are lazy-loaded automatically — when you call `getSequence` or `getSubstring` on a store opened from disk or remote, the sequence data is fetched on first access and cached.\n\n| Method | Returns |\n|--------|---------|\n| `getSequence(digest)` | Full sequence string for the given digest |\n| `getSubstring(digest, start, end)` | Substring (0-indexed, exclusive end) |\n| `getSequenceByName(collectionDigest, name)` | Sequence looked up by collection digest and sequence name |\n\n### Listing and metadata\n\n| Method | Returns |\n|--------|---------|\n| `listSequences()` | `SequenceMetadata[]` — name, length, sha512T24U, md5 for each sequence |\n| `listCollections(page?, pageSize?)` | `CollectionMetadata[]` — supports optional pagination |\n| `getSequenceMetadata(digest)` | `SequenceMetadata \\| null` |\n| `getCollectionMetadata(digest)` | `CollectionMetadata \\| null` |\n| `stats()` | `StoreStats` — counts and storage mode |\n\n**Note:** `listSequences()` returns all sequences at once. For large stores (500k+ sequences), use `stats()` to check the count first and prefer `getSequenceMetadata(digest)` for individual lookups.\n\n### Streaming\n\n`streamSequence` returns a Node `stream.Readable` that emits ASCII sequence bytes as they are decoded from the underlying store — no full-sequence buffering on the JS side. This is the recommended path for HTTP refget servers that want to pipe sequence bytes directly to the response body with bounded memory usage.\n\n| Method | Returns |\n|--------|---------|\n| `streamSequence(digest, start?, end?)` | `stream.Readable` yielding ASCII bases |\n\nExample — an Express handler for `GET /sequence/:digest`:\n\n```javascript\nconst { RefgetStore } = require('@databio/gtars-node')\nconst express = require('express')\n\nconst store = RefgetStore.openLocal('/path/to/store')\nconst app = express()\n\napp.get('/sequence/:digest', (req, res) => {\n  const stream = store.streamSequence(req.params.digest)\n  stream.on('error', (err) => {\n    res.status(/not found/i.test(err.message) ? 404 : 500).send(err.message)\n  })\n  res.setHeader('Content-Type', 'text/vnd.ga4gh.refget.v2.0.0+plain')\n  stream.pipe(res)\n})\n```\n\n### Mutation and persistence\n\n| Method | Description |\n|--------|-------------|\n| `addFasta(fastaPath)` | Load sequences from a FASTA file (gzipped or plain) |\n| `write(path)` | Save the store to a directory on disk |\n| `compare(digestA, digestB)` | Compare two collections; returns a JSON string |\n| `ensureDecoded(digest)` | Decode a sequence into the cache |\n| `clearDecodedCache()` | Free memory used by decoded sequences |\n\n## Development\n\n```bash\n# Build the native module (requires Rust toolchain)\nnpm run build\n\n# Run tests\nnpm test\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}