@camstack/types 1.1.20 → 1.1.22

package/dist/units/convert.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Pure unit-conversion API over `UNIT_TABLE`. No dependencies, no side effects.
+ *
+ * Conversion is refused (throws `UnitConversionError`, or returns `undefined`
+ * from the `try*` variant) whenever a unit is unknown or the two units belong
+ * to different dimensions — cross-dimension conversion is deliberately
+ * impossible so a render override can never make the value and its unit label
+ * disagree.
+ *
+ * Callers pass units through `normalizeUnit` (`../device/source-info.ts`) BEFORE
+ * calling here — the table keys only canonical spellings.
+ */
+import { type UnitDimension } from './unit-table.js';
+/** Why a conversion could not be performed. */
+export type UnitConversionReason = 'unknown-from' | 'unknown-to' | 'cross-dimension';
+/** Thrown by `convertUnit` when a conversion is refused. Carries the offending
+ *  units + a machine-readable `reason` for callers that branch on the cause. */
+export declare class UnitConversionError extends Error {
+    readonly from: string;
+    readonly to: string;
+    readonly reason: UnitConversionReason;
+    constructor(from: string, to: string, reason: UnitConversionReason);
+}
+/** The dimension a unit belongs to, or `undefined` for an unknown unit. */
+export declare function unitDimension(unit: string): UnitDimension | undefined;
+/**
+ * Convert `value` from unit `from` to unit `to`. Identity when `from === to`.
+ * Throws `UnitConversionError` when either unit is unknown or the units belong
+ * to different dimensions.
+ */
+export declare function convertUnit(value: number, from: string, to: string): number;
+/**
+ * Graceful variant for the render path: returns the converted value, or
+ * `undefined` when the conversion is refused (unknown unit / cross-dimension).
+ * Never throws — a render caller falls back to the raw value + source unit.
+ */
+export declare function tryConvertUnit(value: number, from: string, to: string): number | undefined;
+/**
+ * Whether `value` can be converted between `from` and `to` (same dimension,
+ * both known). Cheap boolean probe for the UI's same-dimension unit picker and
+ * the resolver's convertibility branch — compute ONCE so a unit label and its
+ * value math can never disagree.
+ */
+export declare function canConvertUnit(from: string, to: string): boolean;
+/**
+ * Every known unit spelling in a dimension (table insertion order — canonical
+ * unit first). Powers the UI's same-dimension unit picker.
+ */
+export declare function unitsForDimension(dimension: UnitDimension): readonly string[];

package/dist/units/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pure unit-conversion module. Re-exported from the types barrel so both the
+ * render path and the future expression engine share one table.
+ */
+export { UNIT_TABLE } from './unit-table.js';
+export type { UnitDimension, UnitSpec, KnownUnit } from './unit-table.js';
+export { UnitConversionError, unitDimension, convertUnit, tryConvertUnit, canConvertUnit, unitsForDimension, } from './convert.js';
+export type { UnitConversionReason } from './convert.js';

package/dist/units/unit-table.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Unit-of-measurement conversion table — the single source of truth shared by
+ * the render path (`resolveSensorDisplay` in `@camstack/ui-library`) and the
+ * future Stage-X expression engine's `convert()` builtin.
+ *
+ * Every unit maps to a `UnitSpec` describing the LINEAR transform to its
+ * dimension's canonical unit:
+ *
+ *   canonical = value * factor + offset
+ *
+ * `offset` is non-zero ONLY for the temperature family (°F / K carry an
+ * additive term); every other dimension is a pure scale (`offset = 0`).
+ * Cross-dimension conversion is intentionally impossible: a lookup returns the
+ * unit's `dimension`, and `convertUnit` refuses any pair whose dimensions
+ * differ (see `convert.ts`).
+ *
+ * Keys are the CANONICAL spellings `normalizeUnit` (`../device/source-info.ts`)
+ * produces — callers pass a raw unit through `normalizeUnit` BEFORE lookup.
+ * Unknown spellings resolve to `undefined` and cause conversion to be refused
+ * (the render path falls back to the raw value + source unit — never silently
+ * wrong). Single-unit dimensions (illuminance, irradiance, percentage, …) exist
+ * so a same-unit identity conversion is well-defined while cross-family
+ * conversion stays refused.
+ */
+/** The physical dimensions CamStack surfaces across HA + Ecowitt + vendors. */
+export type UnitDimension = 'temperature' | 'pressure' | 'speed' | 'precipitation-rate' | 'length' | 'illuminance' | 'irradiance' | 'power' | 'apparent-power' | 'energy' | 'voltage' | 'current' | 'concentration-volume' | 'concentration-mass' | 'mass' | 'percentage';
+/**
+ * Linear conversion spec: `canonical = value * factor + offset`. Temperature is
+ * the ONLY family using a non-zero `offset`.
+ */
+export interface UnitSpec {
+    readonly dimension: UnitDimension;
+    readonly factor: number;
+    readonly offset: number;
+}
+/**
+ * Frozen unit → spec table. `•` in the doc marks each dimension's canonical
+ * unit (`factor: 1, offset: 0`). °F derives from `°C = (°F − 32) × 5/9` ⇒
+ * `factor = 5/9`, `offset = -160/9` (kept as exact expressions, not rounded
+ * decimals). K derives from `°C = K − 273.15`.
+ */
+export declare const UNIT_TABLE: {
+    readonly '\u00B0C': {
+        readonly dimension: "temperature";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly '\u00B0F': {
+        readonly dimension: "temperature";
+        readonly factor: number;
+        readonly offset: number;
+    };
+    readonly K: {
+        readonly dimension: "temperature";
+        readonly factor: 1;
+        readonly offset: -273.15;
+    };
+    readonly hPa: {
+        readonly dimension: "pressure";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly kPa: {
+        readonly dimension: "pressure";
+        readonly factor: 10;
+        readonly offset: 0;
+    };
+    readonly Pa: {
+        readonly dimension: "pressure";
+        readonly factor: 0.01;
+        readonly offset: 0;
+    };
+    readonly mbar: {
+        readonly dimension: "pressure";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly bar: {
+        readonly dimension: "pressure";
+        readonly factor: 1000;
+        readonly offset: 0;
+    };
+    readonly inHg: {
+        readonly dimension: "pressure";
+        readonly factor: 33.8639;
+        readonly offset: 0;
+    };
+    readonly mmHg: {
+        readonly dimension: "pressure";
+        readonly factor: 1.33322;
+        readonly offset: 0;
+    };
+    readonly psi: {
+        readonly dimension: "pressure";
+        readonly factor: 68.9476;
+        readonly offset: 0;
+    };
+    readonly 'm/s': {
+        readonly dimension: "speed";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly 'km/h': {
+        readonly dimension: "speed";
+        readonly factor: number;
+        readonly offset: 0;
+    };
+    readonly mph: {
+        readonly dimension: "speed";
+        readonly factor: 0.44704;
+        readonly offset: 0;
+    };
+    readonly kn: {
+        readonly dimension: "speed";
+        readonly factor: 0.514444;
+        readonly offset: 0;
+    };
+    readonly 'mm/h': {
+        readonly dimension: "precipitation-rate";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly 'in/h': {
+        readonly dimension: "precipitation-rate";
+        readonly factor: 25.4;
+        readonly offset: 0;
+    };
+    readonly m: {
+        readonly dimension: "length";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly mm: {
+        readonly dimension: "length";
+        readonly factor: 0.001;
+        readonly offset: 0;
+    };
+    readonly cm: {
+        readonly dimension: "length";
+        readonly factor: 0.01;
+        readonly offset: 0;
+    };
+    readonly km: {
+        readonly dimension: "length";
+        readonly factor: 1000;
+        readonly offset: 0;
+    };
+    readonly in: {
+        readonly dimension: "length";
+        readonly factor: 0.0254;
+        readonly offset: 0;
+    };
+    readonly ft: {
+        readonly dimension: "length";
+        readonly factor: 0.3048;
+        readonly offset: 0;
+    };
+    readonly mi: {
+        readonly dimension: "length";
+        readonly factor: 1609.344;
+        readonly offset: 0;
+    };
+    readonly lx: {
+        readonly dimension: "illuminance";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly 'W/m\u00B2': {
+        readonly dimension: "irradiance";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly W: {
+        readonly dimension: "power";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly kW: {
+        readonly dimension: "power";
+        readonly factor: 1000;
+        readonly offset: 0;
+    };
+    readonly VA: {
+        readonly dimension: "apparent-power";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly Wh: {
+        readonly dimension: "energy";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly kWh: {
+        readonly dimension: "energy";
+        readonly factor: 1000;
+        readonly offset: 0;
+    };
+    readonly MWh: {
+        readonly dimension: "energy";
+        readonly factor: 1000000;
+        readonly offset: 0;
+    };
+    readonly V: {
+        readonly dimension: "voltage";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly mV: {
+        readonly dimension: "voltage";
+        readonly factor: 0.001;
+        readonly offset: 0;
+    };
+    readonly A: {
+        readonly dimension: "current";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly mA: {
+        readonly dimension: "current";
+        readonly factor: 0.001;
+        readonly offset: 0;
+    };
+    readonly ppm: {
+        readonly dimension: "concentration-volume";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly ppb: {
+        readonly dimension: "concentration-volume";
+        readonly factor: 0.001;
+        readonly offset: 0;
+    };
+    readonly '\u00B5g/m\u00B3': {
+        readonly dimension: "concentration-mass";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly 'mg/m\u00B3': {
+        readonly dimension: "concentration-mass";
+        readonly factor: 1000;
+        readonly offset: 0;
+    };
+    readonly kg: {
+        readonly dimension: "mass";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+    readonly g: {
+        readonly dimension: "mass";
+        readonly factor: 0.001;
+        readonly offset: 0;
+    };
+    readonly lb: {
+        readonly dimension: "mass";
+        readonly factor: 0.453592;
+        readonly offset: 0;
+    };
+    readonly oz: {
+        readonly dimension: "mass";
+        readonly factor: 0.0283495;
+        readonly offset: 0;
+    };
+    readonly '%': {
+        readonly dimension: "percentage";
+        readonly factor: 1;
+        readonly offset: 0;
+    };
+};
+/** Union of every canonical unit key present in `UNIT_TABLE`. */
+export type KnownUnit = keyof typeof UNIT_TABLE;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.1.20",
+  "version": "1.1.22",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",