iapws-if97 2.2.0 → 2.8.0

package/dist/transport/properties.js

@@ -35,6 +35,7 @@ const MU1_H = [
  * Dynamic viscosity of water/steam [Pa·s]
  * @param T   Temperature [K]
  * @param rho Density [kg/m³]
+ * @throws {IF97Error} If the calculated viscosity is non-finite or non-positive.
  */
 export function viscosity(T, rho) {
     assertFiniteNumber('Temperature', T);
@@ -64,7 +65,10 @@ export function viscosity(T, rho) {
     // (within ~1 K and ~1 MPa). The original reference library also omits it.
     // Keeping μ₂ = 1 (no enhancement) for practical use.
     const mu2 = 1;
-    return mu0 * mu1 * mu2 / 1e6; // Convert μPa·s to Pa·s
+    const mu = mu0 * mu1 * mu2 / 1e6; // Convert μPa·s to Pa·s
+    assertFiniteNumber('Dynamic viscosity', mu);
+    assertPositiveNumber('Dynamic viscosity', mu);
+    return mu;
 }
 // ─── Thermal Conductivity (IAPWS 2011) ──────────────────────────────────────
 const K0_L = [2.443221e-3, 1.323095e-2, 6.770357e-3, -3.454586e-3, 4.096266e-4];
@@ -92,7 +96,7 @@ const DRHO_REF_COEFFS = [
  *
  * @param T   Temperature [K]
  * @param rho Density [kg/m³]
- * @param cp  Isobaric heat capacity [kJ/(kg·K)] (optional)
+ * @param cp  Positive isobaric heat capacity [kJ/(kg·K)] (optional)
  * @param cv  Isochoric heat capacity [kJ/(kg·K)] (optional)
  * @param drhodP_T  Isothermal density derivative ∂ρ/∂P|_T [kg/m³/MPa] (optional)
  * @param mu  Dynamic viscosity [Pa·s] (optional)
@@ -102,8 +106,10 @@ export function thermalConductivity(T, rho, cp, cv, drhodP_T, mu) {
     assertFiniteNumber('Density', rho);
     assertPositiveNumber('Temperature', T);
     assertNonNegativeNumber('Density', rho);
-    if (cp !== undefined)
+    if (cp !== undefined) {
         assertFiniteNumber('Isobaric heat capacity', cp);
+        assertPositiveNumber('Isobaric heat capacity', cp);
+    }
     if (cv !== undefined) {
         assertFiniteNumber('Isochoric heat capacity', cv);
         assertPositiveNumber('Isochoric heat capacity', cv);
@@ -198,14 +204,18 @@ const DC_Ih = [1, 1, 1, 2, 3, 3, 4, 5, 6, 7, 10];
 const DC_Jh = [0.25, 1, 2.5, 1.5, 1.5, 2.5, 2, 2, 5, 0.5, 10];
 /**
  * Static dielectric constant [dimensionless]
- * @param T   Temperature [K]
+ * @param T   Temperature [K], must be greater than 228 K
  * @param rho Density [kg/m³]
+ * @throws {IF97Error} If T is at or below the equation's 228 K singularity.
  */
 export function dielectricConstant(T, rho) {
     assertFiniteNumber('Temperature', T);
     assertFiniteNumber('Density', rho);
     assertPositiveNumber('Temperature', T);
     assertNonNegativeNumber('Density', rho);
+    if (T <= 228) {
+        throw new IF97Error('Temperature must be greater than 228 K for the dielectric constant');
+    }
     const MW = 0.018015268;
     const rhoM = rho / MW;
     const rhoRc = rhoM / (RHOc / MW);

package/dist/types.d.ts

@@ -46,6 +46,8 @@ export interface SteamState {
     speedOfSound: number | null;
     /** Vapour quality (0–1), only defined on accepted Region 4 saturation states */
     quality: number | null;
+    /** Saturation phases without transport properties, only present for Region 4. */
+    saturation?: SaturationEndpoints;
     /** Dynamic viscosity [Pa·s], null for two-phase mixtures */
     viscosity: number | null;
     /** Thermal conductivity [W/(m·K)], null for two-phase mixtures */
@@ -79,6 +81,14 @@ export interface BasicProperties {
     quality: number | null;
     isobaricExpansion: number | null;
     isothermalCompressibility: number | null;
+    saturation?: SaturationEndpoints;
+}
+/** Saturated liquid/vapor EOS states without nested saturation metadata. */
+export interface SaturationEndpoints {
+    pressure: number;
+    temperature: number;
+    liquid: Omit<BasicProperties, 'saturation'>;
+    vapor: Omit<BasicProperties, 'saturation'>;
 }
 /** Supported thermodynamic input combinations */
 export type InputMode = 'PT' | 'PH' | 'PS' | 'HS' | 'Px' | 'Tx' | 'TH' | 'TS';
@@ -137,6 +147,14 @@ export type CoefficientTable = readonly (readonly [number, number, number])[];
 export declare class IF97Error extends Error {
     constructor(message: string);
 }
+/** Thrown when TH or TS inputs identify multiple physical states. */
+export declare class AmbiguousStateError extends IF97Error {
+    /** Validated basic states in ascending pressure order; order does not imply preference. */
+    readonly candidates: readonly BasicProperties[];
+    constructor(T: number, value: number, property?: 'enthalpy' | 'entropy', 
+    /** Validated basic states in ascending pressure order; order does not imply preference. */
+    candidates?: readonly BasicProperties[]);
+}
 /** Thrown when input values are outside IAPWS-IF97 valid ranges */
 export declare class OutOfRangeError extends IF97Error {
     readonly parameter: string;

package/dist/types.js

@@ -27,6 +27,20 @@ export class IF97Error extends Error {
         this.name = 'IF97Error';
     }
 }
+/** Thrown when TH or TS inputs identify multiple physical states. */
+export class AmbiguousStateError extends IF97Error {
+    candidates;
+    constructor(T, value, property = 'enthalpy', 
+    /** Validated basic states in ascending pressure order; order does not imply preference. */
+    candidates = []) {
+        const symbol = property === 'enthalpy' ? 'h' : 's';
+        const unit = property === 'enthalpy' ? 'kJ/kg' : 'kJ/(kg·K)';
+        const pressureMode = property === 'enthalpy' ? 'PH' : 'PS';
+        super(`Ambiguous T-${symbol} state for T=${T} K, ${symbol}=${value} ${unit}: multiple physical states exist; supply an independent state constraint, for example using PT, ${pressureMode}, or Tx`);
+        this.candidates = candidates;
+        this.name = 'AmbiguousStateError';
+    }
+}
 /** Thrown when input values are outside IAPWS-IF97 valid ranges */
 export class OutOfRangeError extends IF97Error {
     parameter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iapws-if97",
-  "version": "2.2.0",
+  "version": "2.8.0",
   "description": "TypeScript implementation of IAPWS-IF97 for water and steam properties, including forward/backward solvers, saturation states, and transport properties.",
   "author": "jltonghui",
   "repository": {
@@ -64,15 +64,15 @@
   "scripts": {
     "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "tsc",
+    "typecheck": "tsc -p tsconfig.test.json",
     "test": "vitest run",
-    "test:package": "npm run build && node scripts/check-package.mjs",
+    "test:package": "npm run build && node --test scripts/check-package.test.mjs",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:standards": "vitest run tests/standards-asme tests/standards-cn",
     "test:standards:asme": "vitest run tests/standards-asme",
     "test:standards:cn": "vitest run tests/standards-cn",
-    "prepack": "npm run test:package && npm test",
-    "prepublishOnly": "npm run build && npm test"
+    "prepack": "npm run typecheck && npm run test:package && npm run test:coverage"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.0",

package/dist/core/public-normalization.d.ts

@@ -1,3 +0,0 @@
-import type { BasicProperties, SteamState } from '../types.js';
-export declare function normalizePublicState(state: SteamState): SteamState;
-export declare function normalizePublicState(state: BasicProperties): BasicProperties;

package/dist/core/public-normalization.js

@@ -1,53 +0,0 @@
-// Only snap values that are effectively simple decimals plus machine-noise.
-const SIMPLE_DECIMAL_PLACES = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
-const SNAP_ULPS = 8;
-function snapSimpleDecimal(value) {
-    if (!Number.isFinite(value)) {
-        return value;
-    }
-    for (const decimals of SIMPLE_DECIMAL_PLACES) {
-        const factor = 10 ** decimals;
-        const candidate = Math.round(value * factor) / factor;
-        // Scale the acceptance window with magnitude so we only absorb
-        // binary floating-point residue, not meaningful engineering deltas.
-        const tolerance = SNAP_ULPS * Number.EPSILON * Math.max(1, Math.abs(value), Math.abs(candidate));
-        if (Math.abs(value - candidate) <= tolerance) {
-            return Object.is(candidate, -0) ? 0 : candidate;
-        }
-    }
-    return Object.is(value, -0) ? 0 : value;
-}
-function normalizeNullableNumber(value) {
-    return value === null ? null : snapSimpleDecimal(value);
-}
-function normalizeBasicProperties(state) {
-    return {
-        region: state.region,
-        pressure: snapSimpleDecimal(state.pressure),
-        temperature: snapSimpleDecimal(state.temperature),
-        specificVolume: snapSimpleDecimal(state.specificVolume),
-        internalEnergy: snapSimpleDecimal(state.internalEnergy),
-        entropy: snapSimpleDecimal(state.entropy),
-        enthalpy: snapSimpleDecimal(state.enthalpy),
-        cp: normalizeNullableNumber(state.cp),
-        cv: normalizeNullableNumber(state.cv),
-        speedOfSound: normalizeNullableNumber(state.speedOfSound),
-        quality: normalizeNullableNumber(state.quality),
-        isobaricExpansion: normalizeNullableNumber(state.isobaricExpansion),
-        isothermalCompressibility: normalizeNullableNumber(state.isothermalCompressibility),
-    };
-}
-function normalizeSteamState(state) {
-    return {
-        ...normalizeBasicProperties(state),
-        density: snapSimpleDecimal(state.density),
-        viscosity: normalizeNullableNumber(state.viscosity),
-        thermalConductivity: normalizeNullableNumber(state.thermalConductivity),
-        surfaceTension: normalizeNullableNumber(state.surfaceTension),
-        dielectricConstant: normalizeNullableNumber(state.dielectricConstant),
-        ionizationConstant: normalizeNullableNumber(state.ionizationConstant),
-    };
-}
-export function normalizePublicState(state) {
-    return 'density' in state ? normalizeSteamState(state) : normalizeBasicProperties(state);
-}