Conversion module for the UOR Math-JS library Provides utilities for converting between different number representations Supports full interoperability between standard JavaScript number types and UniversalNumber Implements the conversion utilities specified in the Prime Framework

Members

(inner, constant) Conversion

Combine all conversion utilities into a single module

(inner, constant) canonicalFrame

Default canonical reference frame used for standard computations In the Prime Framework, this represents the fixed reference point x ∈ M

Methods

(inner) baseConversionStep(toBase, optionsopt) → {ConversionStep}

Common conversion step: base conversion

Parameters:
NameTypeAttributesDescription
toBasenumber

Target base for conversion

optionsObject<optional>

Additional options

Returns:

A conversion step for the pipeline

Type: 
ConversionStep

(inner) calculateGCD(a, b) → {BigInt}

Calculate the greatest common divisor (GCD) for fraction simplification

Parameters:
NameTypeDescription
aBigInt

First number

bBigInt

Second number

Returns:

The GCD

Type: 
BigInt

(inner) coherenceInnerProduct(a, b, optionsopt) → {BigInt}

Compute the coherence inner product between two universal coordinate representations This function implements the positive-definite inner product ⟨·,·⟩c defined in the Prime Framework

Parameters:
NameTypeAttributesDescription
aMap.<BigInt, BigInt> | Object

First universal coordinates

bMap.<BigInt, BigInt> | Object

Second universal coordinates

optionsObject<optional>

Options for computing the inner product

Properties
NameTypeAttributesDefaultDescription
referenceFrameReferenceFrame<optional>
canonicalFrame

Reference frame to use

Returns:

The coherence inner product value

Type: 
BigInt

(inner) coherenceNorm(coordinates, optionsopt) → {BigInt}

Compute the coherence norm of universal coordinates This implements the norm derived from the coherence inner product

Parameters:
NameTypeAttributesDescription
coordinatesMap.<BigInt, BigInt> | Object

Universal coordinates

optionsObject<optional>

Options for computing the norm

Properties
NameTypeAttributesDefaultDescription
referenceFrameReferenceFrame<optional>
canonicalFrame

Reference frame to use

Returns:

The coherence norm value

Type: 
BigInt

(inner) computeDigitsFromFactorization(factorization, base) → {string|null}

Compute digits directly from prime factorization for certain bases This is faster than going through BigInt for some special cases

Parameters:
NameTypeDescription
factorizationMap.<BigInt, BigInt>

The prime factorization

basenumber

The target base

Returns:

The digits in the target base, or null if direct computation not possible

Type: 
string | null

(inner) convertBase(value, fromBaseopt, toBaseopt) → {string}

Convert a number from one base to another

Parameters:
NameTypeAttributesDefaultDescription
valuestring | number | BigInt

The value to convert

fromBasenumber<optional>
10

The base of the input (default is decimal)

toBasenumber<optional>
10

The base to convert to (default is decimal)

Throws:

If the value cannot be converted or the base is invalid

Type
PrimeMathError
Returns:

The converted value as a string

Type: 
string

(inner) convertBaseViaUniversal(value, fromBase, toBase, optionsopt) → {string}

Optimized direct base conversion utility Converts a number between different bases using universal coordinates Implements efficient algorithms that leverage prime factorization properties

Parameters:
NameTypeAttributesDescription
valuenumber | string | BigInt | Map.<BigInt, BigInt>

The value to convert

fromBasenumber

Base of the input (2-36)

toBasenumber

Base for the output (2-36)

optionsObject<optional>

Additional options for the conversion

Properties
NameTypeAttributesDefaultDescription
useFactorizationShortcutsboolean<optional>
true

Whether to use factorization shortcuts for speed

useDirectComputationboolean<optional>
true

Whether to use direct digit computation where possible

Returns:

The value in the target base

Type: 
string

(inner) convertBigIntToBase(value, base) → {string}

Convert a BigInt to a string representation in the given base

Parameters:
NameTypeDescription
valueBigInt

The BigInt value to convert

basenumber

The base to convert to (2-36)

Returns:

The string representation in the given base

Type: 
string

(inner) convertToUniversalStep(optionsopt) → {ConversionStep}

Common conversion step: convert to universal coordinates

Parameters:
NameTypeAttributesDescription
optionsObject<optional>

Step-specific options

Returns:

A conversion step for the pipeline

Type: 
ConversionStep

(inner) createConversionPipeline(steps, optionsopt) → {function}

Creates a conversion pipeline for processing large sets of numbers This allows efficient batch processing with minimal intermediate transformations

Parameters:
NameTypeAttributesDescription
stepsArray.<ConversionStep>

Array of conversion steps to apply

optionsConversionPipelineOptions<optional>

Pipeline configuration options

Returns:

Pipeline function

Type: 
function

(inner) createReferenceFrame(options) → {ReferenceFrame}

Create a new reference frame for the Prime Framework Each reference frame corresponds to a fiber in the Prime Framework's algebraic geometry

Parameters:
NameTypeDescription
optionsObject

Options for creating the reference frame

Properties
NameTypeAttributesDefaultDescription
idstring<optional>
'canonical'

Identifier for the reference frame

parametersMap.<string, any> | Object<optional>
{}

Parameters for the reference geometry

Returns:

A new reference frame object

Type: 
ReferenceFrame

(inner) factorizationToBaseString(factorization, baseopt) → {string}

Convert a prime factorization to a string representation in the given base

Parameters:
NameTypeAttributesDefaultDescription
factorizationMap.<BigInt, BigInt>

The prime factorization to convert

basenumber<optional>
10

The base for the output representation (2-36)

Throws:

If the factorization is invalid or the base is not supported

Type
PrimeMathError
Returns:

The string representation in the specified base

Type: 
string

(inner) factorizationToBigInt(factorization) → {BigInt}

Convert a prime factorization to a BigInt value This is a standalone version of the method for converting a factorization to its numeric value

Parameters:
NameTypeDescription
factorizationMap.<BigInt, BigInt>

The prime factorization to convert

Throws:

If the factorization is invalid

Type
PrimeMathError
Returns:

The numeric value represented by the factorization

Type: 
BigInt

(inner) factorizationToString(factorsInput) → {string}

Create a string representation of a prime factorization

Parameters:
NameTypeDescription
factorsInputMap.<BigInt, BigInt> | Object

Map of prime factors or object with factorization and sign

Returns:

Human-readable representation of the factorization (with optional negative sign)

Type: 
string

(inner) fromBigInt(b) → {Map.<BigInt, BigInt>}

Convert a BigInt to a factorized universal representation

Parameters:
NameTypeDescription
bBigInt

The BigInt value to convert

Returns:

The prime factorization (universal coordinates)

Type: 
Map.<BigInt, BigInt>

(inner) fromNumber(n) → {Object}

Convert a JavaScript Number to a factorized universal representation Floors the number if it's not an integer, throws an error if not safe (above 2^53)

Parameters:
NameTypeDescription
nnumber

The JavaScript Number to convert

Throws:

If the number is not safe or is not finite

Type
PrimeMathError
Returns:

The prime factorization (universal coordinates) and sign flag

Type: 
Object

(inner) fromString(str, baseopt) → {Object}

Parse a string representing a number in a given base and convert to universal coordinates

Parameters:
NameTypeAttributesDefaultDescription
strstring

The string representing a number

basenumber<optional>
10

The base of the input string (configurable, default: 2-36)

Throws:

If the string cannot be parsed or is zero

Type
PrimeMathError
Returns:

The prime factorization (universal coordinates) and sign flag

Type: 
Object

(inner) getCliffAlgebra() → {Object}

Get the Clifford algebra at this reference point In the Prime Framework, the fiber at each point is modeled as a Clifford algebra Cx

Returns:

The Clifford algebra object

Type: 
Object

(inner) getDigitCharset(base) → {string}

Get the digit character set for a specific base Supports extended bases beyond the standard 36

Parameters:
NameTypeDescription
basenumber

The base for which to get the character set

Returns:

The character set for the given base

Type: 
string

(inner) getDigits(value, baseopt, leastSignificantFirstopt) → {Array.<number>}

Extract the digits of a number in a specific base

Parameters:
NameTypeAttributesDefaultDescription
valuenumber | string | BigInt

The value to extract digits from

basenumber<optional>
10

The base to use for extraction (default is decimal)

leastSignificantFirstboolean<optional>
false

If true, returns digits with least significant first

Throws:

If the value is invalid or the base is not supported

Type
PrimeMathError
Returns:

Array of digits in the specified base

Type: 
Array.<number>

(inner) getErrorMessage(error) → {string}

Helper function to safely extract error message Non-recursive implementation to avoid stack overflows

Parameters:
NameTypeDescription
errorunknown

Any error value

Returns:

The error message

Type: 
string

(inner) isCanonicalForm(coordinates, optionsopt) → {boolean}

Check if universal coordinates are in canonical (minimal norm) form This implements the coherence criteria from the Prime Framework specification as detailed in lib-spec.md section "Coherence Inner Product and Norm"

Parameters:
NameTypeAttributesDescription
coordinatesMap.<BigInt, BigInt> | Object

Universal coordinates

optionsObject<optional>

Options for checking canonical form

Properties
NameTypeAttributesDefaultDescription
referenceFrameReferenceFrame<optional>
canonicalFrame

Reference frame to use

Returns:

Whether the coordinates are in canonical form

Type: 
boolean

(inner) isPrime(value) → {boolean}

Determines if a given number is a valid prime This ensures the factorization contains only actual primes as required by the Prime Framework

Parameters:
NameTypeDescription
valueBigInt

The value to check for primality

Returns:

Whether the value is prime

Type: 
boolean

(inner) parseFactorization(str, optionsopt) → {Map.<BigInt, BigInt>|Object}

Parses a string representation of a prime factorization Accepts formats like "2^3 × 3^2 × 5", "2^3 * 3^2 * 5", "22233*5", a single term like "2^4" Also handles negative representations like "-(2^3 × 3)" or "-1"

Parameters:
NameTypeAttributesDescription
strstring

The string representation of the factorization

optionsObject<optional>

Optional parameters for parsing

Properties
NameTypeAttributesDefaultDescription
withSignFlagboolean<optional>
false

Whether to include a sign flag in the result

Throws:

If the string is not a valid factorization

Type
PrimeMathError
Returns:

Map of prime factors (or with sign flag if requested)

Type: 
Map.<BigInt, BigInt> | Object

(inner) toFraction(value) → {Object}

Convert a number, string, or BigInt to a fraction (numerator/denominator) This is useful for exact representation of decimal values

Parameters:
NameTypeDescription
valuestring | number | BigInt

The value to convert (eg. "3.14159", 3.14159, or BigInt)

Throws:

If the value is not a valid number

Type
PrimeMathError
Returns:

Object with numerator and denominator as BigInt values

Type: 
Object

(inner) toJSON(data, optionsopt) → {string}

Serializes number data to JSON format with advanced options

Parameters:
NameTypeAttributesDescription
dataObject

The number data to serialize

Properties
NameTypeAttributesDefaultDescription
valueBigInt | Map.<BigInt, BigInt>

The numeric value or prime factorization

isFactorizationboolean<optional>
false

If true, value is treated as factorization

optionsObject<optional>

Serialization options

Properties
NameTypeAttributesDefaultDescription
formatSerializationFormat<optional>
'standard'

Format to use for serialization

includeMetadataboolean<optional>
false

Whether to include additional metadata

Returns:

JSON string representation

Type: 
string

(inner) toScientificNotation(value, precisionopt) → {string}

Convert a number to a string representation in scientific notation

Parameters:
NameTypeAttributesDefaultDescription
valuenumber | string | BigInt

The value to convert

precisionnumber<optional>
6

Number of significant digits to include

Throws:

If the value is invalid

Type
PrimeMathError
Returns:

The number in scientific notation

Type: 
string

(inner) transform(coordinates, _targetFrame) → {Map.<BigInt, BigInt>|Object}

Transform coordinates from this frame to another This implements the G-action on M that carries representations between fibers As described in lib-spec.md's section on Topological and Geometric Framework

Parameters:
NameTypeDescription
coordinatesMap.<BigInt, BigInt> | Object

Universal coordinates to transform

_targetFrameReferenceFrame

The target reference frame (used for conforming to abstract interface)

Returns:

Transformed coordinates

Type: 
Map.<BigInt, BigInt> | Object

(inner) tryBaseConversionShortcut(value, fromBase, toBase) → {string|null}

Try optimized base conversion shortcuts for common bases Provides fast conversion paths for common base combinations like binary ↔ hexadecimal

Parameters:
NameTypeDescription
valuestring | number | BigInt

The value to convert

fromBasenumber

The base of the input

toBasenumber

The base to convert to

Returns:

The converted value or null if no shortcut is available

Type: 
string | null

(inner) validateStringForBase(str, base) → {boolean}

Validates if a string is a valid representation of a number in the given base

Parameters:
NameTypeDescription
strstring

The string to validate

basenumber

The base of the number representation (configurable, default: 2-36)

Returns:

True if the string is a valid representation

Type: 
boolean

Type Definitions

BigIntResult

Type:
  • Object
Properties
NameTypeAttributesDescription
formatstring

The format used (standard, compact, binary, streaming)

primeCountnumber

Number of prime factors

timestampstring

ISO timestamp of serialization

typestring

Always 'Factorization'

factorsRecord.<string, string>

Object mapping prime factors to exponents

metadataFactorizationMetadata<optional>

Optional metadata

typestring

Always 'CompactFactorization'

primesArray.<string>

Array of prime factors as strings

exponentsArray.<string>

Array of exponents as strings

metadataFactorizationMetadata<optional>

Optional metadata

typestring

Always 'BinaryFactorization'

encodingstring

Encoding type (e.g., 'base64')

datastring

Encoded data

metadataFactorizationMetadata<optional>

Optional metadata

typestring

Always 'StreamingFactorization'

chunkCountnumber

Number of chunks

chunksArray.<{primes: Array.<string>, exponents: Array.<string>}>

Array of chunks

metadataFactorizationMetadata<optional>

Optional metadata

typestring

Always 'BigInt'

valuestring

String representation of the BigInt value

metadataObject<optional>

Optional metadata

ConversionPipelineOptions

Conversion pipeline configuration options

Type:
  • Object
Properties
NameTypeAttributesDefaultDescription
parallelboolean<optional>
false

Whether to process items in parallel (when supported)

batchSizenumber<optional>
100

Size of batches for batch processing

preserveFactorizationboolean<optional>
true

Whether to preserve factorization between steps

streamingOutputboolean<optional>
false

Whether to stream output or return all at once

ConversionStep

Conversion pipeline step definition

Type:
  • Object
Properties
NameTypeAttributesDescription
typestring

Type of conversion step ('format', 'transform', 'compute')

processfunction

Function to process a value in the pipeline

optionsObject<optional>

Step-specific options

DigitResult

Get the digit representation of a number in a specific base This extracts digits directly from the value

Type:
  • Object
Properties
NameTypeAttributesDescription
digitsArray.<number>

Array of digits in the specified base

isNegativeboolean<optional>

Whether the value is negative (only included if includeSign is true)

ParsedJSONResult

Parses a JSON string back to number data with advanced options

Type:
  • Object
Properties
NameTypeAttributesDescription
valueBigInt | Map.<BigInt, BigInt>

The numeric value or prime factorization

isFactorizationboolean

Whether the value is a factorization (true) or BigInt (false)

metadataObject<optional>

Additional metadata if present and validated

ReferenceFrame

Represents a reference frame in the Prime Framework A reference frame defines a specific algebraic context for universal coordinates This corresponds to a point on the smooth reference manifold M described in lib-spec.md

Type:
  • Object
Properties
NameTypeDescription
idstring

Unique identifier for the reference frame

parametersMap.<string, any>

Parameters defining the specific reference geometry

transformfunction

Function to transform coordinates between frames

getCliffAlgebrafunction

Gets the Clifford algebra at this reference point

SerializationFormat

Advanced serialization format options Provides different serialization strategies for universal coordinates

Type:
  • 'standard' | 'compact' | 'binary' | 'streaming'