chematic-wasm

WebAssembly bindings for chematic, a pure-Rust cheminformatics library.

Published to npm as @kent-tokyo/chematic.

The current workspace line is 1.0.21. The binding keeps bounded parsing, typed failures, and opt-in embed_pipeline_v2_json; 3D/MMFF94 behavior remains Experimental and is not a claim of full RDKit parity.

Installation

npm install @kent-tokyo/chematic

Features

• Parse SMILES strings into molecule handles
• Molecular descriptors: MW, TPSA, LogP, Fsp3, QED, exact mass, rotatable bonds, HBD/HBA, aromatic ring count, Labute ASA
• Drug-likeness filters: Lipinski, Veber, Egan, REOS, Ghose
• EState indices (Hall & Kier 1991): per-atom values, sum/max/min
• Gasteiger-Marsili PEOE partial charges: per-heavy-atom charges
• VSA descriptors: SlogP_VSA (×12), SMR_VSA (×10), PEOE_VSA (×14)
• SA score: synthetic accessibility estimate [1, 10]
• Functional group identification (Ertl 2017 IFG)
• Canonical SMILES generation
• ECFP4/6, AtomPair, Torsion, path, and RDKit-compatible RDK fingerprints with Tanimoto similarity
• BRICS fragment count
• SDF/MOL block parsing, including bounded resumable sdf_records_batch_json, xyz_frames_batch_json, and extxyz_frames_batch_json manifests with deterministic input indices and partial/complete status; bounded malformed XYZ frames are grouped inline as rejected records when a later count-line boundary is recoverable (core file-backed readers remain fail-stop)
• Bounded topology parsing for CML (mol_from_cml_strict provides the opt-in non-empty, balanced, single-root boundary), ChemicalJSON (mol_from_cjson), MolJSON, CDXML, MOL2, and PDB/mmCIF
• Index-aligned wildcard/R-group inspection with MolHandle.atom_pseudo_labels_json() and immutable edits through mol_with_atom_pseudo_label; labels are bounded to *, R, and R1..R9999
• PDBx/mmCIF, PQR, QCSchema JSON, ORCA input/output, Gaussian Cube, OpenDX, and LAMMPS data/dump I/O (JSON-based bindings; see format_io.rs)
• Topological descriptors: Wiener index, Hall-Kier κ, χ connectivity indices, Bertz CT
• Shape descriptors (with 3D coordinates): PMI, NPR, radius of gyration, asphericity
• 2D SVG depiction with CPK colors and atom/bond highlighting
• SVG grid layout for multiple molecules
• Reaction SMILES/SMIRKS parsing and transform
• Add/remove explicit hydrogens
• embed_pipeline_v2_json: torsion-knowledge-aware 3D embedding + stereo verification/repair + policy-gated force field, mirroring the Python Mol.embed_pipeline_v2() binding — opt-in, not a default 3D API (usage)

Usage

The generated handle declarations include Symbol.dispose for explicit resource release. TypeScript consumers should include ESNext.Disposable in their tsconfig.json lib list (in addition to their normal browser or Node libraries):

{
  "compilerOptions": {
    "lib": ["ES2022", "DOM", "ESNext.Disposable"]
  }
}

import init, {
  parse_smiles,
  tanimoto_ecfp4,
  tanimoto_atom_pair,
  tanimoto_torsion,
  brics_fragment_count,
  gasteiger_charges_json,
  slogp_vsa_json,
  smr_vsa_json,
  peoe_vsa_json,
  identify_functional_groups,
} from '@kent-tokyo/chematic';

await init();

const mol = parse_smiles('CC(=O)Oc1ccccc1C(=O)O'); // aspirin

// Descriptors
console.log(mol.atom_count());          // 13
console.log(mol.molecular_weight());    // ~180.16
console.log(mol.formula());             // "C9H8O4"
console.log(mol.tpsa());               // ~63.6
console.log(mol.logp_crippen());        // ~1.2
console.log(mol.fsp3());               // ~0.111
console.log(mol.qed());                // drug-likeness score [0, 1]
console.log(mol.exact_mass());         // ~180.042
console.log(mol.hbd_count());          // 1
console.log(mol.hba_count());          // 4
console.log(mol.rotatable_bond_count()); // 2 (RDKit Lipinski definition)
console.log(mol.aromatic_ring_count()); // 1
console.log(mol.lipinski_passes());     // true
console.log(mol.canonical_smiles());    // canonical SMILES string

// BRICS fragmentation
console.log(brics_fragment_count(mol)); // ≥ 2

// Fingerprint similarity
const caffeine = parse_smiles('Cn1cnc2c1c(=O)n(c(=O)n2C)C');
console.log(tanimoto_ecfp4(mol, caffeine));    // ECFP4 Tanimoto
console.log(tanimoto_atom_pair(mol, caffeine)); // AtomPair Tanimoto
console.log(tanimoto_torsion(mol, caffeine));   // Torsion Tanimoto

Node.js

The published package is built with wasm-pack's web target. In a browser, await init() locates the adjacent WASM asset. Node does not fetch file: URLs, so pass the asset bytes explicitly:

import { readFile } from 'node:fs/promises';
import init, { parse_smiles } from '@kent-tokyo/chematic';

const wasm = await readFile(new URL(
  './node_modules/@kent-tokyo/chematic/chematic_wasm_bg.wasm',
  import.meta.url,
));
await init({ module_or_path: wasm });
const mol = parse_smiles('c1ccccc1');
console.log(mol.formula()); // C6H6
mol.free();

// Sprint Q: New descriptors (v0.1.15)
console.log(mol.sa_score());                     // synthetic accessibility [1,10]
console.log(mol.labute_asa());                   // Labute approx. surface area (Ų)

// Gasteiger partial charges (per heavy atom)
const charges = JSON.parse(gasteiger_charges_json(mol));
console.log(charges); // [-0.08, 0.12, -0.43, ...]

// Explicit RDKit-compatibility descriptor profile (kept separate from the
// historical native get_descriptors_json() profile)
const rdkitDescriptors = JSON.parse(get_rdkit_descriptors_json(mol));
console.log(rdkitDescriptors.aromatic_ring_count);

// VSA descriptor bins
const slogpVsa = JSON.parse(slogp_vsa_json(mol));
const smrVsa   = JSON.parse(smr_vsa_json(mol));
const peoeVsa  = JSON.parse(peoe_vsa_json(mol));

// Functional group identification
const ifg = JSON.parse(identify_functional_groups(mol));
console.log(ifg); // [{"atoms":[1,2,3],"types":"OC=O"}, ...]

3D embedding (embed_pipeline_v2_json)

Opt-in — does not change behavior of any existing 3D API (generate_coords, generate_and_minimize_*, etc.), which remain the defaults.

const response = JSON.parse(embed_pipeline_v2_json(mol, JSON.stringify({
  embedSeed: 7,
  maxAttempts: 8,
  embedTimeoutMs: null,
  useExpTorsions: false,
  useSmallRingTorsions: false,
  useMacrocycleTorsions: false,
  useMacrocycle14Bounds: false,
  includeLegacyTorsionHeuristic: false,
  stereoPolicy: "ignore",
  failOnUnevaluableStereo: false,
  forceFieldPolicy: "none",
  forceFieldMaxIterations: 200,
  gateMmff94TorsionOop: false,
  gateMmff94StretchBend: false,
  ringTorsionPolicy: "fail_closed",
  totalTimeoutMs: null,
  enforceChirality: false,
  expandImplicitHThroughPipeline: false,
})));
// response.ok, response.result / response.error — same shape as
// Mol.embed_pipeline_v2() in the Python binding.

For ring-fused declared stereocenters (e.g. testosterone, cholesterol) that enforceChirality alone can't repair, stereoPolicy: "repair_and_verify" + enforceChirality: true + expandImplicitHThroughPipeline: true are needed together (issue #291/#383) — pipeline_v2_stereo_safe_config_json builds that exact combination so a caller can't set one and forget another:

const configResponse = JSON.parse(pipeline_v2_stereo_safe_config_json(
  "mmff94_with_uff_fallback", "fail_closed"
));
// configResponse.ok, configResponse.config (or configResponse.error, same
// shape as embed_pipeline_v2_json's own error) — modify configResponse.config
// (e.g. a different embedSeed) before passing it to embed_pipeline_v2_json.
const response = JSON.parse(
  embed_pipeline_v2_json(mol, JSON.stringify(configResponse.config))
);

Verified working end-to-end under real WASM (both wasm-pack --target nodejs and --target web, the latter being what this package's npm build actually uses) — success, typed-failure, and typed-timeout paths all return real results. embedTimeoutMs/totalTimeoutMs use a monotonic clock that's portable across native and wasm32-unknown-unknown (web-time, backed by Performance.now() in the browser); this does not claim identical wall-clock precision across every JS engine, only that the value is finite, non-negative, and enforced correctly on all of them.

nearest_neighbors_json keeps its historical chematic-native ECFP4 profile. For the separately named RDKit-compatible Morgan profile, use rdkit_nearest_neighbors_json(querySmiles, dbSmilesJson, k). It returns the same {index, tanimoto} shape and reports preprocessing failures without silently falling back to native ECFP4.

For repeated queries, construct new RdkitSearchIndex(dbSmilesJson) once and call index.search_json(querySmiles, k). The prepared index is intended for chunked libraries up to the WASM batch limit and applies the same fail-closed RDKit-compatible profile without rebuilding database fingerprints per query.

V3000 SGROUP syntax view

v3000_sgroups_json(block) exposes bounded, typed SGROUP syntax without expanding polymer or Markush semantics. It preserves source order for unknown attributes and returns kindToken for unknown group kinds. Group IDs, parent references, atom references, and grouped-field counts are validated before JSON is returned.

const groups = JSON.parse(v3000_sgroups_json(v3000Block));
// [{ id, kind, parentId, atomIds, attributes, kindToken? }]

This is a syntax-level API; it does not claim polymer expansion, Markush interpretation, or cross-engine semantic compatibility.

Bundle size

The published v1.0.15 npm WASM asset is 4,005,280 bytes raw / 1,460,499 bytes gzip. Bundle size depends on features and toolchain; see the published-package scorecard for package versions, digests, tools, and reproduction steps.

PNG rasterization (tiny_skia) is excluded from the WASM build — use SVG output instead. All SVG depiction APIs remain fully available.

Versioned document binding boundary

The *_v1 document APIs provide a stable JSON boundary for downstream editors:

const parsed = JSON.parse(reaction_document_json_v1(JSON.stringify(document)));
const edited = JSON.parse(edit_reaction_document_json_v1(
  JSON.stringify(parsed),
  JSON.stringify({ kind: "set_step_condition", step_id: "step-1", key: "temperature", value: "25 C" }),
));

const cdxmlEnvelope = JSON.parse(cdxml_document_json_v1(cdxml));
const cdxmlAgain = cdxml_document_from_json_v1(JSON.stringify(cdxmlEnvelope));

cdxml_document_json_v1 retains the exact source string and returns a structural document summary with opaque objects and diagnostics. Use edit_cdxml_document_json_v1 for bounded page/object edits; it reparses the result before returning. Errors are JSON-shaped with stable code, path, and message fields (malformed_input, resource_limit, unsupported_construct, lossy_conversion, or serialization_error). reaction_document_to_rxn_v1 and cdxml_document_projection_json_v1 reject lossy legacy projections with lossy_conversion diagnostics. These APIs do not claim mechanism correctness, product prediction, complete stoichiometry, or full ChemDraw/RXN compatibility.

Building from source

wasm-pack build --target bundler --release