Options for the fromJson function

Properties

allowEntries?

optional allowEntries: boolean

Defined in: src/json.d.ts:166

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.

allowEntriesInArrays?

optional allowEntriesInArrays: boolean

Defined in: src/json.d.ts:177

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.

allowEntriesInObjects?

optional allowEntriesInObjects: boolean

Defined in: src/json.d.ts:189

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.

allowEntriesInRoot?

optional allowEntriesInRoot: boolean

Defined in: src/json.d.ts:199

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.

indentation?

optional indentation: string | number

Defined in: src/json.d.ts:256

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

nodeName?

optional nodeName: string

Defined in: src/json.d.ts:158

Name of the root node to create

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

replaceJsonValue()?

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

Defined in: src/json.d.ts:272

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

Parameter	Type	Description
`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

replaceKdlValue()?

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

Defined in: src/json.d.ts:290

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

Parameter	Type	Description
`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

JiKReviver()<T>

Defined in: src/json.d.ts:216

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

Type Parameter
`T`

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

Defined in: src/json.d.ts:223

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

Parameter	Type	Description
`value`	`JsonValue`	The JSON value
`key`	`string` \| `number`	The key of the value, empty string for the root value
`data`	{ `location`: `Entry` \| `Node`; }	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

JsonObject

Defined in: src/json.d.ts:13

A JSON object

Indexable

[property: string]: JsonValue

StringifyOptions

Defined in: src/json.d.ts:248

Options for the stringify function

Extended by

FromJsonOptions

Properties

indentation?

optional indentation: string | number

Defined in: src/json.d.ts:256

The indentation to give each nested level of node

replaceJsonValue()?

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

Defined in: src/json.d.ts:272

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

Parameter	Type	Description
`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

replaceKdlValue()?

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

Defined in: src/json.d.ts:290

Replacer function called for every KDL node or entry created

Parameters

Parameter	Type	Description
`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

ToJsonOptions

Defined in: src/json.d.ts:31

Options for the toJson function

Properties

ignoreValues?

optional ignoreValues: boolean

Defined in: src/json.d.ts:62

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}),
  ]),
)

ToJsonReviver<T>

Defined in: src/json.d.ts:85

Extra option to modify the return value of the toJson function

Type Parameters

Type Parameter
`T`

Properties

reviver

reviver: JiKReviver<T>

Defined in: src/json.d.ts:89

Reviver to use

ToJsonType<T>

Defined in: src/json.d.ts:68

Extra option for providing a type hint to the toJson function

Type Parameters

Type Parameter
`T`

Properties

type

type: T

Defined in: src/json.d.ts:79

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

Type Aliases

JsonValue

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

Defined in: src/json.d.ts:20

A JSON value

Functions

fromJson()

fromJson(value, options?): Node

Defined in: src/json.d.ts:208

Encode the given JSON value into a JiK node

Parameters

Parameter	Type	Description
`value`	`JsonValue`	The JSON value to encode
`options`?	`FromJsonOptions`	-

Returns

Node

Throws

If the given value contains cycles.

parse()

Call Signature

parse(text, reviver?): JsonValue

Defined in: src/json.d.ts:236

Parse the given JiK text to its encoded JSON value

Parameters

Parameter	Type	Description
`text`	`string`	The JiK text to parse
`reviver`?	`JiKReviver`<`JsonValue`>	-

Returns

JsonValue

Throws

If the given text is not a valid JiK document

Call Signature

parse(text, reviver): unknown

Defined in: src/json.d.ts:243

Parse the given JiK text to its encoded JSON value

Parameters

Parameter	Type	Description
`text`	`string`	The JiK text to parse
`reviver`	`JiKReviver`<`unknown`>	-

Returns

unknown

Throws

If the given text is not a valid JiK document

stringify()

Call Signature

stringify(value, options?): string

Defined in: src/json.d.ts:305

Stringify the given JSON value into JiK text

Parameters

Parameter	Type	Description
`value`	`unknown`	The JSON value to encode
`options`?	`StringifyOptions`	Optional options

Returns

string

Throws

If the given JSON value contains cycles.

Call Signature

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

Defined in: src/json.d.ts:315

Stringify the given JSON value into JiK text

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

Parameters

Parameter	Type	Description
`value`	`unknown`	The JSON value to encode
`replacer`?	(`key`, `value`, `originalValue`) => `unknown`	-
`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.

toJson()

Call Signature

toJson(nodeOrDocument, options): JsonObject

Defined in: src/json.d.ts:101

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

Parameter	Type	Description
`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

Call Signature

toJson(nodeOrDocument, options): JsonValue[]

Defined in: src/json.d.ts:114

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

Parameter	Type	Description
`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

Call Signature

toJson(nodeOrDocument, options?): JsonValue

Defined in: src/json.d.ts:127

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

Parameter	Type	Description
`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`>>	-

toJson(nodeOrDocument, options?): unknown

Defined in: src/json.d.ts:142

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

Parameter	Type	Description
`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`>>	-