diff --git a/.gitignore b/.gitignore index c6942cf..32698f2 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,8 @@ docs deps node_modules target -.idea \ No newline at end of file +.idea +.classpath +.project +.settings/ + diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..d21051a --- /dev/null +++ b/.npmignore @@ -0,0 +1,7 @@ +deps +node_modules +.idea +.classpath +.project +.settings/ +.vscode diff --git a/README_ts.md b/README_ts.md new file mode 100644 index 0000000..d3d8398 --- /dev/null +++ b/README_ts.md @@ -0,0 +1,289 @@ +# transit-js + +Transit is a data format and a set of libraries for conveying values between +applications written in different languages. This library provides support for +marshalling Transit data to/from JavaScript. transit-js will work with any +[ECMAScript-262 Edition +3](http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%203rd%20edition,%20December%201999.pdf) +or newer JavaScript implementation provided that a [JSON](http://www.json.org) +module that supplies `parse` and `stringify` methods is present. transit-js does +not currently support encoding to [MessagePack](http://msgpack.org). Unlike the +Java and Clojure implementations it relies on the non-streaming JSON parsing +mechanism of the host JavaScript environment. + +* [Rationale](http://blog.cognitect.com/blog/2014/7/22/transit) +* [Getting Started](https://github.com/cognitect/transit-js/wiki/Getting-Started), Get up and running ASAP +* [API docs](http://cognitect.github.io/transit-js/classes/transit.html) +* [Specification](http://github.com/cognitect/transit-format) +* [Take a tour!](http://cognitect.github.io/transit-tour) +* [FAQ](http://github.com/cognitect/transit-js/wiki/FAQ), for common transit-js specific questions + +This implementation's major.minor version number corresponds to the version of +the Transit specification it supports. + +_NOTE: Transit is a work in progress and may evolve based on feedback. +As a result, while Transit is a great option for transferring data +between applications, it should not yet be used for storing data +durably over time. This recommendation will change when the +specification is complete._ + +## Releases and Dependency Information + +* Latest release: 0.8.846 +* [All Released Versions](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.cognitect%22%20AND%20a%3A%22transit-js%22) + +### JavaScript + +You can include either the +[release](http://cdn.cognitect.com/transit/transit-0.8.846-min.js) (10K gzipped) +or [development](http://cdn.cognitect.com/transit/transit-0.8.846.js) build of +transit-js on your webpage. We also provide [Require.js](http://requirejs.org) +compatible +[release](http://cdn.cognitect.com/transit/transit-0.8.846-amd-min.js) and +[dev](http://cdn.cognitect.com/transit/transit-0.8.846-amd.js) builds. + +### Node.js + +transit-js is released to [npm](https://www.npmjs.org). Add transit-js to your +`package.json` dependencies: + +```typescript +{... + "dependencies": { + "transit-js": "0.8.846" + } + ...} +``` + +### Bower + +You can also include transit-js in your `bower.json` dependencies: + +```typescript +{... + "dependencies": { + "transit-js": "0.8.846" + } + ...} +``` + +### Maven + +[Maven](http://maven.apache.org/) dependency information: + +```xml + + com.cognitect + transit-js + 0.8.846 + +``` + +## Documentation + +Comprehensive documentation can be found [here](http://cognitect.github.io/transit-js/classes/transit.html). + +## Overview + +transit-js supports the conveyance of semantically rich and extensible +data between heterogenous software systems whose components include +JavaScript servers and clients. + +#### Beyond JSON + +The [Transit rationale](http://blog.cognitect.com/blog/2014/7/22/transit) covers +many of the reasons to put aside the limitations of JSON. As with the other +Transit implementations, transit-js supports conveying a larger range of scalar +and non-scalar values than permitted by JSON. Of these types, the transit-js +handling of the map representation is the most novel from the perspective of a +JavaScript applications developer. + +#### Transit Maps + +Transit representations of maps are decoded by transit-js into a high +performance data structure that largely mirrors the [ECMAScript Edition +6](http://wiki.ecmascript.org/doku.php?id=harmony:specification_drafts) +[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) +data type. Doing so allows natural indexing of data using common scalars like 64 +bit integers and dates without requiring the out of band application logic often +encountered in systems that marshal JSON. + +The adaptive implementation of transit-js maps delivers performance comparable +to plain JavaScript objects and native ES6 Map implementations. + +## Usage + +Please see the [Getting +Started](https://github.com/cognitect/transit-js/wiki/Getting-Started) page. For +an interactive guide check out the +[tour](http://cognitect.github.io/transit-tour). + +From the browser transit-js is available at the top level: + +```javascript +var t = transit; + +function roundtrip(x) { + var r = t.reader("json"), + w = t.writer("json"); + return r.read(w.write(x)); +} + +function testRoundtrip() { + var arr1 = ["red", "green", "blue"], + arr2 = ["apple", "pear", "grape"], + data = t.map(); + data.set(t.integer(1), arr1); + data.set(t.integer(2), arr2); + return t.equals(data, roundtrip(data)); +} +``` + +From Node.js you must require transit-js (assuming you've +included it in your project dependencies): + +```typescript +import t = require("transit-js"); + +function roundtrip(x: any): any { + let r = t.reader("json"); + let w = t.writer("json"); + return r.read(w.write(x)); +} + +function testRoundtrip(): boolean { + const arr1 = ["red", "green", "blue"]; + const arr2 = ["apple", "pear", "grape"]; + let data: t.Map = t.map(); + data.set(t.integer(1), arr1); + data.set(t.integer(2), arr2); + return t.equals(data, roundtrip(data)); +} +``` + +## Default Type Mapping + +Abbreviations: +* t = transit + +|Transit type|Write accepts|Read returns| +|------------|-------------|------------| +|null|null|null| +|string|String|String| +|boolean|Boolean|Boolean| +|integer|Number, t.integer|Number, t.integer| +|decimal|Number|Number| +|keyword|t.keyword|t.keyword| +|symbol|t.symbol|t.symbol| +|big integer|t.tagged|t.tagged| +|big decimal|t.tagged|t.tagged| +|bytes|Buffer, Uint8Array, t.tagged|Buffer, Uint8Array, t.tagged| +|time|Date|Date| +|uri|t.tagged|t.tagged| +|uuid|t.uuid|t.uuid| +|char|String|String| +|array|Array|Array| +|list|t.tagged|t.tagged| +|set|t.set|t.set| +|map|t.map|t.map| +|link|t.tagged|t.tagged| +|cmap|t.map|t.map| + +## Contributing + +This library is open source, developed internally by Cognitect. We welcome +discussions of potential problems and enhancement suggestions on the +[transit-format mailing +list](https://groups.google.com/forum/#!forum/transit-format). Issues can be +filed using GitHub [issues](https://github.com/cognitect/transit-js/issues) for +this project. Because transit is incorporated into products and client projects, +we prefer to do development internally and are not accepting pull requests or +patches. + +## Development + +### Dependencies + +Building and testing transit-js requires +[Node.js](http://nodejs.org). Install the project's additional +development dependencies with the following command from the repo +directory: + +``` +bin/deps +``` + +In order to build transit-js for +[ClojureScript](http://github.com/clojure/clojurescript), +[Maven](http://maven.apache.org) must be installed. + +### Running the tests + +``` +bin/test +``` + +In order to run the `bin/verify` tests from +[transit-format](https://github.com/cognitect/transit-format), you must first +clone transit-format into the same parent directory as your transit-js checkout. +Then build the production Node.js build: + +``` +bin/build_release_node +``` + +### Build + +#### Version + +The build version is automatically incremented. To determine the current build +version: + +``` +build/revision +``` + +#### Build for Node.js + +``` +bin/build_release_node +``` + +#### Build for Browser + +``` +bin/build_release_browser +``` + +#### Building the documentaiton + +``` +bin/docs +``` + +#### Build JAR for ClojureScript + +Assuming you have a +[JDK](http://www.oracle.com/technetwork/java/javaee/downloads/java-ee-sdk-6u3-jdk-7u1-downloads-523391.html) +and [Maven](http://maven.apache.org) installed, the following will install a JAR +suitable for use from ClojureScript into your local Maven repository. + +``` +build/package_local +``` + +## Copyright and License + +Copyright © 2014-2015 Cognitect + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/package.json b/package.json index e39d528..9d252f5 100644 --- a/package.json +++ b/package.json @@ -20,6 +20,10 @@ "url": "git://github.com/cognitect/transit-js.git" }, "main": "target/transit.js", + "types": "types/transit.d.ts", + "directories":{ + "target": "target" + }, "bugs": { "url": "https://github.com/cognitect/transit-js/issues" }, diff --git a/types/transit.d.ts b/types/transit.d.ts new file mode 100644 index 0000000..9ad6099 --- /dev/null +++ b/types/transit.d.ts @@ -0,0 +1,92 @@ + +/// +/// +/// +/// +/// + +/** + * http://cognitect.github.io/transit-js/classes/transit.html + */ + +declare module "transit-js" { + import { + TaggedValue, Symbol, Keyword, + TransitArrayMap, TransitMap, TransitSet, + UUID, BigDecimal, Binary, URI + } from "transit.types"; + import { Decoder } from "transit.impl.decoder"; + import { ReadCache, WriteCache } from "transit.caching"; + import { Reader } from "transit.impl.reader"; + import { Writer } from "transit.impl.writer"; + + + export function bigDec(s: string): TaggedValue; + export function bigInt(s: string): TaggedValue; + export function binary(s: string): TaggedValue | Uint8Array; + export function date(s: string | number): Date; + export function decoder(options: any): Decoder; + export function exentdToEQ(x: any): any; + export function hash(x: any): number; + export function hashArrayLike(x: any): number; + export function hashMapLike(x: any): number; + export function integer(s: number | string): number; + + export function isBigDec(x: any): boolean; + export function isBigInt(x: any): boolean; + export function isBinary(x: any): boolean; + export function isInteger(x: any): boolean; + export function isKeyword(x: any): boolean; + export function isLink(x: any): boolean; + export function isList(x: any): boolean; + export function isMap(x: any): boolean; + export function isQuoted(x: any): boolean; + export function isSet(x: any): boolean; + export function isSymbol(x: any): boolean; + export function isTaggedValue(x: any): boolean; + export function isURI(x: any): boolean; + export function isUUID(x: any): boolean; + + export function keyword(name: string): Keyword; + export function link(a: TransitArrayMap | TransitMap): any; + export function list(a: any[]): TaggedValue; + export function makeWriteHandler(obj: WriteHandler): any; + export function map(xs: any[]): TransitArrayMap | TransitMap; + export function mapToObject(m: TransitArrayMap | TransitMap): any; + export function objectToMap(a: any): TransitArrayMap | TransitMap; + export function quoted(x: any): TaggedValue; + + export interface ReaderOptions { + handlers?: any; + arrayBuilder?: any; + mapBuilder?: any; + } + + export type Encodings = "json" | "json-verbose"; + + export function readCache(): ReadCache; + export function reader(type: Encodings, opts?: ReaderOptions): Reader; + + export function set(xs: any[]): TransitSet; + export function symbol(name: string): Symbol; + export function tagged(tag: string, value: any): TaggedValue; + export function uri(a: string): TaggedValue; + + export interface WriteHandler { + tag: any; + rep: any; + stringRep: any; + getVerboseHandler?: boolean; + } + + export interface WriterOptions { + handlers?: any; + handlerForForeign?: any; + } + + export function writeCache(): WriteCache; + export function writer(type: Encodings, opts?: WriterOptions): Writer; + +} + + diff --git a/types/transit/caching.d.ts b/types/transit/caching.d.ts new file mode 100644 index 0000000..18538b9 --- /dev/null +++ b/types/transit/caching.d.ts @@ -0,0 +1,5 @@ + +declare module "transit.caching" { + export type ReadCache = any; + export type WriteCache = any; +} \ No newline at end of file diff --git a/types/transit/impl/decoder.d.ts b/types/transit/impl/decoder.d.ts new file mode 100644 index 0000000..ed2f462 --- /dev/null +++ b/types/transit/impl/decoder.d.ts @@ -0,0 +1,4 @@ + +declare module "transit.impl.decoder" { + export type Decoder = any; +} \ No newline at end of file diff --git a/types/transit/impl/reader.d.ts b/types/transit/impl/reader.d.ts new file mode 100644 index 0000000..f777a27 --- /dev/null +++ b/types/transit/impl/reader.d.ts @@ -0,0 +1,7 @@ + + +declare module "transit.impl.reader" { + export interface Reader { + read(payload: string): any; + } +} \ No newline at end of file diff --git a/types/transit/impl/writer.d.ts b/types/transit/impl/writer.d.ts new file mode 100644 index 0000000..04e334a --- /dev/null +++ b/types/transit/impl/writer.d.ts @@ -0,0 +1,6 @@ + +declare module "transit.impl.writer" { + export interface Writer { + write(payload: any); + } +} \ No newline at end of file diff --git a/types/transit/types.d.ts b/types/transit/types.d.ts new file mode 100644 index 0000000..5767e17 --- /dev/null +++ b/types/transit/types.d.ts @@ -0,0 +1,36 @@ + +declare module "transit.types" { + + class TransitType { + toString(): string; + equiv(other: any): boolean; + } + + /* + http://cognitect.github.io/transit-js/files/src_com_cognitect_transit_types.js.html + */ + export class TaggedValue extends TransitType { + constructor(tag: string, rep: any); + } + export function taggedValue(tag: string, rep: any): TaggedValue; + export function isTaggedValue(x: any): boolean; + + export function nullValue(): null; + export function boolValue(s: "t" | any): boolean; + + export const MAX_INT: number; + export const MIN_INT: number; + + // classes of TransitType + export type BigDecimal = any; + export type Keyword = any; + export type Symbol = any; + export type UUID = any; + export type Binary = any; + export type URI = any; + + type TransitMapIterator = any; + export type TransitArrayMap = any; + export type TransitMap = any; + export type TransitSet = any; +} \ No newline at end of file