selfies-js 0.2.0 → 0.3.2

package/README.md

@@ -1,74 +1,54 @@
 <div align="center">
-  <img src="toluene-logo.svg" alt="Toluene molecule" width="200"/>
+  <img src="icon.svg" alt="Toluene molecule" width="200"/>
   <h1>selfies-js</h1>
-  <p>A pure JavaScript implementation of the SELFIES molecular string representation</p>
+  <p><strong>Molecular fragments as reusable code.</strong></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)**
+## Why 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
+SELFIES was designed for machine learning — every string is a valid molecule, eliminating syntax errors in generative models. This DSL extends that principle: named fragments are easier for LLMs to compose correctly than raw atom strings, and undefined references fail loudly instead of producing silent errors.
 
-```javascript
-import {
-  decode, encode, isValid,
-  getMolecularWeight, getFormula,
-  lenSelfies, getSemanticConstraints,
-  isChemicallyValid, getCanonicalSmiles, validateRoundtrip
-} from 'selfies-js'
+## The Problem
 
-// SELFIES → SMILES
-decode('[C][C][O]')  // 'CCO'
+Pharmaceutical SMILES strings are unreadable:
 
-// 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
+```
+CC(=O)Nc1ccc(O)cc1
+```
 
-// Properties
-getMolecularWeight('[C][C][O]')  // 46.07
-getFormula('[C][C][O]')  // 'C2H6O'
+What is that? Acetaminophen. But you'd never know by looking at it.
 
-// Utilities
-lenSelfies('[C][C][O]')  // 3 (symbol count, not string length)
+And when LLMs generate SMILES, they hallucinate invalid structures. SELFIES fixes the validity problem. The DSL fixes the readability problem.
 
-// Semantic constraints
-const constraints = getSemanticConstraints()
-console.log(constraints['C'])  // 4 (max bonds for carbon)
+## The Solution
 
-// SVG Rendering (using RDKit.js)
-import { renderSelfies } from 'selfies-js'
+Define named fragments. Compose molecules like code. Import and reuse across projects.
 
-const svg = await renderSelfies('[C][C][O]', {
-  width: 300,
-  height: 300
-})
+```selfies
+# base-fragments.selfies - your team's shared library
+[methyl] = [C]
+[amino] = [N]
+[hydroxyl] = [O]
+[phenyl] = [C][=C][C][=C][C][=C][Ring1][=Branch1]
 ```
 
-## Interactive Playground
+```selfies
+# molecules.selfies - today's work
+import [methyl, amino, hydroxyl, phenyl] from "./base-fragments.selfies"
 
-Try SELFIES-JS live in your browser:
+[methanol] = [methyl][hydroxyl]
+[aniline] = [phenyl][amino]
+[toluene] = [methyl][phenyl]
+```
 
-**[https://ghost---shadow.github.io/selfies-js/](https://ghost---shadow.github.io/selfies-js/)**
+```bash
+$ selfies run molecules.selfies --format=smiles
+methanol: CO
+aniline: NC1=CC=CC=C1
+toluene: CC1=CC=CC=C1
+```
 
-Features:
-- Live SELFIES ↔ SMILES conversion
-- Real-time molecular properties
-- Built-in test suite
-- Syntax highlighting
+Your molecule definitions are now version-controlled, diffable, and shareable.
 
 ## Installation
 
@@ -76,210 +56,154 @@ Features:
 npm install selfies-js
 ```
 
-### Browser Usage (CDN)
+## Quick Start
 
-For direct browser usage without a bundler:
+**1. Create a fragment library** (`fragments.selfies`):
 
-```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>
+```selfies
+[methyl] = [C]
+[ethyl] = [C][C]
+[hydroxyl] = [O]
+[carbonyl] = [C][=O]
+[carboxyl] = [C][=O][O]
 ```
 
-Download from the [latest release](https://github.com/Ghost---Shadow/selfies-js/releases/latest).
+**2. Compose molecules** (`molecules.selfies`):
 
-## Features
+```selfies
+import "./fragments.selfies"
 
-- **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
+[ethanol] = [ethyl][hydroxyl]
+[acetic_acid] = [methyl][carboxyl]
+```
 
-## CLI Usage
+**3. Compile to SMILES**:
 
-The `selfies-js` CLI allows you to work with `.selfies` DSL files from the command line.
+```bash
+$ selfies run molecules.selfies --format=smiles
+ethanol: CCO
+acetic_acid: CC(=O)O
+```
 
-### Commands
+## CLI Commands
 
 ```bash
-# Execute a .selfies file and output resolved definitions
-bun src/cli.js run molecules.selfies
+# Compile a .selfies file to SMILES
+selfies run molecules.selfies --format=smiles
 
-# Output as SMILES instead of SELFIES
-bun src/cli.js run molecules.selfies --format=smiles
+# Output as SELFIES (default)
+selfies run molecules.selfies
 
-# Validate a .selfies file for errors
-bun src/cli.js validate molecules.selfies
+# Validate syntax without running
+selfies validate molecules.selfies
 
 # List all definitions in a file
-bun src/cli.js list molecules.selfies
-
-# Show help
-bun src/cli.js help
+selfies list molecules.selfies
 ```
 
-### DSL Syntax
-
-The `.selfies` DSL allows you to define named molecular fragments and compose them hierarchically:
+## DSL Syntax
 
 ```selfies
 # Comments start with #
 
-# Basic definitions
-[methyl] = [C]
-[ethyl] = [C][C]
-[hydroxyl] = [O]
+# Define a fragment
+[name] = [SELFIES][tokens][here]
 
-# Composition - reference other definitions
+# Reference other fragments
 [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 from other files
+import "./other-file.selfies"                    # import all
+import [methyl, ethyl] from "./fragments.selfies" # import specific
 ```
 
-### Import Syntax
+## JavaScript API
 
-Import definitions from other `.selfies` files:
+```javascript
+import { parse, resolve, resolveAll, loadFile } from 'selfies-js/dsl'
 
-```selfies
-# Import all definitions from another file
-import "./fragments.selfies"
+// Load a file with imports
+const program = loadFile('molecules.selfies')
 
-# Alternative syntax for importing all
-import * from "./common.selfies"
+// Resolve a single definition to SELFIES
+resolve(program, 'ethanol')  // '[C][C][O]'
 
-# Import specific definitions only
-import [methyl, ethyl, hydroxyl] from "./base.selfies"
+// Resolve to SMILES
+resolve(program, 'ethanol', { decode: true })  // 'CCO'
 
-# Use imported definitions
-[my_molecule] = [methyl][hydroxyl]
+// Resolve all definitions
+resolveAll(program)  // Map { 'ethanol' => '[C][C][O]', ... }
 ```
 
-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
+### Core SELFIES functions
 
-### Example Output
+```javascript
+import { encode, decode, isValid, getMolecularWeight, getFormula } from 'selfies-js'
 
-```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
+decode('[C][C][O]')           // 'CCO'
+encode('CCO')                 // '[C][C][O]'
+isValid('[C][C][O]')          // true
+getMolecularWeight('[C][C][O]') // 46.07
+getFormula('[C][C][O]')       // 'C2H6O'
 ```
 
-## DSL API
+### SVG Rendering
 
 ```javascript
-import { parse, resolve, resolveAll } from 'selfies-js/dsl'
-import { loadFile } from 'selfies-js/dsl'
+import { renderSelfies, initRDKit } from 'selfies-js'
 
-// Load a file with imports
-const program = loadFile('molecules.selfies')
+await initRDKit()
+const svg = await renderSelfies('[C][C][O]', { width: 300, height: 300 })
+```
 
-// Or parse source directly
-const source = `
-[methyl] = [C]
-[ethanol] = [methyl][C][O]
-`
-const program = parse(source)
+## VS Code Extension
 
-// Resolve a single definition
-resolve(program, 'ethanol')  // '[C][C][O]'
+Get live visualization as you author `.selfies` files. See the molecular structure update line-by-line as you navigate your code.
 
-// Resolve with SMILES output
-resolve(program, 'ethanol', { decode: true })  // 'CCO'
+**[Install from VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=ghost---shadow.selfies-lang)**
 
-// Resolve all definitions
-const all = resolveAll(program)
-// Map { 'methyl' => '[C]', 'ethanol' => '[C][C][O]' }
+## Browser Usage
+
+```html
+<script src="https://github.com/Ghost---Shadow/selfies-js/releases/latest/download/selfies.umd.min.js"></script>
+<script>
+  SELFIES.encode('CCO')                    // '[C][C][O]'
+  SELFIES.decode('[C][C][O]')              // 'CCO'
+  SELFIES.getMolecularWeight('[C][C][O]')  // 46.07
+</script>
 ```
 
-## Visualization
+## Examples
 
-The library uses **RDKit.js** for professional molecule rendering:
+See the [`examples/`](./examples) directory:
 
-```javascript
-import { renderSelfies, initRDKit } from 'selfies-js'
+- `base-fragments.selfies` — Reusable building blocks (alkyl groups, functional groups, halogens)
+- `molecules-with-imports.selfies` — Composing molecules from imported fragments
+- `selective-import.selfies` — Importing only what you need
 
-// Initialize RDKit (async, only needed once)
-await initRDKit()
+## What is SELFIES?
 
-// Render toluene
-const svg = await renderSelfies('[C][C][=C][C][=C][C][=C][Ring1][=Branch1]', {
-  width: 300,
-  height: 300
-})
-```
+SELFIES (SELF-referencIng Embedded Strings) is a molecular string representation where **every string is a valid molecule**. Unlike SMILES, you can't write an invalid SELFIES string. This makes it ideal for machine learning and generative chemistry.
 
-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
+This library is a JavaScript port of the Python implementation: [aspuru-guzik-group/selfies](https://github.com/aspuru-guzik-group/selfies)
 
-## Examples
+> 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.
 
-See the `examples/` directory for sample `.selfies` files:
+## Interactive Playground
 
-- `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
+Try it live: **[https://ghost---shadow.github.io/selfies-js/](https://ghost---shadow.github.io/selfies-js/)**
 
 ## 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)
+- **Bracket atoms** in SMILES (`[nH]`, `[C@@]`, `[13C]`) — limited support
+- **Fused aromatic ring systems** — some complex cases may not roundtrip
+- **Polycyclic structures** — partial support
 
-## References
+For complete SELFIES support, use the Python library: [aspuru-guzik-group/selfies](https://github.com/aspuru-guzik-group/selfies)
 
-- **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)
+## Testimonies
 
-- **Python Implementation:** [github.com/aspuru-guzik-group/selfies](https://github.com/aspuru-guzik-group/selfies)
+![testimony.png](testimony.png)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selfies-js",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "description": "Pure JavaScript SELFIES encoder/decoder with DSL for molecular composition",
   "type": "module",
   "main": "src/index.js",