@classytic/stage 0.3.0 → 0.4.0

package/dist/electro/couples.d.mts

@@ -0,0 +1,114 @@
+//#region src/electro/couples.d.ts
+/**
+ * Standard electrode potentials: the measured half of electrochemistry.
+ *
+ * ## One convention, stated once, and never a second table
+ *
+ * Every value here is a standard REDUCTION potential, written for the half-reaction running as
+ *
+ *     Ox + n e⁻ → Red        E° in volts, against the standard hydrogen electrode at 298.15 K
+ *
+ * That is the IUPAC convention and it is the only one stored. Oxidation potentials are the same
+ * numbers with the sign flipped, so {@link oxidationPotential} computes them rather than a second
+ * table repeating them. That matters more than it sounds: a table of oxidation potentials beside a
+ * table of reduction potentials is the single commonest source of sign errors in this topic, and
+ * two tables can disagree while one cannot.
+ *
+ * Textbooks write the same cell either way. "E°cell = E°anode(ox) + E°cathode(red)" and
+ * "E°cell = E°cathode(red) − E°anode(red)" are the same statement, because E°ox = −E°red. Both
+ * routes are reachable from what is here, and neither needs its own data.
+ *
+ * ## Why a couple is not a metal
+ *
+ * The obvious shape for this data is a list of metals, and it is wrong. Iron has two couples in
+ * ordinary use, Fe²⁺/Fe at −0.44 V and Fe³⁺/Fe²⁺ at +0.77 V, and they sit at opposite ends of the
+ * series: one of the most readily oxidised metals and a respectable oxidising agent. The same is
+ * true of copper, tin and manganese. Keying on the element would make those unreachable or, worse,
+ * silently pick one.
+ *
+ * So the record is the COUPLE, and a half-reaction it can write out.
+ *
+ * ## Provenance
+ *
+ * Aqueous standard reduction potentials at 298.15 K, unit activity, from the CRC Handbook's
+ * electrochemical series. Values are quoted to the two decimals that data booklets use, because
+ * that is the precision a learner is asked to work to and quoting more would imply an agreement
+ * between sources that does not exist at the third decimal.
+ *
+ * Pure: no React, no pixels.
+ */
+/** Which electrode a half-cell ends up as in a given cell. */
+type Role = 'cathode' | 'anode';
+interface Couple {
+  /** Stable key, e.g. `Zn2+/Zn`. */
+  readonly id: string;
+  /**
+   * The BALANCED reduction half-equation, written out.
+   *
+   * Stored rather than assembled, because assembling it needs stoichiometry this record does not
+   * carry. A template of `oxidised + ne⁻ → reduced` is right only for a metal and its own ion, and
+   * it was quietly wrong for most of this table: it produced `Cl₂ + 2e⁻ → Cl⁻`, missing the 2 on
+   * the chloride, and `OH⁻ → O₂ + 4e⁻` with no water in it at all. Both look like half-equations
+   * and neither balances.
+   *
+   * A rendered lab caught it, because a wrong equation printed under a beaker is still a
+   * perfectly plausible-looking string.
+   */
+  readonly halfEquation: string;
+  /** The oxidised form, as written in the half-equation. */
+  readonly oxidised: string;
+  /** The reduced form. */
+  readonly reduced: string;
+  /** Electrons transferred in the half-reaction as written. */
+  readonly electrons: number;
+  /** Standard REDUCTION potential, volts against the standard hydrogen electrode. */
+  readonly standardPotential: number;
+  /**
+   * Species whose concentration enters the reaction quotient, with the power it is raised to.
+   *
+   * Positive powers for the oxidised side, negative for the reduced side, and solids and the
+   * solvent omitted entirely. A solid has unit activity, so including copper metal in Q as though
+   * it had a concentration is exactly the error that makes a learner's Nernst answer drift.
+   */
+  readonly quotient: Readonly<Record<string, number>>;
+  /** True where the electrode is inert and only carries electrons (platinum, graphite). */
+  readonly inertElectrode?: boolean;
+}
+/**
+ * The electrochemical series, most negative first.
+ *
+ * Ordering is by potential rather than by insertion, so "more readily oxidised" is a position in
+ * this array and never a separate claim that could drift out of step with the numbers.
+ */
+declare const COUPLES: readonly Couple[];
+/** A couple by id, case-insensitively. Undefined rather than a guess when it is not in the series. */
+declare const coupleById: (id: string) => Couple | undefined;
+/**
+ * The standard OXIDATION potential, which is the reduction potential with its sign reversed.
+ *
+ * Computed rather than stored. See the note at the top of this file on why a second table would be
+ * a liability rather than a convenience.
+ */
+declare const oxidationPotential: (couple: Couple) => number;
+/** The balanced half-equation as written for reduction, e.g. `Cu²⁺ + 2e⁻ → Cu`. */
+declare const reductionEquation: (couple: Couple) => string;
+/**
+ * The same half-reaction run backwards, which is what happens at an anode.
+ *
+ * Derived from the reduction equation by swapping the sides and carrying the electrons across,
+ * rather than stored a second time. Two strings for one reaction could disagree; this cannot, and
+ * it keeps whatever stoichiometry and spectator water the reduction form already got right.
+ */
+declare function oxidationEquation(couple: Couple): string;
+/**
+ * Is the reduced form of `a` able to reduce the oxidised form of `b`?
+ *
+ * The whole predictive content of the series in one comparison: a couple lower in the table has
+ * the stronger reducing agent on its reduced side, so zinc metal reduces copper(II) and copper
+ * metal does not reduce zinc(II).
+ */
+declare const canReduce: (a: Couple, b: Couple) => boolean;
+/** The stronger oxidising agent of two oxidised forms, which is the one higher in the series. */
+declare const strongerOxidant: (a: Couple, b: Couple) => Couple;
+//#endregion
+export { COUPLES, Couple, Role, canReduce, coupleById, oxidationEquation, oxidationPotential, reductionEquation, strongerOxidant };

package/dist/electro/couples.mjs

@@ -0,0 +1,334 @@
+//#region src/electro/couples.ts
+/**
+* The electrochemical series, most negative first.
+*
+* Ordering is by potential rather than by insertion, so "more readily oxidised" is a position in
+* this array and never a separate claim that could drift out of step with the numbers.
+*/
+const COUPLES = [
+	{
+		id: "Li+/Li",
+		halfEquation: "Li⁺ + e⁻ → Li",
+		oxidised: "Li⁺",
+		reduced: "Li",
+		electrons: 1,
+		standardPotential: -3.04,
+		quotient: { "Li+": 1 }
+	},
+	{
+		id: "K+/K",
+		halfEquation: "K⁺ + e⁻ → K",
+		oxidised: "K⁺",
+		reduced: "K",
+		electrons: 1,
+		standardPotential: -2.93,
+		quotient: { "K+": 1 }
+	},
+	{
+		id: "Ca2+/Ca",
+		halfEquation: "Ca²⁺ + 2e⁻ → Ca",
+		oxidised: "Ca²⁺",
+		reduced: "Ca",
+		electrons: 2,
+		standardPotential: -2.87,
+		quotient: { "Ca2+": 1 }
+	},
+	{
+		id: "Na+/Na",
+		halfEquation: "Na⁺ + e⁻ → Na",
+		oxidised: "Na⁺",
+		reduced: "Na",
+		electrons: 1,
+		standardPotential: -2.71,
+		quotient: { "Na+": 1 }
+	},
+	{
+		id: "Mg2+/Mg",
+		halfEquation: "Mg²⁺ + 2e⁻ → Mg",
+		oxidised: "Mg²⁺",
+		reduced: "Mg",
+		electrons: 2,
+		standardPotential: -2.37,
+		quotient: { "Mg2+": 1 }
+	},
+	{
+		id: "Al3+/Al",
+		halfEquation: "Al³⁺ + 3e⁻ → Al",
+		oxidised: "Al³⁺",
+		reduced: "Al",
+		electrons: 3,
+		standardPotential: -1.66,
+		quotient: { "Al3+": 1 }
+	},
+	{
+		id: "Mn2+/Mn",
+		halfEquation: "Mn²⁺ + 2e⁻ → Mn",
+		oxidised: "Mn²⁺",
+		reduced: "Mn",
+		electrons: 2,
+		standardPotential: -1.18,
+		quotient: { "Mn2+": 1 }
+	},
+	{
+		id: "Zn2+/Zn",
+		halfEquation: "Zn²⁺ + 2e⁻ → Zn",
+		oxidised: "Zn²⁺",
+		reduced: "Zn",
+		electrons: 2,
+		standardPotential: -.76,
+		quotient: { "Zn2+": 1 }
+	},
+	{
+		id: "Cr3+/Cr",
+		halfEquation: "Cr³⁺ + 3e⁻ → Cr",
+		oxidised: "Cr³⁺",
+		reduced: "Cr",
+		electrons: 3,
+		standardPotential: -.74,
+		quotient: { "Cr3+": 1 }
+	},
+	{
+		id: "Fe2+/Fe",
+		halfEquation: "Fe²⁺ + 2e⁻ → Fe",
+		oxidised: "Fe²⁺",
+		reduced: "Fe",
+		electrons: 2,
+		standardPotential: -.44,
+		quotient: { "Fe2+": 1 }
+	},
+	{
+		id: "Cd2+/Cd",
+		halfEquation: "Cd²⁺ + 2e⁻ → Cd",
+		oxidised: "Cd²⁺",
+		reduced: "Cd",
+		electrons: 2,
+		standardPotential: -.4,
+		quotient: { "Cd2+": 1 }
+	},
+	{
+		id: "Co2+/Co",
+		halfEquation: "Co²⁺ + 2e⁻ → Co",
+		oxidised: "Co²⁺",
+		reduced: "Co",
+		electrons: 2,
+		standardPotential: -.28,
+		quotient: { "Co2+": 1 }
+	},
+	{
+		id: "Ni2+/Ni",
+		halfEquation: "Ni²⁺ + 2e⁻ → Ni",
+		oxidised: "Ni²⁺",
+		reduced: "Ni",
+		electrons: 2,
+		standardPotential: -.25,
+		quotient: { "Ni2+": 1 }
+	},
+	{
+		id: "Sn2+/Sn",
+		halfEquation: "Sn²⁺ + 2e⁻ → Sn",
+		oxidised: "Sn²⁺",
+		reduced: "Sn",
+		electrons: 2,
+		standardPotential: -.14,
+		quotient: { "Sn2+": 1 }
+	},
+	{
+		id: "Pb2+/Pb",
+		halfEquation: "Pb²⁺ + 2e⁻ → Pb",
+		oxidised: "Pb²⁺",
+		reduced: "Pb",
+		electrons: 2,
+		standardPotential: -.13,
+		quotient: { "Pb2+": 1 }
+	},
+	{
+		id: "H+/H2",
+		halfEquation: "2H⁺ + 2e⁻ → H₂",
+		oxidised: "H⁺",
+		reduced: "H₂",
+		electrons: 2,
+		standardPotential: 0,
+		quotient: {
+			"H+": 2,
+			H2: -1
+		},
+		inertElectrode: true
+	},
+	{
+		id: "Sn4+/Sn2+",
+		halfEquation: "Sn⁴⁺ + 2e⁻ → Sn²⁺",
+		oxidised: "Sn⁴⁺",
+		reduced: "Sn²⁺",
+		electrons: 2,
+		standardPotential: .15,
+		quotient: {
+			"Sn4+": 1,
+			"Sn2+": -1
+		},
+		inertElectrode: true
+	},
+	{
+		id: "Cu2+/Cu",
+		halfEquation: "Cu²⁺ + 2e⁻ → Cu",
+		oxidised: "Cu²⁺",
+		reduced: "Cu",
+		electrons: 2,
+		standardPotential: .34,
+		quotient: { "Cu2+": 1 }
+	},
+	{
+		id: "O2/OH-",
+		halfEquation: "O₂ + 2H₂O + 4e⁻ → 4OH⁻",
+		oxidised: "O₂",
+		reduced: "OH⁻",
+		electrons: 4,
+		standardPotential: .4,
+		quotient: {
+			O2: 1,
+			"OH-": -4
+		},
+		inertElectrode: true
+	},
+	{
+		id: "I2/I-",
+		halfEquation: "I₂ + 2e⁻ → 2I⁻",
+		oxidised: "I₂",
+		reduced: "I⁻",
+		electrons: 2,
+		standardPotential: .54,
+		quotient: { "I-": -2 },
+		inertElectrode: true
+	},
+	{
+		id: "Fe3+/Fe2+",
+		halfEquation: "Fe³⁺ + e⁻ → Fe²⁺",
+		oxidised: "Fe³⁺",
+		reduced: "Fe²⁺",
+		electrons: 1,
+		standardPotential: .77,
+		quotient: {
+			"Fe3+": 1,
+			"Fe2+": -1
+		},
+		inertElectrode: true
+	},
+	{
+		id: "Ag+/Ag",
+		halfEquation: "Ag⁺ + e⁻ → Ag",
+		oxidised: "Ag⁺",
+		reduced: "Ag",
+		electrons: 1,
+		standardPotential: .8,
+		quotient: { "Ag+": 1 }
+	},
+	{
+		id: "Br2/Br-",
+		halfEquation: "Br₂ + 2e⁻ → 2Br⁻",
+		oxidised: "Br₂",
+		reduced: "Br⁻",
+		electrons: 2,
+		standardPotential: 1.07,
+		quotient: { "Br-": -2 },
+		inertElectrode: true
+	},
+	{
+		id: "O2/H2O",
+		halfEquation: "O₂ + 4H⁺ + 4e⁻ → 2H₂O",
+		oxidised: "O₂",
+		reduced: "H₂O",
+		electrons: 4,
+		standardPotential: 1.23,
+		quotient: {
+			O2: 1,
+			"H+": 4
+		},
+		inertElectrode: true
+	},
+	{
+		id: "Cr2O7^2-/Cr3+",
+		halfEquation: "Cr₂O₇²⁻ + 14H⁺ + 6e⁻ → 2Cr³⁺ + 7H₂O",
+		oxidised: "Cr₂O₇²⁻",
+		reduced: "Cr³⁺",
+		electrons: 6,
+		standardPotential: 1.33,
+		quotient: {
+			"Cr2O7^2-": 1,
+			"H+": 14,
+			"Cr3+": -2
+		},
+		inertElectrode: true
+	},
+	{
+		id: "Cl2/Cl-",
+		halfEquation: "Cl₂ + 2e⁻ → 2Cl⁻",
+		oxidised: "Cl₂",
+		reduced: "Cl⁻",
+		electrons: 2,
+		standardPotential: 1.36,
+		quotient: { "Cl-": -2 },
+		inertElectrode: true
+	},
+	{
+		id: "MnO4-/Mn2+",
+		halfEquation: "MnO₄⁻ + 8H⁺ + 5e⁻ → Mn²⁺ + 4H₂O",
+		oxidised: "MnO₄⁻",
+		reduced: "Mn²⁺",
+		electrons: 5,
+		standardPotential: 1.51,
+		quotient: {
+			"MnO4-": 1,
+			"H+": 8,
+			"Mn2+": -1
+		},
+		inertElectrode: true
+	},
+	{
+		id: "F2/F-",
+		halfEquation: "F₂ + 2e⁻ → 2F⁻",
+		oxidised: "F₂",
+		reduced: "F⁻",
+		electrons: 2,
+		standardPotential: 2.87,
+		quotient: { "F-": -2 },
+		inertElectrode: true
+	}
+];
+const BY_ID = new Map(COUPLES.map((c) => [c.id.toLowerCase(), c]));
+/** A couple by id, case-insensitively. Undefined rather than a guess when it is not in the series. */
+const coupleById = (id) => BY_ID.get(id.toLowerCase());
+/**
+* The standard OXIDATION potential, which is the reduction potential with its sign reversed.
+*
+* Computed rather than stored. See the note at the top of this file on why a second table would be
+* a liability rather than a convenience.
+*/
+const oxidationPotential = (couple) => -couple.standardPotential;
+/** The balanced half-equation as written for reduction, e.g. `Cu²⁺ + 2e⁻ → Cu`. */
+const reductionEquation = (couple) => couple.halfEquation;
+/**
+* The same half-reaction run backwards, which is what happens at an anode.
+*
+* Derived from the reduction equation by swapping the sides and carrying the electrons across,
+* rather than stored a second time. Two strings for one reaction could disagree; this cannot, and
+* it keeps whatever stoichiometry and spectator water the reduction form already got right.
+*/
+function oxidationEquation(couple) {
+	const [left, right] = couple.halfEquation.split("→");
+	if (left === void 0 || right === void 0) return couple.halfEquation;
+	const electrons = couple.electrons === 1 ? "e⁻" : `${couple.electrons}e⁻`;
+	const withoutElectrons = left.split("+").map((part) => part.trim()).filter((part) => part !== electrons).join(" + ");
+	return `${right.trim()} → ${withoutElectrons} + ${electrons}`;
+}
+/**
+* Is the reduced form of `a` able to reduce the oxidised form of `b`?
+*
+* The whole predictive content of the series in one comparison: a couple lower in the table has
+* the stronger reducing agent on its reduced side, so zinc metal reduces copper(II) and copper
+* metal does not reduce zinc(II).
+*/
+const canReduce = (a, b) => a.standardPotential < b.standardPotential;
+/** The stronger oxidising agent of two oxidised forms, which is the one higher in the series. */
+const strongerOxidant = (a, b) => a.standardPotential >= b.standardPotential ? a : b;
+
+//#endregion
+export { COUPLES, canReduce, coupleById, oxidationEquation, oxidationPotential, reductionEquation, strongerOxidant };

package/dist/electro/electrolysis.d.mts

@@ -0,0 +1,96 @@
+//#region src/electro/electrolysis.d.ts
+/**
+ * Electrolysis: deciding what comes off each electrode, rather than remembering it.
+ *
+ * ## Why this is a decision and not a table
+ *
+ * The usual way this is taught is a table of electrolytes with their products written beside them,
+ * and it fails the first time a learner is asked about a solution that is not in the table. The
+ * worst case is the one most examined: CONCENTRATED sodium chloride gives chlorine at the anode
+ * and DILUTE sodium chloride gives oxygen, from the same two ions in the same solution. A table
+ * with one row for "NaCl(aq)" cannot express that, and a learner holding one will get it wrong.
+ *
+ * So nothing here stores a product. Three competitions are resolved:
+ *
+ *   1. At the cathode, which cation is reduced: the one lower in the reactivity series, meaning
+ *      the higher standard potential. Water, supplying H⁺, is always a candidate in solution, so a
+ *      metal more reactive than hydrogen never plates out of an aqueous solution.
+ *   2. At the anode, which anion is oxidised. Oxoanions such as sulfate and nitrate are never
+ *      discharged: their central atom is already fully oxidised, so OH⁻ from the water goes
+ *      instead and oxygen comes off. A halide competes with OH⁻ and wins when concentrated.
+ *   3. Whether the anode is inert at all. A copper anode in copper sulfate dissolves rather than
+ *      releasing oxygen, because oxidising the electrode itself is easier than oxidising anything
+ *      in the solution. That is not a special case to memorise, it is the same "easiest oxidation
+ *      wins" rule with one more candidate.
+ *
+ * ## Concentration, and being honest about a rule of thumb
+ *
+ * Whether chloride beats hydroxide is not decided by standard potentials: on those alone, OH⁻
+ * (+0.40 V) should always win over Cl⁻ (+1.36 V), and in concentrated brine it plainly does not.
+ * The real reasons are the overpotential for oxygen on most anode materials and the concentration
+ * term, and neither is examined at this level. The threshold used here is the teaching rule, and
+ * it is labelled as one rather than dressed up as a computed result.
+ *
+ * Pure: no React, no pixels.
+ */
+/** How the electrolyte is presented to the cell. */
+type Phase = 'molten' | 'aqueous';
+/** What the electrodes are made of. */
+type ElectrodeMaterial = 'inert' | 'copper' | 'silver' | 'nickel';
+interface Electrolyte {
+  readonly formula: string;
+  readonly cation: string;
+  readonly anion: string;
+  /** The couple that would reduce this cation. */
+  readonly cationCouple: string;
+  /** The couple that would oxidise this anion, or undefined for an oxoanion that never is. */
+  readonly anionCouple?: string;
+}
+/**
+ * The electrolytes a syllabus actually asks about.
+ *
+ * This IS a table, and it is a table of what is dissolved rather than of what comes out. The
+ * distinction is the whole point: composition is a fact about the beaker, products are a
+ * consequence to be worked out.
+ */
+declare const ELECTROLYTES: readonly Electrolyte[];
+declare const electrolyteByFormula: (formula: string) => Electrolyte | undefined;
+/**
+ * Above this concentration a halide is discharged in preference to hydroxide.
+ *
+ * A teaching threshold, not a measured boundary. See the note at the top of this file: the real
+ * crossover depends on the anode material's oxygen overpotential and moves with it. Half a mole
+ * per cubic decimetre sits between the "dilute" and "concentrated" of every question that asks.
+ */
+declare const HALIDE_DISCHARGE_THRESHOLD = 0.5;
+interface Discharge {
+  /** The species that reacts at this electrode. */
+  readonly species: string;
+  /** What comes off, or what happens to the electrode. */
+  readonly product: string;
+  /** The half-equation, written in the direction it runs. */
+  readonly equation: string;
+  /** Electrons per formula unit of product. */
+  readonly electrons: number;
+  /** Why this one and not the alternative. */
+  readonly because: string;
+  /** The alternative that lost, where there was one. */
+  readonly insteadOf?: string;
+}
+interface ElectrolysisConditions {
+  readonly electrolyte: Electrolyte;
+  readonly phase: Phase;
+  /** Concentration in mol/dm³. Ignored when molten. */
+  readonly concentration?: number;
+  readonly anodeMaterial?: ElectrodeMaterial;
+}
+interface ElectrolysisResult {
+  readonly cathode: Discharge;
+  readonly anode: Discharge;
+  /** What happens to the solution while it runs. */
+  readonly solution: string;
+}
+/** Run the three competitions and report what each electrode does. */
+declare function electrolyse(conditions: ElectrolysisConditions): ElectrolysisResult;
+//#endregion
+export { Discharge, ELECTROLYTES, ElectrodeMaterial, ElectrolysisConditions, ElectrolysisResult, Electrolyte, HALIDE_DISCHARGE_THRESHOLD, Phase, electrolyse, electrolyteByFormula };