Parse

Functions for parsing from JSON values into SDL-supported types.

Each parsing function accepts a value and a ParserTracer, which is used to record parsing/validation errors. Functions return either the parsed value, or undefined; if undefined is returned (and unexpected) the caller should use the getMessage method to extract the error.

If undefined is a valid value, the caller should check for this before invoking the parsing function.

For more information on SDL datatypes and their serialisation, refer to: https://gitlab.cartax.io/platform/sdl/-/blob/master/docs/datatypes.md

Constructors

new Parse(): Parse

Methods

Static methods

staticany<T = any>(x: T): Tsource

The identity function.

staticarray<T>(elementParser: ParseFn): ParseFnsource

Returns a parser that parses an array, applying the given elementParser to each element.

The array will be rejected if the elementParser returns undefined for any element of the array.

staticbool(x: any, t: ParserTracer): undefined | booleansource

Parses a boolean value.

staticdate(x: any, t: ParserTracer): undefined | PlainDatesource

Parses a string in ISO8601 date format (YYYY-MM-DD) into a Temporal.PlainDate.

staticdecimal<N extends number>(numDecimals: N): ParseFnsource

Returns a parser that parsers a string to a Decimal, with an optional fixed number of decimals.

staticenum<Domain extends EnumDomain>(name: string, domain: Domain): ParseFnsource

Returns a parser that parses a string to a value of the given enumeration domain.

staticfromArrayUsingQueryMetadata<T>(queryMetadata: QueryReflectionMetadata): Functionsource

Returns a parser that parses an array of values into the desired object type, using the given reflection metadata.

staticfromObjectUsingFastPathWithConstructor<T>(metadata: ReflectionMetadata, constructor: Function): ParseFnsource

Returns a parser that instantiates its object by invoking a constructor function whose arguments correspond to the fields of the structure.

staticfromObjectUsingMetadata<T>(metadata: ReflectionMetadata): ParseFnsource

Returns a parser that parses an object using the given reflection metadata.

staticfromObjectUsingSlowPathWithObjectCreate<T>(metadata: ReflectionMetadata): ParseFnsource

Returns a parser that instantiates its object using Object.create with the prototype given in the metadata, and sets fields one at a time. This is slightly slower but the only option when no constructor is available.

statici16(x: any, t: ParserTracer): undefined | numbersource

Expects a number and validates that it is within the signed 16-bit range.

statici32(x: any, t: ParserTracer): undefined | numbersource

Expects a number and validates that it is within the signed 32-bit range.

statici64(x: any, t: ParserTracer): undefined | numbersource

Expects a number and validates that it is within the signed 64-bit range.

statici8(x: any, t: ParserTracer): undefined | numbersource

Expects a number and validates that it is within the signed 8-bit range.

staticjson(value: any, t: ParserTracer): anysource

JSON parses a string to a value.

This is just a wrapper around JSON.parse with exceptions routed into the given ParserTracer.

staticliteral<T extends string>(value: T): ParseFnsource

Returns a parser that parses a string of a fixed value.

staticmap<K, V>(parseKey: ParseFn, parseValue: ParseFn): ParseFnsource

Returns a parser that parsers an object to a Map. The keys and values of the map are formed by applying the given key and value parsing functions. If either parser returns undefined at any stage, the entire map is rejected.

staticnullable<T>(parseFn: ParseFn): ParseFnsource

Wraps the given parse function so that it accepts and passes through null and undefined.

staticobject(value: any, t: ParserTracer): undefined | objectsource

Parses an object, without performing any validation of its contents.

staticoneOf<T extends TypeMap>(parserMap: ParserMap<T>): ParseFnsource

Returns a parser that parses the serialised representation of a sum type to its equivalent in-memory value. The serialised form may be one of the following:

Literal: primitive types (boolean, number, string, or null) may be directly stored in the field.
Tagged: for a struct type, the value is stored as an object with a single entry. The key of the entry is the 'tag' of the type; this is either explicitly defined by the model author, or defaults to the name of the struct type.

Each type may appear at most once in the tag map.

staticset<T>(elementParser: ParseFn): ParseFnsource

Returns a parser that parses an array to a Set, applying the given elementParser to each element. The set will be rejected if elementParser returns undefined for any element for any element of the array.

staticstr(x: any, t: ParserTracer): undefined | stringsource

Returns a parser that parses a string.

statictimestamp(x: any, t: ParserTracer): undefined | Instantsource

Parses a string in ISO8601 timestamp format into a Temporal.Instant.

statictuple<Ts extends any[]>(parsers: ParserTuple<Ts>): ParseFnsource

Returns a parser that parses an fixed-size array using a bijective mapping of parser to value. This differs from array in that the former is strictly homogenous, while a tuple may be heterogenous.

The array is rejected if:

its length differs from the expected length; or
any element parsing function returns undefined.

staticu16(x: any, t: ParserTracer): undefined | numbersource

Expects a number and validates that it is within the unsigned 16-bit range.

staticu32(x: any, t: ParserTracer): undefined | numbersource

Expects a number and validates that it is within the unsigned 32-bit range.

staticu64(x: any, t: ParserTracer): undefined | numbersource

Expects a number and validates that it is within the unsigned 64-bit range.

staticu8(x: any, t: ParserTracer): undefined | numbersource

Expects a number and validates that it is within the unsigned 8-bit range.

staticunwrappedTuple<Ts extends any[]>(parsers: ParserTuple<Ts>): ParseFnsource

Returns a parser that parses either a fixed-size array or a single value. This is the same as tuple, except that 1-tuples are not expected to be enclosed in an array.

staticuuid(x: any, t: ParserTracer): undefined | uuidsource

Parses a string in UUIDv4 format into a uuid.

staticyearMonth(x: any, t: ParserTracer): undefined | PlainYearMonthsource

Parses a string in ISO8601 year-month format (YYYY-MM) into a Temporal.PlainYearMonth.