bio-forge-wasm 0.3.0

package/README.md

@@ -0,0 +1,132 @@
+<h1><img src="https://raw.githubusercontent.com/TKanX/bio-forge/main/assets/logo.svg" alt="BioForge Logo" width="50em"> BioForge</h1>
+
+**BioForge** is a pure-Rust toolkit for automated preparation of biological macromolecules. It reads experimental structures (PDB/mmCIF), reconciles them with high-quality residue templates, repairs missing atoms, assigns hydrogens and termini, builds topologies, and optionally solvates the system with water and ions—all without leaving the Rust type system.
+
+## Highlights
+
+- **Template-driven accuracy** – Curated TOML templates for standard amino acids, nucleotides, and water guarantee reproducible coordinates, charges, and bonding.
+- **High performance** – Multithreaded processing (via rayon) handles million-atom systems in milliseconds; single-pass parsing, in-place mutation, and zero-copy serialization minimize overhead.
+- **Rich structure model** – Lightweight `Atom`, `Residue`, `Chain`, and `Structure` types backed by `nalgebra` make geometric operations trivial.
+- **Format interoperability** – Buffered readers/writers for PDB, mmCIF, and MOL2 plus error types that surface precise parsing diagnostics.
+- **Preparation pipeline** – Cleaning, repairing, protonating, solvation, coordinate transforms, and topology reconstruction share a common `ops::Error` so workflows compose cleanly.
+- **WebAssembly support** – Full-featured WASM bindings for modern JavaScript bundlers (Vite, webpack, Rollup); ideal for browser-based molecular viewers and web applications.
+- **Rust-first ergonomics** – No FFI, no global mutable state beyond the lazily-loaded template store, and edition 2024 guarantees modern language features.
+
+## Processing Pipeline
+
+```
+Load → Clean → Repair → Hydrogenate → Solvate → Topology → Write
+```
+
+1. **Load** – `io::read_pdb_structure` or `io::read_mmcif_structure` parses coordinates with `IoContext` alias resolution.
+2. **Clean** – `ops::clean_structure` removes waters, ions, hetero residues, or arbitrary residue names via `CleanConfig`.
+3. **Repair** – `ops::repair_structure` realigns residues to templates and rebuilds missing heavy atoms (OXT on C-termini, OP3 on 5'-phosphorylated nucleic acids).
+4. **Hydrogenate** – `ops::add_hydrogens` infers protonation states (configurable pH and histidine strategy) and reconstructs hydrogens from template anchors.
+5. **Solvate** – `ops::solvate_structure` creates a periodic box, packs water on a configurable lattice, and swaps molecules for ions to satisfy a target charge.
+6. **Topology** – `ops::TopologyBuilder` emits bond connectivity with peptide-link detection, nucleic backbone connectivity, and disulfide heuristics.
+7. **Write** – `io::write_pdb_structure` / `io::write_mmcif_structure` serialize the processed structure; `write_*_topology` helpers emit CONECT or `struct_conn` records.
+
+## Quick Start
+
+### For CLI Users
+
+Install the latest BioForge CLI binary from the [releases page](https://github.com/TKanX/bio-forge/releases) or via `cargo`:
+
+```bash
+cargo install bio-forge
+```
+
+Once the `bioforge` binary is installed, you can repair a structure in a single step:
+
+```bash
+bioforge repair -i input.pdb -o repaired.pdb
+```
+
+Explore the complete preparation pipeline in the [user manual](MANUAL.md) and browse the [examples directory](https://github.com/TKanX/bio-forge/tree/main/examples) for runnable walkthroughs.
+
+### For Library Developers (Rust)
+
+BioForge is also available as a library crate. Add it to your `Cargo.toml` dependencies:
+
+```toml
+[dependencies]
+bio-forge = "0.3.0"
+```
+
+#### Example: Preparing a PDB Structure
+
+```rust
+use std::{fs::File, io::{BufReader, BufWriter}};
+
+use bio_forge::{
+    io::{
+        read_pdb_structure,
+        write_pdb_structure,
+        write_pdb_topology,
+        IoContext,
+    },
+    ops::{
+        add_hydrogens, clean_structure, repair_structure, solvate_structure,
+        CleanConfig, HydroConfig, SolvateConfig, TopologyBuilder,
+    },
+};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let ctx = IoContext::new_default();
+    let input = BufReader::new(File::open("input.pdb")?);
+    let mut structure = read_pdb_structure(input, &ctx)?;
+
+    clean_structure(&mut structure, &CleanConfig::water_only())?;
+    repair_structure(&mut structure)?;
+    add_hydrogens(&mut structure, &HydroConfig::default())?;
+    solvate_structure(&mut structure, &SolvateConfig::default())?;
+
+    let topology = TopologyBuilder::new().build(structure.clone())?;
+
+    write_pdb_structure(BufWriter::new(File::create("prepared.pdb")?), &structure)?;
+    write_pdb_topology(BufWriter::new(File::create("prepared-topology.pdb")?), &topology)?;
+    Ok(())
+}
+```
+
+> Prefer mmCIF? Swap in `read_mmcif_structure` / `write_mmcif_structure`. Need to process ligands? Parse them via `io::read_mol2_template` and feed the resulting `Template` into `TopologyBuilder::add_hetero_template`.
+
+### For Library Developers (JavaScript/TypeScript)
+
+Install via npm:
+
+```bash
+npm install bio-forge-wasm
+```
+
+Prepare a structure with the following code:
+
+```typescript
+import { Structure } from "bio-forge-wasm";
+
+const pdb = await fetch("https://files.rcsb.org/view/1UBQ.pdb").then((r) =>
+  r.text()
+);
+const structure = Structure.fromPdb(pdb);
+
+structure.clean({ removeWater: true });
+structure.repair();
+structure.addHydrogens({ hisStrategy: "network" });
+
+const topology = structure.toTopology();
+console.log(`Bonds: ${topology.bondCount}`);
+```
+
+## Documentation
+
+| Resource                                                          | Description                    |
+| ----------------------------------------------------------------- | ------------------------------ |
+| [CLI Manual](MANUAL.md)                                           | Command-line usage and options |
+| [JS/TS API](https://github.com/TKanX/bio-forge/blob/main/API.md)  | WebAssembly bindings reference |
+| [Rust API](https://docs.rs/bio-forge)                             | Library documentation          |
+| [Architecture](ARCHITECTURE.md)                                   | Internal design and algorithms |
+| [Examples](https://github.com/TKanX/bio-forge/tree/main/examples) | Runnable walkthroughs          |
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/bio_forge_wasm.d.ts

@@ -0,0 +1,319 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Configuration for structure cleaning operations.
+ */
+export interface CleanConfig {
+    /**
+     * Remove water molecules (HOH). Default: `false`
+     */
+    removeWater?: boolean;
+    /**
+     * Remove ion residues. Default: `false`
+     */
+    removeIons?: boolean;
+    /**
+     * Remove hydrogen atoms. Default: `false`
+     */
+    removeHydrogens?: boolean;
+    /**
+     * Remove hetero residues (ligands). Default: `false`
+     */
+    removeHetero?: boolean;
+    /**
+     * Specific residue names to remove. Default: `[]`
+     */
+    removeResidueNames?: string[];
+    /**
+     * Specific residue names to keep (overrides other rules). Default: `[]`
+     */
+    keepResidueNames?: string[];
+}
+
+/**
+ * Per-chain information.
+ */
+export interface ChainInfo {
+    /**
+     * Chain identifier.
+     */
+    id: string;
+    /**
+     * Number of residues in this chain.
+     */
+    residueCount: number;
+    /**
+     * Number of atoms in this chain.
+     */
+    atomCount: number;
+    /**
+     * Polymer classifications present in this chain.
+     * Possible values: `\"protein\"`, `\"nucleic\"`, `\"solvent\"`, `\"hetero\"`.
+     * An empty array indicates an empty chain.
+     */
+    polymerTypes: Array<"protein" | "nucleic" | "solvent" | "hetero">;
+}
+
+/**
+ * Configuration for solvation.
+ */
+export interface SolvateConfig {
+    /**
+     * Margin around solute (Å). Default: `10.0`
+     */
+    margin?: number;
+    /**
+     * Water grid spacing (Å). Default: `3.1`
+     */
+    waterSpacing?: number;
+    /**
+     * Minimum solvent-solute distance (Å). Default: `2.4`
+     */
+    vdwCutoff?: number;
+    /**
+     * Remove existing solvent before solvating. Default: `true`
+     */
+    removeExisting?: boolean;
+    /**
+     * Cation species: `\"Na\"`, `\"K\"`, `\"Mg\"`, `\"Ca\"`, `\"Li\"`, `\"Zn\"`. Default: `[\"Na\"]`
+     */
+    cations?: Array<"Na" | "K" | "Mg" | "Ca" | "Li" | "Zn">;
+    /**
+     * Anion species: `\"Cl\"`, `\"Br\"`, `\"I\"`, `\"F\"`. Default: `[\"Cl\"]`
+     */
+    anions?: Array<"Cl" | "Br" | "I" | "F">;
+    /**
+     * Target net charge after solvation. Default: `0`
+     */
+    targetCharge?: number;
+    /**
+     * Random seed for reproducible placement.
+     */
+    rngSeed?: number | undefined;
+}
+
+/**
+ * Comprehensive structure information.
+ */
+export interface StructureInfo {
+    /**
+     * Number of chains.
+     */
+    chainCount: number;
+    /**
+     * Total number of residues.
+     */
+    residueCount: number;
+    /**
+     * Total number of atoms.
+     */
+    atomCount: number;
+    /**
+     * Box dimensions `[a, b, c]` in Å, if present.
+     */
+    boxLengths: [number, number, number] | undefined;
+    /**
+     * Box angles `[α, β, γ]` in degrees, if present.
+     */
+    boxAngles: [number, number, number] | undefined;
+    /**
+     * Per-chain information.
+     */
+    chains: ChainInfo[];
+}
+
+/**
+ * Configuration for topology building.
+ */
+export interface TopologyConfig {
+    /**
+     * Disulfide bond cutoff (Å). Default: `2.2`
+     */
+    disulfideCutoff?: number;
+}
+
+/**
+ * Configuration for hydrogen addition.
+ */
+export interface HydroConfig {
+    /**
+     * Target pH for protonation state decisions. Default: `undefined` (neutral)
+     */
+    targetPh?: number | undefined;
+    /**
+     * Remove existing hydrogens before adding new ones. Default: `true`
+     */
+    removeExistingH?: boolean;
+    /**
+     * Histidine tautomer strategy: `\"hid\"`, `\"hie\"`, `\"random\"`, `\"network\"`. Default: `\"network\"`
+     */
+    hisStrategy?: "hid" | "hie" | "random" | "network";
+}
+
+
+export class Structure {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Parses an mmCIF string into a Structure.
+   */
+  static fromMmcif(content: string): Structure;
+  /**
+   * Centers the center of mass at the origin.
+   */
+  centerMass(): void;
+  /**
+   * Builds a Topology from this structure.
+   */
+  toTopology(config?: TopologyConfig | null, templates?: Template[] | null): Topology;
+  /**
+   * Rotates using Euler angles (XYZ convention, all in radians).
+   */
+  rotateEuler(x: number, y: number, z: number): void;
+  /**
+   * Serializes to PDB format as bytes.
+   */
+  toPdbBytes(): Uint8Array;
+  /**
+   * Adds hydrogen atoms.
+   */
+  addHydrogens(config?: HydroConfig | null): void;
+  /**
+   * Parses a PDB byte array into a Structure.
+   */
+  static fromPdbBytes(content: Uint8Array): Structure;
+  /**
+   * Serializes to mmCIF format as bytes.
+   */
+  toMmcifBytes(): Uint8Array;
+  /**
+   * Centers the geometric centroid at the origin.
+   */
+  centerGeometry(): void;
+  /**
+   * Creates a deep copy of the structure.
+   */
+  clone(): Structure;
+  /**
+   * Parses an mmCIF byte array into a Structure.
+   */
+  static fromMmcifBytes(content: Uint8Array): Structure;
+  /**
+   * Returns comprehensive structure statistics.
+   */
+  info(): StructureInfo;
+  /**
+   * Removes unwanted components (water, ions, hydrogens, hetero residues).
+   */
+  clean(config?: CleanConfig | null): void;
+  /**
+   * Reconstructs missing atoms from templates.
+   */
+  repair(): void;
+  /**
+   * Serializes to PDB format.
+   */
+  toPdb(): string;
+  /**
+   * Solvates the structure with water and ions.
+   */
+  solvate(config?: SolvateConfig | null): void;
+  /**
+   * Parses a PDB string into a Structure.
+   */
+  static fromPdb(content: string): Structure;
+  /**
+   * Rotates around the X axis (angle in radians).
+   */
+  rotateX(radians: number): void;
+  /**
+   * Rotates around the Y axis (angle in radians).
+   */
+  rotateY(radians: number): void;
+  /**
+   * Rotates around the Z axis (angle in radians).
+   */
+  rotateZ(radians: number): void;
+  /**
+   * Serializes to mmCIF format.
+   */
+  toMmcif(): string;
+  /**
+   * Translates all atoms by the given vector (x, y, z in Å).
+   */
+  translate(x: number, y: number, z: number): void;
+  /**
+   * Returns the number of atoms.
+   */
+  readonly atomCount: number;
+  /**
+   * Returns the number of chains.
+   */
+  readonly chainCount: number;
+  /**
+   * Returns the number of residues.
+   */
+  readonly residueCount: number;
+}
+
+export class Template {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Parses a MOL2 byte array into a Template.
+   */
+  static fromMol2Bytes(content: Uint8Array): Template;
+  /**
+   * Parses a MOL2 string into a Template.
+   */
+  static fromMol2(content: string): Template;
+  /**
+   * Returns the template name (residue code).
+   */
+  readonly name: string;
+}
+
+export class Topology {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Serializes to PDB format as bytes.
+   */
+  toPdbBytes(): Uint8Array;
+  /**
+   * Creates a Topology from a Structure.
+   */
+  static fromStructure(structure: Structure, config?: TopologyConfig | null, templates?: Template[] | null): Topology;
+  /**
+   * Serializes to mmCIF format as bytes.
+   */
+  toMmcifBytes(): Uint8Array;
+  /**
+   * Serializes to PDB format with CONECT records.
+   */
+  toPdb(): string;
+  /**
+   * Serializes to mmCIF format with struct_conn records.
+   */
+  toMmcif(): string;
+  /**
+   * Returns the number of bonds.
+   */
+  readonly bondCount: number;
+  /**
+   * Returns a copy of the underlying structure.
+   */
+  readonly structure: Structure;
+}
+
+/**
+ * Initializes panic hook for better error messages in browser console.
+ *
+ * This function is automatically called when the WASM module is loaded.
+ * It sets up `console_error_panic_hook` to provide readable panic messages
+ * in the browser's developer console instead of cryptic WASM error codes.
+ */
+export function init(): void;

package/bio_forge_wasm.js

@@ -0,0 +1,5 @@
+import * as wasm from "./bio_forge_wasm_bg.wasm";
+export * from "./bio_forge_wasm_bg.js";
+import { __wbg_set_wasm } from "./bio_forge_wasm_bg.js";
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();