json

Index

Classes

Interfaces

FromJsonOptions

Options for the fromJson function

Extends

Properties

allowEntries?

optional allowEntries: boolean

Whether to allow literal children to be encoded into values or properties

Defaults to true. This value can be defined specifically for arrays, objects, or the root node.

Defined in

src/json.d.ts:166


allowEntriesInArrays?

optional allowEntriesInArrays: boolean

Whether to allow literal items in the array to be encoded as values on a node

If set to false, all array items will be encoded as children.

If set to true, all leading literal values of arrays will be encoded as node values instead.

The default value is the value of allowEntries, which in turn defaults to true.

Defined in

src/json.d.ts:177


allowEntriesInObjects?

optional allowEntriesInObjects: boolean

Whether to allow literal properties in the object to be encoded as property on a node

If set to false, all node properties will be encoded as children.

If set to true, all properties with literal values of objects will be encoded as node properties instead. Note that this changes the order of properties, which are assumed not to matter in JSON.

The default value is the value of allowEntries, which in turn defaults to true.

Defined in

src/json.d.ts:189


allowEntriesInRoot?

optional allowEntriesInRoot: boolean

Whether to allow literal children to be encoded as values or properties on the root node

This property only has effect if the given value is an object or an array. Literal values are always encoded as values on the root node.

The default value of this option is the value of allowEntriesInArrays or allowEntriesInObjects, depending on the type of the value.

Defined in

src/json.d.ts:199


indentation?

optional indentation: string | number

The indentation to give each nested level of node

If a string is passed, that string is used as indentation. If a number higher than zero is passed, the indentation is set to the whitespace character repeated for that number of times. If zero is passed or no indentation is given, no newlines with indentation will be inserted into the output.

Inherited from

StringifyOptions.indentation

Defined in

src/json.d.ts:256


nodeName?

optional nodeName: string

Name of the root node to create

If no name is passed, the node will be called "-".

Defined in

src/json.d.ts:158


replaceJsonValue()?

optional replaceJsonValue: (key, value, originalValue) => unknown

Replacer function called for every JSON value in the data being transformed

The replacer can return any JSON value, which will be used instead of the original value. If undefined is returned, the value will be discarded.

If the originalValue had a toJSON method, it will be called and the result will be the value parameter. In all other cases value and originalValue will be the same value.

Parameters

key: string | number

The name of the property or the index inside an array

value: unknown

The value being handled

originalValue: unknown

The original value

Returns

unknown

Inherited from

StringifyOptions.replaceJsonValue

Defined in

src/json.d.ts:272


replaceKdlValue()?

optional replaceKdlValue: (key, value, jsonValue, originalJsonValue) => undefined | Entry | Node

Replacer function called for every KDL node or entry created

The replacer can return an entry or node. If an entry is returned but an entry would not be valid in the given location, it will be transformed into a node. If undefined is returned, the value will be discarded.

Parameters

key: string | number

The name of the property or the index inside an array

value: Entry | Node

The entry or node that was created

jsonValue: unknown

The JSON value that was transformed into the KDL value

originalJsonValue: unknown

Returns

undefined | Entry | Node

Inherited from

StringifyOptions.replaceKdlValue

Defined in

src/json.d.ts:290


JiKReviver()<T>

Reviver function that can be passed into parse or toJson

The function is called for every JSON value while it's being serialized. These values are replaced by the return value of this function.

Type Parameters

T

JiKReviver(value, key, data): undefined | T

Reviver function that can be passed into parse or toJson

The function is called for every JSON value while it's being serialized. These values are replaced by the return value of this function.

Parameters

value: JsonValue

The JSON value

key: string | number

The key of the value, empty string for the root value

data

The node or entry where the value was defined

data.location: Entry | Node

Returns

undefined | T

The value to use, if the value is undefined then the property is removed from the result

Defined in

src/json.d.ts:223


JsonObject

A JSON object

Indexable

[property: string]: JsonValue


StringifyOptions

Options for the stringify function

Extended by

Properties

indentation?

optional indentation: string | number

The indentation to give each nested level of node

If a string is passed, that string is used as indentation. If a number higher than zero is passed, the indentation is set to the whitespace character repeated for that number of times. If zero is passed or no indentation is given, no newlines with indentation will be inserted into the output.

Defined in

src/json.d.ts:256


replaceJsonValue()?

optional replaceJsonValue: (key, value, originalValue) => unknown

Replacer function called for every JSON value in the data being transformed

The replacer can return any JSON value, which will be used instead of the original value. If undefined is returned, the value will be discarded.

If the originalValue had a toJSON method, it will be called and the result will be the value parameter. In all other cases value and originalValue will be the same value.

Parameters

key: string | number

The name of the property or the index inside an array

value: unknown

The value being handled

originalValue: unknown

The original value

Returns

unknown

Defined in

src/json.d.ts:272


replaceKdlValue()?

optional replaceKdlValue: (key, value, jsonValue, originalJsonValue) => undefined | Entry | Node

Replacer function called for every KDL node or entry created

The replacer can return an entry or node. If an entry is returned but an entry would not be valid in the given location, it will be transformed into a node. If undefined is returned, the value will be discarded.

Parameters

key: string | number

The name of the property or the index inside an array

value: Entry | Node

The entry or node that was created

jsonValue: unknown

The JSON value that was transformed into the KDL value

originalJsonValue: unknown

Returns

undefined | Entry | Node

Defined in

src/json.d.ts:290


ToJsonOptions

Options for the toJson function

Properties

ignoreValues?

optional ignoreValues: boolean

Whether to ignore values on the root node

Turning this option on deviates from the JiK standard by ignoring all values on the root node. This makes it possible to encode parameterized nodes as JiK.

For example, every book node in the following document is a JiK node:

book "The Fellowship of the Ring" {
  author "J.R.R. Tolkien"
  publicationYear 1954
}

book "Dune" publicationYear=1965 {
  author "Frank Herbert"
}

Here's how this could be turned into an map containing all books:

const books = new Map(
  document.findNodesByName('book').map(node => [
	   node.getArgument(0),
    toJson(node, {ignoreValues: true}),
  ]),
)
Defined in

src/json.d.ts:62


ToJsonReviver<T>

Extra option to modify the return value of the toJson function

Type Parameters

T

Properties

reviver

reviver: JiKReviver<T>

Reviver to use

Defined in

src/json.d.ts:89


ToJsonType<T>

Extra option for providing a type hint to the toJson function

Type Parameters

T

Properties

type

type: T

Type to use for the node

Possible values are:

  • object: The node must be a valid object, and nodes that are ambiguous and could be objects or something else are assumed to be an object
  • array: The node must be a valid array, and nodes that are ambiguous and could be arrays or something else are assumed to be an array
Defined in

src/json.d.ts:79

Type Aliases

JsonValue

JsonValue: null | number | boolean | string | JsonObject | JsonValue[]

A JSON value

Defined in

src/json.d.ts:20

Functions

fromJson()

fromJson(value, options?): Node

Encode the given JSON value into a JiK node

Parameters

value: JsonValue

The JSON value to encode

options?: FromJsonOptions

Returns

Node

Throws

If the given value contains cycles.

Defined in

src/json.d.ts:208


parse()

parse(text, reviver)

parse(text, reviver?): JsonValue

Parse the given JiK text to its encoded JSON value

Parameters

text: string

The JiK text to parse

reviver?: JiKReviver<JsonValue>

Returns

JsonValue

Throws

If the given text is not a valid JiK document

Defined in

src/json.d.ts:236

parse(text, reviver)

parse(text, reviver): unknown

Parse the given JiK text to its encoded JSON value

Parameters

text: string

The JiK text to parse

reviver: JiKReviver<unknown>

Returns

unknown

Throws

If the given text is not a valid JiK document

Defined in

src/json.d.ts:243


stringify()

stringify(value, options)

stringify(value, options?): string

Stringify the given JSON value into JiK text

Parameters

value: unknown

The JSON value to encode

options?: StringifyOptions

Optional options

Returns

string

Throws

If the given JSON value contains cycles.

Defined in

src/json.d.ts:305

stringify(value, replacer, indentation)

stringify(value, replacer?, indentation?): string

Stringify the given JSON value into JiK text

This function's signrature is explicitly kept similar to JSON.stringify.

Parameters

value: unknown

The JSON value to encode

replacer?

indentation?: string | number

The indentation to give each nested level of node, either the actual indentation string or the number of spaces

Returns

string

Throws

If the given JSON value contains cycles.

Defined in

src/json.d.ts:315


toJson()

toJson(nodeOrDocument, options)

toJson(nodeOrDocument, options): JsonObject

Extract the JSON value encoded into the given JiK node or document.

If passed a document, the document must contain a single node, which acts as the root of the JiK value.

Parameters

nodeOrDocument: Node | Document

A valid JiK node or a document containing a single node which is a valid JiK node

options: ToJsonOptions & ToJsonType<"object"> & object

Returns

JsonObject

See

https://github.com/kdl-org/kdl/blob/76d5dd542a9043257bc65476c0a70b94667052a7/JSON-IN-KDL.md

Throws

If the given node is not a valid JiK node or if the given document doesn't contain exactly one node

Defined in

src/json.d.ts:101

toJson(nodeOrDocument, options)

toJson(nodeOrDocument, options): JsonValue[]

Extract the JSON value encoded into the given JiK node or document.

If passed a document, the document must contain a single node, which acts as the root of the JiK value.

Parameters

nodeOrDocument: Node | Document

A valid JiK node or a document containing a single node which is a valid JiK node

options: ToJsonOptions & ToJsonType<"array"> & object

Returns

JsonValue[]

See

https://github.com/kdl-org/kdl/blob/76d5dd542a9043257bc65476c0a70b94667052a7/JSON-IN-KDL.md

Throws

If the given node is not a valid JiK node or if the given document doesn't contain exactly one node

Defined in

src/json.d.ts:114

toJson(nodeOrDocument, options)

toJson(nodeOrDocument, options?): JsonValue

Extract the JSON value encoded into the given JiK node or document.

If passed a document, the document must contain a single node, which acts as the root of the JiK value.

Parameters

nodeOrDocument: Node | Document

A valid JiK node or a document containing a single node which is a valid JiK node

options?: ToJsonOptions & Partial<ToJsonType<string>> & Partial<ToJsonReviver<JsonValue>>

Returns

JsonValue

See

https://github.com/kdl-org/kdl/blob/76d5dd542a9043257bc65476c0a70b94667052a7/JSON-IN-KDL.md

Throws

If the given node is not a valid JiK node or if the given document doesn't contain exactly one node

Defined in

src/json.d.ts:127

toJson(nodeOrDocument, options)

toJson(nodeOrDocument, options?): unknown

Extract the JSON value encoded into the given JiK node or document.

If passed a document, the document must contain a single node, which acts as the root of the JiK value.

Parameters

nodeOrDocument: Node | Document

A valid JiK node or a document containing a single node which is a valid JiK node

options?: ToJsonOptions & Partial<ToJsonType<string>> & Partial<ToJsonReviver<unknown>>

Returns

unknown

See

https://github.com/kdl-org/kdl/blob/76d5dd542a9043257bc65476c0a70b94667052a7/JSON-IN-KDL.md

Throws

If the given node is not a valid JiK node or if the given document doesn't contain exactly one node

Defined in

src/json.d.ts:142