selfies-js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,274 @@
+<div align="center">
+  <img src="toluene-logo.svg" alt="Toluene molecule" width="200"/>
+  <h1>selfies-js</h1>
+  <p>A pure JavaScript implementation of the SELFIES molecular string representation</p>
+</div>
+
+## What is SELFIES?
+
+**SELFIES** (SELF-referencIng Embedded Strings) is a 100% robust molecular string representation. Unlike SMILES, every SELFIES string corresponds to a valid molecule, making it ideal for machine learning and generative models in chemistry.
+
+This library is a JavaScript port inspired by the original Python implementation: **[aspuru-guzik-group/selfies](https://github.com/aspuru-guzik-group/selfies)**
+
+> Krenn, M., Häse, F., Nigam, A., Friederich, P., & Aspuru-Guzik, A. (2020). Self-Referencing Embedded Strings (SELFIES): A 100% robust molecular string representation. *Machine Learning: Science and Technology*, 1(4), 045024.
+
+## Overview
+
+```javascript
+import {
+  decode, encode, isValid,
+  getMolecularWeight, getFormula,
+  lenSelfies, getSemanticConstraints,
+  isChemicallyValid, getCanonicalSmiles, validateRoundtrip
+} from 'selfies-js'
+
+// SELFIES → SMILES
+decode('[C][C][O]')  // 'CCO'
+
+// SMILES → SELFIES
+encode('CCO')  // '[C][C][O]'
+
+// Syntax validation
+isValid('[C][C][O]')  // true
+
+// Chemistry validation (requires RDKit)
+import { initRDKit } from 'selfies-js'
+await initRDKit()
+await isChemicallyValid('[C][C][O]')  // true - molecule is chemically valid
+await getCanonicalSmiles('[C][C][O]')  // 'CCO' - canonical SMILES representation
+await validateRoundtrip('CCO', '[C][C][O]')  // true - structure preserved
+
+// Properties
+getMolecularWeight('[C][C][O]')  // 46.07
+getFormula('[C][C][O]')  // 'C2H6O'
+
+// Utilities
+lenSelfies('[C][C][O]')  // 3 (symbol count, not string length)
+
+// Semantic constraints
+const constraints = getSemanticConstraints()
+console.log(constraints['C'])  // 4 (max bonds for carbon)
+
+// SVG Rendering (using RDKit.js)
+import { renderSelfies } from 'selfies-js'
+
+const svg = await renderSelfies('[C][C][O]', {
+  width: 300,
+  height: 300
+})
+```
+
+## Installation
+
+```bash
+npm install selfies-js
+```
+
+### Browser Usage (CDN)
+
+For direct browser usage without a bundler:
+
+```html
+<!-- Complete bundle: DSL + SELFIES encode/decode + utilities -->
+<script src="https://github.com/Ghost---Shadow/selfies-js/releases/latest/download/selfies.umd.min.js"></script>
+<script>
+  // SELFIES encoding/decoding
+  const encoded = SELFIES.encode('CC');
+  console.log(encoded); // '[C][C]'
+
+  const decoded = SELFIES.decode('[C][C][O]');
+  console.log(decoded); // 'CCO'
+
+  // DSL parsing
+  const parsed = SELFIES.parse('[methyl] = [C]');
+  console.log(parsed);
+
+  // Molecular properties
+  const mw = SELFIES.getMolecularWeight('[C][C][O]');
+  console.log(mw); // 46.07
+</script>
+```
+
+Download from the [latest release](https://github.com/Ghost---Shadow/selfies-js/releases/latest).
+
+## Features
+
+- **Core:** Decode SELFIES to SMILES
+- **Core:** Encode SMILES to SELFIES
+- **Validation:** Syntax and semantic validation
+- **Chemistry Validation:** RDKit-based molecular validity checking
+- **Canonical SMILES:** Structure comparison and roundtrip validation
+- **Properties:** Molecular weight and formula calculation
+- **Constraints:** Customizable semantic constraints (bonding rules)
+- **Utilities:** Symbol counting, alphabet extraction
+- **DSL:** Define and resolve molecule libraries with named definitions
+- **Imports:** Modular .selfies files with import support
+- **CLI:** Command-line interface for executing .selfies files
+- **Rendering:** SVG visualization of molecular structures
+
+## CLI Usage
+
+The `selfies-js` CLI allows you to work with `.selfies` DSL files from the command line.
+
+### Commands
+
+```bash
+# Execute a .selfies file and output resolved definitions
+bun src/cli.js run molecules.selfies
+
+# Output as SMILES instead of SELFIES
+bun src/cli.js run molecules.selfies --format=smiles
+
+# Validate a .selfies file for errors
+bun src/cli.js validate molecules.selfies
+
+# List all definitions in a file
+bun src/cli.js list molecules.selfies
+
+# Show help
+bun src/cli.js help
+```
+
+### DSL Syntax
+
+The `.selfies` DSL allows you to define named molecular fragments and compose them hierarchically:
+
+```selfies
+# Comments start with #
+
+# Basic definitions
+[methyl] = [C]
+[ethyl] = [C][C]
+[hydroxyl] = [O]
+
+# Composition - reference other definitions
+[ethanol] = [ethyl][hydroxyl]
+
+# Complex structures with branches
+[isopropyl] = [C][Branch1][C][C][C]
+[isopropanol] = [isopropyl][hydroxyl]
+
+# Aromatic rings
+[phenyl] = [C][=C][C][=C][C][=C][Ring1][=Branch1]
+[toluene] = [methyl][phenyl]
+```
+
+### Import Syntax
+
+Import definitions from other `.selfies` files:
+
+```selfies
+# Import all definitions from another file
+import "./fragments.selfies"
+
+# Alternative syntax for importing all
+import * from "./common.selfies"
+
+# Import specific definitions only
+import [methyl, ethyl, hydroxyl] from "./base.selfies"
+
+# Use imported definitions
+[my_molecule] = [methyl][hydroxyl]
+```
+
+Imports support:
+- **Relative paths** resolved from the importing file's location
+- **Chained imports** (file A imports B, B imports C)
+- **Circular import detection** with clear error messages
+- **Selective imports** to only include what you need
+
+### Example Output
+
+```bash
+$ bun src/cli.js run molecules.selfies --format=smiles
+methyl: C
+ethyl: CC
+hydroxyl: O
+ethanol: CCO
+isopropyl: C(C)C
+isopropanol: C(C)CO
+phenyl: C1=CC=CC=C1
+toluene: CC1=CC=CC=C1
+```
+
+## DSL API
+
+```javascript
+import { parse, resolve, resolveAll } from 'selfies-js/dsl'
+import { loadFile } from 'selfies-js/dsl'
+
+// Load a file with imports
+const program = loadFile('molecules.selfies')
+
+// Or parse source directly
+const source = `
+[methyl] = [C]
+[ethanol] = [methyl][C][O]
+`
+const program = parse(source)
+
+// Resolve a single definition
+resolve(program, 'ethanol')  // '[C][C][O]'
+
+// Resolve with SMILES output
+resolve(program, 'ethanol', { decode: true })  // 'CCO'
+
+// Resolve all definitions
+const all = resolveAll(program)
+// Map { 'methyl' => '[C]', 'ethanol' => '[C][C][O]' }
+```
+
+## Visualization
+
+The library uses **RDKit.js** for professional molecule rendering:
+
+```javascript
+import { renderSelfies, initRDKit } from 'selfies-js'
+
+// Initialize RDKit (async, only needed once)
+await initRDKit()
+
+// Render toluene
+const svg = await renderSelfies('[C][C][=C][C][=C][C][=C][Ring1][=Branch1]', {
+  width: 300,
+  height: 300
+})
+```
+
+Features:
+- Professional 2D coordinate generation via RDKit
+- Proper skeletal formulas (carbons hidden)
+- Correct benzene ring geometry
+- Support for all bond types
+- Stereochemistry notation
+- Industry-standard rendering
+
+## Examples
+
+See the `examples/` directory for sample `.selfies` files:
+
+- `base-fragments.selfies` - Reusable building blocks (alkyl groups, functional groups, halogens)
+- `molecules-with-imports.selfies` - Demonstrates importing and composing molecules
+- `organic-chemistry.selfies` - Alcohols, aldehydes, acids, amines, ethers
+- `drug-fragments.selfies` - Pharmacophore fragments, drug-like building blocks
+- `polymers.selfies` - Monomers, repeat units, oligomers
+
+## Known Limitations
+
+The encoder/decoder handles most common organic molecules correctly. Some complex cases have known limitations:
+
+- **Bracket atoms** in SMILES (`[nH]`, `[C@@]`, `[13C]`) - limited support
+- **Fused aromatic ring systems** - some complex cases may not roundtrip correctly
+- **Polycyclic structures** with multiple ring closures - partial support
+
+For complete SELFIES support, use the original Python library: [aspuru-guzik-group/selfies](https://github.com/aspuru-guzik-group/selfies)
+
+## References
+
+- **Original SELFIES Paper:** Krenn, M., Häse, F., Nigam, A., Friederich, P., & Aspuru-Guzik, A. (2020). Self-Referencing Embedded Strings (SELFIES): A 100% robust molecular string representation. *Machine Learning: Science and Technology*, 1(4), 045024. [DOI: 10.1088/2632-2153/aba947](https://doi.org/10.1088/2632-2153/aba947)
+
+- **Python Implementation:** [github.com/aspuru-guzik-group/selfies](https://github.com/aspuru-guzik-group/selfies)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "selfies-js",
+  "version": "0.1.0",
+  "description": "Pure JavaScript SELFIES encoder/decoder with DSL for molecular composition",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "selfies-js": "./src/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./dsl": "./src/dsl/index.js",
+    "./syntax": "./src/syntax.js"
+  },
+  "files": [
+    "src/**/*.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "bench": "bun run bench/decode.bench.js",
+    "lint": "echo 'Linting...'; exit 0",
+    "prepublishOnly": "bun test",
+    "pack": "bun pm pack",
+    "publish:dry": "bun pm pack --dry-run"
+  },
+  "keywords": [
+    "selfies",
+    "smiles",
+    "chemistry",
+    "cheminformatics",
+    "molecules",
+    "molecular-design",
+    "drug-discovery",
+    "encoder",
+    "decoder",
+    "dsl",
+    "parser"
+  ],
+  "author": "SELFIES Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ghost---Shadow/selfies-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ghost---Shadow/selfies-js/issues"
+  },
+  "homepage": "https://github.com/Ghost---Shadow/selfies-js#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "peerDependencies": {
+    "@rdkit/rdkit": "^2025.3.4-1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@rdkit/rdkit": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rdkit/rdkit": "^2025.3.4-1.0.0"
+  }
+}

package/src/alphabet.js

@@ -0,0 +1,150 @@
+/**
+ * Alphabet - Valid SELFIES token sets
+ *
+ * Defines the full SELFIES alphabet and semantic-robust subset.
+ */
+
+/**
+ * Full SELFIES alphabet - all valid tokens
+ * @type {Set<string>}
+ */
+let _alphabet = null
+
+/**
+ * Semantic-robust alphabet - tokens that are always chemically meaningful
+ * @type {Set<string>}
+ */
+let _semanticAlphabet = null
+
+/**
+ * Gets the full SELFIES alphabet
+ * @returns {Set<string>} Set of all valid SELFIES tokens
+ */
+export function getAlphabet() {
+  if (_alphabet === null) {
+    _alphabet = new Set()
+
+    // Add all atom tokens (basic, double bond, triple bond)
+    const atomTokens = buildAtomTokens()
+    for (const token of atomTokens) {
+      _alphabet.add(token)
+    }
+
+    // Add structural tokens (branches, rings, length specifiers)
+    const structuralTokens = buildStructuralTokens()
+    for (const token of structuralTokens) {
+      _alphabet.add(token)
+    }
+  }
+
+  return _alphabet
+}
+
+/**
+ * Gets the semantic-robust SELFIES alphabet
+ * @returns {Set<string>} Set of semantically robust tokens
+ *
+ * Semantic-robust tokens are those that produce valid molecules
+ * regardless of context (no branch/ring tokens, etc.)
+ */
+export function getSemanticAlphabet() {
+  if (_semanticAlphabet === null) {
+    _semanticAlphabet = new Set()
+
+    // Add only atom tokens (basic, double bond, triple bond)
+    // Exclude structural tokens (Branch, Ring) as they are context-dependent
+    const atomTokens = buildAtomTokens()
+    for (const token of atomTokens) {
+      _semanticAlphabet.add(token)
+    }
+  }
+
+  return _semanticAlphabet
+}
+
+/**
+ * Checks if a token is in the alphabet
+ * @param {string} token - Token to check
+ * @returns {boolean} True if token is valid
+ */
+export function isValidToken(token) {
+  return getAlphabet().has(token)
+}
+
+/**
+ * Checks if a token is semantic-robust
+ * @param {string} token - Token to check
+ * @returns {boolean} True if token is semantic-robust
+ */
+export function isSemanticRobust(token) {
+  return getSemanticAlphabet().has(token)
+}
+
+/**
+ * Builds the list of all atom tokens (with bond modifiers)
+ * @returns {string[]} Array of atom tokens
+ */
+function buildAtomTokens() {
+  const elements = ['C', 'N', 'O', 'S', 'P', 'F', 'Cl', 'Br', 'I', 'B']
+  const tokens = []
+
+  for (const element of elements) {
+    tokens.push(`[${element}]`)      // basic atom
+    tokens.push(`[=${element}]`)     // double bond
+    tokens.push(`[#${element}]`)     // triple bond
+  }
+
+  return tokens
+}
+
+/**
+ * Builds the list of structural tokens (branch, ring)
+ * @returns {string[]} Array of structural tokens
+ */
+function buildStructuralTokens() {
+  const tokens = []
+
+  // Branch and Ring tokens
+  tokens.push('[Branch1]', '[Branch2]', '[Branch3]')
+  tokens.push('[Ring1]', '[Ring2]', '[Ring3]')
+
+  // Numeric tokens used as length specifiers (based on atom tokens)
+  // These are the same as bond-modified atoms but used as numbers
+  tokens.push('[=Branch1]', '[=Branch2]', '[=Branch3]')
+  tokens.push('[#Branch1]', '[#Branch2]', '[#Branch3]')
+
+  // Stereochemistry ring tokens
+  tokens.push('[-/Ring1]', '[-/Ring2]', '[-/Ring3]')
+  tokens.push('[\\\\/Ring1]', '[\\\\/Ring2]', '[\\\\/Ring3]')
+
+  return tokens
+}
+
+/**
+ * Extracts the unique SELFIES alphabet from a collection of SELFIES strings
+ * @param {Iterable<string>} selfiesIterable - Collection of SELFIES strings
+ * @returns {Set<string>} Set of unique SELFIES symbols found
+ *
+ * Based on selfies-py's get_alphabet_from_selfies() function.
+ *
+ * Example:
+ *   const alphabet = getAlphabetFromSelfies(['[C][C][O]', '[N][C][=O]'])
+ *   // Set { '[C]', '[O]', '[N]', '[=O]' }
+ *
+ * Reference: selfies-py/selfies/utils/selfies_utils.py::get_alphabet_from_selfies()
+ */
+export function getAlphabetFromSelfies(selfiesIterable) {
+  // TODO: Will implement this after tokenizer is ready
+  // For now, manually tokenize by extracting [...] patterns
+  const alphabet = new Set()
+
+  for (const selfies of selfiesIterable) {
+    // Simple regex-based tokenization (temporary until tokenizer.js is ready)
+    const tokens = selfies.match(/\[[^\]]+\]/g) || []
+    for (const token of tokens) {
+      alphabet.add(token)
+    }
+  }
+
+  return alphabet
+}

package/src/alphabet.test.js

@@ -0,0 +1,82 @@
+/**
+ * Tests for SELFIES alphabet
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { getAlphabet, getSemanticAlphabet, isValidToken, isSemanticRobust } from './alphabet.js'
+
+describe('getAlphabet', () => {
+  test('includes basic atoms', () => {
+    const alphabet = getAlphabet()
+    expect(alphabet.has('[C]')).toBe(true)
+    expect(alphabet.has('[N]')).toBe(true)
+    expect(alphabet.has('[O]')).toBe(true)
+  })
+
+  test('includes bond modifiers', () => {
+    const alphabet = getAlphabet()
+    expect(alphabet.has('[=C]')).toBe(true)
+    expect(alphabet.has('[#N]')).toBe(true)
+  })
+
+  test('includes multi-char elements', () => {
+    const alphabet = getAlphabet()
+    expect(alphabet.has('[Cl]')).toBe(true)
+    expect(alphabet.has('[Br]')).toBe(true)
+  })
+
+  test('includes structural tokens', () => {
+    const alphabet = getAlphabet()
+    expect(alphabet.has('[Branch1]')).toBe(true)
+    expect(alphabet.has('[Ring1]')).toBe(true)
+  })
+
+  test('excludes invalid tokens', () => {
+    const alphabet = getAlphabet()
+    expect(alphabet.has('[Xyz]')).toBe(false)
+    expect(alphabet.has('[123]')).toBe(false)
+  })
+})
+
+describe('getSemanticAlphabet', () => {
+  test('includes atoms and bonds only', () => {
+    const alphabet = getSemanticAlphabet()
+    expect(alphabet.has('[C]')).toBe(true)
+    expect(alphabet.has('[=C]')).toBe(true)
+  })
+
+  test('excludes structural tokens', () => {
+    const alphabet = getSemanticAlphabet()
+    expect(alphabet.has('[Branch1]')).toBe(false)
+    expect(alphabet.has('[Ring1]')).toBe(false)
+  })
+
+  test('is subset of full alphabet', () => {
+    const full = getAlphabet()
+    const semantic = getSemanticAlphabet()
+    for (const token of semantic) {
+      expect(full.has(token)).toBe(true)
+    }
+  })
+})
+
+describe('isValidToken', () => {
+  test('validates basic atoms', () => {
+    expect(isValidToken('[C]')).toBe(true)
+    expect(isValidToken('[O]')).toBe(true)
+  })
+
+  test('rejects invalid tokens', () => {
+    expect(isValidToken('[Xyz]')).toBe(false)
+  })
+})
+
+describe('isSemanticRobust', () => {
+  test('atoms are semantic robust', () => {
+    expect(isSemanticRobust('[C]')).toBe(true)
+  })
+
+  test('structural tokens are not semantic robust', () => {
+    expect(isSemanticRobust('[Branch1]')).toBe(false)
+  })
+})