Module number

Number shape types and operations.

Defines the shape describing the numeric values a resource may carry and its constraint types, and provides the factories stating them, mapping the JSON number type to XSD 1.0 numeric datatypes. The number factory bounds a shape by range and enumeration constraints; the typed factories fix the datatype and precision of a particular XSD type.

Important

Contradictory constraints are rejected as the shape is built, so a shape that exists admits at least one value: stating minInclusive above maxInclusive throws a TraceError.

XSD Datatype ¹	Factory	Description	Range
byte	byte	8-bit signed integer	[‑2⁷, 2⁷‑1]
short	short	16-bit signed integer	[‑2¹⁵, 2¹⁵‑1]
int	int	32-bit signed integer	[‑2³¹, 2³¹‑1]
long	long ²	64-bit signed integer	[‑2⁶³, 2⁶³‑1]
float	float	IEEE 754 32-bit float	m < 2²⁴, e ∈ [‑126, 127]
double	double	IEEE 754 64-bit float	m < 2⁵³, e ∈ [‑1022, 1023]
integer	integer ²	arbitrary-precision integer	±#
decimal	decimal ²	arbitrary-precision decimal	±#.#

¹ XSD 1.0 datatypes are referenced by RDF 1.1 and JSON-LD 1.1 as normative

² Numeric types with ranges exceeding JavaScript's safe integer range (±2⁵³-1) or requiring arbitrary precision cannot be fully represented in JSON/JavaScript

Compatibility

XSD datatype	JSON	JavaScript
byte, short, int	integer	represented exactly
long	integer	exact only within ±2⁵³‑1
float, double	number; no NaN, no ±INF	IEEE 754, NaN and ±Infinity included
integer	integer	needs BigInt beyond ±2⁵³‑1
decimal	number	no native arbitrary-precision decimal

Defining number shapes

import { decimal, integer, number } from '@metreeca/blue/number';

const count = number();                                       // unconstrained number
const score = number({ minInclusive: 0, maxInclusive: 100 }); // constrained range
const age = integer({ minInclusive: 0 });                     // arbitrary-precision integer
const price = decimal({ minInclusive: 0 });                   // arbitrary-precision decimal
const die = number({ in: [1, 2, 3, 4, 5, 6] });               // enumeration-constrained
const coin = number(0, 1);                                    // the same, stated as bare values

Note

An enumeration also narrows the value the shape describes: die admits 1 | 2 | 3 | 4 | 5 | 6, not the whole numeric domain.

Typed numeric factories

Specialised factories map to XSD numeric datatypes with predefined precision:

import { byte, double, float, int, long, short } from '@metreeca/blue/number';

const priority = byte();       // 8-bit signed integer
const port = short();          // 16-bit signed integer
const quantity = int();        // 32-bit signed integer
const offset = long();         // 64-bit signed integer
const ratio = float();         // IEEE 754 single-precision
const measurement = double();  // IEEE 754 double-precision

Using in resource shapes

import { optional, required, resource } from '@metreeca/blue/resource';
import { decimal, integer } from '@metreeca/blue/number';

const Product = resource({
  price: required(decimal({ minInclusive: 0 })),
  quantity: optional(integer({ minInclusive: 0 })),
  rating: optional(decimal({ minInclusive: 0, maxInclusive: 5 }))
});

See

Type Aliases

NumberShape: Describes a numeric value.
NumberConstraints: Constraints accepted by the number shape factory.
NumberRangeConstraints: Value range bounds accepted by the number shape factories.

Functions

number: Creates a number shape.
byte: Creates a shape for 8-bit signed integer values.
short: Creates a shape for 16-bit signed integer values.
int: Creates a shape for 32-bit signed integer values.
long: Creates a shape for 64-bit signed integer values.
float: Creates a shape for IEEE 754 single-precision floating-point values.
double: Creates a shape for IEEE 754 double-precision floating-point values.
integer: Creates a shape for arbitrary-precision integer values.
decimal: Creates a shape for arbitrary-precision decimal values.

Module number

See

Type Aliases

Functions

Settings

On This Page