Equamistry 🧪

A powerful, type-safe TypeScript library for parsing, rendering, and manipulating chemical equations, compounds, and symbols with natural syntax support.

🚀 Features

• Natural Chemical Notation: Write chemistry naturally - H2O, Ca(OH)2, Fe(OH)3
• Charges & States: Na{+}, SO4{2-}, H2O{l} with proper rendering
• Advanced Chemistry: Hydrates, complex ions, equations, and particles
• Smart Rendering: States appear as subscripts: NaCl(aq) → NaCl<sub>(aq)</sub>
• React Integration: Single unified component with auto-detection
• TypeScript: Full type safety and IntelliSense support
• Production Ready: 223/223 tests passed, comprehensive error handling

📦 Installation

npm install equamistry

🧪 Quick Start

Basic Usage

import { Compound, Equation, Symbol } from 'equamistry';

// Parse compounds
const water = Compound.fromString('H2O');
console.log(water.toHTML()); // H<sub>2</sub>O

// Parse with states (rendered as subscripts)
const saltSolution = Compound.fromString('NaCl(aq)');
console.log(saltSolution.toHTML()); // NaCl<sub>(aq)</sub>

// Parse equations
const reaction = Equation.fromString('H2 + Cl2 -> 2HCl');
console.log(reaction.toHTML()); // H<sub>2</sub> + Cl<sub>2</sub> → 2HCl

// Parse symbols with charges
const calcium = Symbol.fromString('Ca{2+}');
console.log(calcium.toHTML()); // Ca<sup>2+</sup>

React Component

import { EquationComponent as Equation } from 'equamistry';

function ChemistryApp() {
  return (
    <div>
      {/* Auto-detection */}
      <Equation>H2O(l)</Equation>                     {/* Compound with state */}
      <Equation>Ca{2+}</Equation>                     {/* Ion */}
      <Equation>H2 + Cl2 -> 2HCl</Equation>          {/* Equation */}
      
      {/* Complex structures */}
      <Equation>CuSO4.5H2O</Equation>                 {/* Hydrate */}
      <Equation>[Fe(CN)6]{3-}</Equation>              {/* Complex ion */}
    </div>
  );
}

📚 Supported Notation

Basic Chemistry

H2O           → H₂O
CO2(g)        → CO₂<sub>(g)</sub>
NaCl(aq)      → NaCl<sub>(aq)</sub>
Ca(OH)2(s)    → Ca(OH)₂<sub>(s)</sub>

Charges (Use Curly Braces)

Na{+}         → Na⁺
Cl{-}         → Cl⁻
Ca{2+}        → Ca²⁺
SO4{2-}       → SO₄²⁻

States (Rendered as Subscripts)

H2O(l)        → H₂O<sub>(l)</sub>
CO2(g)        → CO₂<sub>(g)</sub>
NaCl(aq)      → NaCl<sub>(aq)</sub>
CaCO3(s)      → CaCO₃<sub>(s)</sub>

Hydrates (Use Regular Dot)

CuSO4.H2O     → CuSO₄·H₂O
CuSO4.5H2O    → CuSO₄·5H₂O
2CuSO4.5H2O   → 2CuSO₄·5H₂O

Complex Ions

K3[Fe(CN)6]         → K₃[Fe(CN)₆]
[Cu(NH3)4]SO4       → [Cu(NH₃)₄]SO₄
[Fe(CN)6]{3-}       → [Fe(CN)₆]³⁻

Chemical Equations

H2 + Cl2 -> 2HCl                           → H₂ + Cl₂ → 2HCl
NaCl(aq) + AgNO3(aq) -> AgCl(s) + NaNO3(aq) → NaCl<sub>(aq)</sub> + AgNO₃<sub>(aq)</sub> → AgCl<sub>(s)</sub> + NaNO₃<sub>(aq)</sub>
CaCO3(s) -> CaO(s) + CO2(g)                → CaCO₃<sub>(s)</sub> → CaO<sub>(s)</sub> + CO₂<sub>(g)</sub>

🔧 API Reference

Compound Class

class Compound {
  static fromString(input: string): Compound
  toHTML(options?: RenderOptions): string
  toReact(options?: RenderOptions): React.ReactElement
  toString(): string
  getData(): CompoundData
}

Equation Class

class Equation {
  static fromString(input: string): Equation
  toHTML(options?: RenderOptions): string
  toReact(options?: RenderOptions): React.ReactElement
  toString(): string
  getData(): EquationData
}

Symbol Class

class Symbol {
  static fromString(input: string): Symbol
  toHTML(options?: RenderOptions): string
  toReact(options?: RenderOptions): React.ReactElement
  toString(): string
  getData(): SymbolData
}

React Component

interface EquationProps {
  children: string;
  type?: 'auto' | 'symbol' | 'compound' | 'equation';
  display?: 'block' | 'inline';
  className?: string;
}

🎨 Render Options

interface RenderOptions {
  display?: 'inline' | 'block';
  align?: 'left' | 'center' | 'right';
  className?: string;
}

🧠 Smart Auto-Detection

The React component automatically detects the type of chemistry expression:

• Equations: Contains ->, <-, <->, or =
• Compounds: Contains parentheses, brackets, braces, or numbers
• Symbols: Simple element names

🏗️ Architecture

The library is built with a clean, consolidated architecture:

equamistry/
├── Compound.ts     # Core chemistry parsing (includes Equation class)
├── Symbol.ts       # Basic symbol parsing
├── index.ts        # Main exports
└── components/
    └── Equation.tsx # Unified React component

🌟 Examples

Complex Chemistry

import { Compound, Equation } from 'equamistry';

// Complex compounds with states
const hydrate = Compound.fromString('CuSO4.5H2O(s)');
console.log(hydrate.toHTML()); 
// → CuSO₄·5H₂O<sub>(s)</sub>

// Ionic equations with states
const precipitation = Equation.fromString('AgNO3(aq) + NaCl(aq) -> AgCl(s) + NaNO3(aq)');
console.log(precipitation.toHTML());
// → AgNO₃<sub>(aq)</sub> + NaCl<sub>(aq)</sub> → AgCl<sub>(s)</sub> + NaNO₃<sub>(aq)</sub>

// Complex ions with charges
const complexIon = Compound.fromString('[Fe(CN)6]{3-}');
console.log(complexIon.toHTML());
// → [Fe(CN)₆]³⁻

// Multiple charges and states
const ionicCompound = Compound.fromString('Ca{2+}(aq)');
console.log(ionicCompound.toHTML());
// → Ca²⁺<sub>(aq)</sub>

React Integration

import { EquationComponent as Equation } from 'equamistry';

function ChemistryLesson() {
  return (
    <div className="chemistry-content">
      <h2>Photosynthesis</h2>
      <Equation display="block" className="text-center">
        6CO2(g) + 6H2O(l) -> C6H12O6(aq) + 6O2(g)
      </Equation>
      
      <h2>Ionic Precipitation</h2>
      <Equation>
        AgNO3(aq) + NaCl(aq) -> AgCl(s) + NaNO3(aq)
      </Equation>
      
      <h2>Complex Ion Formation</h2>
      <Equation>
        Cu{2+}(aq) + 4NH3(aq) -> [Cu(NH3)4]{2+}(aq)
      </Equation>
      
      <h2>Hydrate Formation</h2>
      <Equation>
        CuSO4(s) + 5H2O(l) -> CuSO4.5H2O(s)
      </Equation>
    </div>
  );
}

✨ Recent Updates (v1.0.0)

🐛 Critical Fixes

• State Rendering: States now properly render as subscripts
• Charge Parsing: Fixed charge parsing with curly brace syntax
• Hydrate Coefficients: Proper coefficient placement in hydrates
• HTML Structure: Clean, semantic HTML output with proper CSS classes

🧪 Tested & Verified

• 223/223 tests passed: Comprehensive test coverage
• HTML Rendering: Verified correct subscripts, superscripts, and structure
• Production Ready: All parsing edge cases handled
• TypeScript: Full type safety with proper error handling

🎯 Syntax Clarifications

• Charges: Use {+}, {2-}, {3+} syntax
• States: Use parentheses (aq), (s), (l), (g) - rendered as subscripts
• Hydrates: Use regular dot . notation: CuSO4.5H2O
• Complex ions: Use square brackets with charges: [Fe(CN)6]{3-}

📄 License

MIT

👨‍💻 Author

Usama (themrsami)

• GitHub: @themrsami
• npm: ~themrsami

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🐛 Issues

Found a bug or have a feature request? Please open an issue on GitHub.