Tagged JSON (TJSON): a JSON-based microformat with rich type annotations
npm install tjson-js[npm-version]: https://badge.fury.io/js/tjson-js.svg
[npm-link]: https://www.npmjs.com/package/tjson-js
[build-image]: https://secure.travis-ci.org/tjson/tjson-js.svg?branch=master
[build-link]: https://travis-ci.org/tjson/tjson-js
[license-image]: https://img.shields.io/badge/license-MIT-blue.svg
[license-link]: https://github.com/tjson/tjson-ruby/blob/master/LICENSE.txt
JavaScript-compatible implementation of [Tagged JSON (TJSON)][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:
``json`
{
"array-example:A
{
"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": [1, 2, 3]
}
[TJSON]: https://www.tjson.org
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])
[TJSON Gitter]: https://gitter.im/tjson/Lobby
[TJSON Google Group]: https://groups.google.com/forum/#!forum/tjson
[tjson+subscribe@googlegroups.com]: mailto:tjson+subscribe@googlegroups.com
tjson-js is presently targeting ES2017. This is because we soon plan on
making use of the [TC39 Integer] 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.
[babel]: https://babeljs.io/docs/plugins/preset-es2017/
Via npm:
`bash`
npm install tjson-js
Via Yarn:
`bash`
yarn install tjson-js
Import TJSON into your project with:
`js`
import TJSON from "tjson-js";
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])
[JSON.parse()]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse
#### 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
`js`
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) }
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]])
[JSON.stringify()]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
#### 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.
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 Integer] when available |u
| | [Number] | Will switch to [TC39 Integer] when available |s
| | [String] | |t
| | [Date] | |
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Objects
[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Indexed_collections_Arrays_and_typed_Arrays
[Set]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
[Boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type
[Uint8Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
[Number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type
[TC39 Integer]: https://tc39.github.io/proposal-integer/
[String]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type
[Date]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
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][errata]:
* 64-bit integer range unsupported: can't be supported in JavaScript until
the [TC39 Integer] 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.
[errata]: https://github.com/tjson/tjson-js/blob/master/test/tjson.spec.ts#L8
Bug reports and pull requests are welcome on GitHub at https://github.com/tjson/tjson-js
Copyright (c) 2017 Tony Arcieri. Distributed under the MIT License. See
LICENSE.txt
for further details.