From 86dd576f598df84b389f3df8970a89e8d8075b7d Mon Sep 17 00:00:00 2001 From: Fredrick Eisele Date: Fri, 7 Apr 2017 11:08:25 -0500 Subject: [PATCH 1/4] Add basic type-script definitions --- .gitignore | 6 +- README_ts.md | 289 ++++++++++++++++++++++++++++++++ package.json | 1 + types/transit.d.ts | 77 +++++++++ types/transit/caching.d.ts | 5 + types/transit/impl/decoder.d.ts | 4 + types/transit/impl/reader.d.ts | 5 + types/transit/impl/writer.d.ts | 4 + types/transit/types.d.ts | 10 ++ 9 files changed, 400 insertions(+), 1 deletion(-) create mode 100644 README_ts.md create mode 100644 types/transit.d.ts create mode 100644 types/transit/caching.d.ts create mode 100644 types/transit/impl/decoder.d.ts create mode 100644 types/transit/impl/reader.d.ts create mode 100644 types/transit/impl/writer.d.ts create mode 100644 types/transit/types.d.ts 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/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 bb75f05..132159c 100644 --- a/package.json +++ b/package.json @@ -20,6 +20,7 @@ "url": "git://github.com/cognitect/transit-js.git" }, "main": "target/transit.js", + "types": "types/transit.d.ts", "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..ea83cc6 --- /dev/null +++ b/types/transit.d.ts @@ -0,0 +1,77 @@ + +/// +/// +/// +/// +/// + +/** + * http://cognitect.github.io/transit-js/classes/transit.html + */ + +declare module "transit" { + import { + TaggedValue, Keyword, + TransitArrayMap, TransitMap, TransitSet, + UUID + } 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 interface WriteHandler { + tag: any; + rep: any; + stringRep: any; + getVerboseHandler?: boolean; + } + + 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 function readCache(): ReadCache; + export function reader(type: "json" | "json-verbose", opts: any): 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 function writeCache(): WriteCache; + export function writer(type: "json" | "json-verbose", opts: any ): 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..3e99521 --- /dev/null +++ b/types/transit/impl/reader.d.ts @@ -0,0 +1,5 @@ + + +declare module "transit.impl.reader" { + export type Reader = 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..abceef0 --- /dev/null +++ b/types/transit/impl/writer.d.ts @@ -0,0 +1,4 @@ + +declare module "transit.impl.writer" { + export type Writer = 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..f3dce44 --- /dev/null +++ b/types/transit/types.d.ts @@ -0,0 +1,10 @@ + +declare module "transit.types" { + + export type TaggedValue = any; + export type Keyword = any; + export type TransitArrayMap = any; + export type TransitMap = any; + export type TransitSet = any; + export type UUID = any; +} \ No newline at end of file From 34d3b7a5a19b7ed9dfc1428bd7066cb5a282e4d8 Mon Sep 17 00:00:00 2001 From: Fredrick Eisele Date: Fri, 7 Apr 2017 11:27:29 -0500 Subject: [PATCH 2/4] expand types --- types/transit.d.ts | 4 ++-- types/transit/types.d.ts | 30 ++++++++++++++++++++++++++++-- 2 files changed, 30 insertions(+), 4 deletions(-) diff --git a/types/transit.d.ts b/types/transit.d.ts index ea83cc6..5bb46ab 100644 --- a/types/transit.d.ts +++ b/types/transit.d.ts @@ -11,9 +11,9 @@ declare module "transit" { import { - TaggedValue, Keyword, + TaggedValue, Symbol, Keyword, TransitArrayMap, TransitMap, TransitSet, - UUID + UUID, BigDecimal, Binary, URI } from "transit.types"; import { Decoder } from "transit.impl.decoder"; import { ReadCache, WriteCache } from "transit.caching"; diff --git a/types/transit/types.d.ts b/types/transit/types.d.ts index f3dce44..5767e17 100644 --- a/types/transit/types.d.ts +++ b/types/transit/types.d.ts @@ -1,10 +1,36 @@ declare module "transit.types" { - export type TaggedValue = any; + 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; - export type UUID = any; } \ No newline at end of file From cc8a47692227c0fcb69c38cc9169bfabfe07d6dc Mon Sep 17 00:00:00 2001 From: Fredrick Eisele Date: Fri, 7 Apr 2017 15:49:40 -0500 Subject: [PATCH 3/4] typed options and renamed module --- types/transit.d.ts | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/types/transit.d.ts b/types/transit.d.ts index 5bb46ab..eeb144a 100644 --- a/types/transit.d.ts +++ b/types/transit.d.ts @@ -9,7 +9,7 @@ * http://cognitect.github.io/transit-js/classes/transit.html */ -declare module "transit" { +declare module "transit-js" { import { TaggedValue, Symbol, Keyword, TransitArrayMap, TransitMap, TransitSet, @@ -20,12 +20,6 @@ declare module "transit" { import { Reader } from "transit.impl.reader"; import { Writer } from "transit.impl.writer"; - export interface WriteHandler { - tag: any; - rep: any; - stringRep: any; - getVerboseHandler?: boolean; - } export function bigDec(s: string): TaggedValue; export function bigInt(s: string): TaggedValue; @@ -61,17 +55,36 @@ declare module "transit" { 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 function readCache(): ReadCache; - export function reader(type: "json" | "json-verbose", opts: any): Reader; + export function reader(type: "json" | "json-verbose", 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: "json" | "json-verbose", opts: any ): Writer; - + export function writer(type: "json" | "json-verbose", opts?: WriterOptions): Writer; + } From e93db2d3ac544aac0c54f1a906c425d97425951f Mon Sep 17 00:00:00 2001 From: Fredrick Eisele Date: Mon, 26 Jun 2017 15:56:48 -0500 Subject: [PATCH 4/4] updates reader/writer interface --- .npmignore | 7 +++++++ package.json | 3 +++ types/transit.d.ts | 6 ++++-- types/transit/impl/reader.d.ts | 4 +++- types/transit/impl/writer.d.ts | 4 +++- 5 files changed, 20 insertions(+), 4 deletions(-) create mode 100644 .npmignore 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/package.json b/package.json index 888858e..9d252f5 100644 --- a/package.json +++ b/package.json @@ -21,6 +21,9 @@ }, "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 index eeb144a..9ad6099 100644 --- a/types/transit.d.ts +++ b/types/transit.d.ts @@ -62,8 +62,10 @@ declare module "transit-js" { mapBuilder?: any; } + export type Encodings = "json" | "json-verbose"; + export function readCache(): ReadCache; - export function reader(type: "json" | "json-verbose", opts?: ReaderOptions): Reader; + export function reader(type: Encodings, opts?: ReaderOptions): Reader; export function set(xs: any[]): TransitSet; export function symbol(name: string): Symbol; @@ -83,7 +85,7 @@ declare module "transit-js" { } export function writeCache(): WriteCache; - export function writer(type: "json" | "json-verbose", opts?: WriterOptions): Writer; + export function writer(type: Encodings, opts?: WriterOptions): Writer; } diff --git a/types/transit/impl/reader.d.ts b/types/transit/impl/reader.d.ts index 3e99521..f777a27 100644 --- a/types/transit/impl/reader.d.ts +++ b/types/transit/impl/reader.d.ts @@ -1,5 +1,7 @@ declare module "transit.impl.reader" { - export type Reader = any; + 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 index abceef0..04e334a 100644 --- a/types/transit/impl/writer.d.ts +++ b/types/transit/impl/writer.d.ts @@ -1,4 +1,6 @@ declare module "transit.impl.writer" { - export type Writer = any; + export interface Writer { + write(payload: any); + } } \ No newline at end of file