diff --git a/msgpack-lite/index.d.ts b/msgpack-lite/index.d.ts index 400d22b2e7..53ed592afa 100644 --- a/msgpack-lite/index.d.ts +++ b/msgpack-lite/index.d.ts @@ -1,14 +1,72 @@ -// Type definitions for msgpack-lite 0.1.20 +// Type definitions for msgpack-lite v0.1.26 // Project: https://github.com/kawanet/msgpack-lite -// Definitions by: Endel Dreyer +// Definitions by: Endel Dreyer , Edmund Fokschaner // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped /// -declare module "msgpack-lite" { - import { Transform } from "stream"; +declare module 'msgpack-lite' { + import * as stream from 'stream'; namespace MsgpackLite { - interface BufferOptions { codec: any; } + /** + * encode from JS Object to MessagePack + */ + function encode(input: any, options?: EncoderOptions): Buffer; + + /** + * decode from MessagePack to JS Object + */ + function decode(input: Buffer | Uint8Array | Array, options?: DecoderOptions): any; + + /** + * create a stream that encodes from JS Object to MessagePack + */ + function createEncodeStream(options?: EncoderOptions & stream.TransformOptions ): EncodeStream; + + /** + * create a stream that decodes from MessagePack (Buffer) to JS Object + */ + function createDecodeStream(options?: DecoderOptions & stream.TransformOptions): DecodeStream; + + /** + * Codecs allow for Custom Extension Types + * Register a custom extension type number to serialize/deserialize your own class instances. + * https://github.com/kawanet/msgpack-lite#custom-extension-types-codecs + * If you wish to modify the default built-in codec, you can access it at msgpack.codec.preset + */ + function createCodec(options?: CodecOptions): Codec; + + /** + * The default built-in codec + */ + var codec: { + /** + * The default built-in codec + */ + preset: Codec; + }; + + interface Codec { + /** + * Register a custom extension to serialize your own class instances + * + * @param etype an integer within the range of 0 and 127 (0x0 and 0x7F) + * @param Class the constructor of the type you wish to serialize + * @param packer a function that converts an instance of T to bytes + */ + addExtPacker( + etype: number, + Class: new(...args: any[]) => T, + packer: (t: T) => Buffer | Uint8Array): void; + + /** + * Register a custom extension to deserialize your own class instances + * + * @param etype an integer within the range of 0 and 127 (0x0 and 0x7F) + * @param unpacker a function that converts bytes to an instance of T + */ + addExtUnpacker(etype: number, unpacker: (data: Buffer | Uint8Array) => T): void; + } interface Encoder { bufferish: any; @@ -42,29 +100,59 @@ declare module "msgpack-lite" { end: (chunk: any) => void; } - interface EncodeStream extends Transform { + interface EncodeStream extends stream.Transform { encoder: Encoder; } - interface DecodeStream extends Transform { + + interface DecodeStream extends stream.Transform { decoder: Decoder; } - interface Codec { - new (options?: any): Codec; - options: any; - init (): void; - addExtPacker (etype: number, Class: any, packer: (value: any) => any): void; - getExtPacker (value: any): (value: any) => any; - addExtUnpacker (etype: number, unpacker: (value: any) => any): void; - getExtUnpacker (etype: number): (value: any) => any; + interface CodecOptions { + /** + * It includes the preset extensions for JavaScript native objects. + * @see https://github.com/kawanet/msgpack-lite#extension-types + * @default false + */ + preset?: boolean; + /** + * It runs a validation of the value before writing it into buffer. + * This is the default behavior for some old browsers which do not support ArrayBuffer object. + * @default varies + */ + safe?: boolean; + /** + * It uses raw formats instead of bin and str. + * Set true for compatibility with msgpack's old spec. + * @see https://github.com/kawanet/msgpack-lite#compatibility-mode + * @default false + */ + raw?: boolean; + /** + * It decodes msgpack's int64/uint64 formats with int64-buffer object. + * int64-buffer is a cutom integer type with 64 bits of precision instead + * of the built-in IEEE-754 53 bits. See https://github.com/kawanet/int64-buffer + * @default false + */ + int64?: boolean; + /** + * It ties msgpack's bin format with ArrayBuffer object, instead of Buffer object. + * @default false + */ + binarraybuffer?: boolean; + /** + * It returns Uint8Array object when encoding, instead of Buffer object. + */ + uint8array?: boolean; } - export function encode(input: any, options?: BufferOptions): any; - export function decode(input: Buffer | Uint8Array | Array, options?: BufferOptions): any; - export function createEncodeStream (): EncodeStream; - export function createDecodeStream (): DecodeStream; - export function createCodec (options?: any): Codec; - export function codec (): { preset: Codec }; + interface EncoderOptions { + codec?: Codec + } + + interface DecoderOptions { + codec?: Codec + } } export = MsgpackLite; diff --git a/msgpack-lite/msgpack-lite-tests.ts b/msgpack-lite/msgpack-lite-tests.ts index f6d8725754..3608e6bfd9 100644 --- a/msgpack-lite/msgpack-lite-tests.ts +++ b/msgpack-lite/msgpack-lite-tests.ts @@ -1,5 +1,75 @@ +import * as msgpack from 'msgpack-lite'; -import * as msgpack from "msgpack-lite"; +// https://github.com/kawanet/msgpack-lite#encoding-and-decoding-messagepack +function encodingAndDecoding() { + // encode from JS Object to MessagePack (Buffer) + var buffer = msgpack.encode({"foo": "bar"}); -var encoded = msgpack.encode(""); -msgpack.decode(encoded); + // decode from MessagePack (Buffer) to JS Object + var data = msgpack.decode(buffer); // => {"foo": "bar"} +} + +// https://github.com/kawanet/msgpack-lite#writing-to-messagepack-stream +function writingToStream() { + var fs = require("fs"); + + var writeStream = fs.createWriteStream("test.msp"); + var encodeStream = msgpack.createEncodeStream(); + encodeStream.pipe(writeStream); + + // send multiple objects to stream + encodeStream.write({foo: "bar"}); + encodeStream.write({baz: "qux"}); + + // call this once you're done writing to the stream. + encodeStream.end(); +} + +// https://github.com/kawanet/msgpack-lite#reading-from-messagepack-stream +function readingFromStream() { + var fs = require("fs"); + var msgpack = require("msgpack-lite"); + + var readStream = fs.createReadStream("test.msp"); + var decodeStream = msgpack.createDecodeStream(); + + // show multiple objects decoded from stream + readStream.pipe(decodeStream).on("data", console.warn); +} + +// https://github.com/kawanet/msgpack-lite#decoding-messagepack-bytes-array +function decodingBytesArray() { + // decode() accepts Buffer instance per default + msgpack.decode(new Buffer([0x81, 0xA3, 0x66, 0x6F, 0x6F, 0xA3, 0x62, 0x61, 0x72])); + + // decode() also accepts Array instance + msgpack.decode([0x81, 0xA3, 0x66, 0x6F, 0x6F, 0xA3, 0x62, 0x61, 0x72]); + + // decode() accepts raw Uint8Array instance as well + msgpack.decode(new Uint8Array([0x81, 0xA3, 0x66, 0x6F, 0x6F, 0xA3, 0x62, 0x61, 0x72])); +} + +// https://github.com/kawanet/msgpack-lite#custom-extension-types-codecs +function customExtensionTypes() { + var codec = msgpack.createCodec(); + codec.addExtPacker(0x3F, MyVector, myVectorPacker); + codec.addExtUnpacker(0x3F, myVectorUnpacker); + + var data = new MyVector(1, 2); + var encoded = msgpack.encode(data, {codec: codec}); + var decoded = msgpack.decode(encoded, {codec: codec}); + + class MyVector { + constructor(public x: number, public y: number) {} + } + + function myVectorPacker(vector: MyVector) { + var array = [vector.x, vector.y]; + return msgpack.encode(array); // return Buffer serialized + } + + function myVectorUnpacker(buffer: Buffer | Uint8Array): MyVector { + var array = msgpack.decode(buffer); + return new MyVector(array[0], array[1]); // return Object deserialized + } +} diff --git a/msgpack-lite/tsconfig.json b/msgpack-lite/tsconfig.json index 39588c1eef..6070c69ece 100644 --- a/msgpack-lite/tsconfig.json +++ b/msgpack-lite/tsconfig.json @@ -4,7 +4,7 @@ "target": "es6", "noImplicitAny": true, "noImplicitThis": true, - "strictNullChecks": false, + "strictNullChecks": true, "baseUrl": "../", "typeRoots": [ "../"