selfies-js 0.1.0

package/src/grammar_rules.js

@@ -0,0 +1,146 @@
+/**
+ * Grammar rules for SELFIES derivation
+ * Based on selfies-py/selfies/grammar_rules.py
+ */
+
+// Index alphabet for Q-value calculations
+export const INDEX_ALPHABET = [
+  '[C]', '[Ring1]', '[Ring2]',
+  '[Branch1]', '[=Branch1]', '[#Branch1]',
+  '[Branch2]', '[=Branch2]', '[#Branch2]',
+  '[O]', '[N]', '[=N]', '[=C]', '[#C]', '[S]', '[P]'
+]
+
+// Index code mapping
+export const INDEX_CODE = {}
+for (let i = 0; i < INDEX_ALPHABET.length; i++) {
+  INDEX_CODE[INDEX_ALPHABET[i]] = i
+}
+
+/**
+ * Process branch symbol and extract (bond_order, L)
+ * where L is the number of tokens to read for the Q-value
+ */
+export function processBranchSymbol(symbol) {
+  const match = symbol.match(/^\[(=|#)?Branch([1-3])\]$/)
+  if (!match) return null
+
+  const bondChar = match[1] || ''
+  const L = parseInt(match[2])
+  const order = bondChar === '=' ? 2 : bondChar === '#' ? 3 : 1
+
+  return { order, L }
+}
+
+/**
+ * Process ring symbol and extract (bond_order, L, stereo)
+ * where L is the number of tokens to read for the Q-value
+ */
+export function processRingSymbol(symbol) {
+  // Basic rings: [Ring1], [=Ring1], [#Ring1], etc.
+  const basicMatch = symbol.match(/^\[(=|#)?Ring([1-3])\]$/)
+  if (basicMatch) {
+    const bondChar = basicMatch[1] || ''
+    const L = parseInt(basicMatch[2])
+    const order = bondChar === '=' ? 2 : bondChar === '#' ? 3 : 1
+    return { order, L, stereo: null }
+  }
+
+  // Stereo rings: [-/Ring1], [\/Ring1], etc.
+  const stereoMatch = symbol.match(/^\[([-\\/])([-\\/])Ring([1-3])\]$/)
+  if (stereoMatch) {
+    const L = parseInt(stereoMatch[3])
+    return { order: 1, L, stereo: [stereoMatch[1], stereoMatch[2]] }
+  }
+
+  return null
+}
+
+/**
+ * Calculate next state after processing an atom
+ * Returns [actualBondOrder, nextState]
+ */
+export function nextAtomState(requestedBondOrder, bondingCapacity, state) {
+  let actualBondOrder = requestedBondOrder
+
+  if (state === 0) {
+    actualBondOrder = 0
+  } else {
+    actualBondOrder = Math.min(requestedBondOrder, state, bondingCapacity)
+  }
+
+  const bondsLeft = bondingCapacity - actualBondOrder
+  const nextState = bondsLeft === 0 ? null : bondsLeft
+
+  return [actualBondOrder, nextState]
+}
+
+/**
+ * Calculate branch init state and next state
+ * Returns [branchInitState, nextState]
+ */
+export function nextBranchState(branchType, state) {
+  if (state <= 1) {
+    throw new Error('Branch requires state > 1')
+  }
+
+  const branchInitState = Math.min(state - 1, branchType)
+  const nextState = state - branchInitState
+
+  return [branchInitState, nextState]
+}
+
+/**
+ * Calculate bond order and next state for ring
+ * Returns [bondOrder, nextState]
+ */
+export function nextRingState(ringType, state) {
+  if (state === 0) {
+    throw new Error('Ring requires state > 0')
+  }
+
+  const bondOrder = Math.min(ringType, state)
+  const bondsLeft = state - bondOrder
+  const nextState = bondsLeft === 0 ? null : bondsLeft
+
+  return [bondOrder, nextState]
+}
+
+/**
+ * Get index value from SELFIES symbols
+ * @param {string[]} symbols - Array of symbol contents (without brackets)
+ */
+export function getIndexFromSelfies(symbols) {
+  let index = 0
+  const base = INDEX_ALPHABET.length
+
+  for (let i = 0; i < symbols.length; i++) {
+    const symbolIndex = symbols.length - 1 - i
+    const code = INDEX_CODE[symbols[symbolIndex]] || 0
+    index += code * Math.pow(base, i)
+  }
+
+  return index
+}
+
+/**
+ * Get SELFIES symbols from index value
+ */
+export function getSelfiesFromIndex(index) {
+  if (index < 0) {
+    throw new Error('Index must be non-negative')
+  }
+  if (index === 0) {
+    return [INDEX_ALPHABET[0]]
+  }
+
+  const symbols = []
+  const base = INDEX_ALPHABET.length
+
+  while (index > 0) {
+    symbols.push(INDEX_ALPHABET[index % base])
+    index = Math.floor(index / base)
+  }
+
+  return symbols.reverse()
+}

package/src/index.js

@@ -0,0 +1,70 @@
+/**
+ * selfies-js - Pure JavaScript SELFIES encoder/decoder
+ *
+ * Public API exports
+ */
+
+// Core functionality
+export { decode, decodeToAST, dumpAST } from './decoder.js'
+export { encode } from './encoder.js'
+export { isValid } from './validator.js'
+
+// Tokenization
+export { tokenize, join, lenSelfies } from './tokenizer.js'
+
+// Properties
+export { getMolecularWeight } from './properties/molecularWeight.js'
+export { getFormula } from './properties/formula.js'
+
+// Alphabet
+export { getAlphabet, getSemanticAlphabet, getAlphabetFromSelfies } from './alphabet.js'
+
+// Constraints
+export {
+  getPresetConstraints,
+  getSemanticConstraints,
+  setSemanticConstraints,
+  getBondingCapacity,
+  resetConstraints
+} from './constraints.js'
+
+// DSL
+export { parse } from './dsl/parser.js'
+export { resolve, resolveAll } from './dsl/resolver.js'
+export { getDependencies, getDependents } from './dsl/analyzer.js'
+
+// Errors
+export {
+  SelfiesError,
+  DecodeError,
+  EncodeError,
+  ResolveError,
+  ValidationError,
+  ParseError,
+} from './errors.js'
+
+// Chemistry Validation (RDKit-based)
+export {
+  isChemicallyValid,
+  getCanonicalSmiles,
+  validateRoundtrip,
+  getValidationDetails,
+  batchValidate
+} from './chemistryValidator.js'
+
+// Renderers (RDKit-based)
+export { renderSelfies, initRDKit } from './renderers/svg.js'
+
+// Syntax Highlighting API
+export {
+  tokenizeSelfies,
+  tokenizeDSL,
+  SyntaxTokenType,
+  TokenModifier,
+  getColorScheme,
+  getTextMateScopes,
+  getMonacoTokenTypes,
+  createMonacoLanguage,
+  validateTokenization,
+  highlightToHtml
+} from './syntax.js'

package/src/parser.js

@@ -0,0 +1,96 @@
+/**
+ * Parser - Converts SELFIES tokens into an internal molecule representation (IR)
+ *
+ * The IR is a graph structure with atoms and bonds that can be used for
+ * decoding to SMILES, validation, and property calculation.
+ */
+
+/**
+ * Parses SELFIES tokens into a molecule IR
+ * @param {string[]} tokens - Array of SELFIES tokens
+ * @returns {Object} Molecule IR with atoms and bonds
+ *
+ * IR Structure:
+ * {
+ *   atoms: [
+ *     { element: 'C', index: 0, valence: 4, usedValence: 0 },
+ *     { element: 'O', index: 1, valence: 2, usedValence: 0 },
+ *     ...
+ *   ],
+ *   bonds: [
+ *     { from: 0, to: 1, order: 1 },
+ *     ...
+ *   ]
+ * }
+ */
+import { getValence } from './properties/atoms.js'
+
+export function parse(tokens) {
+  const atoms = []
+  const bonds = []
+
+  for (let i = 0; i < tokens.length; i++) {
+    const tokenInfo = parseToken(tokens[i])
+
+    // Skip branch/ring tokens for now (simplified)
+    if (isBranchToken(tokens[i]) || isRingToken(tokens[i])) {
+      continue
+    }
+
+    if (tokenInfo.element) {
+      const atom = {
+        element: tokenInfo.element,
+        index: atoms.length,
+        valence: getValence(tokenInfo.element),
+        usedValence: 0
+      }
+      atoms.push(atom)
+
+      // Create bond to previous atom
+      if (atoms.length > 1) {
+        bonds.push({
+          from: atoms.length - 2,
+          to: atoms.length - 1,
+          order: tokenInfo.bondOrder
+        })
+      }
+    }
+  }
+
+  return { atoms, bonds }
+}
+
+/**
+ * Extracts element symbol and bond prefix from a token
+ * @param {string} token - SELFIES token like '[C]', '[=O]', '[#N]'
+ * @returns {{element: string, bondOrder: number}} Parsed token info
+ */
+function parseToken(token) {
+  const content = token.slice(1, -1)
+
+  if (content.startsWith('=')) {
+    return { element: content.slice(1), bondOrder: 2 }
+  } else if (content.startsWith('#')) {
+    return { element: content.slice(1), bondOrder: 3 }
+  } else {
+    return { element: content, bondOrder: 1 }
+  }
+}
+
+/**
+ * Determines if a token is a branch token
+ * @param {string} token - SELFIES token
+ * @returns {boolean} True if token is [Branch1], [Branch2], or [Branch3]
+ */
+function isBranchToken(token) {
+  return token.match(/^\[=?#?Branch[123]\]$/) !== null
+}
+
+/**
+ * Determines if a token is a ring token
+ * @param {string} token - SELFIES token
+ * @returns {boolean} True if token is [Ring1], [Ring2], or [Ring3]
+ */
+function isRingToken(token) {
+  return token.match(/^\[=?#?Ring[123]\]$/) !== null
+}

package/src/parser.test.js

@@ -0,0 +1,96 @@
+/**
+ * Tests for SELFIES parser (tokens → IR)
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { parse } from './parser.js'
+
+describe('parse', () => {
+  // TODO: Basic parsing
+  test('parses simple molecule', () => {
+    // TODO: const tokens = ['[C]', '[C]', '[O]']
+    // TODO: const ir = parse(tokens)
+    // TODO: expect(ir.atoms).toHaveLength(3)
+    // TODO: expect(ir.bonds).toHaveLength(2)
+  })
+
+  test('parses with bond modifiers', () => {
+    // TODO: const tokens = ['[C]', '[=C]']
+    // TODO: const ir = parse(tokens)
+    // TODO: expect(ir.bonds[0].order).toBe(2)  // double bond
+  })
+
+  test('parses triple bonds', () => {
+    // TODO: const tokens = ['[C]', '[#N]']
+    // TODO: const ir = parse(tokens)
+    // TODO: expect(ir.bonds[0].order).toBe(3)  // triple bond
+  })
+
+  // TODO: Branch parsing
+  test('parses simple branch', () => {
+    // TODO: const tokens = ['[C]', '[C]', '[Branch1]', '[C]', '[C]', '[C]']
+    // TODO: const ir = parse(tokens)
+    // TODO: expect(ir.atoms).toHaveLength(4)
+    // TODO: expect(ir.bonds).toHaveLength(3)
+  })
+
+  test('parses nested branches', () => {
+    // TODO: const tokens = ['[C]', '[C]', '[Branch1]', '[C]', '[C]', '[Branch1]', '[C]', '[C]', '[C]']
+    // TODO: const ir = parse(tokens)
+    // TODO: Verify branch structure
+  })
+
+  // TODO: Ring parsing
+  test('parses simple ring', () => {
+    // TODO: const tokens = ['[C]', '[C]', '[C]', '[Ring1]', '[C]']
+    // TODO: const ir = parse(tokens)
+    // TODO: Verify ring closure bond exists
+  })
+
+  test('parses benzene ring', () => {
+    // TODO: const tokens = ['[C]', '[=C]', '[C]', '[=C]', '[C]', '[=C]', '[Ring1]', '[=Branch1]']
+    // TODO: const ir = parse(tokens)
+    // TODO: expect(ir.atoms).toHaveLength(6)
+    // TODO: Verify alternating double bonds
+  })
+
+  // TODO: IR structure validation
+  test('returns valid IR structure', () => {
+    // TODO: const tokens = ['[C]', '[C]']
+    // TODO: const ir = parse(tokens)
+    // TODO: expect(ir).toHaveProperty('atoms')
+    // TODO: expect(ir).toHaveProperty('bonds')
+    // TODO: expect(Array.isArray(ir.atoms)).toBe(true)
+    // TODO: expect(Array.isArray(ir.bonds)).toBe(true)
+  })
+
+  test('atoms have required properties', () => {
+    // TODO: const ir = parse(['[C]'])
+    // TODO: const atom = ir.atoms[0]
+    // TODO: expect(atom).toHaveProperty('element')
+    // TODO: expect(atom).toHaveProperty('index')
+    // TODO: expect(atom).toHaveProperty('valence')
+    // TODO: expect(atom).toHaveProperty('usedValence')
+  })
+
+  test('bonds have required properties', () => {
+    // TODO: const ir = parse(['[C]', '[C]'])
+    // TODO: const bond = ir.bonds[0]
+    // TODO: expect(bond).toHaveProperty('from')
+    // TODO: expect(bond).toHaveProperty('to')
+    // TODO: expect(bond).toHaveProperty('order')
+  })
+
+  // TODO: Error cases
+  test('throws on invalid tokens', () => {
+    // TODO: expect(() => parse(['[Xyz]'])).toThrow()
+  })
+
+  test('throws on malformed branch', () => {
+    // TODO: expect(() => parse(['[Branch1]'])).toThrow()  // branch at start
+  })
+
+  test('throws on malformed ring', () => {
+    // TODO: expect(() => parse(['[Ring1]'])).toThrow()  // ring at start
+  })
+})

package/src/properties/atoms.js

@@ -0,0 +1,69 @@
+/**
+ * Atoms - Atomic data for SELFIES elements
+ *
+ * Contains atomic masses, valences, and other properties for
+ * supported elements.
+ */
+
+/**
+ * Atomic data for supported elements
+ * Maps element symbol to properties
+ */
+export const ATOMIC_DATA = {
+  'C': { mass: 12.011, valence: 4, name: 'Carbon' },
+  'N': { mass: 14.007, valence: 3, name: 'Nitrogen' },
+  'O': { mass: 15.999, valence: 2, name: 'Oxygen' },
+  'S': { mass: 32.06, valence: 2, name: 'Sulfur' },
+  'P': { mass: 30.974, valence: 3, name: 'Phosphorus' },
+  'F': { mass: 18.998, valence: 1, name: 'Fluorine' },
+  'Cl': { mass: 35.45, valence: 1, name: 'Chlorine' },
+  'Br': { mass: 79.904, valence: 1, name: 'Bromine' },
+  'I': { mass: 126.904, valence: 1, name: 'Iodine' },
+  'B': { mass: 10.81, valence: 3, name: 'Boron' },
+  'H': { mass: 1.008, valence: 1, name: 'Hydrogen' }
+}
+
+/**
+ * Gets atomic mass for an element
+ * @param {string} element - Element symbol (e.g., 'C', 'N', 'O')
+ * @returns {number} Atomic mass in g/mol
+ * @throws {Error} If element is not supported
+ */
+export function getAtomicMass(element) {
+  const data = ATOMIC_DATA[element]
+  if (!data) {
+    throw new Error(`Unsupported element: ${element}`)
+  }
+  return data.mass
+}
+
+/**
+ * Gets standard valence for an element
+ * @param {string} element - Element symbol
+ * @returns {number} Standard valence
+ * @throws {Error} If element is not supported
+ */
+export function getValence(element) {
+  const data = ATOMIC_DATA[element]
+  if (!data) {
+    throw new Error(`Unsupported element: ${element}`)
+  }
+  return data.valence
+}
+
+/**
+ * Checks if an element is supported
+ * @param {string} element - Element symbol to check
+ * @returns {boolean} True if element is supported
+ */
+export function isSupported(element) {
+  return element in ATOMIC_DATA
+}
+
+/**
+ * Gets list of all supported element symbols
+ * @returns {string[]} Array of element symbols
+ */
+export function getSupportedElements() {
+  return Object.keys(ATOMIC_DATA)
+}

package/src/properties/atoms.test.js

@@ -0,0 +1,116 @@
+/**
+ * Tests for atomic data
+ */
+
+import { describe, test, expect } from 'bun:test'
+import {
+  ATOMIC_DATA,
+  getAtomicMass,
+  getValence,
+  isSupported,
+  getSupportedElements
+} from './atoms.js'
+
+describe('ATOMIC_DATA', () => {
+  test('contains required elements', () => {
+    expect(ATOMIC_DATA).toHaveProperty('C')
+    expect(ATOMIC_DATA).toHaveProperty('N')
+    expect(ATOMIC_DATA).toHaveProperty('O')
+    expect(ATOMIC_DATA).toHaveProperty('S')
+    expect(ATOMIC_DATA).toHaveProperty('P')
+    expect(ATOMIC_DATA).toHaveProperty('F')
+    expect(ATOMIC_DATA).toHaveProperty('Cl')
+    expect(ATOMIC_DATA).toHaveProperty('Br')
+    expect(ATOMIC_DATA).toHaveProperty('I')
+    expect(ATOMIC_DATA).toHaveProperty('B')
+  })
+
+  test('each element has mass and valence', () => {
+    for (const [element, data] of Object.entries(ATOMIC_DATA)) {
+      expect(data).toHaveProperty('mass')
+      expect(data).toHaveProperty('valence')
+      expect(data).toHaveProperty('name')
+    }
+  })
+})
+
+describe('getAtomicMass', () => {
+  test('returns correct mass for carbon', () => {
+    expect(getAtomicMass('C')).toBeCloseTo(12.011, 2)
+  })
+
+  test('returns correct mass for oxygen', () => {
+    expect(getAtomicMass('O')).toBeCloseTo(15.999, 2)
+  })
+
+  test('returns correct mass for nitrogen', () => {
+    expect(getAtomicMass('N')).toBeCloseTo(14.007, 2)
+  })
+
+  test('throws on unsupported element', () => {
+    expect(() => getAtomicMass('Xx')).toThrow()
+  })
+})
+
+describe('getValence', () => {
+  test('returns correct valence for carbon', () => {
+    expect(getValence('C')).toBe(4)
+  })
+
+  test('returns correct valence for nitrogen', () => {
+    expect(getValence('N')).toBe(3)
+  })
+
+  test('returns correct valence for oxygen', () => {
+    expect(getValence('O')).toBe(2)
+  })
+
+  test('returns correct valence for halogens', () => {
+    expect(getValence('F')).toBe(1)
+    expect(getValence('Cl')).toBe(1)
+    expect(getValence('Br')).toBe(1)
+    expect(getValence('I')).toBe(1)
+  })
+
+  test('throws on unsupported element', () => {
+    expect(() => getValence('Xx')).toThrow()
+  })
+})
+
+describe('isSupported', () => {
+  test('returns true for supported elements', () => {
+    expect(isSupported('C')).toBe(true)
+    expect(isSupported('N')).toBe(true)
+    expect(isSupported('O')).toBe(true)
+  })
+
+  test('returns false for unsupported elements', () => {
+    expect(isSupported('Xx')).toBe(false)
+    expect(isSupported('He')).toBe(false)
+  })
+})
+
+describe('getSupportedElements', () => {
+  test('returns array of elements', () => {
+    const elements = getSupportedElements()
+    expect(Array.isArray(elements)).toBe(true)
+    expect(elements.length).toBeGreaterThan(0)
+  })
+
+  test('includes all required elements', () => {
+    const elements = getSupportedElements()
+    expect(elements).toContain('C')
+    expect(elements).toContain('N')
+    expect(elements).toContain('O')
+    expect(elements).toContain('S')
+    expect(elements).toContain('P')
+  })
+
+  test('includes halogens', () => {
+    const elements = getSupportedElements()
+    expect(elements).toContain('F')
+    expect(elements).toContain('Cl')
+    expect(elements).toContain('Br')
+    expect(elements).toContain('I')
+  })
+})

package/src/properties/formula.js

@@ -0,0 +1,111 @@
+/**
+ * Formula - Generates molecular formula from SELFIES
+ *
+ * Computes the molecular formula in Hill notation:
+ * C first, then H, then other elements alphabetically.
+ */
+
+import { tokenize } from '../tokenizer.js'
+import { parse } from '../parser.js'
+
+/**
+ * Generates molecular formula from SELFIES string
+ * @param {string} selfies - SELFIES string
+ * @returns {string} Molecular formula in Hill notation
+ *
+ * Hill notation:
+ * - Carbon first (if present)
+ * - Hydrogen second (if present)
+ * - Other elements alphabetically
+ * - Omit count if 1
+ *
+ * Examples:
+ *   getFormula('[C][C][O]') // => 'C2H6O'
+ *   getFormula('[C]') // => 'CH4'
+ *   getFormula('[N][C][C][=O]') // => 'C2H5NO'
+ */
+export function getFormula(selfies) {
+  const tokens = tokenize(selfies)
+  const ir = parse(tokens)
+  const counts = countAtoms(ir)
+  return formatHill(counts)
+}
+
+/**
+ * Counts atoms in molecule IR (including implicit hydrogens)
+ * @param {Object} ir - Molecule internal representation
+ * @returns {Object} Map of element to count
+ */
+function countAtoms(ir) {
+  const counts = {}
+
+  // Count explicit atoms
+  for (const atom of ir.atoms) {
+    counts[atom.element] = (counts[atom.element] || 0) + 1
+  }
+
+  // Calculate used valence from bonds
+  const usedValence = new Array(ir.atoms.length).fill(0)
+  for (const bond of ir.bonds) {
+    usedValence[bond.from] += bond.order
+    usedValence[bond.to] += bond.order
+  }
+
+  // Add implicit hydrogens
+  let totalH = 0
+  for (let i = 0; i < ir.atoms.length; i++) {
+    const atom = ir.atoms[i]
+    const implicitH = Math.max(0, atom.valence - usedValence[i])
+    totalH += implicitH
+  }
+
+  if (totalH > 0) {
+    counts['H'] = totalH
+  }
+
+  return counts
+}
+
+/**
+ * Formats atom counts as Hill notation formula
+ * @param {Object} counts - Map of element to count
+ * @returns {string} Formatted formula
+ *
+ * Example:
+ *   formatHill({ C: 2, H: 6, O: 1 }) // => 'C2H6O'
+ *   formatHill({ H: 2, O: 1 }) // => 'H2O'
+ */
+function formatHill(counts) {
+  let formula = ''
+
+  // C first
+  if (counts['C']) {
+    formula += formatElement('C', counts['C'])
+  }
+
+  // H second
+  if (counts['H']) {
+    formula += formatElement('H', counts['H'])
+  }
+
+  // Other elements alphabetically
+  const others = Object.keys(counts)
+    .filter(el => el !== 'C' && el !== 'H')
+    .sort()
+
+  for (const element of others) {
+    formula += formatElement(element, counts[element])
+  }
+
+  return formula
+}
+
+/**
+ * Formats a single element count
+ * @param {string} element - Element symbol
+ * @param {number} count - Number of atoms
+ * @returns {string} Formatted string (e.g., 'C2', 'O', 'H3')
+ */
+function formatElement(element, count) {
+  return count === 1 ? element : element + count
+}