iforge-edp-values

Structured engineering values for AEC/industrial applications. Type-safe unit conversion, internal SI normalization, and UI-friendly formatting — built on Math.js.

Live demo · Specification · Changelog

Features

• 12 engineering quantities: length, area, volume, angle, temperature, mass, force, pressure, time, ratio, bool, and count
• Automatic SI normalization: every value converts to a stable internal unit (meters, radians, pascals…) regardless of input unit
• Precision gating: display precision is automatically capped by the domain's internal resolution (e.g. millimeter values never show more than 1 decimal place)
• Fractional inch I/O: full imperial support following ANSI/ASME Y14.5 — parse "1 1/4", format 2.375 → "2 3/8", with four precision tiers (construction, precision, machining, fine)
• BIM/AEC output presets: curated presets for millimeter modeling, meter annotations, square-meter schedules, kilonewton structural loads, kilopascal HVAC, and more
• Zero-dependency browser usage: works in the browser via import maps — no CDN, no bundler
• Pure ESM (.mjs), tree-shakeable, no TypeScript

Install

npm install @dricosr/iforge-edp-values

Usage

import { createValue, tryCreateValue, formatDisplayValue, formatEditValue } from "@dricosr/iforge-edp-values";

// Create a structured engineering value
const value = createValue({
  value: 2002,
  valueType: "number",
  quantity: "length",
  unit: "mm",
  output: { id: "beam-1", unit: "m", precision: 3 }
});

console.log(value.internal);
// { value: 2.002, unit: "m" }

console.log(formatDisplayValue(value));
// "2.002 m"

console.log(formatEditValue(value, { unit: "mm", precision: 4 }));
// "2002.0"

// Validate user input
const result = tryCreateValue({
  value: "10,5",
  valueType: "number",
  quantity: "length",
  unit: "mm"
});

console.log(result);
// { ok: false, value: null, error: ValueInputError { code: "invalid_numeric_value", ... } }

Fractional inches

import { createValue, FractionalInchOutput, UNIT_TOKENS } from "@dricosr/iforge-edp-values";

const pipe = createValue({
  value: "1 1/4",
  valueType: "number",
  quantity: "length",
  unit: UNIT_TOKENS.INCH,
  output: new FractionalInchOutput({ id: "nps-1-1-4", prefix: "⌀ " })
});

console.log(pipe.input.formatForDisplay());  // '⌀ 1 1/4"'
console.log(pipe.input.formatForEdit());     // "1 1/4"
console.log(pipe.internal);                  // { value: 0.03175, unit: "m" }

Output presets

import { OUTPUT_PRESETS, PARAMETER_SAMPLES, createValuePreview } from "@dricosr/iforge-edp-values";

// Explore available presets
console.log(OUTPUT_PRESETS["pressure:hvac-kilopascal"].name);
// "HVAC Pressure (kPa)"

// Preview a parameter with a preset
const preview = createValuePreview({
  parameter: PARAMETER_SAMPLES["length:beam-span"],
  output: { presetId: "length:annotation-meter" }
});

console.log(preview.previews.display);
// "7.200 m"

Supported quantities

| Quantity | Internal unit | Example inputs | | --- | --- | --- | | length | m | mm, cm, m, in, ft | | area | m^2 | mm^2, cm^2, m^2 | | volume | m^3 | mm^3, cm^3, m^3 | | angle | rad | deg, rad | | temperature | degC | degC, degF, K | | mass | kg | g, kg, lb | | force | N | N, kN, lbf | | pressure | Pa | Pa, kPa, bar, psi | | time | s | s, min, h | | ratio | — | dimensionless | | bool | — | true / false with configurable labels | | count | — | discrete integer counts (un) |

Value types: string, integer, float, boolean.

Documentation

• Specification — domain rules: quantities, internal units, resolution limits, display constraints
• API Reference — all public exports with descriptions
• Fractional Inch Guide — imperial piping, sheet metal, fasteners, and construction
• Browser Usage — import maps setup for zero-dependency browser loading

API Reference

Core functions

| Export | Description | | --- | --- | | createValue(options) | Parse input into a structured value with input and internal fields | | tryCreateValue(options) | Safe parse returning { ok, value, error } for UI validation | | createValuePreview(options) | Build a preview payload (display + edit) from a sample parameter and output preset | | formatDisplayValue(value, options?) | Human-readable string with unit and affixes | | formatEditValue(value, options?) | Plain number string for input fields, precision-capped | | convertValue({ value, fromUnit, toUnit }) | Raw unit conversion via Math.js |

Configuration classes

| Export | Description | | --- | --- | | Output | Output configuration: target unit, precision, prefix/suffix affixes | | CustomOutputAffix | User-defined prefix or suffix character sequence | | FractionalInchOutput | Drop-in Output replacement for fractional inch I/O | | FractionalInchParser | Parse "1 1/4" → 1.25 with validation | | FractionalInchFormatter | Format 1.25 → "1 1/4" with automatic reduction |

Presets and samples

| Export | Description | | --- | --- | | OUTPUT_PRESETS | Curated BIM/AEC output presets by quantity | | PARAMETER_SAMPLES | Realistic parameter samples grouped by quantity | | FRACTIONAL_INCH_DENOMINATORS | Precision tier constants: CONSTRUCTION, PRECISION, MACHINING, FINE |

Advanced (specialist classes)

For advanced composition, the package also exports: ValueFactory, UnitConverter, InternalResolutionApplier, DisplayPrecisionService, DisplayPrecisionResolver, DisplayValueFormatter, EditValueFormatter, QuantityProfileRegistry, and per-quantity profiles (LengthQuantityProfile, AreaQuantityProfile, …).

Fractional inch I/O

The library provides specialized handling for fractional inches — the imperial standard for pipe diameters (NPS), sheet metal thickness, fastener sizes, lumber dimensions, and construction measurements. Follows ANSI/ASME Y14.5 and ISO 129-1.

Precision tiers

| Tier | Max denominator | Use case | | --- | --- | --- | | CONSTRUCTION | 1/16 | Piping, lumber, framing, valve sizes | | PRECISION | 1/32 | Sheet metal, plate thickness | | MACHINING | 1/64 | Machining, tooling, general fabrication | | FINE | 1/128 | Tool & die, fine machining, metrology |

Validation rules

• Denominator must be a power of 2 (2, 4, 8, 16, 32, 64, 128)
• Fraction must be proper (numerator < denominator)
• Only one fraction per input; accepts space (1 1/4), hyphen (1-1/4), or decimal (1.25)

Real-world examples

| Domain | Input | Output | | --- | --- | --- | | NPS 2" pipe OD | 2.375 in | ⌀ 2 3/8" | | 16 ga sheet metal | 0.0625 in | 1/16" | | 1/4"-20 UNC fastener | 0.250 in | 1/4" | | 2×4 lumber (actual) | 1.5 in | 1 1/2" |

Browser usage

Works in the browser without a build step using import maps:

<script type="importmap">
{
  "imports": {
    "mathjs": "/mathjs/index.js",
    "@dricosr/iforge-edp-values": "/iforge-edp-values/index.mjs"
  }
}
</script>

<script type="module">
  import { createValue, formatDisplayValue } from "@dricosr/iforge-edp-values"
</script>

Requires serving mathjs/lib/esm and the library's src/ as static files from your Express server. See the specification for full setup details.

Build

git clone https://github.com/Dricosr/iforge-edp-values.git
cd iforge-edp-values
npm install
npm run build       # ESM + CJS + IIFE → dist/

Test

npm test                # all tests (Vitest)
npm run test:visual     # visual I/O tests only
npm run test:coverage   # with coverage report

Windows users: run Vitest from PowerShell or bash — cmd.exe has known incompatibilities with Vitest 4.x.

Design principles

• Calculations always use internal.value (SI); user input is preserved but never used for computation
• Unit preference belongs to the UI or project config — not stored in the value
• Display precision is always capped by the quantity's internal resolution
• Small specialist classes with single responsibilities; shared constants in dedicated catalogs
• Quantity-specific behavior lives in specialist profiles, not generic conditionals

Contributing

Contributions are welcome — bug reports, documentation improvements, new quantity profiles, and code changes. See CONTRIBUTING.md for setup instructions and guidelines.

This project follows a Code of Conduct. By participating you agree to abide by its terms.

License

MIT — © 2026 Adriano Ribeiro