oxyd

Convert a chemical formula into its fully oxidised equivalent.

oxyd parses a chemical formula, maps each element to its common (highest) oxide, and returns the stoichiometrically balanced set of oxide products — the same products you would get from complete combustion.

Install

npm install oxyd

Usage

The package is ESM-only and exports oxidise as both the default and a named export, alongside the OXIDES lookup table.

import oxidise from 'oxyd';
// or: import { oxidise, OXIDES } from 'oxyd';

oxidise('CH4');      // 'CO2 + 2H2O'
oxidise('Fe');       // 'Fe2O3'
oxidise('C6H12O6');  // '6CO2 + 6H2O'
oxidise('Ca(OH)2');  // 'CaO + H2O'
oxidise('C2H5OH');  // '2CO2 + 3H2O'
oxidise('O2');       // 'O2' — already fully oxidised

More examples

| Input | Output | | --- | --- | | CH4 | CO2 + 2H2O | | S | SO3 | | Na | Na2O | | NH3 | N2O5 + 3H2O | | Fe3O4 | 3Fe2O3 | | KMnO4 | K2O + 2MnO2* |

* oxygen passes through as part of the oxides, so oxygen in the input is not listed separately.

API

oxidise(formula)

• formula — a chemical formula string. Multi-letter symbols, subscripts and nested parentheses are supported (Ca(OH)2, Fe3(SO4)2). Whitespace is ignored.
• Returns the oxidised equivalent as a string, with multiple products joined by +.

When oxide units would be fractional, all terms are scaled by the smallest factor that makes every coefficient an integer. For example, a single sodium atom formally yields half a unit of Na2O, so the result is scaled and reported as Na2O; likewise Fe reports Fe2O3. Ratios between products are always exact.

OXIDES

A map of element symbol to [oxideFormula, atomsPerUnit], for example H: ['H2O', 2]. To support additional elements, extend the exported object:

import { OXIDES } from 'oxyd';

OXIDES['Xe'] = ['XeO3', 1];
oxidise('Xe'); // 'XeO3'

Elements not present in the table throw an error rather than guessing an oxidation state.

Errors

oxidise throws on invalid input with a descriptive message:

| Problem | Example message | | --- | --- | | Non-string argument | formula must be a string | | Empty formula | formula must not be empty | | Unrecognised character | Unexpected character "c" in "ch4" | | Unbalanced brackets | Unbalanced "(" in "C(" | | Unsupported element | No known oxide for element "Xe" |

License

Not yet licensed. Add a LICENSE file before publishing.