CREB-JS Documentation

Advanced Chemical Reaction Equation Balancer with PubChem Integration

🧪 What is CREB-JS?

CREB-JS is a comprehensive JavaScript library that revolutionizes chemical equation balancing and stoichiometric calculations. Built with modern TypeScript, it combines robust equation parsing algorithms with real-world chemical data from the PubChem database to provide accurate, validated chemical computations.

Whether you're a student learning chemistry, a researcher performing calculations, or a developer building chemical informatics applications, CREB-JS provides the tools you need with a simple, intuitive API.

🚀 Quick Start

Get started with CREB-JS in just a few lines of code:

// Install the package
npm install creb-js

// Basic equation balancing
import { ChemicalEquationBalancer } from 'creb-js';

const balancer = new ChemicalEquationBalancer();
const result = balancer.balance('H2 + O2 = H2O');
console.log(result); // "2 H2 + O2 = 2 H2O"

// Enhanced features with PubChem integration
import { Compound } from 'creb-pubchem-js';
import { EnhancedStoichiometry } from 'creb-js';

// Search for compounds
const aspirin = await Compound.fromName('aspirin');
console.log(aspirin.molecularFormula); // "C9H8O4"
console.log(aspirin.molecularWeight);  // 180.16

// Enhanced stoichiometry with real chemical data
const enhanced = new EnhancedStoichiometry();
const analysis = await enhanced.calculateWithPubChem('C6H12O6 + O2 = CO2 + H2O');

✨ Key Features

⚖️ Smart Equation Balancing

Advanced algorithms automatically balance even complex chemical equations with robust error handling and validation.

🧮 Stoichiometric Calculations

Calculate molar relationships, limiting reagents, theoretical yields, and percent yields with precision.

🔍 PubChem Integration

Access real chemical data including molecular weights, formulas, properties, and structural information.

🆚 Compound Comparison

Compare multiple compounds side-by-side with detailed property analysis and structural similarities.

✅ Data Validation

Cross-reference calculated results with PubChem data to ensure accuracy and catch potential errors.

🌐 Universal Compatibility

Works in browsers, Node.js, and modern frameworks with TypeScript support and multiple output formats.

🎯 Use Cases

Educational Tools: Interactive chemistry learning platforms and homework helpers
Research Applications: Laboratory calculations and chemical analysis workflows
Industrial Software: Chemical process optimization and quality control systems
Web Applications: Chemistry calculators and molecular property databases
Academic Research: Computational chemistry and cheminformatics projects

📚 Documentation Structure

This documentation is organized into several sections to help you get the most out of CREB-JS:

Getting Started: Installation, setup, and basic usage patterns
Balancing Equations: Comprehensive guide to equation balancing features
Stoichiometry: Advanced calculations and molar relationships
PubChem Integration: Accessing and using real chemical data
API Reference: Complete method documentation and parameters
Examples: Practical code samples and common patterns

🔗 Useful Links

📦 GitHub Repository

Source code, issues, and contributions

📋 NPM Package

Installation and version information

🔬 PubChem API

Official PubChem REST API documentation

🐛 Issue Tracker

Bug reports and feature requests

🚀 Getting Started

Complete setup guide and first steps with CREB-JS

📦 Installation

CREB-JS is distributed as npm packages. Choose the installation method that works best for your project:

Install Core Package

For basic equation balancing and stoichiometry calculations:

npm install creb-js

Add PubChem Integration (Optional)

For enhanced features with real chemical data:

npm install creb-pubchem-js

Browser Usage

For direct browser usage, include the UMD builds:

<script src="path/to/creb-js/dist/index.umd.js"></script>
<script src="path/to/pubchem-js/dist/index.umd.js"></script>

⚡ Quick Setup

Get up and running with CREB-JS in minutes:

// ES6 Modules (Node.js, modern bundlers)
import { ChemicalEquationBalancer, EnhancedStoichiometry } from 'creb-js';
import { Compound } from 'creb-pubchem-js';

// CommonJS (Node.js)
const { ChemicalEquationBalancer } = require('creb-js');
const { Compound } = require('creb-pubchem-js');

// Browser Global (UMD)
const balancer = new window.CREB.ChemicalEquationBalancer();
const compound = new window.PubChemJS.Compound();

🧪 Your First Equation

Let's balance your first chemical equation with the interactive demo below:

⚗️ Chemical Equation Balancer

Enter an unbalanced chemical equation and get the balanced version instantly.

Chemical equation Try examples: "H2 + O2 = H2O", "Fe + O2 = Fe2O3", "C3H8 + O2 = CO2 + H2O"

// This is what happens behind the scenes:
import { ChemicalEquationBalancer } from 'creb-js';

const balancer = new ChemicalEquationBalancer();
const equation = 'Al + CuSO4 = Al2(SO4)3 + Cu';
const result = balancer.balance(equation);

console.log(result); 
// Output: "2 Al + 3 CuSO4 = Al2(SO4)3 + 3 Cu"

🎓 Learning Path

Follow this recommended learning path to master CREB-JS:

1️⃣ Basic Balancing

Start with simple equation balancing to understand the core functionality and API.

→ Learn Balancing

2️⃣ Stoichiometry

Learn to calculate molar relationships, limiting reagents, and yields.

→ Learn Stoichiometry

3️⃣ PubChem Data

Enhance your calculations with real chemical data from PubChem.

→ Learn PubChem

4️⃣ Advanced Features

Explore compound comparison, validation, and enhanced calculations.

→ Advanced Features

🔧 Configuration

CREB-JS works out of the box with sensible defaults, but you can customize its behavior:

// Custom configuration example
const balancer = new ChemicalEquationBalancer({
    strictMode: true,        // Stricter parsing rules
    allowPartialBalancing: false,  // Require complete balancing
    maxIterations: 1000,     // Maximum balancing attempts
    timeout: 10000          // Timeout in milliseconds
});

// PubChem configuration
const compound = new Compound({
    apiKey: 'your-api-key',  // Optional API key for higher rate limits
    timeout: 15000,          // Request timeout
    retryAttempts: 3         // Number of retry attempts
});

❓ Need Help?

If you encounter any issues or have questions:

Check the API Documentation for detailed method information
Browse Code Examples for common usage patterns
Visit our GitHub Issues to report bugs or request features
Read the README for additional setup information

Balancing equations

Advanced equation balancing features

CREB-JS uses matrix algebra to solve systems of linear equations, ensuring accurate balancing of even complex chemical equations.

⚖️ Advanced Equation Balancing

Try complex equations with multiple reactants and products:

Complex equation

How it works

The balancing algorithm:

Parses the chemical equation to extract reactants and products
Creates a matrix of element coefficients
Solves the system using Gaussian elimination
Returns the smallest integer coefficients

Stoichiometry

Calculate molar relationships and conversions

Perform stoichiometric calculations to determine the quantities of reactants and products in chemical reactions.

📊 Stoichiometric Calculator

Calculate molar relationships from a balanced equation:

Balanced equation

Species

Amount (moles)

⚖️ Molar Weight Calculator

Calculate the molar weight of any chemical formula:

Chemical formula

Compound search

Search PubChem database for chemical compounds

CREB-JS integrates with the PubChem database to provide access to millions of chemical compounds and their properties.

🔍 Search by PubChem CID

Enter a PubChem Compound ID to retrieve detailed compound information:

PubChem CID

// Example: Search aspirin by CID
const compound = await PubChemJS.Compound.fromCid(2244);
console.log(compound.molecularFormula); // "C9H8O4"

🧪 Formula Search

Search for compounds by molecular formula using PubChem's comprehensive database

🔍 Search by Molecular Formula

Enter a molecular formula to find all compounds with that exact formula. This is useful for finding isomers and exploring chemical diversity.

Formula Search Demo

Molecular Formula:

💡 Common Formula Examples

Try these common molecular formulas to explore different types of compounds:

H₂O

Water and related compounds

C₆H₁₂O₆

Glucose and sugar isomers

C₉H₈O₄

Aspirin and related compounds

C₈H₁₀N₄O₂

Caffeine and similar stimulants

C₂H₆O

Ethanol and ether isomers

CH₄

Methane and simple hydrocarbons

📊 Formula Search Features

🔍 Comprehensive Search

Search PubChem's database of millions of compounds by exact molecular formula match.

⚡ Fast Results

Optimized search returns up to 100 results quickly, perfect for exploring chemical space.

🧬 Isomer Discovery

Find all structural isomers that share the same molecular formula but different arrangements.

📈 Rich Data

Each result includes CID, molecular weight, IUPAC names, and other chemical properties.

💻 Formula Search API

Use formula search in your applications with these simple methods:

// Get all compounds with a specific formula
const compounds = await Compound.fromFormula('C6H12O6');
console.log(`Found ${compounds.length} compounds with formula C6H12O6`);

// Get just the first/most relevant compound
const glucose = await Compound.getByFormula('C6H12O6');
if (glucose) {
    console.log(`Primary compound: ${glucose.iupacName}`);
    console.log(`CID: ${glucose.cid}, MW: ${glucose.molecularWeight}`);
}

// Explore isomers
const ethanolIsomers = await Compound.fromFormula('C2H6O');
ethanolIsomers.forEach((compound, index) => {
    console.log(`Isomer ${index + 1}: CID ${compound.cid}`);
    console.log(`  Name: ${compound.iupacName}`);
    console.log(`  Weight: ${compound.molecularWeight} g/mol`);
});

🧪 Enhanced Chemical Intelligence

Advanced equation balancing with real-world compound data from PubChem

🌟 PubChem-Enhanced Balancing

Balance equations and get comprehensive compound information including molecular weights, IUPAC names, and validation from the authoritative PubChem database.

Enhanced Balancing Demo

Chemical Equation:

💡 Example Equations

Try these common chemical reactions to see enhanced balancing in action:

Acid-Base Neutralization

Sulfuric acid + Sodium hydroxide

Glucose Combustion

Cellular respiration reaction

Limestone Dissolution

Calcium carbonate + Hydrochloric acid

Iron Oxidation

Rust formation reaction

Ammonia Reaction

Ammonium chloride formation

Methane Combustion

Natural gas burning

📊 Enhanced Intelligence Features

🎯 Real Molecular Weights

Get precise molecular weights from PubChem instead of calculated approximations.

🏷️ IUPAC Names

See standardized chemical names alongside molecular formulas for better understanding.

✅ Mass Balance Validation

Automatic verification that mass is conserved using real molecular weight data.

🔍 Compound Validation

Verify that all compounds in your equation exist and are correctly identified.

💻 Enhanced Intelligence API

Access enhanced chemical intelligence in your applications:

import { EnhancedChemicalEquationBalancer } from 'creb-js';

const balancer = new EnhancedChemicalEquationBalancer();
const result = await balancer.balanceWithPubChemData("H2SO4 + NaOH = Na2SO4 + H2O");

console.log(result.coefficients);                    // [1, 2, 1, 2]
console.log(result.compoundData.H2SO4.iupacName);    // "sulfuric acid"
console.log(result.compoundData.H2SO4.molarWeight);  // 98.08 g/mol (from PubChem)
console.log(result.validation.massBalanced);         // true

🏷️ Compound Name Resolution

Balance equations using common chemical names instead of formulas

🌟 Balance by Common Names

Enter equations using everyday chemical names like "water", "sulfuric acid", or "sodium hydroxide". CREB-JS will automatically resolve these names to their chemical formulas using PubChem and then balance the equation.

Name Resolution Demo

Equation with Common Names:

💡 Common Name Examples

Try these equations using common chemical names:

Acid-Base Reaction

Using common acid/base names

Gas Absorption

HCl gas + ammonia reaction

Cellular Respiration

Using biochemical names

Natural Gas Combustion

Common fuel burning

Limestone Reaction

Geological chemistry

Alcohol Combustion

Ethyl alcohol burning

📊 Name Resolution Features

🧠 Intelligent Parsing

Automatically identifies and separates compound names from the equation structure.

🏷️ Name Standardization

Handles variations like "sulfuric acid" vs "sulphuric acid" automatically.

🔍 PubChem Resolution

Resolves names to chemical formulas using PubChem's comprehensive database.

🔗 Name Mapping

Maintains mapping between original names and resolved formulas for transparency.

💻 Name Resolution API

Use name resolution in your applications:

import { EnhancedChemicalEquationBalancer } from 'creb-js';

const balancer = new EnhancedChemicalEquationBalancer();
const result = await balancer.balanceByName(
  "sulfuric acid + sodium hydroxide = sodium sulfate + water"
);

console.log(result.equation); // "H2O4S + 2 HNaO = Na2O4S + 2 H2O"

// See how names were resolved
for (const [formula, info] of Object.entries(result.compoundData)) {
  if (info.originalName) {
    console.log(`"${info.originalName}" → ${formula}`);
  }
}

⚗️ Enhanced Stoichiometry

Precise stoichiometric calculations using real molecular weights from PubChem

🌟 PubChem-Powered Calculations

Perform stoichiometric calculations with unprecedented accuracy using real molecular weights from the PubChem database. Compare calculated vs. real molecular weights and get precision assessments.

Enhanced Stoichiometry Demo

Chemical Equation:

Given Species:

Amount (moles):

💡 Example Calculations

Try these stoichiometry problems with enhanced accuracy:

Silver Chloride Precipitation

0.171 mol NaCl → ? g AgCl

Glucose Respiration

1.0 mol glucose → ? g CO₂

Water Formation

2.0 mol H₂ → ? g H₂O

Limestone Dissolution

0.5 mol CaCO₃ → ? g CO₂

Iron Chloride Formation

1.5 mol Fe → ? g FeCl₃

Methane Combustion

0.75 mol CH₄ → ? g H₂O

📊 Enhanced Stoichiometry Features

🎯 Real Molecular Weights

Use precise molecular weights from PubChem instead of calculated approximations.

📊 Accuracy Analysis

Compare calculated vs. real molecular weights and assess precision levels.

✅ Mass Balance Validation

Verify conservation of mass using real molecular weight data.

🔍 Compound Validation

Ensure all compounds exist and are correctly identified before calculations.

💻 Enhanced Stoichiometry API

Perform enhanced calculations in your applications:

import { EnhancedStoichiometry } from 'creb-js';

const stoich = new EnhancedStoichiometry();
await stoich.initializeWithValidation("2 NaCl + AgNO3 = AgCl + 2 NaNO3");

const result = await stoich.calculateFromMolesEnhanced("NaCl", 0.171);

console.log(result.products.AgCl.grams);           // 24.51 g (PubChem accuracy)
console.log(result.pubchemMolarWeights.AgCl);      // 143.32 g/mol (real weight)
console.log(result.validation.warnings);           // Precision analysis

⚠️ Chemical Safety Information

Comprehensive safety warnings and hazard classifications for chemical reactions

🛡️ GHS Safety Integration

Get comprehensive safety information including GHS hazard classifications, signal words, and precautionary statements for all compounds in your chemical equations.

Safety Analysis Demo

Chemical Equation:

💡 Example Safety Analyses

See safety information for these common chemical reactions:

Strong Acid + Base

High hazard corrosive reaction

Acid + Ammonia

Respiratory and corrosion hazards

Glucose Combustion

Relatively safe organic reaction

Methane Combustion

Flammable gas hazards

Limestone + Acid

Acid handling precautions

Iron Oxidation

Minimal safety concerns

📊 Safety Information Features

🔴 GHS Classifications

Standard H-codes (H314, H290, etc.) for consistent hazard identification.

⚠️ Severity Levels

Color-coded warnings: 🔴 Extreme, 🟠 High, 🟡 Medium, 🟢 Low hazards.

🛡️ Precautionary Statements

Specific safety recommendations for handling each chemical.

📋 Signal Words

Standard "Danger" or "Warning" classifications per GHS guidelines.

🎨 Safety Color Code

🔴

Extreme Hazard

Fatal, severe burns, extreme toxicity

🟠

High Hazard

Serious injury, corrosive, harmful

🟡

Medium Hazard

Irritant, mild toxicity, caution required

🟢

Low Hazard

Minimal risk, general precautions

💻 Safety Information API

Integrate safety analysis into your applications:

import { EnhancedChemicalEquationBalancer } from 'creb-js';

const balancer = new EnhancedChemicalEquationBalancer();
const result = await balancer.balanceWithSafety("H2SO4 + NaOH = Na2SO4 + H2O");

result.safetyWarnings.forEach(warning => {
  console.log(`⚠️ ${warning.compound}: ${warning.hazard}`);
  console.log(`   Severity: ${warning.severity}`);
  console.log(`   GHS: ${warning.ghsClassification}`);
});

// Access detailed safety data
const h2so4Safety = result.compoundData.H2SO4.safetyInfo;
console.log(`Signal Word: ${h2so4Safety.signalWord}`); // "Danger"

Enhanced Chemical Equation Balancer with PubChem Validation

Chemical equation:

Enhanced Stoichiometry with PubChem Data

Chemical equation:

Species for calculation:

Amount (moles):

Compound Comparison

First compound (name or CID):

Second compound (name or CID):

});

ℹ️ About CREB-JS

Chemical Reaction Equation Balancer with Advanced Features

Project Overview

CREB-JS is a comprehensive chemical equation balancer and stoichiometry calculator, enhanced with real chemical data from the PubChem database. This project combines robust equation balancing algorithms with modern web technologies to provide an intuitive chemical computation toolkit.

⚗️

Equation Balancing

Advanced algorithms to balance complex chemical equations automatically with detailed error handling and validation.

🧮

Stoichiometry

Calculate molar relationships, convert between units, and perform comprehensive stoichiometric analysis.

🧬

PubChem Integration

Access real chemical data including molecular weights, formulas, SMILES, and comprehensive compound information.

🔍

Compound Search

Search compounds by name, CID, SMILES, or molecular formula with intelligent matching and suggestions.

📊

Analysis Tools

Compare compounds, analyze molecular properties, and perform enhanced stoichiometric calculations.

🌐

Modern Web Stack

Built with TypeScript, modern ES modules, comprehensive testing, and responsive design principles.

Technical Stack

Core: TypeScript, Rollup, Jest

Integration: PubChem REST API, Modern HTTP Client

Build: Multiple output formats (CJS, ESM, UMD)

Testing: Comprehensive unit and integration tests

📚 API Documentation

Complete reference for CREB-JS APIs and methods

🧪 ChemicalEquationBalancer

The core class for balancing chemical equations with advanced parsing and validation.

constructor(options?: BalancerOptions)

Description

Creates a new ChemicalEquationBalancer instance with optional configuration.

Parameters

options (optional) - Configuration object with the following properties:
• strictMode: boolean - Enable stricter parsing (default: false)
• maxIterations: number - Maximum balancing attempts (default: 100)
• timeout: number - Timeout in milliseconds (default: 5000)

Example

const balancer = new ChemicalEquationBalancer({
    strictMode: true,
    maxIterations: 200,
    timeout: 10000
});

balance(equation: string): string

Description

Balances a chemical equation and returns the balanced equation as a string.

Parameters

equation - The unbalanced chemical equation string

Returns

Balanced chemical equation string with coefficients

Example

const result = balancer.balance('H2 + O2 = H2O');
// Returns: "2 H2 + O2 = 2 H2O"

calculateStoichiometry(equation: string, compound: string, amount: number): StoichiometryResult

Description

Calculates stoichiometric relationships for a given compound and amount.

Parameters

equation - Balanced chemical equation
compound - Target compound formula
amount - Amount in moles

Returns

Object containing molar relationships for all compounds in the equation

Example

const stoich = balancer.calculateStoichiometry('2 H2 + O2 = 2 H2O', 'H2', 4);
// Returns molar amounts for all compounds based on 4 moles of H2

async balanceByName(equation: string): Promise<EnhancedBalanceResult> ✨ NEW!

Description

Balance chemical equations using compound names instead of formulas. Automatically resolves compound names to chemical formulas using PubChem database and provides enhanced results with compound information.

Parameters

equation - Chemical equation with compound names (e.g., "water + sodium = sodium hydroxide + hydrogen")

Returns

Promise resolving to enhanced balance result with compound data, safety information, and balance details

Example

const result = await balancer.balanceByName('water + sodium = sodium hydroxide + hydrogen');
console.log(result.balanced); // Balanced equation with formulas
console.log(result.compounds); // Array of compound objects with PubChem data

async balanceWithSafety(equation: string): Promise<SafetyEnhancedResult> ✨ NEW!

Description

Balance chemical equations and include comprehensive safety information for all compounds. Provides GHS hazard classifications, safety warnings, and handling recommendations.

Parameters

equation - Chemical equation string with compound formulas or names

Returns

Promise resolving to result with balanced equation, compound data, and detailed safety information

Example

const result = await balancer.balanceWithSafety('H2SO4 + NaOH = Na2SO4 + H2O');
console.log(result.balanced); // Balanced equation
console.log(result.safetyInfo); // Safety classifications and warnings
result.safetyInfo.hazards.forEach(h => console.log(h.statement));

🔬 Compound (PubChem Integration)

Access PubChem database for real chemical compound data and properties.

static async fromCid(cid: number): Promise<Compound>

Description

Retrieve a compound by its PubChem Compound ID (CID).

Parameters

cid - PubChem Compound ID (numeric)

Returns

Promise resolving to a single Compound instance

Example

const water = await Compound.fromCid(962);
const glucose = await Compound.fromCid(5793);

static async fromName(name: string): Promise<Compound[]>

Description

Search for compounds by common or IUPAC name. Returns array of all matching compounds.

Parameters

name - Common name, IUPAC name, or synonym of the compound

Returns

Promise resolving to array of Compound instances

Example

const aspirinResults = await Compound.fromName('aspirin');
const aspirin = aspirinResults[0]; // Get first result
console.log(`Found ${aspirinResults.length} compounds`);

static async getByName(name: string): Promise<Compound | null>

Description

Convenience method to get the first compound matching a name, or null if not found.

Parameters

name - Common name, IUPAC name, or synonym of the compound

Returns

Promise resolving to a single Compound instance or null

Example

const aspirin = await Compound.getByName('aspirin');
const caffeine = await Compound.getByName('caffeine');

static async fromSmiles(smiles: string): Promise<Compound[]>

Description

Search for compounds using SMILES notation. Returns array of all matching compounds.

Parameters

smiles - SMILES string representation of the molecule

Returns

Promise resolving to array of Compound instances

Example

const benzeneResults = await Compound.fromSmiles('c1ccccc1');
const ethanolResults = await Compound.fromSmiles('CCO');

static async getBySmiles(smiles: string): Promise<Compound | null>

Description

Convenience method to get the first compound matching a SMILES string.

Parameters

smiles - SMILES string representation of the molecule

Returns

Promise resolving to a single Compound instance or null

Example

const benzene = await Compound.getBySmiles('c1ccccc1');
const ethanol = await Compound.getBySmiles('CCO');

static async fromFormula(formula: string): Promise<Compound[]> ✨ NEW!

Description

Search for compounds by molecular formula. Returns array of all compounds with matching formula (up to 100 results).

Parameters

formula - Molecular formula (e.g., "H2O", "C6H12O6", "C9H8O4")

Returns

Promise resolving to array of Compound instances

Example

const waterCompounds = await Compound.fromFormula('H2O');
const glucoseIsomers = await Compound.fromFormula('C6H12O6');
console.log(`Found ${glucoseIsomers.length} compounds with formula C6H12O6`);

static async getByFormula(formula: string): Promise<Compound | null> ✨ NEW!

Description

Convenience method to get the first compound matching a molecular formula.

Parameters

formula - Molecular formula (e.g., "H2O", "C6H12O6", "C9H8O4")

Returns

Promise resolving to a single Compound instance or null

Example

const water = await Compound.getByFormula('H2O');
const glucose = await Compound.getByFormula('C6H12O6');
const aspirin = await Compound.getByFormula('C9H8O4');

📊 Compound Properties

Available properties on Compound instances retrieved from PubChem:

Basic Properties

cid - PubChem Compound ID
name - Primary compound name
molecularFormula - Chemical formula
molecularWeight - Molecular weight (g/mol)

Structural Data

smiles - SMILES notation
inchi - InChI identifier
inchiKey - InChI Key
iupacName - IUPAC systematic name

Physical Properties

meltingPoint - Melting point (°C)
boilingPoint - Boiling point (°C)
density - Density (g/cm³)
solubility - Water solubility

Chemical Properties

charge - Formal charge
complexity - Structural complexity
heavyAtomCount - Number of heavy atoms
synonyms - Array of name synonyms

⚗️ EnhancedStoichiometry

Advanced stoichiometric calculations with PubChem validation and enhanced features.

async calculateWithPubChem(equation: string): Promise<EnhancedResult>

Description

Performs equation balancing with PubChem validation and enhanced stoichiometric analysis.

Parameters

equation - Chemical equation to balance and analyze

Returns

Promise resolving to an object containing:

balancedEquation - The balanced equation
validation - PubChem validation results
compounds - Array of PubChem compound data
massBalance - Mass balance verification
stoichiometry - Detailed stoichiometric relationships

Example

const enhanced = new EnhancedStoichiometry();
const result = await enhanced.calculateWithPubChem('C6H12O6 + O2 = CO2 + H2O');

console.log(result.balancedEquation);    // Balanced equation
console.log(result.validation.isValid); // PubChem validation status
console.log(result.compounds);           // Compound data array

async calculateReagentQuantities(equation: string, targetCompound: string, desiredAmount: number, unit?: string): Promise<ReagentCalculationResult> ✨ NEW!

Description

Calculate required reagent quantities for a chemical reaction based on desired product amount. Includes molecular weight data from PubChem for accurate mass calculations.

Parameters

equation - Chemical equation string
targetCompound - Formula of the target product compound
desiredAmount - Desired amount of target compound
unit - Unit for calculations ('moles' or 'grams', default: 'moles')

Returns

Promise resolving to detailed reagent quantity calculations with molecular data

Example

const enhanced = new EnhancedStoichiometry();
const result = await enhanced.calculateReagentQuantities(
    'C6H12O6 + 6O2 = 6CO2 + 6H2O', 
    'CO2', 
    10, 
    'grams'
);
console.log(result.reagents); // Required amounts of all reagents

async getReactionEfficiency(equation: string, actualYields: Record<string, number>): Promise<EfficiencyAnalysis> ✨ NEW!

Description

Analyze reaction efficiency by comparing theoretical vs actual yields for products. Provides detailed efficiency metrics and identifies limiting reagents.

Parameters

equation - Balanced chemical equation
actualYields - Object mapping compound formulas to their actual yields

Returns

Promise resolving to comprehensive efficiency analysis with yield percentages and recommendations

Example

const enhanced = new EnhancedStoichiometry();
const efficiency = await enhanced.getReactionEfficiency(
    '2H2 + O2 = 2H2O',
    { 'H2O': 1.8 } // Actual yield: 1.8 moles of water
);
console.log(efficiency.yieldPercentage); // Efficiency percentage
console.log(efficiency.limitingReagent); // Identified limiting reagent

🔧 Error Handling

CREB-JS provides comprehensive error handling for robust applications:

try {
    const result = balancer.balance('invalid equation');
} catch (error) {
    if (error instanceof BalancingError) {
        console.log('Could not balance equation:', error.message);
    } else if (error instanceof ParseError) {
        console.log('Could not parse equation:', error.message);
    }
}

// Async error handling for PubChem operations
try {
    const compound = await Compound.fromName('nonexistent compound');
} catch (error) {
    if (error instanceof CompoundNotFoundError) {
        console.log('Compound not found in PubChem');
    } else if (error instanceof NetworkError) {
        console.log('Network error accessing PubChem');
    }
}

📖 Type Definitions

CREB-JS is fully typed with TypeScript. Key interfaces include:

interface StoichiometryResult {
    compound: string;
    coefficient: number;
    moles: number;
    mass: number;
    percentage: number;
}

interface BalancerOptions {
    strictMode?: boolean;
    maxIterations?: number;
    timeout?: number;
}

interface EnhancedResult {
    balancedEquation: string;
    validation: ValidationResult;
    compounds: CompoundData[];
    massBalance: MassBalanceResult;
    stoichiometry: StoichiometryResult[];
}

// Enhanced Features Types ✨ NEW!
interface EnhancedBalanceResult {
    balanced: string;
    compounds: CompoundInfo[];
    intelligence: ChemicalIntelligence;
    validation: ValidationResult;
}

interface SafetyEnhancedResult {
    balanced: string;
    compounds: CompoundInfo[];
    safetyInfo: SafetyInformation;
    validation: ValidationResult;
}

interface SafetyInformation {
    overallRisk: 'LOW' | 'MODERATE' | 'HIGH' | 'EXTREME';
    hazards: GHSHazard[];
    warnings: string[];
    recommendations: string[];
    personalProtection: string[];
}

interface GHSHazard {
    code: string;           // e.g., "H301"
    category: string;       // e.g., "Acute toxicity"
    statement: string;      // e.g., "Toxic if swallowed"
    severity: 'LOW' | 'MODERATE' | 'HIGH' | 'EXTREME';
}

interface ReagentCalculationResult {
    equation: string;
    target: CompoundInfo;
    reagents: Record<string, ReagentQuantity>;
    massBalance: MassBalanceData;
}

interface EfficiencyAnalysis {
    yieldPercentage: number;
    limitingReagent: string;
    theoreticalYields: Record<string, number>;
    actualYields: Record<string, number>;
    efficiency: Record<string, number>;
}

💡 Code Examples

Practical examples and real-world usage patterns

🔤 Basic Equation Balancing

Start with simple equation balancing for common chemical reactions:

import { ChemicalEquationBalancer } from 'creb-js';

const balancer = new ChemicalEquationBalancer();

// Simple synthesis reactions
console.log(balancer.balance('H2 + O2 = H2O'));
// Output: "2 H2 + O2 = 2 H2O"

console.log(balancer.balance('Fe + O2 = Fe2O3'));
// Output: "4 Fe + 3 O2 = 2 Fe2O3"

// Combustion reactions
console.log(balancer.balance('C3H8 + O2 = CO2 + H2O'));
// Output: "C3H8 + 5 O2 = 3 CO2 + 4 H2O"

console.log(balancer.balance('C6H12O6 + O2 = CO2 + H2O'));
// Output: "C6H12O6 + 6 O2 = 6 CO2 + 6 H2O"

🧮 Stoichiometric Calculations

Calculate molar relationships and quantities in chemical reactions:

// Calculate stoichiometry for a balanced equation
const equation = '2 H2 + O2 = 2 H2O';
const stoichResult = balancer.calculateStoichiometry(equation, 'H2', 4);

console.log(`Starting with 4 moles of H2:`);
console.log(`O2 needed: ${stoichResult.O2.moles} moles`);
console.log(`H2O produced: ${stoichResult.H2O.moles} moles`);

// Mass calculations
const massResult = balancer.calculateStoichiometry(equation, 'H2', 2, 'mass');
console.log(`H2 mass: ${massResult.H2.mass} g`);
console.log(`O2 mass needed: ${massResult.O2.mass} g`);
console.log(`H2O mass produced: ${massResult.H2O.mass} g`);

🔬 PubChem Integration

Access real chemical data from the PubChem database:

import { Compound } from 'creb-pubchem-js';

// Search compounds by different methods
async function searchExamples() {
    // By common name
    const aspirin = await Compound.fromName('aspirin');
    console.log(`Aspirin formula: ${aspirin.molecularFormula}`); // C9H8O4
    console.log(`Molecular weight: ${aspirin.molecularWeight}`); // 180.16
    
    // By PubChem CID
    const caffeine = await Compound.fromCID(2519);
    console.log(`Caffeine SMILES: ${caffeine.smiles}`);
    
    // By SMILES notation
    const ethanol = await Compound.fromSMILES('CCO');
    console.log(`Ethanol IUPAC: ${ethanol.iupacName}`);
    
    // Access various properties
    console.log(`Solubility: ${aspirin.solubility}`);
    console.log(`Melting point: ${aspirin.meltingPoint}°C`);
    console.log(`Synonyms: ${aspirin.synonyms.slice(0, 3).join(', ')}`);
}

⚗️ Enhanced Stoichiometry

Combine equation balancing with PubChem validation for accurate calculations:

import { EnhancedStoichiometry } from 'creb-js';

async function enhancedCalculations() {
    const enhanced = new EnhancedStoichiometry();
    
    // Enhanced equation balancing with validation
    const result = await enhanced.calculateWithPubChem(
        'C6H12O6 + O2 = CO2 + H2O'
    );
    
    console.log('Balanced equation:', result.balancedEquation);
    console.log('Validation status:', result.validation.isValid);
    console.log('Mass balance check:', result.massBalance.isBalanced);
    
    // Access compound data
    result.compounds.forEach(compound => {
        console.log(`${compound.formula}: ${compound.name}`);
        console.log(`  Molecular weight: ${compound.molecularWeight}`);
        console.log(`  PubChem CID: ${compound.cid}`);
    });
    
    // Detailed stoichiometric analysis
    console.log('Stoichiometric relationships:');
    result.stoichiometry.forEach(relation => {
        console.log(`  ${relation.compound}: ${relation.coefficient} moles`);
    });
}

🆚 Compound Comparison

Compare multiple compounds side-by-side for research and analysis:

async function compareCompounds() {
    // Compare pain relievers
    const compounds = await Promise.all([
        Compound.fromName('aspirin'),
        Compound.fromName('ibuprofen'),
        Compound.fromName('acetaminophen')
    ]);
    
    console.log('Pain Reliever Comparison:');
    console.log('========================');
    
    compounds.forEach(compound => {
        console.log(`\n${compound.name}:`);
        console.log(`  Formula: ${compound.molecularFormula}`);
        console.log(`  Weight: ${compound.molecularWeight} g/mol`);
        console.log(`  Complexity: ${compound.complexity}`);
        console.log(`  Heavy atoms: ${compound.heavyAtomCount}`);
    });
    
    // Find compound with highest/lowest molecular weight
    const heaviest = compounds.reduce((prev, current) => 
        prev.molecularWeight > current.molecularWeight ? prev : current
    );
    console.log(`\nHeaviest compound: ${heaviest.name} (${heaviest.molecularWeight} g/mol)`);
}

🔄 Batch Processing

Process multiple equations or compounds efficiently:

async function batchProcessing() {
    const balancer = new ChemicalEquationBalancer();
    
    // Batch equation balancing
    const equations = [
        'H2 + O2 = H2O',
        'CH4 + O2 = CO2 + H2O',
        'Fe + HCl = FeCl2 + H2',
        'CaCO3 = CaO + CO2'
    ];
    
    const balancedEquations = equations.map(eq => ({
        original: eq,
        balanced: balancer.balance(eq)
    }));
    
    console.log('Batch Balancing Results:');
    balancedEquations.forEach(result => {
        console.log(`${result.original} → ${result.balanced}`);
    });
    
    // Batch compound lookup
    const compoundNames = ['water', 'glucose', 'sodium chloride', 'caffeine'];
    const compoundData = await Promise.all(
        compoundNames.map(async name => {
            try {
                const compound = await Compound.fromName(name);
                return {
                    name: compound.name,
                    formula: compound.molecularFormula,
                    weight: compound.molecularWeight,
                    cid: compound.cid
                };
            } catch (error) {
                return { name, error: error.message };
            }
        })
    );
    
    console.log('\nBatch Compound Lookup:');
    compoundData.forEach(data => {
        if (data.error) {
            console.log(`${data.name}: Error - ${data.error}`);
        } else {
            console.log(`${data.name}: ${data.formula} (MW: ${data.weight}, CID: ${data.cid})`);
        }
    });
}

🛠️ Error Handling & Validation

Robust error handling for production applications:

import { BalancingError, ParseError, CompoundNotFoundError } from 'creb-js';

async function robustChemicalCalculations() {
    const balancer = new ChemicalEquationBalancer();
    
    // Safe equation balancing
    function safeBalance(equation) {
        try {
            const result = balancer.balance(equation);
            return { success: true, result };
        } catch (error) {
            if (error instanceof BalancingError) {
                return { success: false, error: 'Could not balance equation', details: error.message };
            } else if (error instanceof ParseError) {
                return { success: false, error: 'Invalid equation format', details: error.message };
            } else {
                return { success: false, error: 'Unexpected error', details: error.message };
            }
        }
    }
    
    // Safe compound lookup
    async function safeCompoundLookup(identifier, method = 'name') {
        try {
            let compound;
            switch (method) {
                case 'name':
                    compound = await Compound.fromName(identifier);
                    break;
                case 'cid':
                    compound = await Compound.fromCID(identifier);
                    break;
                case 'smiles':
                    compound = await Compound.fromSMILES(identifier);
                    break;
                default:
                    throw new Error('Invalid lookup method');
            }
            return { success: true, compound };
        } catch (error) {
            if (error instanceof CompoundNotFoundError) {
                return { success: false, error: 'Compound not found in PubChem' };
            } else {
                return { success: false, error: 'Lookup failed', details: error.message };
            }
        }
    }
    
    // Usage examples
    const balanceResult = safeBalance('H2 + O2 = H2O');
    if (balanceResult.success) {
        console.log('Balanced:', balanceResult.result);
    } else {
        console.error('Error:', balanceResult.error);
    }
    
    const compoundResult = await safeCompoundLookup('aspirin');
    if (compoundResult.success) {
        console.log('Found:', compoundResult.compound.name);
    } else {
        console.error('Error:', compoundResult.error);
    }
}

🌐 Browser Integration

Using CREB-JS in web applications with modern frameworks:

// React component example
import React, { useState, useEffect } from 'react';
import { ChemicalEquationBalancer } from 'creb-js';
import { Compound } from 'creb-pubchem-js';

function ChemicalCalculator() {
    const [equation, setEquation] = useState('');
    const [result, setResult] = useState('');
    const [balancer] = useState(() => new ChemicalEquationBalancer());
    
    const handleBalance = async () => {
        try {
            const balanced = balancer.balance(equation);
            setResult(balanced);
        } catch (error) {
            setResult(`Error: ${error.message}`);
        }
    };
    
    return (
        <div>
            <input 
                value={equation}
                onChange={(e) => setEquation(e.target.value)}
                placeholder="Enter chemical equation"
            />
            <button onClick={handleBalance}>Balance</button>
            <div>Result: {result}</div>
        </div>
    );
}

// Vue.js component example
export default {
    data() {
        return {
            compoundName: '',
            compoundData: null,
            loading: false
        };
    },
    methods: {
        async searchCompound() {
            this.loading = true;
            try {
                this.compoundData = await Compound.fromName(this.compoundName);
            } catch (error) {
                console.error('Search failed:', error);
                this.compoundData = null;
            } finally {
                this.loading = false;
            }
        }
    }
};

⚖️ Compound Comparison

Compare chemical compounds side by side

Compare Compounds

📖 User Guide

Complete guide to using CREB-JS effectively

Getting Started

CREB-JS provides comprehensive chemical equation balancing and analysis. Start with basic equation balancing and progress to advanced PubChem integration.

Install the package: npm install creb-js
Import the balancer: import { ChemicalEquationBalancer } from 'creb-js'
Create an instance and balance equations

Best Practices

Use standard chemical notation (H2O, CO2, etc.)
Include states when relevant (g), (l), (s), (aq)
Leverage PubChem integration for accurate molecular data
Cache compound data when performing multiple calculations

CREB-JS Documentation

🧪 What is CREB-JS?

🚀 Quick Start

✨ Key Features

⚖️ Smart Equation Balancing

🧮 Stoichiometric Calculations

🔍 PubChem Integration

🆚 Compound Comparison

✅ Data Validation

🌐 Universal Compatibility

🎯 Use Cases

📚 Documentation Structure

🔗 Useful Links

📦 GitHub Repository

📋 NPM Package

🔬 PubChem API

🐛 Issue Tracker

🚀 Getting Started

📦 Installation

Install Core Package

Add PubChem Integration (Optional)

Browser Usage

⚡ Quick Setup

🧪 Your First Equation

⚗️ Chemical Equation Balancer

🎓 Learning Path

1️⃣ Basic Balancing

2️⃣ Stoichiometry

3️⃣ PubChem Data

4️⃣ Advanced Features

🔧 Configuration

❓ Need Help?

Balancing equations

⚖️ Advanced Equation Balancing

How it works

Stoichiometry

📊 Stoichiometric Calculator

⚖️ Molar Weight Calculator

Compound search

🔍 Search by PubChem CID

📝 Search by Compound Name

🧪 Search by SMILES

🧪 Formula Search

🔍 Search by Molecular Formula

Formula Search Demo

💡 Common Formula Examples

H₂O

C₆H₁₂O₆

C₉H₈O₄

C₈H₁₀N₄O₂

C₂H₆O

CH₄

📊 Formula Search Features

🔍 Comprehensive Search

⚡ Fast Results

🧬 Isomer Discovery

📈 Rich Data

💻 Formula Search API

🧪 Enhanced Chemical Intelligence

🌟 PubChem-Enhanced Balancing

Enhanced Balancing Demo

💡 Example Equations

Acid-Base Neutralization

Glucose Combustion

Limestone Dissolution

Iron Oxidation

Ammonia Reaction

Methane Combustion

📊 Enhanced Intelligence Features

🎯 Real Molecular Weights

🏷️ IUPAC Names

✅ Mass Balance Validation

🔍 Compound Validation

💻 Enhanced Intelligence API

🏷️ Compound Name Resolution

🌟 Balance by Common Names

Name Resolution Demo

💡 Common Name Examples

Acid-Base Reaction

Gas Absorption