tjson-js
Version:
Tagged JSON (TJSON): a JSON-based microformat with rich type annotations
183 lines (132 loc) • 6.96 kB
Markdown
# tjson-js [![npm version][npm-version]][npm-link] [![Build Status][build-image]][build-link] [![MIT licensed][license-image]][license-link]
[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<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]
}
```
[TJSON]: https://www.tjson.org
## 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])
[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
## Requirements
tjson-js is presently targeting <b>ES2017</b>. 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/
## Installation
Via [npm](https://www.npmjs.com/):
```bash
npm install tjson-js
```
Via [Yarn](https://yarnpkg.com/):
```bash
yarn install tjson-js
```
Import TJSON into your project with:
```js
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])
```
[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) }
```
### 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]])
```
[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`.
## 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 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
## 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][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
## 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](https://github.com/tjson/tjson-js/blob/master/LICENSE.txt)
for further details.