tjson-js

JavaScript-compatible implementation of Tagged JSON (TJSON), written in TypeScript.

TJSON is a microformat which supplements JSON with an extended set of data types by supplying a type "tag" embedded in object member names:

{
  "array-example:A<O>": [
    {
      "string-example:s": "foobar",
      "binary-example:d": "QklOQVJZ",
      "float-example:f": 0.42,
      "int-example:i": "42",
      "timestamp-example:t": "2016-11-06T22:27:34Z",
      "boolean-example:b": true
    }
  ],
  "set-example:S<i>": [1, 2, 3]
}

Help and Discussion

Have questions? Want to suggest a feature or change?

• TJSON Gitter: web-based chat
• TJSON Google Group: join via web or email (tjson+subscribe@googlegroups.com)

Requirements

tjson-js is presently targeting ES2017. This is because we soon plan on making use of the TC39 BigInt type when it becomes available, and want to make sure users of this library can handle modern ECMAScript versions.

Please make sure your JS runtime is ES2017 compliant, or use a transpiler like babel support older versions of ECMAScript.

Installation

Via npm:

npm install tjson-js

Via Yarn:

yarn install tjson-js

Import TJSON into your project with:

import TJSON from "tjson-js";

API

TJSON.parse()

The TJSON.parse() method parses a TJSON string, returning an Object described by the string. This method is analogous to JavaScript's built-in JSON.parse() method.

TJSON.parse(tjsonString[, decodeUTF8 = true])

Parameters

• tjsonString: The string to parse, containing data serialized as TJSON.

• decodeUTF8: instructs whether or not to first decode the TJSON string from UTF-8 before parsing it. By default UTF-8 will be automatically decoded to the engine's internal string representation (e.g. UCS-2). If you would like to skip automatic encoding conversions (e.g. because they happen at the I/O boundary) pass false.

Example

TJSON.parse('{"some-string-data:s":"Hello, world!","some-time-ago:t":"2017-04-22T20:40:53.182Z"}');
// Object { some-string-data: "Hello, world!", some-time-ago: Sat Apr 22 2017 13:40:53 GMT-0700 (PDT) }

TJSON.stringify()

The TJSON.stringify() method converts a JavaScript value to a TJSON string. This method is analogous to JavaScript's built-in JSON.stringify() method.

TJSON.stringify(value[, space = 0[, encodeUTF8 = true]])

Parameters

• value: The value to convert to a TJSON string.

• space: a String or Number object that's to insert white space into the output JSON string for readability purposes. For more information, please see the JSON.stringify() documentation.

• encodeUTF8: instructs whether or not to encode the resulting document as UTF-8. The TJSON specification requires all confirming documents are encoded as UTF-8. If you would like to skip automatic encoding conversions (e.g. because they happen at the I/O boundary) pass false.

Type Conversions

The table below shows how TJSON tags map to JavaScript types:

Tag	JavaScript Type	Notes
O	Object
A	Array
S	Set
b	Boolean
d	Uint8Array
f	Number
i	Number	Will switch to TC39 BigInt when available
u	Number	Will switch to TC39 BigInt when available
s	String
t	Date

TJSON Spec Deviations

This is not (yet) a fully compliant TJSON parser. It contains the following defects, which can also be found in tjson.spec.ts's skipped examples:

• 64-bit integer range unsupported: can't be supported in JavaScript until the TC39 BigInt type is available.
• Repeated JSON object member names tolerated: the spec mandates that the names of JSON object members must be unique. This implementation silently ignores them.
• Set uniqueness not guaranteed: the spec mandates that all members of sets must be unique. Unfortunately JavaScript's Set type and equality semantics allow members that are identical if compared by value.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/tjson/tjson-js

License

Copyright (c) 2017 Tony Arcieri. Distributed under the MIT License. See LICENSE.txt for further details.