smiles-js 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run tests
+        run: npm test

package/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - '*'
+  release:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish (leave empty to use package.json version)'
+        required: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # Required for npm provenance
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Run tests
+        run: npm test
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release Summary
+        run: |
+          echo "## 📦 Published to npm" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Package: \`smiles-js\`" >> $GITHUB_STEP_SUMMARY
+          echo "Version: \`$(node -p "require('./package.json').version")\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Install" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "npm install smiles-js" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Souradeep Nanda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,353 @@
+# Molecular DSL
+
+A JavaScript library for building molecules using composable fragments.
+
+## Installation
+
+```bash
+npm install smiles-js
+```
+
+## Quick Start
+
+```js
+import { Fragment, Ring, FusedRings } from 'smiles-js';
+
+const methyl = Fragment('C');
+const benzene = Ring('c', 6);
+const toluene = benzene(methyl);
+
+console.log(toluene);  // c1ccccc1C
+```
+
+## Core Concepts
+
+Molecules are built by composing fragments. There are three composition operations:
+
+| Operation | Syntax | Result |
+|-----------|--------|--------|
+| Branch | `a(b)` | `b` attached as branch to `a` |
+| Multiple branches | `a(b)(c)(d)` | `b`, `c`, `d` all branch from `a` |
+| Nested branches | `a(b(c))` | `c` branches from `b`, which branches from `a` |
+
+## API
+
+### Fragment(smiles)
+
+Creates a fragment from a SMILES string.
+
+```js
+const methyl = Fragment('C');
+const ethyl = Fragment('CC');
+const hydroxyl = Fragment('O');
+const carbonyl = Fragment('C=O');
+const carboxyl = Fragment('C(=O)O');
+```
+
+Fragments are composable:
+
+```js
+const ethanol = ethyl(hydroxyl);                   // CC(O)
+const acetone = methyl(Fragment('=O'))(methyl);    // CC(=O)C
+```
+
+Nested branching:
+
+```js
+const a = Fragment('C');
+const b = Fragment('CC');
+const c = Fragment('CCC');
+
+const molecule = a(b(c));  // C(CC(CCC))
+```
+
+### Ring(atom, size)
+
+Creates a simple ring.
+
+```js
+const benzene = Ring('c', 6);       // c1ccccc1
+const cyclohexane = Ring('C', 6);   // C1CCCCC1
+const cyclopentane = Ring('C', 5);  // C1CCCC1
+const pyridine = Ring('c', 6, { replace: { 0: 'n' } });  // n1ccccc1
+```
+
+**Parameters:**
+
+- `atom` — The atom type. Lowercase for aromatic, uppercase for aliphatic.
+- `size` — Number of atoms in the ring (3-8 typical).
+- `options.replace` — Object mapping positions to different atoms.
+
+**Substituted rings:**
+
+```js
+const benzene = Ring('c', 6);
+const toluene = benzene(methyl);           // c1ccccc1C
+const xylene = benzene(methyl)(methyl);    // c1ccccc1(C)C
+```
+
+### FusedRings(sizes, atom, options?)
+
+Creates fused ring systems.
+
+```js
+const naphthalene = FusedRings([6, 6], 'c');      // c1ccc2ccccc2c1
+const anthracene = FusedRings([6, 6, 6], 'c');   // linear fusion
+const indene = FusedRings([6, 5], 'c');          // 6-membered fused to 5-membered
+```
+
+**Parameters:**
+
+- `sizes` — Array of ring sizes, fused linearly.
+- `atom` — Default atom type.
+- `options.hetero` — Object mapping positions to heteroatoms.
+
+**Examples:**
+
+```js
+// Indole: benzene fused to pyrrole
+const indole = FusedRings([6, 5], 'c', { 
+  hetero: { 8: '[nH]' } 
+});
+
+// Quinoline: benzene fused to pyridine
+const quinoline = FusedRings([6, 6], 'c', { 
+  hetero: { 0: 'n' } 
+});
+```
+
+### Repeat(fragment, count)
+
+Creates repeating units for polymers and chains.
+
+```js
+const hexane = Repeat('C', 6);           // CCCCCC
+const peg = Repeat('CCO', 4);            // CCOCCOCCOCCOCCO
+const polyethylene = Repeat('CC', 100);  // CC...CC (200 carbons)
+```
+
+**Parameters:**
+
+- `fragment` — SMILES string or Fragment to repeat.
+- `count` — Number of repetitions.
+
+## Composition
+
+### Branching with `()`
+
+Calling a fragment with another fragment creates a branch:
+
+```js
+const methyl = Fragment('C');
+const ethyl = Fragment('CC');
+
+methyl(ethyl);           // C(CC)
+methyl(ethyl)(ethyl);    // C(CC)(CC)
+```
+
+The branch attaches to the last atom of the parent fragment.
+
+### Nested Branches
+
+Branches can be nested to any depth:
+
+```js
+const C = Fragment('C');
+const CC = Fragment('CC');
+const CCC = Fragment('CCC');
+
+C(CC(CCC));  // C(CC(CCC))
+```
+
+This creates:
+
+```
+C ─ C ─ C
+        │
+        C ─ C ─ C
+```
+
+A more complex example:
+
+```js
+const methyl = Fragment('C');
+const ethyl = Fragment('CC');
+const propyl = Fragment('CCC');
+const butyl = Fragment('CCCC');
+
+// Central carbon with 4 different branches
+methyl(ethyl)(propyl(butyl))(methyl);  // C(CC)(CCC(CCCC))(C)
+```
+
+## Common Fragments
+
+The library includes common fragments:
+
+```js
+import { 
+  // Alkyls
+  methyl,     // C
+  ethyl,      // CC
+  propyl,     // CCC
+  isopropyl,  // C(C)C
+  butyl,      // CCCC
+  tbutyl,     // C(C)(C)C
+  
+  // Functional groups
+  hydroxyl,   // O
+  amino,      // N
+  carboxyl,   // C(=O)O
+  carbonyl,   // C=O
+  nitro,      // [N+](=O)[O-]
+  cyano,      // C#N
+  
+  // Halogens
+  fluoro,     // F
+  chloro,     // Cl
+  bromo,      // Br
+  iodo,       // I
+  
+  // Rings
+  benzene,    // c1ccccc1
+  cyclohexane,// C1CCCCC1
+  pyridine,   // n1ccccc1
+  pyrrole,    // c1cc[nH]c1
+  furan,      // c1ccoc1
+  thiophene,  // c1ccsc1
+  
+  // Fused rings
+  naphthalene,  // c1ccc2ccccc2c1
+  indole,       // c1ccc2[nH]ccc2c1
+  quinoline,    // n1ccc2ccccc2c1
+} from 'molecular-dsl/common';
+```
+
+## Properties
+
+Every fragment exposes:
+
+```js
+const mol = benzene(methyl);
+
+mol.smiles;          // "c1ccccc1C"
+mol.atoms;           // 7
+mol.rings;           // 1
+mol.formula;         // "C7H8"
+mol.molecularWeight; // 92.14
+
+console.log(mol);    // c1ccccc1C
+```
+
+## Validation
+
+Fragments validate on creation:
+
+```js
+Fragment('C(C');  // Error: Unclosed branch
+
+Fragment('c1ccc1');  // Error: Invalid ring closure
+```
+
+To check validity without throwing:
+
+```js
+const result = Fragment.validate('C(C');
+// { valid: false, error: 'Unclosed branch' }
+
+const result = Fragment.validate('CCO');
+// { valid: true }
+```
+
+## Advanced SMILES Features
+
+For features not covered by the DSL, use raw SMILES in `Fragment()`:
+
+**Charges:**
+
+```js
+const ammonium = Fragment('[NH4+]');
+const carboxylate = Fragment('[O-]');
+```
+
+**Explicit hydrogens:**
+
+```js
+const pyrroleN = Fragment('[nH]');
+```
+
+**Stereochemistry:**
+
+```js
+const lAlanine = Fragment('C[C@H](N)C(=O)O');
+const transButene = Fragment('C/C=C/C');
+```
+
+**Isotopes:**
+
+```js
+const deuterium = Fragment('[2H]');
+const carbon13 = Fragment('[13C]');
+```
+
+## Examples
+
+### Aspirin
+
+```js
+const aspirin = benzene(carboxyl)(Fragment('OC(=O)C'));
+```
+
+### Caffeine
+
+```js
+const caffeine = Fragment('Cn1cnc2c1c(=O)n(c(=O)n2C)C');
+```
+
+### Ibuprofen
+
+```js
+const ibuprofen = benzene(
+  Fragment('CC(C)C')
+)(
+  Fragment('CC(C)C(=O)O')
+);
+```
+
+### Building a library
+
+```js
+import { Fragment, benzene, methyl, hydroxyl, carboxyl } from 'molecular-dsl';
+
+// Define your fragments
+const acetyl = Fragment('C(=O)C');
+const phenyl = benzene;
+
+// Compose molecules
+const molecules = {
+  toluene: phenyl(methyl),
+  phenol: phenyl(hydroxyl),
+  benzoicAcid: phenyl(carboxyl),
+  acetophenone: phenyl(acetyl),
+};
+
+// Export SMILES
+for (const [name, mol] of Object.entries(molecules)) {
+  console.log(`${name}: ${mol}`);
+}
+```
+
+Output:
+
+```
+toluene: c1ccccc1C
+phenol: c1ccccc1O
+benzoicAcid: c1ccccc1C(=O)O
+acetophenone: c1ccccc1C(=O)C
+```
+
+### Polymer
+
+```js
+const peg = Repeat('OCO', 10);
+console.log(peg);  // OCOOCOOCOOCOOCOOCOOCOOCOOCOOCO
+```

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "smiles-js",
+  "version": "0.1.0",
+  "description": "A JavaScript library for building molecules using composable fragments",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./common": "./src/common.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ghost---Shadow/smiles-js"
+  },
+  "keywords": [
+    "smiles",
+    "chemistry",
+    "molecules",
+    "dsl"
+  ],
+  "author": "",
+  "license": "MIT"
+}

package/src/common.js

@@ -0,0 +1,33 @@
+import { Fragment } from './fragment.js';
+import { Ring } from './ring.js';
+import { FusedRings } from './fused-rings.js';
+
+export const methyl = Fragment('C');
+export const ethyl = Fragment('CC');
+export const propyl = Fragment('CCC');
+export const isopropyl = Fragment('C(C)C');
+export const butyl = Fragment('CCCC');
+export const tbutyl = Fragment('C(C)(C)C');
+
+export const hydroxyl = Fragment('O');
+export const amino = Fragment('N');
+export const carboxyl = Fragment('C(=O)O');
+export const carbonyl = Fragment('C=O');
+export const nitro = Fragment('[N+](=O)[O-]');
+export const cyano = Fragment('C#N');
+
+export const fluoro = Fragment('F');
+export const chloro = Fragment('Cl');
+export const bromo = Fragment('Br');
+export const iodo = Fragment('I');
+
+export const benzene = Ring('c', 6);
+export const cyclohexane = Ring('C', 6);
+export const pyridine = Ring('c', 6, { replace: { 0: 'n' } });
+export const pyrrole = Ring('c', 5, { replace: { 0: '[nH]' } });
+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 quinoline = FusedRings([6, 6], 'c', { hetero: { 0: 'n' } });

package/src/fragment.js

@@ -0,0 +1,49 @@
+import { validateSMILES } from './validator.js';
+import { countAtoms, countRings, calculateFormula, calculateMolecularWeight } from './properties.js';
+import { findUsedRingNumbers, getNextRingNumber } from './utils.js';
+
+export function Fragment(smiles) {
+  const validation = validateSMILES(smiles);
+  if (!validation.valid) {
+    throw new Error(validation.error);
+  }
+
+  const createFragment = (currentSmiles) => {
+    const fragment = function(...branches) {
+      let result = currentSmiles;
+
+      for (const branch of branches) {
+        const branchSmiles = typeof branch === 'function' ? branch.smiles : String(branch);
+
+        const usedInParent = findUsedRingNumbers(result);
+        const usedInBranch = findUsedRingNumbers(branchSmiles);
+
+        let remappedBranch = branchSmiles;
+        for (const ringNum of usedInBranch) {
+          if (usedInParent.has(ringNum)) {
+            const newNum = getNextRingNumber(result + remappedBranch);
+            remappedBranch = remappedBranch.replaceAll(ringNum, newNum.replace('%', ''));
+          }
+        }
+
+        result += `(${remappedBranch})`;
+      }
+
+      return createFragment(result);
+    };
+
+    fragment.smiles = currentSmiles;
+    fragment.atoms = countAtoms(currentSmiles);
+    fragment.rings = countRings(currentSmiles);
+    fragment.formula = calculateFormula(currentSmiles);
+    fragment.molecularWeight = calculateMolecularWeight(currentSmiles);
+    fragment.toString = () => currentSmiles;
+    fragment[Symbol.toPrimitive] = () => currentSmiles;
+
+    return fragment;
+  };
+
+  return createFragment(smiles);
+}
+
+Fragment.validate = validateSMILES;

package/src/fused-rings.js

@@ -0,0 +1,38 @@
+import { Fragment } from './fragment.js';
+
+export function FusedRings(sizes, atom, options = {}) {
+  const { hetero = {} } = options;
+
+  if (sizes.length !== 2) {
+    throw new Error('FusedRings currently only supports 2 rings');
+  }
+
+  let smiles = '';
+  let atomPosition = 0;
+
+  smiles += (hetero[atomPosition] !== undefined ? hetero[atomPosition] : atom) + '1';
+  atomPosition++;
+
+  const firstRingMiddleAtoms = sizes[0] - 4;
+  for (let i = 0; i < firstRingMiddleAtoms; i++) {
+    smiles += (hetero[atomPosition] !== undefined ? hetero[atomPosition] : atom);
+    atomPosition++;
+  }
+
+  smiles += (hetero[atomPosition] !== undefined ? hetero[atomPosition] : atom) + '2';
+  atomPosition++;
+
+  const ringSize = sizes[1];
+  const middleAtoms = ringSize - 2;
+  for (let i = 0; i < middleAtoms; i++) {
+    smiles += (hetero[atomPosition] !== undefined ? hetero[atomPosition] : atom);
+    atomPosition++;
+  }
+
+  smiles += (hetero[atomPosition] !== undefined ? hetero[atomPosition] : atom) + '2';
+  atomPosition++;
+
+  smiles += (hetero[atomPosition] !== undefined ? hetero[atomPosition] : atom) + '1';
+
+  return Fragment(smiles);
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { Fragment } from './fragment.js';
+export { Ring } from './ring.js';
+export { FusedRings } from './fused-rings.js';
+export { Repeat } from './repeat.js';

package/src/properties.js

@@ -0,0 +1,219 @@
+const ATOMIC_WEIGHTS = {
+  'H': 1.008, 'C': 12.011, 'N': 14.007, 'O': 15.999, 'F': 18.998,
+  'P': 30.974, 'S': 32.06, 'Cl': 35.45, 'Br': 79.904, 'I': 126.90,
+  'B': 10.81, 'Si': 28.085, 'Se': 78.971, 'Na': 22.990, 'K': 39.098,
+  'Ca': 40.078, 'Fe': 55.845, 'Zn': 65.38, 'Mg': 24.305
+};
+
+function parseAtom(smiles, index) {
+  if (smiles[index] === '[') {
+    const end = smiles.indexOf(']', index);
+    if (end === -1) return null;
+    const bracketContent = smiles.substring(index + 1, end);
+
+    let isotope = '';
+    let atom = '';
+    let i = 0;
+
+    while (i < bracketContent.length && bracketContent[i] >= '0' && bracketContent[i] <= '9') {
+      isotope += bracketContent[i];
+      i++;
+    }
+
+    if (i < bracketContent.length && bracketContent[i] >= 'A' && bracketContent[i] <= 'Z') {
+      atom = bracketContent[i];
+      i++;
+      if (i < bracketContent.length && bracketContent[i] >= 'a' && bracketContent[i] <= 'z') {
+        atom += bracketContent[i];
+      }
+    } else if (i < bracketContent.length && bracketContent[i] >= 'a' && bracketContent[i] <= 'z') {
+      atom = bracketContent[i];
+    }
+
+    return { atom, length: end - index + 1 };
+  }
+
+  if (smiles[index] >= 'A' && smiles[index] <= 'Z') {
+    let atom = smiles[index];
+    if (index + 1 < smiles.length && smiles[index + 1] >= 'a' && smiles[index + 1] <= 'z') {
+      atom += smiles[index + 1];
+      return { atom, length: 2 };
+    }
+    return { atom, length: 1 };
+  }
+
+  if (smiles[index] >= 'a' && smiles[index] <= 'z') {
+    return { atom: smiles[index].toUpperCase(), length: 1 };
+  }
+
+  return null;
+}
+
+export function countAtoms(smiles) {
+  let count = 0;
+  let i = 0;
+
+  while (i < smiles.length) {
+    const char = smiles[i];
+
+    if (char === '(' || char === ')' || char === '=' || char === '#' ||
+        char === '/' || char === '\\' || char === '@' || char === '+' || char === '-') {
+      i++;
+      continue;
+    }
+
+    if (char >= '0' && char <= '9') {
+      i++;
+      continue;
+    }
+
+    if (char === '%') {
+      i += 3;
+      continue;
+    }
+
+    const parsed = parseAtom(smiles, i);
+    if (parsed) {
+      count++;
+      i += parsed.length;
+    } else {
+      i++;
+    }
+  }
+
+  return count;
+}
+
+export function countRings(smiles) {
+  const ringNumbers = new Set();
+  let count = 0;
+  let i = 0;
+
+  while (i < smiles.length) {
+    const char = smiles[i];
+
+    if (char >= '0' && char <= '9') {
+      if (ringNumbers.has(char)) {
+        count++;
+        ringNumbers.delete(char);
+      } else {
+        ringNumbers.add(char);
+      }
+      i++;
+    } else if (char === '%' && i + 2 < smiles.length) {
+      const num = smiles.substring(i + 1, i + 3);
+      if (ringNumbers.has(num)) {
+        count++;
+        ringNumbers.delete(num);
+      } else {
+        ringNumbers.add(num);
+      }
+      i += 3;
+    } else {
+      i++;
+    }
+  }
+
+  return count;
+}
+
+export function calculateFormula(smiles) {
+  const elementCounts = {};
+  let i = 0;
+
+  while (i < smiles.length) {
+    const char = smiles[i];
+
+    if (char === '(' || char === ')' || char === '=' || char === '#' ||
+        char === '/' || char === '\\' || char === '@' || char === '+' || char === '-') {
+      i++;
+      continue;
+    }
+
+    if (char >= '0' && char <= '9') {
+      i++;
+      continue;
+    }
+
+    if (char === '%') {
+      i += 3;
+      continue;
+    }
+
+    const parsed = parseAtom(smiles, i);
+    if (parsed && parsed.atom) {
+      const element = parsed.atom;
+      elementCounts[element] = (elementCounts[element] || 0) + 1;
+      i += parsed.length;
+    } else {
+      i++;
+    }
+  }
+
+  const implicitHydrogens = calculateImplicitHydrogens(smiles, elementCounts);
+  if (implicitHydrogens > 0) {
+    elementCounts['H'] = (elementCounts['H'] || 0) + implicitHydrogens;
+  }
+
+  const elements = Object.keys(elementCounts).sort();
+
+  const hillOrder = (a, b) => {
+    if (a === 'C') return -1;
+    if (b === 'C') return 1;
+    if (a === 'H') return -1;
+    if (b === 'H') return 1;
+    return a.localeCompare(b);
+  };
+
+  elements.sort(hillOrder);
+
+  return elements.map(e => {
+    const count = elementCounts[e];
+    return count === 1 ? e : `${e}${count}`;
+  }).join('');
+}
+
+function calculateImplicitHydrogens(smiles, elementCounts) {
+  let totalHydrogens = 0;
+
+  for (const [element, count] of Object.entries(elementCounts)) {
+    if (element === 'C') {
+      totalHydrogens += count * 2 + 2;
+    }
+  }
+
+  const bonds = (smiles.match(/=/g) || []).length + (smiles.match(/#/g) || []).length * 2;
+  totalHydrogens -= bonds * 2;
+
+  const explicitHCount = elementCounts['H'] || 0;
+  totalHydrogens -= explicitHCount;
+
+  return Math.max(0, totalHydrogens);
+}
+
+export function calculateMolecularWeight(smiles) {
+  const formula = calculateFormula(smiles);
+  let weight = 0;
+  let i = 0;
+
+  while (i < formula.length) {
+    let element = formula[i];
+    i++;
+
+    if (i < formula.length && formula[i] >= 'a' && formula[i] <= 'z') {
+      element += formula[i];
+      i++;
+    }
+
+    let count = '';
+    while (i < formula.length && formula[i] >= '0' && formula[i] <= '9') {
+      count += formula[i];
+      i++;
+    }
+
+    const atomCount = count ? parseInt(count) : 1;
+    weight += (ATOMIC_WEIGHTS[element] || 0) * atomCount;
+  }
+
+  return Math.round(weight * 100) / 100;
+}

package/src/repeat.js

@@ -0,0 +1,7 @@
+import { Fragment } from './fragment.js';
+
+export function Repeat(fragment, count) {
+  const smiles = typeof fragment === 'function' ? fragment.smiles : String(fragment);
+  const repeated = smiles.repeat(count);
+  return Fragment(repeated);
+}

package/src/ring.js

@@ -0,0 +1,20 @@
+import { Fragment } from './fragment.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;
+
+    if (i === 0) {
+      smiles += currentAtom + '1';
+    } else if (i === size - 1) {
+      smiles += currentAtom + '1';
+    } else {
+      smiles += currentAtom;
+    }
+  }
+
+  return Fragment(smiles);
+}

package/src/utils.js

@@ -0,0 +1,39 @@
+export function findUsedRingNumbers(smiles) {
+  const used = new Set();
+  let i = 0;
+
+  while (i < smiles.length) {
+    const char = smiles[i];
+
+    if (char >= '0' && char <= '9') {
+      used.add(char);
+      i++;
+    } else if (char === '%' && i + 2 < smiles.length) {
+      const num = smiles.substring(i + 1, i + 3);
+      used.add(num);
+      i += 3;
+    } else {
+      i++;
+    }
+  }
+
+  return used;
+}
+
+export function getNextRingNumber(smiles) {
+  const used = findUsedRingNumbers(smiles);
+
+  for (let i = 1; i <= 9; i++) {
+    if (!used.has(String(i))) {
+      return String(i);
+    }
+  }
+
+  for (let i = 10; i <= 99; i++) {
+    if (!used.has(String(i))) {
+      return `%${i}`;
+    }
+  }
+
+  throw new Error('Too many rings (exhausted ring numbers)');
+}

package/src/validator.js

@@ -0,0 +1,46 @@
+export function validateSMILES(smiles) {
+  const errors = [];
+  let branchCount = 0;
+  let ringNumbers = new Set();
+  let openRings = new Set();
+
+  for (let i = 0; i < smiles.length; i++) {
+    const char = smiles[i];
+
+    if (char === '(') {
+      branchCount++;
+    } else if (char === ')') {
+      branchCount--;
+      if (branchCount < 0) {
+        return { valid: false, error: 'Unmatched closing branch' };
+      }
+    } else if (char >= '0' && char <= '9') {
+      const num = char;
+      if (openRings.has(num)) {
+        openRings.delete(num);
+      } else {
+        openRings.add(num);
+      }
+    } else if (char === '%') {
+      if (i + 2 < smiles.length) {
+        const num = smiles.substring(i + 1, i + 3);
+        if (openRings.has(num)) {
+          openRings.delete(num);
+        } else {
+          openRings.add(num);
+        }
+        i += 2;
+      }
+    }
+  }
+
+  if (branchCount > 0) {
+    return { valid: false, error: 'Unclosed branch' };
+  }
+
+  if (openRings.size > 0) {
+    return { valid: false, error: 'Invalid ring closure' };
+  }
+
+  return { valid: true };
+}

package/test/common.test.js

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

package/test/examples.test.js

@@ -0,0 +1,59 @@
+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';
+
+test('README example: toluene', () => {
+  const benzeneRing = Ring('c', 6);
+  const methylGroup = Fragment('C');
+  const toluene = benzeneRing(methylGroup);
+  assert.strictEqual(String(toluene), 'c1ccccc1(C)');
+});
+
+test('README example: ethanol', () => {
+  const ethyl = Fragment('CC');
+  const hydroxylGroup = Fragment('O');
+  const ethanol = ethyl(hydroxylGroup);
+  assert.strictEqual(ethanol.smiles, 'CC(O)');
+});
+
+test('README example: acetone', () => {
+  const methylGroup = Fragment('C');
+  const acetone = methylGroup(Fragment('=O'))(methylGroup);
+  assert.strictEqual(acetone.smiles, 'C(=O)(C)');
+});
+
+test('README example: nested branching', () => {
+  const a = Fragment('C');
+  const b = Fragment('CC');
+  const c = Fragment('CCC');
+  const molecule = a(b(c));
+  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: 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: molecule library', () => {
+  const acetyl = Fragment('C(=O)C');
+  const phenyl = benzene;
+
+  const molecules = {
+    toluene: phenyl(methyl),
+    phenol: phenyl(hydroxyl),
+    benzoicAcid: phenyl(carboxyl),
+    acetophenone: phenyl(acetyl),
+  };
+
+  assert.strictEqual(String(molecules.toluene), 'c1ccccc1(C)');
+  assert.strictEqual(String(molecules.phenol), 'c1ccccc1(O)');
+  assert.strictEqual(String(molecules.benzoicAcid), 'c1ccccc1(C(=O)O)');
+  assert.strictEqual(String(molecules.acetophenone), 'c1ccccc1(C(=O)C)');
+});

package/test/fragment.test.js

@@ -0,0 +1,97 @@
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { Fragment } from '../src/fragment.js';
+
+test('Fragment creates basic fragments', () => {
+  const methyl = Fragment('C');
+  assert.strictEqual(methyl.smiles, 'C');
+  assert.strictEqual(String(methyl), 'C');
+});
+
+test('Fragment validates SMILES on creation', () => {
+  assert.throws(() => Fragment('C(C'), { message: 'Unclosed branch' });
+});
+
+test('Fragment.validate returns validation result', () => {
+  const result1 = Fragment.validate('C(C');
+  assert.deepStrictEqual(result1, { valid: false, error: 'Unclosed branch' });
+
+  const result2 = Fragment.validate('CCO');
+  assert.deepStrictEqual(result2, { valid: true });
+});
+
+test('Fragment supports branching', () => {
+  const methyl = Fragment('C');
+  const ethyl = Fragment('CC');
+  const result = methyl(ethyl);
+  assert.strictEqual(result.smiles, 'C(CC)');
+});
+
+test('Fragment supports multiple branches', () => {
+  const methyl = Fragment('C');
+  const ethyl = Fragment('CC');
+  const result = methyl(ethyl)(ethyl);
+  assert.strictEqual(result.smiles, 'C(CC)(CC)');
+});
+
+test('Fragment supports nested branches', () => {
+  const a = Fragment('C');
+  const b = Fragment('CC');
+  const c = Fragment('CCC');
+  const result = a(b(c));
+  assert.strictEqual(result.smiles, 'C(CC(CCC))');
+});
+
+test('Fragment counts atoms correctly', () => {
+  const methyl = Fragment('C');
+  assert.strictEqual(methyl.atoms, 1);
+
+  const ethyl = Fragment('CC');
+  assert.strictEqual(ethyl.atoms, 2);
+
+  const benzene = Fragment('c1ccccc1');
+  assert.strictEqual(benzene.atoms, 6);
+});
+
+test('Fragment counts rings correctly', () => {
+  const methyl = Fragment('C');
+  assert.strictEqual(methyl.rings, 0);
+
+  const benzene = Fragment('c1ccccc1');
+  assert.strictEqual(benzene.rings, 1);
+
+  const naphthalene = Fragment('c1ccc2ccccc2c1');
+  assert.strictEqual(naphthalene.rings, 2);
+});
+
+test('Fragment calculates formula correctly', () => {
+  const methyl = Fragment('C');
+  assert.strictEqual(methyl.formula, 'CH4');
+
+  const ethyl = Fragment('CC');
+  assert.strictEqual(ethyl.formula, 'C2H6');
+
+  const carbonyl = Fragment('C=O');
+  assert.strictEqual(carbonyl.formula, 'CH2O');
+});
+
+test('Fragment calculates molecular weight correctly', () => {
+  const methyl = Fragment('C');
+  assert.strictEqual(methyl.molecularWeight, 16.04);
+
+  const ethyl = Fragment('CC');
+  assert.strictEqual(ethyl.molecularWeight, 30.07);
+});
+
+test('Fragment works with complex molecules', () => {
+  const benzene = Fragment('c1ccccc1');
+  const methyl = Fragment('C');
+  const toluene = benzene(methyl);
+  assert.strictEqual(toluene.smiles, 'c1ccccc1(C)');
+});
+
+test('Fragment toString and toPrimitive work correctly', () => {
+  const methyl = Fragment('C');
+  assert.strictEqual(methyl.toString(), 'C');
+  assert.strictEqual(`${methyl}`, 'C');
+});

package/test/fused-rings.test.js

@@ -0,0 +1,41 @@
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { FusedRings } from '../src/fused-rings.js';
+
+test('FusedRings creates naphthalene', () => {
+  const naphthalene = FusedRings([6, 6], 'c');
+  assert.strictEqual(naphthalene.smiles, 'c1ccc2ccccc2c1');
+});
+
+test('FusedRings creates indene', () => {
+  const indene = FusedRings([6, 5], 'c');
+  assert.strictEqual(indene.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 quinoline', () => {
+  const quinoline = FusedRings([6, 6], 'c', { hetero: { 0: 'n' } });
+  assert.strictEqual(quinoline.smiles, 'n1ccc2ccccc2c1');
+});
+
+test('FusedRings throws on single ring', () => {
+  assert.throws(() => FusedRings([6], 'c'), { message: 'FusedRings currently only supports 2 rings' });
+});
+
+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', () => {
+  const naphthalene = FusedRings([6, 6], 'c');
+  assert.strictEqual(naphthalene.atoms, 10);
+});
+
+test('FusedRings counts rings correctly', () => {
+  const naphthalene = FusedRings([6, 6], 'c');
+  assert.strictEqual(naphthalene.rings, 2);
+});

package/test/repeat.test.js

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

package/test/ring-composition.test.js

@@ -0,0 +1,54 @@
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { Ring } from '../src/ring.js';
+import { Fragment } from '../src/fragment.js';
+
+test('Ring composition remaps ring numbers correctly', () => {
+  const benzene = Ring('c', 6);
+  const biphenyl = benzene(benzene);
+  assert.strictEqual(biphenyl.smiles, 'c1ccccc1(c2ccccc2)');
+});
+
+test('Multiple ring compositions remap correctly', () => {
+  const benzene = Ring('c', 6);
+  const triphenyl = benzene(benzene)(benzene);
+  assert.strictEqual(triphenyl.smiles, 'c1ccccc1(c2ccccc2)(c3ccccc3)');
+});
+
+test('Different sized rings compose correctly', () => {
+  const benzene = Ring('c', 6);
+  const cyclopentane = Ring('C', 5);
+  const result = benzene(cyclopentane);
+  assert.strictEqual(result.smiles, 'c1ccccc1(C2CCCC2)');
+});
+
+test('Ring with existing branches composes correctly', () => {
+  const benzene = Ring('c', 6);
+  const methyl = Fragment('C');
+  const toluene = benzene(methyl);
+  const result = toluene(benzene);
+  assert.strictEqual(result.smiles, 'c1ccccc1(C)(c2ccccc2)');
+});
+
+test('Nested ring compositions work correctly', () => {
+  const benzene = Ring('c', 6);
+  const cyclohexane = Ring('C', 6);
+  const inner = benzene(cyclohexane);
+  const outer = benzene(inner);
+  assert.strictEqual(outer.smiles, 'c1ccccc1(c3ccccc3(C2CCCCC2))');
+});
+
+test('Ring composition counts atoms correctly', () => {
+  const benzene = Ring('c', 6);
+  const biphenyl = benzene(benzene);
+  assert.strictEqual(biphenyl.atoms, 12);
+});
+
+test('Ring composition counts rings correctly', () => {
+  const benzene = Ring('c', 6);
+  const biphenyl = benzene(benzene);
+  assert.strictEqual(biphenyl.rings, 2);
+
+  const triphenyl = benzene(benzene)(benzene);
+  assert.strictEqual(triphenyl.rings, 3);
+});

package/test/ring.test.js

@@ -0,0 +1,51 @@
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { Ring } from '../src/ring.js';
+import { Fragment } from '../src/fragment.js';
+
+test('Ring creates benzene', () => {
+  const benzene = Ring('c', 6);
+  assert.strictEqual(benzene.smiles, 'c1ccccc1');
+});
+
+test('Ring creates cyclohexane', () => {
+  const cyclohexane = Ring('C', 6);
+  assert.strictEqual(cyclohexane.smiles, 'C1CCCCC1');
+});
+
+test('Ring creates cyclopentane', () => {
+  const cyclopentane = Ring('C', 5);
+  assert.strictEqual(cyclopentane.smiles, 'C1CCCC1');
+});
+
+test('Ring with replace option creates pyridine', () => {
+  const pyridine = Ring('c', 6, { replace: { 0: 'n' } });
+  assert.strictEqual(pyridine.smiles, 'n1ccccc1');
+});
+
+test('Ring supports substitution', () => {
+  const benzene = Ring('c', 6);
+  const methyl = Fragment('C');
+  const toluene = benzene(methyl);
+  assert.strictEqual(toluene.smiles, 'c1ccccc1(C)');
+});
+
+test('Ring supports multiple substitutions', () => {
+  const benzene = Ring('c', 6);
+  const methyl = Fragment('C');
+  const xylene = benzene(methyl)(methyl);
+  assert.strictEqual(xylene.smiles, 'c1ccccc1(C)(C)');
+});
+
+test('Ring counts atoms correctly', () => {
+  const benzene = Ring('c', 6);
+  assert.strictEqual(benzene.atoms, 6);
+
+  const cyclopentane = Ring('C', 5);
+  assert.strictEqual(cyclopentane.atoms, 5);
+});
+
+test('Ring counts rings correctly', () => {
+  const benzene = Ring('c', 6);
+  assert.strictEqual(benzene.rings, 1);
+});