SMILES-JS

A modern JavaScript library for programmatic molecular construction and SMILES manipulation

Build complex molecules programmatically with an intuitive, composable API. Parse, manipulate, and generate SMILES notation with full round-trip fidelity.

---

Features

• Parse complex SMILES - Handles real-world pharmaceutical molecules (60-80+ characters)
• Programmatic construction - Build molecules using composable Ring, Linear, and Molecule constructors
• Polymer construction - Build repeating units with .repeat() and fused acene systems with .fusedRepeat()
• Mirror symmetry - Create palindromic chains and ABA block patterns with .mirror()
• Round-trip fidelity - Parse SMILES -> AST -> SMILES with structure preservation
• Code generation - Auto-generate JavaScript construction code from SMILES strings
• Pharmaceutical validated - Tested with Atorvastatin, Sildenafil, Ritonavir, and 30+ other drugs

---

Testimony

Claude link

---

Installation

npm install smiles-js

Embedding

<script type="module">
  import { Fragment, Ring, FusedRing, Linear } from 'https://unpkg.com/smiles-js@latest/src/index.js';
  import { benzene, methyl, ethyl, hydroxyl, carboxyl, phenyl, cyclohexane } from 'https://unpkg.com/smiles-js@latest/src/common.js';

  window.SMILES = { Fragment, Ring, FusedRing, Linear, benzene, methyl, ethyl, hydroxyl, carboxyl, phenyl, cyclohexane };
  // Your code
</script>

---

Quick Start

Parse SMILES

import { parse } from 'smiles-js';

// Parse any SMILES string
const aspirin = parse('CC(=O)Oc1ccccc1C(=O)O');
console.log(aspirin.smiles);  // CC(=O)Oc1ccccc1C(=O)O

// Parse complex drugs
const atorvastatin = parse('CC(C)c1c(C(=O)Nc2ccccc2)c(c3ccccc3)c(c4ccc(F)cc4)n1CCC(O)CC(O)CC(=O)O');
console.log(atorvastatin.smiles);  // Perfect round-trip!

Build Molecules Programmatically

import { Ring, Linear, Molecule } from 'smiles-js';

// Create benzene ring
const benzene = Ring({ atoms: 'c', size: 6 });
console.log(benzene.smiles);  // c1ccccc1

// Add methyl group to make toluene
const methyl = Linear(['C']);
const toluene = benzene.attach(1, methyl);
console.log(toluene.smiles);  // c1(C)ccccc1

// Create pyridine via substitution
const pyridine = benzene.substitute(5, 'n');
console.log(pyridine.smiles);  // c1cccnc1

Build Polymers

import { Ring, Linear } from 'smiles-js';

// Polyethylene trimer: repeat ethylene unit 3 times
const ethylene = Linear(['C', 'C']);
const PE = ethylene.repeat(3, 1, 2);
console.log(PE.smiles);  // CCCCCC

// Polystyrene dimer: repeat styrene unit with phenyl branch
const styrene = Linear(['C', 'C']).attach(2, Ring({ atoms: 'c', size: 6 }));
const PS = styrene.repeat(2, 1, 2);
console.log(PS.smiles);  // CC(c1ccccc1)CC(c2ccccc2)

// Acene series via fused repeat
const benzene = Ring({ atoms: 'c', size: 6 });
const naphthalene = benzene.fusedRepeat(2, 4);  // 2 fused rings
const anthracene = benzene.fusedRepeat(3, 4);   // 3 fused rings

Mirror Symmetry

import { Ring, Linear, Molecule } from 'smiles-js';

// Diethyl ether: mirror C-C-O around oxygen
const ether = Linear(['C', 'C', 'O']).mirror();
console.log(ether.smiles);  // CCOCC

// ABA triblock copolymer
const A = Linear(['C', 'C']);
const B = Ring({ atoms: 'c', size: 6 });
const ABA = Molecule([A, B]).mirror();
console.log(ABA.smiles);  // CCc1ccccc1CC

Generate Construction Code

import { parse } from 'smiles-js';

const molecule = parse('CCCc1ccccc1');
console.log(molecule.toCode());

Output:

const molecule1 = Linear(['C', 'C', 'C']);
const molecule2 = Ring({ atoms: 'c', size: 6 });
const molecule3 = Molecule([molecule1, molecule2]);

Round-Trip Validation

import { isValidRoundTrip, normalize } from 'smiles-js';

// Quick boolean check
if (isValidRoundTrip('c1ccccc1')) {
  console.log('Perfect round-trip!');
}

// Automatic normalization
const normalized = normalize('COc1ccc2nc(S(=O)Cc3ncc(C)c(OC)c3C)[nH]c2c1');

---

Full API Reference

See API.md for complete documentation including:

• All constructors and their options
• Ring, Linear, Molecule, and FusedRing manipulation methods
• Functional API imports
• Parsing & serialization utilities
• AST inspection
• Clone utilities
• RDKit integration

---

Documentation

• API Reference - Full API documentation
• Examples & Tutorials - 6 executable examples with real drugs
• Implementation Roadmap - Complete feature roadmap
• Parser Design - Grammar and architecture
• Implementation Status - Current status and testing
• Test Drive Results - Real-world validation

---

Contributing

Contributions welcome! Please see our contributing guidelines.

# Install dependencies
npm install

# Run tests
npm test

# Run linter
npm run lint

---

License

MIT License - see LICENSE file for details

---

Acknowledgments

• Tested with molecules from PubChem
• Inspired by SMILES notation from Daylight Chemical Information Systems
• Built with modern JavaScript and comprehensive testing

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions