selfies-js 0.1.0

package/src/properties/formula.test.js

@@ -0,0 +1,95 @@
+/**
+ * Tests for molecular formula generation
+ *
+ * Note: Also see properties.test.js for more tests
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { getFormula } from './formula.js'
+
+describe('getFormula', () => {
+  // TODO: Simple molecules
+  test('generates methane formula', () => {
+    // TODO: expect(getFormula('[C]')).toBe('CH4')
+  })
+
+  test('generates ethane formula', () => {
+    // TODO: expect(getFormula('[C][C]')).toBe('C2H6')
+  })
+
+  test('generates ethanol formula', () => {
+    // TODO: expect(getFormula('[C][C][O]')).toBe('C2H6O')
+  })
+
+  test('generates water formula', () => {
+    // TODO: expect(getFormula('[O]')).toBe('H2O')
+  })
+
+  // TODO: Hill notation rules
+  test('puts carbon first', () => {
+    // TODO: const formula = getFormula('[N][C][C]')
+    // TODO: expect(formula[0]).toBe('C')
+  })
+
+  test('puts hydrogen second', () => {
+    // TODO: const formula = getFormula('[C][C][O]')
+    // TODO: expect(formula).toMatch(/^C\d+H/)
+  })
+
+  test('orders other elements alphabetically', () => {
+    // TODO: const formula = getFormula('[C][S][N][O]')
+    // TODO: After C and H, should be N, O, S (alphabetical)
+  })
+
+  test('omits count of 1', () => {
+    // TODO: expect(getFormula('[C][O][O]')).toBe('CH2O2')
+    // TODO: Not CH2O2 but C, not C1
+  })
+
+  test('handles no carbon', () => {
+    // TODO: const formula = getFormula('[N][O]')
+    // TODO: Should still have H first if present, then alphabetical
+  })
+
+  // TODO: Different bond types
+  test('accounts for double bonds', () => {
+    // TODO: expect(getFormula('[C][=C]')).toBe('C2H4')
+    // TODO: Ethene, not ethane
+  })
+
+  test('accounts for triple bonds', () => {
+    // TODO: expect(getFormula('[C][#C]')).toBe('C2H2')
+    // TODO: Acetylene
+  })
+
+  // TODO: Complex structures
+  test('handles branching', () => {
+    // TODO: const formula = getFormula('[C][C][Branch1][C][C][C]')
+    // TODO: expect(formula).toBe('C4H10')  // Isobutane
+  })
+
+  test('handles rings', () => {
+    // TODO: const formula = getFormula('[C][=C][C][=C][C][=C][Ring1][=Branch1]')
+    // TODO: expect(formula).toBe('C6H6')  // Benzene
+  })
+
+  // TODO: Edge cases
+  test('handles single atom', () => {
+    // TODO: expect(getFormula('[C]')).toBe('CH4')
+  })
+
+  test('handles no hydrogen', () => {
+    // TODO: const formula = getFormula('[C][Cl][Cl][Cl][Cl]')
+    // TODO: CCl4 - no hydrogen atoms
+    // TODO: expect(formula).toBe('CCl4')
+  })
+
+  // TODO: Error cases
+  test('throws on invalid SELFIES', () => {
+    // TODO: expect(() => getFormula('[Xyz]')).toThrow()
+  })
+
+  test('throws on malformed SELFIES', () => {
+    // TODO: expect(() => getFormula('[C][C')).toThrow()
+  })
+})

package/src/properties/molecularWeight.js

@@ -0,0 +1,80 @@
+/**
+ * Molecular Weight - Calculates molecular weight from SELFIES
+ *
+ * Computes the molecular weight by parsing the SELFIES string,
+ * determining the molecular formula, and summing atomic masses.
+ */
+
+import { tokenize } from '../tokenizer.js'
+import { parse } from '../parser.js'
+import { getAtomicMass } from './atoms.js'
+
+/**
+ * Calculates molecular weight of a SELFIES molecule
+ * @param {string} selfies - SELFIES string
+ * @returns {number} Molecular weight in g/mol
+ *
+ * Example:
+ *   getMolecularWeight('[C][C][O]') // => 46.068 (ethanol: C2H6O)
+ *   getMolecularWeight('[C]') // => 16.043 (methane: CH4)
+ */
+export function getMolecularWeight(selfies) {
+  const tokens = tokenize(selfies)
+  const ir = parse(tokens)
+
+  const counts = countAtoms(ir)
+
+  let totalWeight = 0
+  for (const [element, count] of Object.entries(counts)) {
+    totalWeight += getAtomicMass(element) * count
+  }
+
+  return totalWeight
+}
+
+/**
+ * Counts atoms in molecule IR (including implicit hydrogens)
+ * @param {Object} ir - Molecule internal representation
+ * @returns {Object} Map of element to count
+ *
+ * Example return:
+ *   { 'C': 2, 'H': 6, 'O': 1 }  // for ethanol
+ */
+function countAtoms(ir) {
+  const counts = {}
+
+  // Count explicit atoms and calculate used valence
+  for (const atom of ir.atoms) {
+    counts[atom.element] = (counts[atom.element] || 0) + 1
+  }
+
+  // Calculate used valence from bonds
+  const usedValence = new Array(ir.atoms.length).fill(0)
+  for (const bond of ir.bonds) {
+    usedValence[bond.from] += bond.order
+    usedValence[bond.to] += bond.order
+  }
+
+  // Add implicit hydrogens
+  let totalH = 0
+  for (let i = 0; i < ir.atoms.length; i++) {
+    const atom = ir.atoms[i]
+    const implicitH = Math.max(0, atom.valence - usedValence[i])
+    totalH += implicitH
+  }
+
+  if (totalH > 0) {
+    counts['H'] = totalH
+  }
+
+  return counts
+}
+
+/**
+ * Calculates number of implicit hydrogens for an atom
+ * @param {Object} atom - Atom from IR
+ * @returns {number} Number of implicit hydrogens
+ */
+function getImplicitHydrogens(atom) {
+  return atom.valence - atom.usedValence
+}

package/src/properties/molecularWeight.test.js

@@ -0,0 +1,84 @@
+/**
+ * Tests for molecular weight calculation
+ *
+ * Note: Also see properties.test.js for more tests
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { getMolecularWeight } from './molecularWeight.js'
+
+describe('getMolecularWeight', () => {
+  // TODO: Simple molecules
+  test('calculates methane (CH4)', () => {
+    // TODO: const mw = getMolecularWeight('[C]')
+    // TODO: expect(mw).toBeCloseTo(16.043, 2)
+  })
+
+  test('calculates ethane (C2H6)', () => {
+    // TODO: const mw = getMolecularWeight('[C][C]')
+    // TODO: expect(mw).toBeCloseTo(30.070, 2)
+  })
+
+  test('calculates ethanol (C2H6O)', () => {
+    // TODO: const mw = getMolecularWeight('[C][C][O]')
+    // TODO: expect(mw).toBeCloseTo(46.068, 2)
+  })
+
+  // TODO: Different elements
+  test('includes nitrogen', () => {
+    // TODO: const mw = getMolecularWeight('[N][C][C]')
+    // TODO: Should include N mass (14.007) + 2 C + H atoms
+  })
+
+  test('includes oxygen', () => {
+    // TODO: const mw = getMolecularWeight('[C][=O]')
+    // TODO: Should calculate formaldehyde (CH2O)
+  })
+
+  test('includes sulfur', () => {
+    // TODO: const mw = getMolecularWeight('[C][S][C]')
+    // TODO: Should include S mass (32.06)
+  })
+
+  test('includes halogens', () => {
+    // TODO: const mw = getMolecularWeight('[C][Cl]')
+    // TODO: Should calculate chloromethane
+  })
+
+  // TODO: Implicit hydrogens
+  test('accounts for implicit hydrogens', () => {
+    // TODO: const mw = getMolecularWeight('[C]')
+    // TODO: C has 4 valence, 0 used → 4 H atoms
+    // TODO: MW = 12.011 + 4*1.008 = 16.043
+  })
+
+  test('reduces H for double bonds', () => {
+    // TODO: const mw = getMolecularWeight('[C][=C]')
+    // TODO: Ethene: C2H4, not C2H6
+  })
+
+  test('reduces H for triple bonds', () => {
+    // TODO: const mw = getMolecularWeight('[C][#C]')
+    // TODO: Acetylene: C2H2
+  })
+
+  // TODO: Complex structures
+  test('handles branching', () => {
+    // TODO: const mw = getMolecularWeight('[C][C][Branch1][C][C][C]')
+    // TODO: Isobutane: C4H10
+  })
+
+  test('handles rings', () => {
+    // TODO: const mw = getMolecularWeight('[C][=C][C][=C][C][=C][Ring1][=Branch1]')
+    // TODO: Benzene: C6H6 = 78.114
+  })
+
+  // TODO: Error cases
+  test('throws on invalid SELFIES', () => {
+    // TODO: expect(() => getMolecularWeight('[Xyz]')).toThrow()
+  })
+
+  test('throws on malformed SELFIES', () => {
+    // TODO: expect(() => getMolecularWeight('[C][C')).toThrow()
+  })
+})

package/src/properties/properties.test.js

@@ -0,0 +1,77 @@
+/**
+ * Tests for molecular property calculations
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { getMolecularWeight } from './molecularWeight.js'
+import { getFormula } from './formula.js'
+import { getAtomicMass, getValence } from './atoms.js'
+
+describe('getMolecularWeight', () => {
+  test('calculates methane molecular weight', () => {
+    expect(getMolecularWeight('[C]')).toBeCloseTo(16.043, 1)
+  })
+
+  test('calculates ethanol molecular weight', () => {
+    expect(getMolecularWeight('[C][C][O]')).toBeCloseTo(46.068, 1)
+  })
+
+  test('calculates benzene molecular weight', () => {
+    // TODO: expect(getMolecularWeight('[C][=C][C][=C][C][=C][Ring1][=Branch1]')).toBeCloseTo(78.114, 2)
+  })
+
+  // TODO: Different elements
+  test('calculates with nitrogen', () => {
+    // TODO: expect(getMolecularWeight('[N][C][C]')).toBeCloseTo(43.088, 2)
+  })
+
+  test('calculates with chlorine', () => {
+    // TODO: expect(getMolecularWeight('[Cl][C][C][Cl]')).toBeCloseTo(98.959, 2)
+  })
+})
+
+describe('getFormula', () => {
+  test('generates methane formula', () => {
+    expect(getFormula('[C]')).toBe('CH4')
+  })
+
+  test('generates ethanol formula', () => {
+    expect(getFormula('[C][C][O]')).toBe('C2H6O')
+  })
+
+  test('omits count of 1', () => {
+    expect(getFormula('[C][O][O]')).toBe('CH4O2')
+  })
+})
+
+describe('getAtomicMass', () => {
+  test('returns carbon mass', () => {
+    expect(getAtomicMass('C')).toBeCloseTo(12.011, 2)
+  })
+
+  test('returns oxygen mass', () => {
+    expect(getAtomicMass('O')).toBeCloseTo(15.999, 2)
+  })
+
+  test('throws on unsupported element', () => {
+    expect(() => getAtomicMass('Xx')).toThrow()
+  })
+})
+
+describe('getValence', () => {
+  test('returns carbon valence', () => {
+    expect(getValence('C')).toBe(4)
+  })
+
+  test('returns nitrogen valence', () => {
+    expect(getValence('N')).toBe(3)
+  })
+
+  test('returns oxygen valence', () => {
+    expect(getValence('O')).toBe(2)
+  })
+
+  test('throws on unsupported element', () => {
+    expect(() => getValence('Xx')).toThrow()
+  })
+})

package/src/renderers/README.md

@@ -0,0 +1,127 @@
+# SELFIES Renderers
+
+This directory contains rendering modules for visualizing molecular structures from SELFIES AST (Abstract Syntax Tree) representations.
+
+## SVG Renderer
+
+The SVG renderer converts molecular AST structures into Scalable Vector Graphics (SVG) format for visualization.
+
+### Usage
+
+```javascript
+import { decodeToAST, renderToSVG } from 'selfies-js'
+
+// Decode SELFIES to AST
+const ast = decodeToAST('[C][C][O]')
+
+// Render to SVG
+const svg = renderToSVG(ast)
+
+// Save or use the SVG string
+console.log(svg)
+```
+
+### Options
+
+The `renderToSVG` function accepts an optional options object:
+
+```javascript
+const svg = renderToSVG(ast, {
+  width: 400,              // Canvas width (default: 400)
+  height: 300,             // Canvas height (default: 300)
+  bondLength: 40,          // Length of bonds in pixels (default: 40)
+  atomRadius: 15,          // Radius of atom circles (default: 15)
+  fontSize: 14,            // Font size for atom labels (default: 14)
+  strokeWidth: 2,          // Bond line thickness (default: 2)
+  bondColor: '#333',       // Color of bonds (default: '#333')
+  atomColor: '#000',       // Color of atom text (default: '#000')
+  backgroundColor: 'transparent',  // Background color (default: 'transparent')
+  padding: 40              // Padding around the molecule (default: 40)
+})
+```
+
+### Features
+
+- **Automatic Layout**: Molecules are automatically positioned using a simple layout algorithm
+- **Bond Visualization**: Single, double, and triple bonds are rendered with appropriate styling
+- **Element Colors**: Atoms are colored according to chemistry conventions:
+  - Carbon (C): Gray
+  - Nitrogen (N): Blue
+  - Oxygen (O): Red
+  - Sulfur (S): Yellow
+  - Phosphorus (P): Orange
+  - Halogens (F, Cl, Br, I): Various greens and purples
+- **Ring Structures**: Properly handles ring closures
+- **Stereo Chemistry**: Displays stereochemistry notation (e.g., C@, C@@)
+- **Branching**: Correctly visualizes branched molecules
+
+### Examples
+
+```javascript
+// Simple molecule
+const methane = decodeToAST('[C]')
+const svg1 = renderToSVG(methane)
+
+// Molecule with double bond
+const ethene = decodeToAST('[C][=C]')
+const svg2 = renderToSVG(ethene)
+
+// Branched molecule
+const isobutane = decodeToAST('[C][C][Branch1][C][C][C]')
+const svg3 = renderToSVG(isobutane)
+
+// Ring structure
+const cyclopropane = decodeToAST('[C][C][C][Ring1][C]')
+const svg4 = renderToSVG(cyclopropane)
+
+// Complex aromatic ring
+const benzene = decodeToAST('[C][=C][C][=C][C][=C][Ring1][=Branch1]')
+const svg5 = renderToSVG(benzene)
+```
+
+### Saving SVG Files
+
+To save SVG output to files (Node.js):
+
+```javascript
+import { writeFileSync } from 'fs'
+import { decodeToAST, renderToSVG } from 'selfies-js'
+
+const ast = decodeToAST('[C][C][O]')
+const svg = renderToSVG(ast)
+
+writeFileSync('molecule.svg', svg)
+```
+
+### Browser Usage
+
+In the browser, you can insert the SVG directly into the DOM:
+
+```javascript
+import { decodeToAST, renderToSVG } from 'selfies-js'
+
+const ast = decodeToAST('[C][C][O]')
+const svg = renderToSVG(ast)
+
+// Insert into page
+document.getElementById('molecule-container').innerHTML = svg
+```
+
+## Future Renderers
+
+This directory is designed to accommodate additional renderers in the future:
+
+- **Canvas Renderer**: For rendering to HTML5 Canvas
+- **3D Renderer**: For three-dimensional molecular visualization
+- **ASCII Renderer**: For text-based terminal visualization
+- **WebGL Renderer**: For high-performance 3D rendering
+
+## Architecture
+
+All renderers follow a common pattern:
+
+1. Accept an AST object with `atoms`, `bonds`, and `rings` arrays
+2. Accept an optional configuration object
+3. Return a string or data structure representing the visualization
+
+This allows for consistent usage across different rendering backends.

package/src/renderers/svg.js

@@ -0,0 +1,113 @@
+/**
+ * SVG Renderer using RDKit.js
+ *
+ * Uses RDKit's MinimalLib to generate proper 2D coordinates and render molecules
+ */
+
+import initRDKitModule from '@rdkit/rdkit'
+import { decode } from '../decoder.js'
+
+let RDKitModule = null
+
+/**
+ * Initialize RDKit module (async, only done once)
+ */
+async function initRDKit() {
+  if (!RDKitModule) {
+    RDKitModule = await initRDKitModule()
+  }
+  return RDKitModule
+}
+
+/**
+ * Default rendering options
+ */
+const DEFAULT_OPTIONS = {
+  width: 300,
+  height: 300,
+  backgroundColor: 'transparent'
+}
+
+/**
+ * Renders a molecular structure to SVG using RDKit
+ * @param {Object} ast - AST object (not used, we use SMILES instead)
+ * @param {Object} options - Rendering options (optional)
+ * @returns {Promise<string>} SVG string representation
+ */
+export async function renderToSVG(ast, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options }
+
+  // We need SMILES for RDKit, so if we have an AST, we need to convert back
+  // For now, we'll need the original SELFIES or generate SMILES from AST
+  throw new Error('renderToSVG with AST not yet implemented - use renderSelfies instead')
+}
+
+/**
+ * Renders a SELFIES string to SVG using RDKit
+ * @param {string} selfies - SELFIES string
+ * @param {Object} options - Rendering options (optional)
+ * @returns {Promise<string>} SVG string representation
+ */
+export async function renderSelfies(selfies, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options }
+
+  // Initialize RDKit
+  const RDKit = await initRDKit()
+
+  // Convert SELFIES to SMILES
+  const smiles = decode(selfies)
+
+  // Create molecule from SMILES
+  const mol = RDKit.get_mol(smiles)
+
+  if (!mol || !mol.is_valid()) {
+    throw new Error(`Invalid molecule from SMILES: ${smiles}`)
+  }
+
+  // Generate SVG with RDKit
+  const svg = mol.get_svg_with_highlights(JSON.stringify({
+    width: opts.width,
+    height: opts.height,
+    addStereoAnnotation: true,
+    kekulize: false
+  }))
+
+  // Clean up
+  mol.delete()
+
+  return svg
+}
+
+/**
+ * Synchronous version that returns SVG directly
+ * Note: This will throw if RDKit hasn't been initialized
+ * @param {string} selfies - SELFIES string
+ * @param {Object} options - Rendering options
+ * @returns {string} SVG string
+ */
+export function renderSelfiesSync(selfies, options = {}) {
+  if (!RDKitModule) {
+    throw new Error('RDKit not initialized. Call initRDKit() first or use renderSelfies()')
+  }
+
+  const opts = { ...DEFAULT_OPTIONS, ...options }
+  const smiles = decode(selfies)
+  const mol = RDKitModule.get_mol(smiles)
+
+  if (!mol || !mol.is_valid()) {
+    throw new Error(`Invalid molecule from SMILES: ${smiles}`)
+  }
+
+  const svg = mol.get_svg_with_highlights(JSON.stringify({
+    width: opts.width,
+    height: opts.height,
+    addStereoAnnotation: true,
+    kekulize: false
+  }))
+
+  mol.delete()
+  return svg
+}
+
+// Export init function
+export { initRDKit }

package/src/renderers/svg.test.js

@@ -0,0 +1,42 @@
+/**
+ * Tests for SVG renderer (using RDKit)
+ */
+
+import { describe, test, expect, beforeAll } from 'bun:test'
+import { renderSelfies, initRDKit } from './svg.js'
+
+describe('SVG Renderer (RDKit)', () => {
+  beforeAll(async () => {
+    // Initialize RDKit once before all tests
+    await initRDKit()
+  })
+
+  test('renders methane', async () => {
+    const svg = await renderSelfies('[C]')
+    expect(svg).toContain('<svg')
+    expect(svg).toContain('</svg>')
+  })
+
+  test('renders ethane', async () => {
+    const svg = await renderSelfies('[C][C]')
+    expect(svg).toContain('<svg')
+    expect(svg).toContain('path') // RDKit uses paths for bonds
+  })
+
+  test('renders benzene', async () => {
+    const svg = await renderSelfies('[C][=C][C][=C][C][=C][Ring1][=Branch1]')
+    expect(svg).toContain('<svg')
+    expect(svg).toContain('path')
+  })
+
+  test('renders toluene', async () => {
+    const svg = await renderSelfies('[C][C][=C][C][=C][C][=C][Ring1][=N]')
+    expect(svg).toContain('<svg')
+    expect(svg).toContain('path')
+  })
+
+  test('accepts custom width and height', async () => {
+    const svg = await renderSelfies('[C]', { width: 400, height: 400 })
+    expect(svg).toContain('400')
+  })
+})