selfies-js 0.1.0

package/src/encoder.js

@@ -0,0 +1,467 @@
+/**
+ * Encoder - Converts SMILES strings to SELFIES
+ *
+ * NOTE: This is post-MVP functionality. The encoder is more complex than
+ * the decoder as it requires parsing SMILES and making decisions about
+ * how to represent branches and rings in SELFIES format.
+ */
+
+import { getSelfiesFromIndex } from './grammar_rules.js'
+
+/**
+ * Encodes a SMILES string to SELFIES
+ * @param {string} smiles - The SMILES string to encode
+ * @returns {string} SELFIES representation
+ * @throws {EncodeError} If the SMILES string is invalid
+ *
+ * Example:
+ *   encode('CCO') // => '[C][C][O]'
+ *   encode('c1ccccc1') // => '[C][=C][C][=C][C][=C][Ring1][=Branch1]'
+ */
+export function encode(smiles) {
+  validateSmiles(smiles)
+
+  const state = createEncoderState()
+  let i = 0
+
+  while (i < smiles.length) {
+    const char = smiles[i]
+
+    if (isDigit(char)) {
+      i = handleRingClosure(smiles, i, state)
+    } else if (char === '(') {
+      i = handleBranch(smiles, i, state)
+    } else if (char === ')') {
+      throw new Error('Unexpected closing parenthesis')
+    } else if (char === '=') {
+      i = handleDoubleBond(smiles, i, state)
+    } else if (char === '#') {
+      i = handleTripleBond(smiles, i, state)
+    } else if (char === '/' || char === '\\') {
+      i = handleStereoBond(smiles, i, state)
+    } else if (char === '[') {
+      i = handleBracketAtom(smiles, i, state)
+    } else if (isUpperCase(char)) {
+      i = handleAliphaticAtom(smiles, i, state)
+    } else if (isLowerCase(char)) {
+      i = handleAromaticAtom(smiles, i, state)
+    } else {
+      throw new Error(`Invalid SMILES character: ${char}`)
+    }
+  }
+
+  return state.tokens.join('')
+}
+
+/**
+ * Validates SMILES string input
+ * @param {string} smiles - SMILES string to validate
+ * @throws {Error} If SMILES is empty or null
+ */
+function validateSmiles(smiles) {
+  if (!smiles || smiles.length === 0) {
+    throw new Error('Empty SMILES string')
+  }
+}
+
+/**
+ * Creates initial encoder state
+ * @returns {Object} Encoder state object
+ */
+function createEncoderState() {
+  return {
+    tokens: [],
+    ringClosures: new Map(),
+    aromaticCounter: 0,
+    pendingStereoBond: null  // Tracks / or \ for next bond
+  }
+}
+
+/**
+ * Handles ring closure digits in SMILES
+ * @param {string} smiles - SMILES string
+ * @param {number} index - Current position
+ * @param {Object} state - Encoder state
+ * @returns {number} New position
+ */
+function handleRingClosure(smiles, index, state) {
+  const ringNum = parseInt(smiles[index])
+
+  if (state.ringClosures.has(ringNum)) {
+    closeRing(ringNum, state)
+  } else {
+    openRing(ringNum, state)
+  }
+
+  return index + 1
+}
+
+/**
+ * Opens a new ring at the current position
+ * @param {number} ringNum - Ring number
+ * @param {Object} state - Encoder state
+ */
+function openRing(ringNum, state) {
+  state.ringClosures.set(ringNum, state.tokens.length - 1)
+}
+
+/**
+ * Closes an existing ring
+ * @param {number} ringNum - Ring number
+ * @param {Object} state - Encoder state
+ */
+function closeRing(ringNum, state) {
+  const ringStartPos = state.ringClosures.get(ringNum)
+  const atomsInBetween = state.tokens.length - ringStartPos - 1
+
+  // Add ring token with stereochemistry if present
+  if (state.pendingStereoBond) {
+    state.tokens.push(`[${state.pendingStereoBond}Ring1]`)
+    state.pendingStereoBond = null
+  } else {
+    state.tokens.push('[Ring1]')
+  }
+
+  // For decoder formula: targetIndex = prevAtomIndex - (Q.value + 1)
+  // We want: Q.value + 1 = atomsInBetween, so Q.value = atomsInBetween - 1
+  state.tokens.push(getLengthToken(atomsInBetween - 1))
+  state.ringClosures.delete(ringNum)
+}
+
+/**
+ * Handles branch notation in SMILES
+ * @param {string} smiles - SMILES string
+ * @param {number} index - Current position
+ * @param {Object} state - Encoder state
+ * @returns {number} New position
+ */
+function handleBranch(smiles, index, state) {
+  const { content, endIndex } = extractBranchContent(smiles, index)
+  const branchTokens = encode(content)
+  const branchSymbolCount = countSelfiesSymbols(branchTokens)
+
+  // Determine branch bond order from first character of branch content
+  // If branch starts with = or #, use bonded branch symbol
+  let branchSymbol = '[Branch1]'
+  if (content.startsWith('=')) {
+    branchSymbol = '[=Branch1]'
+  } else if (content.startsWith('#')) {
+    branchSymbol = '[#Branch1]'
+  }
+
+  state.tokens.push(branchSymbol)
+  // For decoder formula: reads Q.value + 1 atoms from branch
+  // We want: Q.value + 1 = branchSymbolCount, so Q.value = branchSymbolCount - 1
+  state.tokens.push(getLengthToken(branchSymbolCount - 1))
+  state.tokens.push(branchTokens)
+
+  return endIndex + 1
+}
+
+/**
+ * Extracts content between matching parentheses
+ * @param {string} smiles - SMILES string
+ * @param {number} startIndex - Position of opening parenthesis
+ * @returns {Object} Branch content and end index
+ */
+function extractBranchContent(smiles, startIndex) {
+  const branchStart = startIndex + 1
+  let depth = 1
+  let branchEnd = branchStart
+
+  while (branchEnd < smiles.length && depth > 0) {
+    if (smiles[branchEnd] === '(') depth++
+    if (smiles[branchEnd] === ')') depth--
+    if (depth > 0) branchEnd++
+  }
+
+  if (depth !== 0) {
+    throw new Error('Unmatched parenthesis in SMILES')
+  }
+
+  return {
+    content: smiles.substring(branchStart, branchEnd),
+    endIndex: branchEnd
+  }
+}
+
+/**
+ * Handles double bond notation
+ * @param {string} smiles - SMILES string
+ * @param {number} index - Current position
+ * @param {Object} state - Encoder state
+ * @returns {number} New position
+ */
+function handleDoubleBond(smiles, index, state) {
+  return handleBondedAtom(smiles, index, state, '=')
+}
+
+/**
+ * Handles triple bond notation
+ * @param {string} smiles - SMILES string
+ * @param {number} index - Current position
+ * @param {Object} state - Encoder state
+ * @returns {number} New position
+ */
+function handleTripleBond(smiles, index, state) {
+  return handleBondedAtom(smiles, index, state, '#')
+}
+
+/**
+ * Handles stereochemistry bond notation (/ and \)
+ * @param {string} smiles - SMILES string
+ * @param {number} index - Current position
+ * @param {Object} state - Encoder state
+ * @returns {number} New position
+ */
+function handleStereoBond(smiles, index, state) {
+  const stereoChar = smiles[index]
+
+  // Store the stereochemistry marker to be used with the next ring closure
+  state.pendingStereoBond = stereoChar === '/' ? '-/' : '\\/'
+
+  return index + 1
+}
+
+/**
+ * Handles atoms with bond prefix (= or #)
+ * @param {string} smiles - SMILES string
+ * @param {number} index - Current position
+ * @param {Object} state - Encoder state
+ * @param {string} bondSymbol - Bond symbol (= or #)
+ * @returns {number} New position
+ */
+function handleBondedAtom(smiles, index, state, bondSymbol) {
+  const nextIndex = index + 1
+
+  if (nextIndex >= smiles.length) {
+    throw new Error('Invalid SMILES: bond symbol at end')
+  }
+
+  const nextChar = smiles[nextIndex]
+
+  if (isUpperCase(nextChar)) {
+    return handleBondedUppercaseAtom(smiles, nextIndex, state, bondSymbol)
+  } else if (isLowerCase(nextChar)) {
+    state.tokens.push(`[${bondSymbol}${nextChar.toUpperCase()}]`)
+    return nextIndex + 1
+  } else {
+    throw new Error(`Invalid SMILES: unexpected character after ${bondSymbol}: ${nextChar}`)
+  }
+}
+
+/**
+ * Handles bonded uppercase atoms (checking for two-letter elements)
+ * @param {string} smiles - SMILES string
+ * @param {number} index - Current position at the atom
+ * @param {Object} state - Encoder state
+ * @param {string} bondSymbol - Bond symbol
+ * @returns {number} New position
+ */
+function handleBondedUppercaseAtom(smiles, index, state, bondSymbol) {
+  const char = smiles[index]
+
+  if (index + 1 < smiles.length && isLowerCase(smiles[index + 1])) {
+    state.tokens.push(`[${bondSymbol}${char}${smiles[index + 1]}]`)
+    return index + 2
+  } else {
+    state.tokens.push(`[${bondSymbol}${char}]`)
+    return index + 1
+  }
+}
+
+/**
+ * Handles bracket atom notation like [nH], [NH2+], etc.
+ * @param {string} smiles - SMILES string
+ * @param {number} index - Current position
+ * @param {Object} state - Encoder state
+ * @returns {number} New position
+ */
+function handleBracketAtom(smiles, index, state) {
+  const closeBracket = smiles.indexOf(']', index)
+
+  if (closeBracket === -1) {
+    throw new Error('Invalid SMILES: unclosed bracket atom')
+  }
+
+  const bracketContent = smiles.substring(index + 1, closeBracket)
+  const element = extractElementFromBracket(bracketContent)
+
+  state.tokens.push(`[${element}]`)
+  return closeBracket + 1
+}
+
+/**
+ * Extracts element symbol from bracket notation
+ * @param {string} bracketContent - Content inside brackets
+ * @returns {string} Element symbol
+ */
+function extractElementFromBracket(bracketContent) {
+  let elementMatch = bracketContent.match(/^([A-Z][a-z]?)/)
+
+  if (!elementMatch) {
+    elementMatch = bracketContent.match(/^([a-z]+)/)
+    if (elementMatch) {
+      return elementMatch[1].charAt(0).toUpperCase() + elementMatch[1].slice(1)
+    }
+  }
+
+  if (elementMatch) {
+    return elementMatch[1]
+  }
+
+  const firstLetter = bracketContent.match(/[A-Za-z]/)
+  if (firstLetter) {
+    return firstLetter[0].toUpperCase()
+  }
+
+  return 'C'
+}
+
+/**
+ * Handles aliphatic (uppercase) atoms
+ * @param {string} smiles - SMILES string
+ * @param {number} index - Current position
+ * @param {Object} state - Encoder state
+ * @returns {number} New position
+ */
+function handleAliphaticAtom(smiles, index, state) {
+  const char = smiles[index]
+
+  // Check if next character forms a two-letter element
+  if (index + 1 < smiles.length && isLowerCase(smiles[index + 1])) {
+    const twoLetter = char + smiles[index + 1]
+    // Valid two-letter elements: Cl, Br, Si, etc.
+    // NOT Cc, Cn, Co, etc. which are separate atoms
+    if (isTwoLetterElement(twoLetter)) {
+      state.tokens.push(`[${twoLetter}]`)
+      return index + 2
+    }
+  }
+
+  // Single-letter element
+  state.tokens.push(`[${char}]`)
+  return index + 1
+}
+
+/**
+ * Handles aromatic (lowercase) atoms
+ * @param {string} smiles - SMILES string
+ * @param {number} index - Current position
+ * @param {Object} state - Encoder state
+ * @returns {number} New position
+ */
+function handleAromaticAtom(smiles, index, state) {
+  const element = smiles[index].toUpperCase()
+
+  if (state.aromaticCounter % 2 === 0) {
+    state.tokens.push(`[${element}]`)
+  } else {
+    state.tokens.push(`[=${element}]`)
+  }
+
+  state.aromaticCounter++
+  return index + 1
+}
+
+/**
+ * Counts SELFIES symbols in a string
+ * @param {string} selfiesString - SELFIES string
+ * @returns {number} Number of symbols (opening brackets)
+ */
+function countSelfiesSymbols(selfiesString) {
+  let count = 0
+  for (let i = 0; i < selfiesString.length; i++) {
+    if (selfiesString[i] === '[') count++
+  }
+  return count
+}
+
+/**
+ * Generates length token for branch/ring notation
+ * Uses INDEX_ALPHABET from grammar_rules.js for consistency with decoder
+ * @param {number} length - Length value (0-indexed, matching atom count)
+ * @returns {string} Length token in SELFIES format
+ * @throws {Error} If length is out of range
+ */
+function getLengthToken(length) {
+  // Use getSelfiesFromIndex to convert length to SELFIES symbols
+  // This ensures encoder and decoder use the same INDEX_ALPHABET
+  const symbols = getSelfiesFromIndex(length)
+
+  // For single symbol, return it directly
+  if (symbols.length === 1) {
+    return symbols[0]
+  }
+
+  // For multiple symbols, join them (for large indices requiring multiple tokens)
+  return symbols.join('')
+}
+
+/**
+ * Checks if a two-character string is a valid two-letter element symbol
+ * @param {string} symbol - Two-character string to check
+ * @returns {boolean} True if valid two-letter element
+ */
+function isTwoLetterElement(symbol) {
+  const twoLetterElements = new Set([
+    'Cl', 'Br', 'Si', 'Se', 'As', 'Al', 'Ca', 'Mg', 'Na', 'He',
+    'Li', 'Be', 'Ne', 'Ar', 'Kr', 'Xe', 'Rn', 'Sc', 'Ti', 'Cr',
+    'Mn', 'Fe', 'Co', 'Ni', 'Cu', 'Zn', 'Ga', 'Ge', 'Sr', 'Zr',
+    'Nb', 'Mo', 'Tc', 'Ru', 'Rh', 'Pd', 'Ag', 'Cd', 'In', 'Sn',
+    'Sb', 'Te', 'Ba', 'La', 'Ce', 'Pr', 'Nd', 'Pm', 'Sm', 'Eu',
+    'Gd', 'Tb', 'Dy', 'Ho', 'Er', 'Tm', 'Yb', 'Lu', 'Hf', 'Ta',
+    'Re', 'Os', 'Ir', 'Pt', 'Au', 'Hg', 'Tl', 'Pb', 'Bi', 'Po',
+    'At', 'Ra', 'Ac', 'Th', 'Pa', 'Np', 'Pu', 'Am', 'Cm', 'Bk',
+    'Cf', 'Es', 'Fm', 'Md', 'No', 'Lr', 'Rf', 'Db', 'Sg', 'Bh',
+    'Hs', 'Mt', 'Ds', 'Rg', 'Cn', 'Nh', 'Fl', 'Mc', 'Lv', 'Ts', 'Og'
+  ])
+  return twoLetterElements.has(symbol)
+}
+
+/**
+ * Checks if character is uppercase letter
+ * @param {string} char - Character to check
+ * @returns {boolean} True if uppercase
+ */
+function isUpperCase(char) {
+  return char >= 'A' && char <= 'Z'
+}
+
+/**
+ * Checks if character is lowercase letter
+ * @param {string} char - Character to check
+ * @returns {boolean} True if lowercase
+ */
+function isLowerCase(char) {
+  return char >= 'a' && char <= 'z'
+}
+
+/**
+ * Checks if character is a digit
+ * @param {string} char - Character to check
+ * @returns {boolean} True if digit
+ */
+function isDigit(char) {
+  return char >= '0' && char <= '9'
+}
+
+/**
+ * Parses a SMILES string into a molecule graph
+ * @param {string} smiles - SMILES string
+ * @returns {Object} Molecule graph structure
+ */
+function parseSmiles(smiles) {
+  // TODO: Implement SMILES parser (POST-MVP)
+  throw new Error('Not implemented - encoder is post-MVP')
+}
+
+/**
+ * Converts aromatic bonds to explicit single/double bonds (Kekulization)
+ * @param {Object} graph - Molecule graph
+ * @returns {Object} Kekulized graph
+ */
+function kekulize(graph) {
+  // TODO: Implement Kekulization (POST-MVP)
+  throw new Error('Not implemented - encoder is post-MVP')
+}

package/src/encoder.test.js

@@ -0,0 +1,61 @@
+/**
+ * Tests for SMILES encoding
+ * NOTE: Encoder is post-MVP, these tests are placeholders
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { encode } from '../src/encoder.js'
+
+describe('encode', () => {
+  // TODO: Basic molecules (POST-MVP)
+  test('encodes methane', () => {
+    expect(encode('C')).toBe('[C]')
+  })
+
+  test('encodes ethane', () => {
+    expect(encode('CC')).toBe('[C][C]')
+  })
+
+  test('encodes ethanol', () => {
+    expect(encode('CCO')).toBe('[C][C][O]')
+  })
+
+  // TODO: Bond orders (POST-MVP)
+  test('encodes ethene', () => {
+    expect(encode('C=C')).toBe('[C][=C]')
+  })
+
+  test('encodes acetylene', () => {
+    expect(encode('C#C')).toBe('[C][#C]')
+  })
+
+  // TODO: Branches (POST-MVP)
+  test('encodes isobutane', () => {
+    expect(encode('CC(C)C')).toBe('[C][C][Branch1][C][C][C]')
+  })
+
+  // TODO: Rings (POST-MVP)
+  test('encodes benzene', () => {
+    // Note: Using lowercase aromatic SMILES for benzene
+    // Fixed: Now uses [=Branch1] (Q=4) instead of [=N] (Q=11)
+    expect(encode('c1ccccc1')).toBe('[C][=C][C][=C][C][=C][Ring1][=Branch1]')
+  })
+
+  test('encodes cyclopropane', () => {
+    // Fixed: Now uses [Ring1] (Q=1) instead of [=C] (Q=12)
+    expect(encode('C1CC1')).toBe('[C][C][C][Ring1][Ring1]')
+  })
+
+  // Error cases
+  test('throws on empty SMILES', () => {
+    expect(() => encode('')).toThrow('Empty SMILES string')
+  })
+
+  test('throws on unmatched parenthesis', () => {
+    expect(() => encode('C(C')).toThrow('Unmatched parenthesis')
+  })
+
+  test('throws on invalid bond at end', () => {
+    expect(() => encode('CC=')).toThrow('bond symbol at end')
+  })
+})

package/src/errors.js

@@ -0,0 +1,79 @@
+/**
+ * Errors - Custom error types for selfies-js
+ *
+ * Defines specific error classes for different failure modes.
+ */
+
+/**
+ * Base error class for selfies-js errors
+ */
+export class SelfiesError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'SelfiesError'
+  }
+}
+
+/**
+ * Error thrown when decoding fails
+ */
+export class DecodeError extends SelfiesError {
+  constructor(message, token = null, position = null) {
+    super(message)
+    this.name = 'DecodeError'
+    this.token = token
+    this.position = position
+  }
+}
+
+/**
+ * Error thrown when encoding fails
+ */
+export class EncodeError extends SelfiesError {
+  constructor(message, smiles = null) {
+    super(message)
+    this.name = 'EncodeError'
+    this.smiles = smiles
+  }
+}
+
+/**
+ * Error thrown when resolution fails
+ */
+export class ResolveError extends SelfiesError {
+  constructor(message, name = null) {
+    super(message)
+    this.name = 'ResolveError'
+    this.definitionName = name
+  }
+}
+
+/**
+ * Error thrown when validation fails
+ */
+export class ValidationError extends SelfiesError {
+  constructor(message, token = null, position = null) {
+    super(message)
+    this.name = 'ValidationError'
+    this.token = token
+    this.position = position
+  }
+}
+
+/**
+ * Error thrown when DSL parsing fails
+ */
+export class ParseError extends SelfiesError {
+  constructor(message, line = null, column = null) {
+    super(message)
+    this.name = 'ParseError'
+    this.line = line
+    this.column = column
+  }
+}
+
+// TODO: Add more specific error types as needed during implementation
+// Examples:
+// - CyclicDependencyError
+// - UndefinedReferenceError
+// - InvalidTokenError

package/src/errors.test.js

@@ -0,0 +1,91 @@
+/**
+ * Tests for error classes
+ */
+
+import { describe, test, expect } from 'bun:test'
+import {
+  SelfiesError,
+  DecodeError,
+  EncodeError,
+  ResolveError,
+  ValidationError,
+  ParseError
+} from './errors.js'
+
+describe('SelfiesError', () => {
+  test('creates base error', () => {
+    const error = new SelfiesError('test message')
+    expect(error.message).toBe('test message')
+    expect(error.name).toBe('SelfiesError')
+    expect(error instanceof Error).toBe(true)
+  })
+})
+
+describe('DecodeError', () => {
+  test('creates decode error with message', () => {
+    const error = new DecodeError('decode failed')
+    expect(error.message).toBe('decode failed')
+    expect(error.name).toBe('DecodeError')
+    expect(error instanceof SelfiesError).toBe(true)
+  })
+
+  test('includes token and position', () => {
+    const error = new DecodeError('invalid token', '[Xyz]', 5)
+    expect(error.token).toBe('[Xyz]')
+    expect(error.position).toBe(5)
+  })
+})
+
+describe('EncodeError', () => {
+  test('creates encode error with message', () => {
+    const error = new EncodeError('encode failed')
+    expect(error.message).toBe('encode failed')
+    expect(error.name).toBe('EncodeError')
+  })
+
+  test('includes smiles string', () => {
+    const error = new EncodeError('invalid smiles', 'invalid')
+    expect(error.smiles).toBe('invalid')
+  })
+})
+
+describe('ResolveError', () => {
+  test('creates resolve error with message', () => {
+    const error = new ResolveError('resolve failed')
+    expect(error.message).toBe('resolve failed')
+    expect(error.name).toBe('ResolveError')
+  })
+
+  test('includes definition name', () => {
+    const error = new ResolveError('undefined reference', 'methyl')
+    expect(error.definitionName).toBe('methyl')
+  })
+})
+
+describe('ValidationError', () => {
+  test('creates validation error', () => {
+    const error = new ValidationError('validation failed')
+    expect(error.message).toBe('validation failed')
+    expect(error.name).toBe('ValidationError')
+  })
+
+  test('includes token and position', () => {
+    const error = new ValidationError('invalid', '[Bad]', 10)
+    expect(error.token).toBe('[Bad]')
+    expect(error.position).toBe(10)
+  })
+})
+
+describe('ParseError', () => {
+  test('creates parse error', () => {
+    const error = new ParseError('parse failed')
+    expect(error.message).toBe('parse failed')
+    expect(error.name).toBe('ParseError')
+  })
+
+  test('includes line and column', () => {
+    const error = new ParseError('syntax error', 5, 10)
+    expect(error.line).toBe(5)
+    expect(error.column).toBe(10)
+  })
+})