Class Quantity<U>

Readonlyunit

Readonlyvalue

add

• add(other: Quantity<U>): Quantity<U>

  Parameters

  • other: Quantity<U>

  Returns Quantity<U>

equals

• equals(other: Quantity<U>): boolean

  Parameters

  • other: Quantity<U>

  Returns boolean

format

• format(): string

  Canonical format: "5 kg", "320 lux", "55.845 g/mol".

  Returns string

formatMml

• formatMml(_viewer?: unknown, scaleName?: string): Mml

  Instrument / analyze emission. Same wrapper, canonical text inside. The optional scaleName flows through to the <quantity tag="..."> attribute when a tag table is registered for the unit at that scale.

  Parameters

  • Optional_viewer: unknown
  • OptionalscaleName: string

  Returns Mml

greaterThan

• greaterThan(other: Quantity<U>): boolean

  Parameters

  • other: Quantity<U>

  Returns boolean

lessThan

• lessThan(other: Quantity<U>): boolean

  Parameters

  • other: Quantity<U>

  Returns boolean

rawValue

• rawValue(): number

  Returns number

scale

• scale(factor: number): Quantity<U>

  Parameters

  • factor: number

  Returns Quantity<U>

subtract

• subtract(other: Quantity<U>): Quantity<U>

  Parameters

  • other: Quantity<U>

  Returns Quantity<U>

tag

• tag(scaleName?: string): string

  Tag-table lookup. Returns the registered tag string when one is defined for the unit; otherwise falls back to the canonical format (so Quantity<g/mol>.tag() reads "55.845 g/mol", not "" or null).

  The optional scaleName selects which vocabulary to consult when the unit has multiple registered scales (e.g. 'color' vs 'thermal' for K). Without scaleName, falls back to the unit's default scale.

  Parameters

  • OptionalscaleName: string

  Returns string

to

• to(targetUnit: Unit): Quantity<Unit>

  Cross-unit conversion. Returns a Quantity<Unit> rather than a narrowly-typed Quantity<TargetUnit> because the target is a runtime parameter — callers that need narrow typing should call the unit-specific accessor on their host (e.g. light.intensity is statically Quantity<'lux'>).

  Parameters

  • targetUnit: Unit

  Returns Quantity<Unit>

toJSON

• toJSON(): { unit: U; value: number }

  Returns { unit: U; value: number }

toMml

• toMml(_viewer?: unknown, scaleName?: string): Mml

  Default-prose emission. Inner text is the tag (or canonical format for tagless units). Viewer parameter is forward-compat for the deferred pedagogical-seam setting. Optional scaleName picks the vocabulary when multiple scales are registered for the unit; default scale otherwise.

  Parameters

  • Optional_viewer: unknown
  • OptionalscaleName: string

  Returns Mml

Static_clearTagTable

• _clearTagTable(unit: Unit, scaleName?: string): void

  Drop a registered scale for unit. When scaleName is omitted, removes every scale registered for the unit. Used by QuantityApi's reload path to handle entries that disappeared from the YAML, and by tests to reset registry state.

  Parameters

  • unit: Unit
  • OptionalscaleName: string

  Returns void

Static_defaultScaleFor

• _defaultScaleFor(unit: Unit): string | null

  Inspect the registered default scale for a unit; null if unset.

  Parameters

  • unit: Unit

  Returns string | null

Static_registeredScales

• _registeredScales(): { scaleName: string; unit: Unit }[]

  Snapshot of the (unit, scaleName) pairs currently carrying a registered table. Used by QuantityApi.reloadTagTables to compute which scales to delete after a re-read.

  Returns { scaleName: string; unit: Unit }[]

StaticcompareTag

• compareTag(unit: Unit, a: string, b: string, scaleName?: string): number

  Compare two tags by their position in a (unit, scaleName)'s registered ordering. Returns a sign-only integer (negative when a precedes b, zero when equal, positive when a follows b) — same shape as Array.prototype.sort's comparator.

  Throws when no table is registered for the pair, or when either tag isn't present in the resolved table.

  Parameters

  • unit: Unit
  • a: string
  • b: string
  • OptionalscaleName: string

  Returns number

StaticfromJSON

• fromJSON<U extends Unit>(json: { unit: U; value: number }): Quantity<U>

  Reconstruct from the persistence shape produced by toJSON. Used by PropertiedMixin's hydrator and by callers passing { value, unit } plain objects through external boundaries.

  Type Parameters

  • U extends Unit

  Parameters

  • json: { unit: U; value: number }

  Returns Quantity<U>

StaticfromTag

• fromTag<U extends Unit>(tag: string, unit: U, scaleName?: string): Quantity<U>

  Tag-table reverse lookup. Resolves through the registered table to a canonical numeric value. The optional scaleName picks which vocabulary to consult when the unit has multiple registered scales (e.g. 'color' vs 'thermal' for K). Without scaleName, falls back to the unit's default scale.

  Throws for tags absent from the resolved table, or for unit / scale pairs with no registered table.

  Type Parameters

  • U extends Unit

  Parameters

  • tag: string
  • unit: U
  • OptionalscaleName: string

  Returns Quantity<U>

Staticof

• of<U extends Unit>(value: number, unit: U): Quantity<U>

  Primary factory. Validates a finite numeric and produces a Quantity<U> with the canonical-unit value.

  Type Parameters

  • U extends Unit

  Parameters

  • value: number
  • unit: U

  Returns Quantity<U>

Staticparse

• parse<U extends Unit>(
      input: string | number,
      targetUnit: U,
      scaleName?: string,
  ): Quantity<U>

  Authoring-friendly parse. Four input shapes:

  • tag: "heavy" → registered threshold for the target unit.
  • canonical literal: "12 kg" → Quantity<kg>(12).
  • alt-unit literal: "12000 g" (target kg) → Quantity<kg>(12).
  • bare number / bare-number string: 5 or "5" → canonical-unit interpretation. mass: 5 on a Quantity<kg> field is 5 kg, not 5 g.

  The optional scaleName selects which tag table to consult when the input is a tag string and the target unit has multiple scales registered.

  Throws on unrecognized tag, unparseable literal, or alt-unit with no registered converter to the target.

  Type Parameters

  • U extends Unit

  Parameters

  • input: string | number
  • targetUnit: U
  • OptionalscaleName: string

  Returns Quantity<U>

StaticregisterTagTable

• registerTagTable(
      unit: Unit,
      scaleName: string,
      entries: readonly TagTableEntry[],
  ): void

  Register a tag table for (unit, scaleName). Replaces any prior table at that pair. First scale registered for a unit becomes that unit's default scale (the one tag() / parse() / fromTag() consult when no scale name is given); setDefaultScale overrides explicitly.

  scaleName defaults to DEFAULT_SCALE ('default') for single-vocabulary units like kg or lux. Units with multiple vocabularies (K's color vs thermal) register each scale by an explicit name.

  Parameters

  • unit: Unit
  • scaleName: string
  • entries: readonly TagTableEntry[]

  Returns void

StaticsetDefaultScale

• setDefaultScale(unit: Unit, scaleName: string): void

  Pick which scale tag() / parse() / fromTag() consult for unit when no scaleName is passed. Throws if the scale isn't registered for that unit.

  Parameters

  • unit: Unit
  • scaleName: string

  Returns void

StaticshiftTag

• shiftTag(unit: Unit, tag: string, shift: number, scaleName?: string): string

  Shift a tag by integer band offset within its registered (unit, scaleName) ordering. Clamps to the [first, last] band range; non-finite shifts are treated as zero (the input tag passes through unchanged).

  Throws when:

  • No table is registered for the (unit, scaleName) pair.
  • tag isn't present in the resolved table.

  Worked example: shiftTag('lux', 'lit', -2) → 'very-dim' (assuming the lux scale order pitch-black/very-dim/dim/lit/ bright/blinding). shiftTag('lux', 'pitch-black', -10) → 'pitch-black' (clamped at the floor).

  Parameters

  • unit: Unit
  • tag: string
  • shift: number
  • OptionalscaleName: string

  Returns string

StatictagsFor

• tagsFor(unit: Unit, scaleName?: string): readonly string[]

  Ordered tag list for a (unit, scaleName) pair. Order is ascending by threshold (the registry sorts entries on register for tagFor's descending walk; this helper exposes the same ordering as a plain string array for callers that need to do shift/compare arithmetic over tag bands).

  Returns an empty array when no table is registered for the pair. scaleName defaults to the unit's registered default scale.

  Cross-unit consumer pattern: LightBand is the lux scale's tag list; a future thermal-K scale would expose its own ordered tag list the same way.

  Parameters

  • unit: Unit
  • OptionalscaleName: string

  Returns readonly string[]