API: CDIF

API › "@mkacct/cdif" › CDIF

class CDIF

The CDIF class contains all of this library's main functionality, both for parsing and serializing cDIF data.

Constructor

public constructor(
    cdifVersion?: number
)

Creates an instance of the cDIF parser/serializer. The one optional argument is the major version of the cDIF specification by which the instance should abide. (If it is omitted, the latest version will be assumed.)

Parameters:

• cdifVersion: number (Optional) – integer major version of cDIF to use (defaults to latest)

Throws:

• RangeError – if cdifVersion is invalid

Static

Symbol

public static readonly Symbol: {...}

An object containing "protocol" symbols used by the cDIF API, comparable to JavaScript's built-in "well-known Symbols". These symbols are as follows:

• CDIF.Symbol.preprocess – Key denoting a method that will be called as a serializer preprocessor function for an object when using usePreprocessMethods(). (Note: The serializer does not look for this method by default. This symbol is only meaningful when using usePreprocessMethods(). See that preprocessor's own documentation for more information.)

OMIT_PROPERTY

public static readonly OMIT_PROPERTY: unique symbol

When returned from a postprocessor or preprocessor function, denotes that the property should be omitted. (See "Postprocessors and preprocessors" for more information.)

getCdifVersion()

public static getCdifVersion(
    cdifText: string
): number | undefined

Determines the major version of cDIF declared by a cDIF file. This method can be used before instantiating a CDIF object, and may be useful if you're parsing a cDIF file of unknown version.

Parameters:

• cdifText: string – a valid cDIF string (read from a file or otherwise)

Returns:

• number | undefined – the cDIF major version, or undefined if no "cDIF" directive is present

Throws:

• CDIFDirectiveError – if an initial "cDIF" directive is present but has an invalid version string

Instance

parse()

public parse(
    cdifText: string,
    parserOptions?: CDIFParserOptions
): unknown

Converts a cDIF string to a JavaScript value. The cDIF string may (or may not) include # directives and other file format elements. You can pass a CDIFParserOptions object (see "Configuration: Parser" for details) to customize the parser behavior.

Parameters:

• cdifText: string – a valid cDIF string (read from a file or otherwise)
• parserOptions: CDIFParserOptions (Optional) – customize the behavior of the parser

Returns:

• unknown – cdifText converted to a JS value (usually an object or array)

Throws:

• CDIFError – if a postprocessor function tries to omit the root value
• CDIFSyntaxError – if the input has invalid syntax
• CDIFDirectiveError – if an unknown directive is encountered, or a directive is used incorrectly
• CDIFDirectiveError – if allowUnexpectedVersionString is false and the "cDIF" directive is used with an unexpected version string
• CDIFReferenceError – if a component reference is not defined
• CDIFReferenceError – if a circular component reference is encountered
• CDIFTypeError – if a spread expression is used with a component of the wrong type

serialize()

public serialize(
    value: unknown,
    serializerOptions?: CDIFSerializerOptions
): string

Converts a JavaScript value to a cDIF data string. It will not contain the # cDIF directive or any other file format elements. You can pass a CDIFSerializerOptions object (see "Configuration: Serializer" for details) to customize the serializer behavior.

Parameters:

• value: unknown – a JS value (usually an object or array) to be converted
• serializerOptions: CDIFSerializerOptions (Optional) – customize the behavior of the serializer

Returns:

• string – value converted to a cDIF data string

Throws:

• CDIFError – if any value is a CDIFPrimitiveValue created with the wrong cDIF version
• CDIFError – if a preprocessor function tries to omit the root value, or, in strict mode, a collection value
• CDIFSyntaxError – if an object property name is not a valid cDIF name
• CDIFSyntaxError – if a preprocessor function returns a type name that is not a valid cDIF type name
• CDIFTypeError – if a circular reference is encountered
• CDIFTypeError – in strict mode, if any value is of a disallowed type

serializeFile()

public serializeFile(
    value: unknown,
    serializerOptions?: CDIFSerializerOptions
    fileOptions?: CDIFFileOptions
): string

Converts a JavaScript value to a cDIF file string (suitable for writing to a file). It may contain various file format elements (such as the # cDIF directive) depending on a provided CDIFFileOptions object (see "Configuration: File formatter" for details). As with CDIF.serialize(), you can also pass a CDIFSerializerOptions object (see "Configuration: Serializer" for details) to customize the serializer behavior.

Parameters:

• value: unknown – a JS value (usually an object or array) to be converted
• serializerOptions: CDIFSerializerOptions (Optional) – customize the behavior of the serializer
• fileOptions: CDIFFileOptions (Optional) – customize the behavior of the file formatter

Returns:

• string – value converted to a cDIF file string

Throws:

• Error – if fileOptions is invalid
• CDIFError – if any value is a CDIFPrimitiveValue created with the wrong cDIF version
• CDIFError – if a preprocessor function tries to omit the root value, or, in strict mode, a collection value
• CDIFSyntaxError – if an object property name is not a valid cDIF name
• CDIFSyntaxError – if a preprocessor function returns a type name that is not a valid cDIF type name
• CDIFTypeError – if a circular reference is encountered
• CDIFTypeError – in strict mode, if any value is of a disallowed type

createPrimitiveValue()

public createPrimitiveValue(
    cdifText: string
): CDIFPrimitiveValue

Creates a CDIFPrimitiveValue instance for the primitive value represented by the provided cDIF text. (See that class's documentation for more information.)

Parameters:

• cdifText: string – valid cDIF text representing a primitive value

Returns:

• CDIFPrimitiveValue – a cDIF primitive value object representation of the primitive value

Throws:

• CDIFSyntaxError – if cdifText is not a valid cDIF primitive value