@ruvector/rvdna 0.1.0

package/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @ruvector/rvdna — AI-native genomic analysis and the .rvdna file format.
+ *
+ * Provides variant calling, protein translation, k-mer vector search,
+ * and the compact .rvdna binary format via Rust NAPI-RS bindings.
+ */
+
+/**
+ * Encode a DNA string to 2-bit packed bytes (4 bases per byte).
+ * A=00, C=01, G=10, T=11. Ambiguous bases (N) map to A.
+ */
+export function encode2bit(sequence: string): Buffer;
+
+/**
+ * Decode 2-bit packed bytes back to a DNA string.
+ * @param buffer - The 2-bit packed buffer
+ * @param length - Number of bases to decode
+ */
+export function decode2bit(buffer: Buffer, length: number): string;
+
+/**
+ * Translate a DNA string to a protein amino acid string.
+ * Uses the standard genetic code. Stops at the first stop codon.
+ */
+export function translateDna(sequence: string): string;
+
+/**
+ * Compute cosine similarity between two numeric arrays.
+ * Returns a value between -1 and 1.
+ */
+export function cosineSimilarity(a: number[], b: number[]): number;
+
+export interface RvdnaOptions {
+  /** K-mer size (default: 11) */
+  k?: number;
+  /** Vector dimensions (default: 512) */
+  dims?: number;
+  /** Block size in bases (default: 500) */
+  blockSize?: number;
+}
+
+/**
+ * Convert a FASTA sequence string to .rvdna binary format.
+ * Requires native bindings.
+ */
+export function fastaToRvdna(sequence: string, options?: RvdnaOptions): Buffer;
+
+export interface RvdnaFile {
+  /** Format version */
+  version: number;
+  /** Sequence length in bases */
+  sequenceLength: number;
+  /** Decoded DNA sequence */
+  sequence: string;
+  /** Pre-computed k-mer vector blocks */
+  kmerVectors: Array<{
+    k: number;
+    dimensions: number;
+    startPos: number;
+    regionLen: number;
+    vector: Float32Array;
+  }>;
+  /** Variant positions and genotype likelihoods */
+  variants: Array<{
+    position: number;
+    refAllele: string;
+    altAllele: string;
+    likelihoods: [number, number, number];
+    quality: number;
+  }> | null;
+  /** Metadata key-value pairs */
+  metadata: Record<string, unknown> | null;
+  /** File statistics */
+  stats: {
+    totalSize: number;
+    bitsPerBase: number;
+    compressionRatio: number;
+  };
+}
+
+/**
+ * Read a .rvdna file from a Buffer. Returns parsed sections.
+ * Requires native bindings.
+ */
+export function readRvdna(buffer: Buffer): RvdnaFile;
+
+/**
+ * Check if native bindings are available for the current platform.
+ */
+export function isNativeAvailable(): boolean;
+
+/**
+ * Direct access to the native NAPI-RS module (null if not available).
+ */
+export const native: Record<string, Function> | null;

package/index.js

@@ -0,0 +1,175 @@
+const { platform, arch } = process;
+
+// Platform-specific native binary packages
+const platformMap = {
+  'linux': {
+    'x64': '@ruvector/rvdna-linux-x64-gnu',
+    'arm64': '@ruvector/rvdna-linux-arm64-gnu'
+  },
+  'darwin': {
+    'x64': '@ruvector/rvdna-darwin-x64',
+    'arm64': '@ruvector/rvdna-darwin-arm64'
+  },
+  'win32': {
+    'x64': '@ruvector/rvdna-win32-x64-msvc'
+  }
+};
+
+function loadNativeModule() {
+  const platformPackage = platformMap[platform]?.[arch];
+
+  if (!platformPackage) {
+    throw new Error(
+      `Unsupported platform: ${platform}-${arch}\n` +
+      `@ruvector/rvdna native bindings are available for:\n` +
+      `- Linux (x64, ARM64)\n` +
+      `- macOS (x64, ARM64)\n` +
+      `- Windows (x64)\n\n` +
+      `For other platforms, use the WASM build: npm install @ruvector/rvdna-wasm`
+    );
+  }
+
+  try {
+    return require(platformPackage);
+  } catch (error) {
+    if (error.code === 'MODULE_NOT_FOUND') {
+      throw new Error(
+        `Native module not found for ${platform}-${arch}\n` +
+        `Please install: npm install ${platformPackage}\n` +
+        `Or reinstall @ruvector/rvdna to get optional dependencies`
+      );
+    }
+    throw error;
+  }
+}
+
+// Try native first, fall back to pure JS shim with basic functionality
+let nativeModule;
+try {
+  nativeModule = loadNativeModule();
+} catch (e) {
+  // Native bindings not available — provide JS shim for basic operations
+  nativeModule = null;
+}
+
+// -------------------------------------------------------------------
+// Public API — wraps native bindings or provides JS fallbacks
+// -------------------------------------------------------------------
+
+/**
+ * Encode a DNA string to 2-bit packed bytes (4 bases per byte).
+ * A=00, C=01, G=10, T=11. Returns a Buffer.
+ */
+function encode2bit(sequence) {
+  if (nativeModule?.encode2bit) return nativeModule.encode2bit(sequence);
+
+  // JS fallback
+  const map = { A: 0, C: 1, G: 2, T: 3, N: 0 };
+  const len = sequence.length;
+  const buf = Buffer.alloc(Math.ceil(len / 4));
+  for (let i = 0; i < len; i++) {
+    const byteIdx = i >> 2;
+    const bitOff = 6 - (i & 3) * 2;
+    buf[byteIdx] |= (map[sequence[i]] || 0) << bitOff;
+  }
+  return buf;
+}
+
+/**
+ * Decode 2-bit packed bytes back to a DNA string.
+ */
+function decode2bit(buffer, length) {
+  if (nativeModule?.decode2bit) return nativeModule.decode2bit(buffer, length);
+
+  const bases = ['A', 'C', 'G', 'T'];
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    const byteIdx = i >> 2;
+    const bitOff = 6 - (i & 3) * 2;
+    result += bases[(buffer[byteIdx] >> bitOff) & 3];
+  }
+  return result;
+}
+
+/**
+ * Translate a DNA string to a protein amino acid string.
+ */
+function translateDna(sequence) {
+  if (nativeModule?.translateDna) return nativeModule.translateDna(sequence);
+
+  // JS fallback — standard genetic code
+  const codons = {
+    'TTT':'F','TTC':'F','TTA':'L','TTG':'L','CTT':'L','CTC':'L','CTA':'L','CTG':'L',
+    'ATT':'I','ATC':'I','ATA':'I','ATG':'M','GTT':'V','GTC':'V','GTA':'V','GTG':'V',
+    'TCT':'S','TCC':'S','TCA':'S','TCG':'S','CCT':'P','CCC':'P','CCA':'P','CCG':'P',
+    'ACT':'T','ACC':'T','ACA':'T','ACG':'T','GCT':'A','GCC':'A','GCA':'A','GCG':'A',
+    'TAT':'Y','TAC':'Y','TAA':'*','TAG':'*','CAT':'H','CAC':'H','CAA':'Q','CAG':'Q',
+    'AAT':'N','AAC':'N','AAA':'K','AAG':'K','GAT':'D','GAC':'D','GAA':'E','GAG':'E',
+    'TGT':'C','TGC':'C','TGA':'*','TGG':'W','CGT':'R','CGC':'R','CGA':'R','CGG':'R',
+    'AGT':'S','AGC':'S','AGA':'R','AGG':'R','GGT':'G','GGC':'G','GGA':'G','GGG':'G',
+  };
+  let protein = '';
+  for (let i = 0; i + 2 < sequence.length; i += 3) {
+    const codon = sequence.slice(i, i + 3).toUpperCase();
+    const aa = codons[codon] || 'X';
+    if (aa === '*') break;
+    protein += aa;
+  }
+  return protein;
+}
+
+/**
+ * Compute cosine similarity between two numeric arrays.
+ */
+function cosineSimilarity(a, b) {
+  if (nativeModule?.cosineSimilarity) return nativeModule.cosineSimilarity(a, b);
+
+  let dot = 0, magA = 0, magB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    magA += a[i] * a[i];
+    magB += b[i] * b[i];
+  }
+  magA = Math.sqrt(magA);
+  magB = Math.sqrt(magB);
+  return (magA && magB) ? dot / (magA * magB) : 0;
+}
+
+/**
+ * Convert a FASTA sequence string to .rvdna binary format.
+ * Returns a Buffer with the complete .rvdna file contents.
+ */
+function fastaToRvdna(sequence, options = {}) {
+  if (nativeModule?.fastaToRvdna) {
+    return nativeModule.fastaToRvdna(sequence, options.k || 11, options.dims || 512, options.blockSize || 500);
+  }
+  throw new Error('fastaToRvdna requires native bindings. Install the platform-specific package.');
+}
+
+/**
+ * Read a .rvdna file from a Buffer. Returns parsed sections.
+ */
+function readRvdna(buffer) {
+  if (nativeModule?.readRvdna) return nativeModule.readRvdna(buffer);
+  throw new Error('readRvdna requires native bindings. Install the platform-specific package.');
+}
+
+/**
+ * Check if native bindings are available.
+ */
+function isNativeAvailable() {
+  return nativeModule !== null;
+}
+
+module.exports = {
+  encode2bit,
+  decode2bit,
+  translateDna,
+  cosineSimilarity,
+  fastaToRvdna,
+  readRvdna,
+  isNativeAvailable,
+
+  // Re-export native module for advanced use
+  native: nativeModule,
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@ruvector/rvdna",
+  "version": "0.1.0",
+  "description": "rvDNA — AI-native genomic analysis and the .rvdna file format. Variant calling, protein prediction, and HNSW vector search powered by Rust via NAPI-RS.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "author": "rUv <info@ruv.io> (https://ruv.io)",
+  "homepage": "https://github.com/ruvnet/ruvector/tree/main/examples/dna",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ruvnet/ruvector.git",
+    "directory": "npm/packages/rvdna"
+  },
+  "bugs": {
+    "url": "https://github.com/ruvnet/ruvector/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build:napi": "napi build --platform --release --cargo-cwd ../../../examples/dna",
+    "test": "node test.js"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.0"
+  },
+  "optionalDependencies": {
+    "@ruvector/rvdna-linux-x64-gnu": "0.1.0",
+    "@ruvector/rvdna-linux-arm64-gnu": "0.1.0",
+    "@ruvector/rvdna-darwin-x64": "0.1.0",
+    "@ruvector/rvdna-darwin-arm64": "0.1.0",
+    "@ruvector/rvdna-win32-x64-msvc": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "genomics",
+    "bioinformatics",
+    "dna",
+    "rvdna",
+    "variant-calling",
+    "protein",
+    "hnsw",
+    "vector-search",
+    "napi",
+    "rust",
+    "wasm",
+    "ai",
+    "machine-learning"
+  ]
+}