smiles-js 0.2.0 → 0.2.2

package/.github/workflows/ci.yml

@@ -19,5 +19,8 @@ jobs:
         with:
           node-version: '20'
 
+      - name: Install dependencies
+        run: npm ci
+
       - name: Run tests
         run: npm test

package/.github/workflows/publish.yml

@@ -29,6 +29,9 @@ jobs:
           node-version: '20'
           registry-url: 'https://registry.npmjs.org'
 
+      - name: Install dependencies
+        run: npm ci
+
       - name: Run tests
         run: npm test
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smiles-js",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A JavaScript library for building molecules using composable fragments",
   "type": "module",
   "main": "src/index.js",
@@ -22,5 +22,8 @@
     "dsl"
   ],
   "author": "",
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "@rdkit/rdkit": "^2025.3.4-1.0.0"
+  }
 }

package/src/common.js

@@ -29,5 +29,5 @@ export const furan = Ring('c', 5, { replace: { 0: 'o' } });
 export const thiophene = Ring('c', 5, { replace: { 0: 's' } });
 
 export const naphthalene = FusedRings([6, 6], 'c');
-export const indole = FusedRings([6, 5], 'c', { hetero: { 7: '[nH]' } });
+export const indole = FusedRings([6, 5], 'c', { hetero: { 4: '[nH]' } });
 export const quinoline = FusedRings([6, 6], 'c', { hetero: { 0: 'n' } });

package/src/ring.js

@@ -1,20 +1,113 @@
 import { Fragment } from './fragment.js';
+import { findUsedRingNumbers, getNextRingNumber } from './utils.js';
 
 export function Ring(atom, size, options = {}) {
   const { replace = {} } = options;
 
-  let smiles = '';
-  for (let i = 0; i < size; i++) {
-    const currentAtom = replace[i] !== undefined ? replace[i] : atom;
+  // Build the ring SMILES
+  const buildRingSmiles = (replacements) => {
+    const parts = [];
 
-    if (i === 0) {
-      smiles += currentAtom + '1';
-    } else if (i === size - 1) {
-      smiles += currentAtom + '1';
-    } else {
-      smiles += currentAtom;
+    for (let i = 0; i < size; i++) {
+      const currentAtom = replacements[i] !== undefined ? replacements[i] : atom;
+
+      if (i === 0) {
+        parts.push(currentAtom + '1');
+      } else if (i === size - 1) {
+        parts.push(currentAtom + '1');
+      } else {
+        parts.push(currentAtom);
+      }
     }
-  }
 
-  return Fragment(smiles);
+    return parts.join('');
+  };
+
+  const smiles = buildRingSmiles(replace);
+  const fragment = Fragment(smiles);
+
+  // Track substituents for chaining
+  const substituents = {};
+
+  // Add attachAt method to the fragment
+  const createAttachAt = (currentSubstituents) => {
+    return function(position, substituent) {
+      if (position < 1 || position > size) {
+        throw new Error(`Position ${position} is out of range for ring of size ${size}`);
+      }
+
+      // Convert 1-based position to 0-based index
+      const index = position - 1;
+
+      // Create new substituents map with this addition
+      const newSubstituents = { ...currentSubstituents };
+
+      // Handle substituent - could be string, Fragment, or Ring
+      let subSmiles;
+      if (typeof substituent === 'string') {
+        subSmiles = substituent;
+      } else if (substituent.smiles) {
+        subSmiles = substituent.smiles;
+      } else {
+        subSmiles = String(substituent);
+      }
+
+      newSubstituents[index] = subSmiles;
+
+      // Build SMILES with all substituents at the specified positions
+      const parts = [];
+
+      for (let i = 0; i < size; i++) {
+        const currentAtom = replace[i] !== undefined ? replace[i] : atom;
+
+        if (newSubstituents[i]) {
+          // Remap ring numbers in substituent to avoid conflicts
+          const currentSmiles = parts.join('');
+          const usedInCurrent = findUsedRingNumbers(currentSmiles);
+          const usedInSubstituent = findUsedRingNumbers(newSubstituents[i]);
+
+          let remappedSubstituent = newSubstituents[i];
+          for (const ringNum of usedInSubstituent) {
+            if (usedInCurrent.has(ringNum)) {
+              const newNum = getNextRingNumber(currentSmiles + remappedSubstituent);
+              // For %NN format, replace the whole %NN
+              // For single digit, replace all occurrences (this works because each ring number appears exactly twice)
+              if (ringNum.length > 1) {
+                remappedSubstituent = remappedSubstituent.replaceAll(`%${ringNum}`, newNum);
+              } else {
+                remappedSubstituent = remappedSubstituent.replaceAll(ringNum, newNum.replace('%', ''));
+              }
+            }
+          }
+
+          // Add substituent at this position
+          if (i === 0) {
+            parts.push(currentAtom + '1(' + remappedSubstituent + ')');
+          } else if (i === size - 1) {
+            parts.push(currentAtom + '(' + remappedSubstituent + ')1');
+          } else {
+            parts.push(currentAtom + '(' + remappedSubstituent + ')');
+          }
+        } else if (i === 0) {
+          parts.push(currentAtom + '1');
+        } else if (i === size - 1) {
+          parts.push(currentAtom + '1');
+        } else {
+          parts.push(currentAtom);
+        }
+      }
+
+      const newSmiles = parts.join('');
+      const newFragment = Fragment(newSmiles);
+
+      // Recursively add attachAt to the new fragment with updated substituents
+      newFragment.attachAt = createAttachAt(newSubstituents);
+
+      return newFragment;
+    };
+  };
+
+  fragment.attachAt = createAttachAt(substituents);
+
+  return fragment;
 }

package/test/common.test.js

@@ -1,5 +1,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert';
+import { isValidSMILES } from './test-utils.js';
 import {
   methyl, ethyl, propyl, isopropyl, butyl, tbutyl,
   hydroxyl, amino, carboxyl, carbonyl, nitro, cyano,
@@ -8,53 +9,81 @@ import {
   naphthalene, indole, quinoline
 } from '../src/common.js';
 
-test('Common alkyls are defined', () => {
+test('Common alkyls are defined', async () => {
   assert.strictEqual(methyl.smiles, 'C');
+  assert.ok(await isValidSMILES(methyl.smiles));
   assert.strictEqual(ethyl.smiles, 'CC');
+  assert.ok(await isValidSMILES(ethyl.smiles));
   assert.strictEqual(propyl.smiles, 'CCC');
+  assert.ok(await isValidSMILES(propyl.smiles));
   assert.strictEqual(isopropyl.smiles, 'C(C)C');
+  assert.ok(await isValidSMILES(isopropyl.smiles));
   assert.strictEqual(butyl.smiles, 'CCCC');
+  assert.ok(await isValidSMILES(butyl.smiles));
   assert.strictEqual(tbutyl.smiles, 'C(C)(C)C');
+  assert.ok(await isValidSMILES(tbutyl.smiles));
 });
 
-test('Common functional groups are defined', () => {
+test('Common functional groups are defined', async () => {
   assert.strictEqual(hydroxyl.smiles, 'O');
+  assert.ok(await isValidSMILES(hydroxyl.smiles));
   assert.strictEqual(amino.smiles, 'N');
+  assert.ok(await isValidSMILES(amino.smiles));
   assert.strictEqual(carboxyl.smiles, 'C(=O)O');
+  assert.ok(await isValidSMILES(carboxyl.smiles));
   assert.strictEqual(carbonyl.smiles, 'C=O');
+  assert.ok(await isValidSMILES(carbonyl.smiles));
   assert.strictEqual(nitro.smiles, '[N+](=O)[O-]');
+  assert.ok(await isValidSMILES(nitro.smiles));
   assert.strictEqual(cyano.smiles, 'C#N');
+  assert.ok(await isValidSMILES(cyano.smiles));
 });
 
-test('Common halogens are defined', () => {
+test('Common halogens are defined', async () => {
   assert.strictEqual(fluoro.smiles, 'F');
+  assert.ok(await isValidSMILES(fluoro.smiles));
   assert.strictEqual(chloro.smiles, 'Cl');
+  assert.ok(await isValidSMILES(chloro.smiles));
   assert.strictEqual(bromo.smiles, 'Br');
+  assert.ok(await isValidSMILES(bromo.smiles));
   assert.strictEqual(iodo.smiles, 'I');
+  assert.ok(await isValidSMILES(iodo.smiles));
 });
 
-test('Common rings are defined', () => {
+test('Common rings are defined', async () => {
   assert.strictEqual(benzene.smiles, 'c1ccccc1');
+  assert.ok(await isValidSMILES(benzene.smiles));
   assert.strictEqual(cyclohexane.smiles, 'C1CCCCC1');
+  assert.ok(await isValidSMILES(cyclohexane.smiles));
   assert.strictEqual(pyridine.smiles, 'n1ccccc1');
+  assert.ok(await isValidSMILES(pyridine.smiles));
   assert.strictEqual(pyrrole.smiles, '[nH]1cccc1');
+  assert.ok(await isValidSMILES(pyrrole.smiles));
   assert.strictEqual(furan.smiles, 'o1cccc1');
+  assert.ok(await isValidSMILES(furan.smiles));
   assert.strictEqual(thiophene.smiles, 's1cccc1');
+  assert.ok(await isValidSMILES(thiophene.smiles));
 });
 
-test('Common fused rings are defined', () => {
+test('Common fused rings are defined', async () => {
   assert.strictEqual(naphthalene.smiles, 'c1ccc2ccccc2c1');
-  assert.strictEqual(indole.smiles, 'c1ccc2ccc[nH]2c1');
+  assert.ok(await isValidSMILES(naphthalene.smiles));
+  assert.strictEqual(indole.smiles, 'c1ccc2[nH]ccc2c1');
+  assert.ok(await isValidSMILES(indole.smiles));
   assert.strictEqual(quinoline.smiles, 'n1ccc2ccccc2c1');
+  assert.ok(await isValidSMILES(quinoline.smiles));
 });
 
-test('Common fragments can be composed', () => {
+test('Common fragments can be composed', async () => {
   const toluene = benzene(methyl);
   assert.strictEqual(toluene.smiles, 'c1ccccc1(C)');
+  assert.ok(await isValidSMILES(toluene.smiles));
 
   const phenol = benzene(hydroxyl);
   assert.strictEqual(phenol.smiles, 'c1ccccc1(O)');
+  assert.ok(await isValidSMILES(phenol.smiles));
 
   const benzoicAcid = benzene(carboxyl);
   assert.strictEqual(benzoicAcid.smiles, 'c1ccccc1(C(=O)O)');
+  assert.ok(await isValidSMILES(benzoicAcid.smiles));
 });

package/test/concat.test.js

@@ -1,190 +1,214 @@
 import { test } from 'node:test';
 import assert from 'node:assert';
 import { Fragment } from '../src/fragment.js';
+import { isValidSMILES } from './test-utils.js';
 
-test('concat combines two simple fragments', () => {
+test('concat combines two simple fragments', async () => {
   const a = Fragment('CC');
   const b = Fragment('CC');
   const result = a.concat(b);
   assert.strictEqual(result.smiles, 'CCCC');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat works with method chaining', () => {
+test('concat works with method chaining', async () => {
   const a = Fragment('C');
   const b = Fragment('C');
   const c = Fragment('C');
   const result = a.concat(b).concat(c);
   assert.strictEqual(result.smiles, 'CCC');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat handles string arguments', () => {
+test('concat handles string arguments', async () => {
   const a = Fragment('CC');
   const result = a.concat('CC');
   assert.strictEqual(result.smiles, 'CCCC');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat preserves properties', () => {
+test('concat preserves properties', async () => {
   const a = Fragment('C');
   const b = Fragment('C');
   const result = a.concat(b);
-  
+
   assert.strictEqual(result.atoms, 2);
   assert.strictEqual(result.formula, 'C2H6');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat handles fragments with branches', () => {
+test('concat handles fragments with branches', async () => {
   const a = Fragment('C(C)C');
   const b = Fragment('CC');
   const result = a.concat(b);
   assert.strictEqual(result.smiles, 'C(C)CCC');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat handles rings without conflicts', () => {
+test('concat handles rings without conflicts', async () => {
   const a = Fragment('C1CCC1');
   const b = Fragment('CC');
   const result = a.concat(b);
   assert.strictEqual(result.smiles, 'C1CCC1CC');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat remaps conflicting ring numbers', () => {
+test('concat remaps conflicting ring numbers', async () => {
   const a = Fragment('C1CCC1');
   const b = Fragment('C1CCC1');
   const result = a.concat(b);
-  
+
   // The second ring should be remapped to ring 2
   assert.strictEqual(result.smiles, 'C1CCC1C2CCC2');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat handles multiple ring conflicts', () => {
+test('concat handles multiple ring conflicts', async () => {
   const a = Fragment('C1CCC1C2CCC2');
   const b = Fragment('C1CCC1C2CCC2');
   const result = a.concat(b);
-  
+
   // Rings should be remapped to 3 and 4
   assert.strictEqual(result.smiles, 'C1CCC1C2CCC2C3CCC3C4CCC4');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat handles aromatic rings', () => {
+test('concat handles aromatic rings', async () => {
   const benzene1 = Fragment('c1ccccc1');
   const benzene2 = Fragment('c1ccccc1');
   const result = benzene1.concat(benzene2);
-  
+
   assert.strictEqual(result.smiles, 'c1ccccc1c2ccccc2');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat works with complex molecules', () => {
+test('concat works with complex molecules', async () => {
   const phenyl = Fragment('c1ccccc1');
   const methyl = Fragment('C');
   const result = phenyl.concat(methyl);
-  
+
   assert.strictEqual(result.smiles, 'c1ccccc1C');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat can be used multiple times', () => {
+test('concat can be used multiple times', async () => {
   const c = Fragment('C');
   const result = c.concat('C').concat('C').concat('C');
-  
+
   assert.strictEqual(result.smiles, 'CCCC');
   assert.strictEqual(result.atoms, 4);
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('Static Fragment.concat works', () => {
+test('Static Fragment.concat works', async () => {
   const a = Fragment('CC');
   const b = Fragment('CC');
   const result = Fragment.concat(a, b);
-  
+
   assert.strictEqual(result.smiles, 'CCCC');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('Static Fragment.concat accepts strings', () => {
+test('Static Fragment.concat accepts strings', async () => {
   const result = Fragment.concat('CC', 'CC');
   assert.strictEqual(result.smiles, 'CCCC');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat with functional groups', () => {
+test('concat with functional groups', async () => {
   const ethyl = Fragment('CC');
   const hydroxyl = Fragment('O');
   const result = ethyl.concat(hydroxyl);
-  
+
   assert.strictEqual(result.smiles, 'CCO');
   assert.strictEqual(result.formula, 'C2H6O');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat preserves original fragments', () => {
+test('concat preserves original fragments', async () => {
   const a = Fragment('CC');
   const b = Fragment('CC');
   const result = a.concat(b);
-  
+
   // Original fragments should be unchanged
   assert.strictEqual(a.smiles, 'CC');
   assert.strictEqual(b.smiles, 'CC');
   assert.strictEqual(result.smiles, 'CCCC');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat with heterocycles', () => {
+test('concat with heterocycles', async () => {
   const pyridine = Fragment('n1ccccc1');
   const methyl = Fragment('C');
   const result = pyridine.concat(methyl);
-  
+
   assert.strictEqual(result.smiles, 'n1ccccc1C');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat builds polymer-like chains', () => {
+test('concat builds polymer-like chains', async () => {
   const ethylene = Fragment('CC');
   let polymer = ethylene;
-  
+
   for (let i = 0; i < 4; i++) {
     polymer = polymer.concat(ethylene);
   }
-  
+
   assert.strictEqual(polymer.smiles, 'CCCCCCCCCC'); // 5 ethylene units = 10 carbons
   assert.strictEqual(polymer.atoms, 10);
+  assert.ok(await isValidSMILES(polymer.smiles));
 });
 
-test('concat with charged species', () => {
-  const a = Fragment('[NH4+]');
-  const b = Fragment('[O-]');
+test('concat with charged species', async () => {
+  const a = Fragment('[NH3+]');
+  const b = Fragment('C');
   const result = a.concat(b);
-  
-  assert.strictEqual(result.smiles, '[NH4+][O-]');
+
+  assert.strictEqual(result.smiles, '[NH3+]C');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat handles double and triple bonds', () => {
+test('concat handles double and triple bonds', async () => {
   const ethylene = Fragment('C=C');
   const methyl = Fragment('C');
   const result = ethylene.concat(methyl);
-  
+
   assert.strictEqual(result.smiles, 'C=CC');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat with stereochemistry', () => {
+test('concat with stereochemistry', async () => {
   const a = Fragment('C[C@H](O)C');
   const b = Fragment('C');
   const result = a.concat(b);
-  
+
   assert.strictEqual(result.smiles, 'C[C@H](O)CC');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat example from requirement: Fragment("CC") + Fragment("CC")', () => {
+test('concat example from requirement: Fragment("CC") + Fragment("CC")', async () => {
   const a = Fragment('CC');
   const b = Fragment('CC');
   const result = a.concat(b);
-  
+
   assert.strictEqual(result.smiles, 'CCCC');
   assert.strictEqual(String(result), 'CCCC');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('concat returns a new Fragment with all methods', () => {
+test('concat returns a new Fragment with all methods', async () => {
   const a = Fragment('C');
   const b = Fragment('C');
   const result = a.concat(b);
-  
+
   // Should have all Fragment methods
   assert.strictEqual(typeof result.concat, 'function');
   assert.strictEqual(typeof result.toString, 'function');
   assert.strictEqual(typeof result, 'function'); // Can be called as a function for branching
-  
+
   // Can still use for branching
   const branched = result(Fragment('O'));
   assert.strictEqual(branched.smiles, 'CC(O)');
+  assert.ok(await isValidSMILES(result.smiles));
+  assert.ok(await isValidSMILES(branched.smiles));
 });

package/test/examples.test.js

@@ -2,46 +2,55 @@ import { test } from 'node:test';
 import assert from 'node:assert';
 import { Fragment, Ring } from '../src/index.js';
 import { benzene, methyl, hydroxyl, carboxyl } from '../src/common.js';
+import { isValidSMILES } from './test-utils.js';
 
-test('README example: toluene', () => {
+test('README example: toluene', async () => {
   const benzeneRing = Ring('c', 6);
   const methylGroup = Fragment('C');
   const toluene = benzeneRing(methylGroup);
+  assert.ok(await isValidSMILES(toluene.smiles));
   assert.strictEqual(String(toluene), 'c1ccccc1(C)');
 });
 
-test('README example: ethanol', () => {
+test('README example: ethanol', async () => {
   const ethyl = Fragment('CC');
   const hydroxylGroup = Fragment('O');
   const ethanol = ethyl(hydroxylGroup);
+  assert.ok(await isValidSMILES(ethanol.smiles));
   assert.strictEqual(ethanol.smiles, 'CC(O)');
 });
 
-test('README example: acetone', () => {
+test('README example: acetone', async () => {
   const methylGroup = Fragment('C');
   const acetone = methylGroup(Fragment('=O'))(methylGroup);
+  assert.ok(await isValidSMILES(acetone.smiles));
   assert.strictEqual(acetone.smiles, 'C(=O)(C)');
 });
 
-test('README example: nested branching', () => {
+test('README example: nested branching', async () => {
   const a = Fragment('C');
   const b = Fragment('CC');
   const c = Fragment('CCC');
   const molecule = a(b(c));
+  assert.ok(await isValidSMILES(molecule.smiles));
   assert.strictEqual(molecule.smiles, 'C(CC(CCC))');
 });
 
-test('README example: aspirin', () => {
-  const aspirin = benzene(carboxyl)(Fragment('OC(=O)C'));
-  assert.strictEqual(aspirin.smiles, 'c1ccccc1(C(=O)O)(OC(=O)C)');
+test('README example: aspirin', async () => {
+  const benzeneRing = Ring('c', 6);
+  const aspirin = benzeneRing.attachAt(2, carboxyl).attachAt(3, Fragment('OC(=O)C'));
+  assert.ok(await isValidSMILES(aspirin.smiles));
+  assert.strictEqual(aspirin.smiles, 'c1c(C(=O)O)c(OC(=O)C)ccc1');
 });
 
-test('README example: ibuprofen', () => {
-  const ibuprofen = benzene(Fragment('CC(C)C'))(Fragment('CC(C)C(=O)O'));
-  assert.strictEqual(ibuprofen.smiles, 'c1ccccc1(CC(C)C)(CC(C)C(=O)O)');
+test('README example: ibuprofen', async () => {
+  const benzeneRing = Ring('c', 6);
+  const ibuprofen = benzeneRing.attachAt(2, Fragment('CC(C)C')).attachAt(5, Fragment('CC(C)C(=O)O'));
+  assert.ok(await isValidSMILES(ibuprofen.smiles));
+  assert.strictEqual(ibuprofen.smiles, 'c1c(CC(C)C)ccc(CC(C)C(=O)O)c1');
 });
 
-test('README example: molecule library', () => {
+test('README example: molecule library', async () => {
   const acetyl = Fragment('C(=O)C');
   const phenyl = benzene;
 
@@ -52,6 +61,10 @@ test('README example: molecule library', () => {
     acetophenone: phenyl(acetyl),
   };
 
+  assert.ok(await isValidSMILES(molecules.toluene.smiles));
+  assert.ok(await isValidSMILES(molecules.phenol.smiles));
+  assert.ok(await isValidSMILES(molecules.benzoicAcid.smiles));
+  assert.ok(await isValidSMILES(molecules.acetophenone.smiles));
   assert.strictEqual(String(molecules.toluene), 'c1ccccc1(C)');
   assert.strictEqual(String(molecules.phenol), 'c1ccccc1(O)');
   assert.strictEqual(String(molecules.benzoicAcid), 'c1ccccc1(C(=O)O)');

package/test/fragment.test.js

@@ -1,10 +1,12 @@
 import { test } from 'node:test';
 import assert from 'node:assert';
 import { Fragment } from '../src/fragment.js';
+import { isValidSMILES } from './test-utils.js';
 
-test('Fragment creates basic fragments', () => {
+test('Fragment creates basic fragments', async () => {
   const methyl = Fragment('C');
   assert.strictEqual(methyl.smiles, 'C');
+  assert.ok(await isValidSMILES(methyl.smiles));
   assert.strictEqual(String(methyl), 'C');
 });
 
@@ -20,78 +22,94 @@ test('Fragment.validate returns validation result', () => {
   assert.deepStrictEqual(result2, { valid: true });
 });
 
-test('Fragment supports branching', () => {
+test('Fragment supports branching', async () => {
   const methyl = Fragment('C');
   const ethyl = Fragment('CC');
   const result = methyl(ethyl);
   assert.strictEqual(result.smiles, 'C(CC)');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('Fragment supports multiple branches', () => {
+test('Fragment supports multiple branches', async () => {
   const methyl = Fragment('C');
   const ethyl = Fragment('CC');
   const result = methyl(ethyl)(ethyl);
   assert.strictEqual(result.smiles, 'C(CC)(CC)');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('Fragment supports nested branches', () => {
+test('Fragment supports nested branches', async () => {
   const a = Fragment('C');
   const b = Fragment('CC');
   const c = Fragment('CCC');
   const result = a(b(c));
   assert.strictEqual(result.smiles, 'C(CC(CCC))');
+  assert.ok(await isValidSMILES(result.smiles));
 });
 
-test('Fragment counts atoms correctly', () => {
+test('Fragment counts atoms correctly', async () => {
   const methyl = Fragment('C');
   assert.strictEqual(methyl.atoms, 1);
+  assert.ok(await isValidSMILES(methyl.smiles));
 
   const ethyl = Fragment('CC');
   assert.strictEqual(ethyl.atoms, 2);
+  assert.ok(await isValidSMILES(ethyl.smiles));
 
   const benzene = Fragment('c1ccccc1');
   assert.strictEqual(benzene.atoms, 6);
+  assert.ok(await isValidSMILES(benzene.smiles));
 });
 
-test('Fragment counts rings correctly', () => {
+test('Fragment counts rings correctly', async () => {
   const methyl = Fragment('C');
   assert.strictEqual(methyl.rings, 0);
+  assert.ok(await isValidSMILES(methyl.smiles));
 
   const benzene = Fragment('c1ccccc1');
   assert.strictEqual(benzene.rings, 1);
+  assert.ok(await isValidSMILES(benzene.smiles));
 
   const naphthalene = Fragment('c1ccc2ccccc2c1');
   assert.strictEqual(naphthalene.rings, 2);
+  assert.ok(await isValidSMILES(naphthalene.smiles));
 });
 
-test('Fragment calculates formula correctly', () => {
+test('Fragment calculates formula correctly', async () => {
   const methyl = Fragment('C');
   assert.strictEqual(methyl.formula, 'CH4');
+  assert.ok(await isValidSMILES(methyl.smiles));
 
   const ethyl = Fragment('CC');
   assert.strictEqual(ethyl.formula, 'C2H6');
+  assert.ok(await isValidSMILES(ethyl.smiles));
 
   const carbonyl = Fragment('C=O');
   assert.strictEqual(carbonyl.formula, 'CH2O');
+  assert.ok(await isValidSMILES(carbonyl.smiles));
 });
 
-test('Fragment calculates molecular weight correctly', () => {
+test('Fragment calculates molecular weight correctly', async () => {
   const methyl = Fragment('C');
   assert.strictEqual(methyl.molecularWeight, 16.04);
+  assert.ok(await isValidSMILES(methyl.smiles));
 
   const ethyl = Fragment('CC');
   assert.strictEqual(ethyl.molecularWeight, 30.07);
+  assert.ok(await isValidSMILES(ethyl.smiles));
 });
 
-test('Fragment works with complex molecules', () => {
+test('Fragment works with complex molecules', async () => {
   const benzene = Fragment('c1ccccc1');
   const methyl = Fragment('C');
   const toluene = benzene(methyl);
   assert.strictEqual(toluene.smiles, 'c1ccccc1(C)');
+  assert.ok(await isValidSMILES(toluene.smiles));
 });
 
-test('Fragment toString and toPrimitive work correctly', () => {
+test('Fragment toString and toPrimitive work correctly', async () => {
   const methyl = Fragment('C');
   assert.strictEqual(methyl.toString(), 'C');
+  assert.ok(await isValidSMILES(methyl.smiles));
   assert.strictEqual(`${methyl}`, 'C');
 });

package/test/fused-rings.test.js

@@ -1,24 +1,29 @@
 import { test } from 'node:test';
 import assert from 'node:assert';
 import { FusedRings } from '../src/fused-rings.js';
+import { isValidSMILES } from './test-utils.js';
 
-test('FusedRings creates naphthalene', () => {
+test('FusedRings creates naphthalene', async () => {
   const naphthalene = FusedRings([6, 6], 'c');
+  assert.ok(await isValidSMILES(naphthalene.smiles));
   assert.strictEqual(naphthalene.smiles, 'c1ccc2ccccc2c1');
 });
 
-test('FusedRings creates indene', () => {
-  const indene = FusedRings([6, 5], 'c');
-  assert.strictEqual(indene.smiles, 'c1ccc2cccc2c1');
+test('FusedRings creates fused 6-5 ring system', async () => {
+  const fused = FusedRings([6, 5], 'C');
+  assert.ok(await isValidSMILES(fused.smiles));
+  assert.strictEqual(fused.smiles, 'C1CCC2CCCC2C1');
 });
 
-test('FusedRings with hetero creates indole-like structure', () => {
-  const indole = FusedRings([6, 5], 'c', { hetero: { 7: '[nH]' } });
-  assert.strictEqual(indole.smiles, 'c1ccc2ccc[nH]2c1');
+test('FusedRings with hetero creates indole-like structure', async () => {
+  const indole = FusedRings([6, 5], 'c', { hetero: { 4: '[nH]' } });
+  assert.ok(await isValidSMILES(indole.smiles));
+  assert.strictEqual(indole.smiles, 'c1ccc2[nH]ccc2c1');
 });
 
-test('FusedRings with hetero creates quinoline', () => {
+test('FusedRings with hetero creates quinoline', async () => {
   const quinoline = FusedRings([6, 6], 'c', { hetero: { 0: 'n' } });
+  assert.ok(await isValidSMILES(quinoline.smiles));
   assert.strictEqual(quinoline.smiles, 'n1ccc2ccccc2c1');
 });
 
@@ -30,12 +35,14 @@ test('FusedRings throws on 3+ rings', () => {
   assert.throws(() => FusedRings([6, 6, 6], 'c'), { message: 'FusedRings currently only supports 2 rings' });
 });
 
-test('FusedRings counts atoms correctly', () => {
+test('FusedRings counts atoms correctly', async () => {
   const naphthalene = FusedRings([6, 6], 'c');
+  assert.ok(await isValidSMILES(naphthalene.smiles));
   assert.strictEqual(naphthalene.atoms, 10);
 });
 
-test('FusedRings counts rings correctly', () => {
+test('FusedRings counts rings correctly', async () => {
   const naphthalene = FusedRings([6, 6], 'c');
+  assert.ok(await isValidSMILES(naphthalene.smiles));
   assert.strictEqual(naphthalene.rings, 2);
 });

package/test/repeat.test.js

@@ -2,29 +2,35 @@ import { test } from 'node:test';
 import assert from 'node:assert';
 import { Repeat } from '../src/repeat.js';
 import { Fragment } from '../src/fragment.js';
+import { isValidSMILES } from './test-utils.js';
 
-test('Repeat creates hexane', () => {
+test('Repeat creates hexane', async () => {
   const hexane = Repeat('C', 6);
+  assert.ok(await isValidSMILES(hexane.smiles));
   assert.strictEqual(hexane.smiles, 'CCCCCC');
 });
 
-test('Repeat creates PEG-like chain', () => {
+test('Repeat creates PEG-like chain', async () => {
   const peg = Repeat('CCO', 4);
+  assert.ok(await isValidSMILES(peg.smiles));
   assert.strictEqual(peg.smiles, 'CCOCCOCCOCCO');
 });
 
-test('Repeat creates polyethylene', () => {
+test('Repeat creates polyethylene', async () => {
   const polyethylene = Repeat('CC', 100);
+  assert.ok(await isValidSMILES(polyethylene.smiles));
   assert.strictEqual(polyethylene.smiles, 'CC'.repeat(100));
 });
 
-test('Repeat works with Fragment objects', () => {
+test('Repeat works with Fragment objects', async () => {
   const methyl = Fragment('C');
   const chain = Repeat(methyl, 5);
+  assert.ok(await isValidSMILES(chain.smiles));
   assert.strictEqual(chain.smiles, 'CCCCC');
 });
 
-test('Repeat counts atoms correctly', () => {
+test('Repeat counts atoms correctly', async () => {
   const hexane = Repeat('C', 6);
+  assert.ok(await isValidSMILES(hexane.smiles));
   assert.strictEqual(hexane.atoms, 6);
 });

package/test/ring-composition.test.js

@@ -2,53 +2,73 @@ import { test } from 'node:test';
 import assert from 'node:assert';
 import { Ring } from '../src/ring.js';
 import { Fragment } from '../src/fragment.js';
+import { isValidSMILES } from './test-utils.js';
 
-test('Ring composition remaps ring numbers correctly', () => {
+test('Ring composition remaps ring numbers correctly', async () => {
   const benzene = Ring('c', 6);
   const biphenyl = benzene(benzene);
+  assert.ok(await isValidSMILES(biphenyl.smiles));
   assert.strictEqual(biphenyl.smiles, 'c1ccccc1(c2ccccc2)');
 });
 
-test('Multiple ring compositions remap correctly', () => {
+test('Multiple ring compositions remap correctly', async () => {
   const benzene = Ring('c', 6);
-  const triphenyl = benzene(benzene)(benzene);
-  assert.strictEqual(triphenyl.smiles, 'c1ccccc1(c2ccccc2)(c3ccccc3)');
+  const triphenyl = benzene.attachAt(2, benzene).attachAt(4, benzene);
+  assert.ok(await isValidSMILES(triphenyl.smiles));
+  assert.strictEqual(triphenyl.smiles, 'c1c(c2ccccc2)cc(c3ccccc3)cc1');
 });
 
-test('Different sized rings compose correctly', () => {
+test('Different sized rings compose correctly', async () => {
   const benzene = Ring('c', 6);
   const cyclopentane = Ring('C', 5);
   const result = benzene(cyclopentane);
+  assert.ok(await isValidSMILES(result.smiles));
   assert.strictEqual(result.smiles, 'c1ccccc1(C2CCCC2)');
 });
 
-test('Ring with existing branches composes correctly', () => {
+test('Ring with existing branches composes correctly', async () => {
   const benzene = Ring('c', 6);
-  const methyl = Fragment('C');
-  const toluene = benzene(methyl);
-  const result = toluene(benzene);
-  assert.strictEqual(result.smiles, 'c1ccccc1(C)(c2ccccc2)');
+  const result = benzene.attachAt(2, 'C').attachAt(3, benzene);
+  assert.ok(await isValidSMILES(result.smiles));
+  assert.strictEqual(result.smiles, 'c1c(C)c(c2ccccc2)ccc1');
 });
 
-test('Nested ring compositions work correctly', () => {
+test('Nested ring compositions work correctly', async () => {
   const benzene = Ring('c', 6);
   const cyclohexane = Ring('C', 6);
   const inner = benzene(cyclohexane);
   const outer = benzene(inner);
+  assert.ok(await isValidSMILES(outer.smiles));
   assert.strictEqual(outer.smiles, 'c1ccccc1(c3ccccc3(C2CCCCC2))');
 });
 
-test('Ring composition counts atoms correctly', () => {
+test('Ring composition counts atoms correctly', async () => {
   const benzene = Ring('c', 6);
   const biphenyl = benzene(benzene);
+  assert.ok(await isValidSMILES(biphenyl.smiles));
   assert.strictEqual(biphenyl.atoms, 12);
 });
 
-test('Ring composition counts rings correctly', () => {
+test('Ring composition counts rings correctly', async () => {
   const benzene = Ring('c', 6);
   const biphenyl = benzene(benzene);
+  assert.ok(await isValidSMILES(biphenyl.smiles));
   assert.strictEqual(biphenyl.rings, 2);
 
-  const triphenyl = benzene(benzene)(benzene);
+  const triphenyl = benzene.attachAt(2, benzene).attachAt(4, benzene);
+  assert.ok(await isValidSMILES(triphenyl.smiles));
   assert.strictEqual(triphenyl.rings, 3);
 });
+
+test('Phenol composition works correctly', async () => {
+  const benzene = Ring('c', 6);
+  const phenol = benzene.attachAt(1, 'O');
+  assert.ok(await isValidSMILES(phenol.smiles));
+  assert.strictEqual(phenol.smiles, 'c1(O)ccccc1');
+});
+
+test('Para-quinone (2,5-cyclohexadiene-1,4-dione) composition works correctly', async () => {
+  const result = Ring('c', 6).attachAt(1, '=O').attachAt(4, '=O');
+  assert.ok(await isValidSMILES(result.smiles));
+  assert.strictEqual(result.smiles, 'c1(=O)ccc(=O)cc1');
+});

package/test/ring.test.js

@@ -2,39 +2,45 @@ import { test } from 'node:test';
 import assert from 'node:assert';
 import { Ring } from '../src/ring.js';
 import { Fragment } from '../src/fragment.js';
+import { isValidSMILES } from './test-utils.js';
 
-test('Ring creates benzene', () => {
+test('Ring creates benzene', async () => {
   const benzene = Ring('c', 6);
   assert.strictEqual(benzene.smiles, 'c1ccccc1');
+  assert.ok(await isValidSMILES(benzene.smiles));
 });
 
-test('Ring creates cyclohexane', () => {
+test('Ring creates cyclohexane', async () => {
   const cyclohexane = Ring('C', 6);
   assert.strictEqual(cyclohexane.smiles, 'C1CCCCC1');
+  assert.ok(await isValidSMILES(cyclohexane.smiles));
 });
 
-test('Ring creates cyclopentane', () => {
+test('Ring creates cyclopentane', async () => {
   const cyclopentane = Ring('C', 5);
   assert.strictEqual(cyclopentane.smiles, 'C1CCCC1');
+  assert.ok(await isValidSMILES(cyclopentane.smiles));
 });
 
-test('Ring with replace option creates pyridine', () => {
+test('Ring with replace option creates pyridine', async () => {
   const pyridine = Ring('c', 6, { replace: { 0: 'n' } });
   assert.strictEqual(pyridine.smiles, 'n1ccccc1');
+  assert.ok(await isValidSMILES(pyridine.smiles));
 });
 
-test('Ring supports substitution', () => {
+test('Ring supports substitution', async () => {
   const benzene = Ring('c', 6);
   const methyl = Fragment('C');
   const toluene = benzene(methyl);
   assert.strictEqual(toluene.smiles, 'c1ccccc1(C)');
+  assert.ok(await isValidSMILES(toluene.smiles));
 });
 
-test('Ring supports multiple substitutions', () => {
+test('Ring supports multiple substitutions', async () => {
   const benzene = Ring('c', 6);
-  const methyl = Fragment('C');
-  const xylene = benzene(methyl)(methyl);
-  assert.strictEqual(xylene.smiles, 'c1ccccc1(C)(C)');
+  const xylene = benzene.attachAt(2, 'C').attachAt(5, 'C');
+  assert.strictEqual(xylene.smiles, 'c1c(C)ccc(C)c1');
+  assert.ok(await isValidSMILES(xylene.smiles));
 });
 
 test('Ring counts atoms correctly', () => {
@@ -49,3 +55,73 @@ test('Ring counts rings correctly', () => {
   const benzene = Ring('c', 6);
   assert.strictEqual(benzene.rings, 1);
 });
+
+test('Ring.attachAt creates toluene at position 1', async () => {
+  const benzene = Ring('c', 6);
+  const toluene = benzene.attachAt(1, 'C');
+  assert.strictEqual(toluene.smiles, 'c1(C)ccccc1');
+  assert.ok(await isValidSMILES(toluene.smiles));
+});
+
+test('Ring.attachAt creates toluene at position 2', async () => {
+  const benzene = Ring('c', 6);
+  const toluene = benzene.attachAt(2, 'C');
+  assert.strictEqual(toluene.smiles, 'c1c(C)cccc1');
+  assert.ok(await isValidSMILES(toluene.smiles));
+});
+
+test('Ring.attachAt creates para-xylene', async () => {
+  const benzene = Ring('c', 6);
+  const toluene = benzene.attachAt(2, 'C');
+  const xylene = toluene.attachAt(5, 'C');
+  assert.strictEqual(xylene.smiles, 'c1c(C)ccc(C)c1');
+  assert.ok(await isValidSMILES(xylene.smiles));
+});
+
+test('Ring.attachAt creates ibuprofen', async () => {
+  const benzene = Ring('c', 6);
+  const ibuprofen = benzene.attachAt(2, 'CC(C)C').attachAt(5, 'CC(C)C(=O)O');
+  assert.strictEqual(ibuprofen.smiles, 'c1c(CC(C)C)ccc(CC(C)C(=O)O)c1');
+  assert.ok(await isValidSMILES(ibuprofen.smiles));
+});
+
+test('Ring.attachAt throws on invalid position', () => {
+  const benzene = Ring('c', 6);
+  assert.throws(() => benzene.attachAt(0, 'C'), /out of range/);
+  assert.throws(() => benzene.attachAt(7, 'C'), /out of range/);
+});
+
+test('Ring.attachAt works with Fragment substituents', async () => {
+  const benzene = Ring('c', 6);
+  const methyl = Fragment('C');
+  const toluene = benzene.attachAt(2, methyl);
+  assert.strictEqual(toluene.smiles, 'c1c(C)cccc1');
+  assert.ok(await isValidSMILES(toluene.smiles));
+});
+
+test('Ring.attachAt works with Ring substituents', async () => {
+  const benzene = Ring('c', 6);
+  const biphenyl = benzene.attachAt(2, benzene);
+  assert.strictEqual(biphenyl.smiles, 'c1c(c2ccccc2)cccc1');
+  assert.ok(await isValidSMILES(biphenyl.smiles));
+});
+
+test('Ring.attachAt chains multiple rings', async () => {
+  const benzene = Ring('c', 6);
+  const terphenyl = benzene.attachAt(2, benzene).attachAt(5, benzene);
+  assert.strictEqual(terphenyl.smiles, 'c1c(c2ccccc2)ccc(c3ccccc3)c1');
+  assert.ok(await isValidSMILES(terphenyl.smiles));
+});
+
+test('Ring.attachAt validates with RDKit', async () => {
+  const { isValidSMILES } = await import('./test-utils.js');
+  const benzene = Ring('c', 6);
+
+  // Test simple ring attachment
+  const biphenyl = benzene.attachAt(2, benzene);
+  assert.ok(await isValidSMILES(biphenyl.smiles));
+
+  // Test chained ring attachments
+  const terphenyl = benzene.attachAt(2, benzene).attachAt(5, benzene);
+  assert.ok(await isValidSMILES(terphenyl.smiles));
+});

package/test/test-utils.js

@@ -0,0 +1,35 @@
+import initRDKitModule from '@rdkit/rdkit';
+
+let RDKitModule = null;
+
+/**
+ * Initialize RDKit module
+ */
+async function initRDKit() {
+  if (!RDKitModule) {
+    RDKitModule = await initRDKitModule();
+  }
+  return RDKitModule;
+}
+
+/**
+ * Check if SMILES is valid using RDKit
+ * @param {string} smiles - SMILES string
+ * @returns {Promise<boolean>}
+ */
+export async function isValidSMILES(smiles) {
+  const rdkit = await initRDKit();
+
+  let mol = null;
+  try {
+    mol = rdkit.get_mol(smiles);
+    if (!mol) return false;
+    return mol.is_valid();
+  } catch {
+    return false;
+  } finally {
+    if (mol) {
+      mol.delete();
+    }
+  }
+}