From cec253fb9a177ac810ec96f4f87186506091fa37 Mon Sep 17 00:00:00 2001 From: dcodeIO Date: Fri, 30 Dec 2016 14:37:44 +0100 Subject: [PATCH] New: Copy-pasted typescript definitions to micro modules, see #599 --- examples/reader-writer.js | 4 ++-- src/util/aspromise/index.d.ts | 9 +++++++ src/util/base64/index.d.ts | 33 +++++++++++++++++++++++++ src/util/codegen/index.d.ts | 23 ++++++++++++++++++ src/util/eventemitter/index.d.ts | 41 ++++++++++++++++++++++++++++++++ src/util/extend/index.d.ts | 8 +++++++ src/util/fetch/index.d.ts | 18 ++++++++++++++ src/util/inquire/index.d.ts | 7 ++++++ src/util/path/index.d.ts | 30 +++++++++++++++++++++++ src/util/pool/index.d.ts | 30 +++++++++++++++++++++++ src/util/utf8/index.d.ts | 32 +++++++++++++++++++++++++ 11 files changed, 233 insertions(+), 2 deletions(-) create mode 100644 src/util/aspromise/index.d.ts create mode 100644 src/util/base64/index.d.ts create mode 100644 src/util/codegen/index.d.ts create mode 100644 src/util/eventemitter/index.d.ts create mode 100644 src/util/extend/index.d.ts create mode 100644 src/util/fetch/index.d.ts create mode 100644 src/util/inquire/index.d.ts create mode 100644 src/util/path/index.d.ts create mode 100644 src/util/pool/index.d.ts create mode 100644 src/util/utf8/index.d.ts diff --git a/examples/reader-writer.js b/examples/reader-writer.js index f788be8fc..36ab58315 100644 --- a/examples/reader-writer.js +++ b/examples/reader-writer.js @@ -2,13 +2,13 @@ var protobuf = require(".."); var writer = protobuf.Writer.create(); var buffer = writer - .int32(1 << 3 | 2) // id 1, wireType 2 + .uint32((1 << 3 | 2) >>> 0) // id 1, wireType 2 .string("hello world!") .finish(); var reader = protobuf.Reader.create(buffer); while (reader.pos < reader.len) { - var tag = reader.int32(); + var tag = reader.uint32(); switch (tag>>>3) { case 1: console.log(reader.string()); diff --git a/src/util/aspromise/index.d.ts b/src/util/aspromise/index.d.ts new file mode 100644 index 000000000..912560b85 --- /dev/null +++ b/src/util/aspromise/index.d.ts @@ -0,0 +1,9 @@ +/** + * Returns a promise from a node-style callback function. + * @memberof util + * @param {function(?Error, ...*)} fn Function to call + * @param {*} ctx Function context + * @param {...*} params Function arguments + * @returns {Promise<*>} Promisified function + */ +declare function asPromise(fn: () => any, ctx: any, params: any): Promise; diff --git a/src/util/base64/index.d.ts b/src/util/base64/index.d.ts new file mode 100644 index 000000000..f7f492bec --- /dev/null +++ b/src/util/base64/index.d.ts @@ -0,0 +1,33 @@ +/** + * A minimal base64 implementation for number arrays. + * @memberof util + * @namespace + */ +declare module base64 { + + /** + * Calculates the byte length of a base64 encoded string. + * @param {string} string Base64 encoded string + * @returns {number} Byte length + */ + function length(string: string): number; + + /** + * Encodes a buffer to a base64 encoded string. + * @param {Uint8Array} buffer Source buffer + * @param {number} start Source start + * @param {number} end Source end + * @returns {string} Base64 encoded string + */ + function encode(buffer: Uint8Array, start: number, end: number): string; + + /** + * Decodes a base64 encoded string to a buffer. + * @param {string} string Source string + * @param {Uint8Array} buffer Destination buffer + * @param {number} offset Destination offset + * @returns {number} Number of bytes written + * @throws {Error} If encoding is invalid + */ + function decode(string: string, buffer: Uint8Array, offset: number): number; +} diff --git a/src/util/codegen/index.d.ts b/src/util/codegen/index.d.ts new file mode 100644 index 000000000..96b2eef93 --- /dev/null +++ b/src/util/codegen/index.d.ts @@ -0,0 +1,23 @@ +/** + * A codegen instance as returned by {@link codegen}, that also is a sprintf-like appender function. + * @typedef Codegen + * @type {function} + * @param {string} format Format string + * @param {...*} args Replacements + * @returns {Codegen} Itself + * @property {function(string=):string} str Stringifies the so far generated function source. + * @property {function(string=, Object=):function} eof Ends generation and builds the function whilst applying a scope. + */ +type Codegen = (format: string, args: any) => Codegen; + +/** + * A closure for generating functions programmatically. + * @memberof util + * @namespace + * @function + * @param {...string} params Function parameter names + * @returns {Codegen} Codegen instance + * @property {boolean} supported Whether code generation is supported by the environment. + * @property {boolean} verbose=false When set to true, codegen will log generated code to console. Useful for debugging. + */ +declare function codegen(params: string): Codegen; diff --git a/src/util/eventemitter/index.d.ts b/src/util/eventemitter/index.d.ts new file mode 100644 index 000000000..069cdb743 --- /dev/null +++ b/src/util/eventemitter/index.d.ts @@ -0,0 +1,41 @@ +/** + * Constructs a new event emitter instance. + * @classdesc A minimal event emitter. + * @memberof util + * @constructor + */ +declare class EventEmitter { + + /** + * Constructs a new event emitter instance. + * @classdesc A minimal event emitter. + * @memberof util + * @constructor + */ + constructor(); + + /** + * Registers an event listener. + * @param {string} evt Event name + * @param {function} fn Listener + * @param {*} [ctx] Listener context + * @returns {util.EventEmitter} `this` + */ + on(evt: string, fn: () => any, ctx?: any): EventEmitter; + + /** + * Removes an event listener or any matching listeners if arguments are omitted. + * @param {string} [evt] Event name. Removes all listeners if omitted. + * @param {function} [fn] Listener to remove. Removes all listeners of `evt` if omitted. + * @returns {util.EventEmitter} `this` + */ + off(evt?: string, fn?: () => any): EventEmitter; + + /** + * Emits an event by calling its listeners with the specified arguments. + * @param {string} evt Event name + * @param {...*} args Arguments + * @returns {util.EventEmitter} `this` + */ + emit(evt: string, args: any): EventEmitter; +} diff --git a/src/util/extend/index.d.ts b/src/util/extend/index.d.ts new file mode 100644 index 000000000..ee7ad4a6b --- /dev/null +++ b/src/util/extend/index.d.ts @@ -0,0 +1,8 @@ +/** + * Lets the specified constructor extend `this` class. + * @memberof util + * @param {*} ctor Extending constructor + * @returns {Object.} Constructor prototype + * @this Function + */ +declare function extend(this: Function, ctor: any): { [k: string]: any }; diff --git a/src/util/fetch/index.d.ts b/src/util/fetch/index.d.ts new file mode 100644 index 000000000..710d7994c --- /dev/null +++ b/src/util/fetch/index.d.ts @@ -0,0 +1,18 @@ +/** + * Node-style callback as used by {@link util.fetch}. + * @typedef FetchCallback + * @type {function} + * @param {?Error} error Error, if any, otherwise `null` + * @param {string} [contents] File contents, if there hasn't been an error + * @returns {undefined} + */ +type FetchCallback = (error: Error, contents?: string) => void; + +/** + * Fetches the contents of a file. + * @memberof util + * @param {string} path File path or url + * @param {FetchCallback} [callback] Callback function + * @returns {Promise|undefined} A Promise if `callback` has been omitted + */ +declare function fetch(path: string, callback?: FetchCallback): (Promise|undefined); diff --git a/src/util/inquire/index.d.ts b/src/util/inquire/index.d.ts new file mode 100644 index 000000000..8ebce566a --- /dev/null +++ b/src/util/inquire/index.d.ts @@ -0,0 +1,7 @@ +/** + * Requires a module only if available. + * @memberof util + * @param {string} moduleName Module to require + * @returns {?Object} Required module if available and not empty, otherwise `null` + */ +declare function inquire(moduleName: string): Object; diff --git a/src/util/path/index.d.ts b/src/util/path/index.d.ts new file mode 100644 index 000000000..b9af93ffb --- /dev/null +++ b/src/util/path/index.d.ts @@ -0,0 +1,30 @@ +/** + * A minimal path module to resolve Unix, Windows and URL paths alike. + * @memberof util + * @namespace + */ +declare module path { + + /** + * Tests if the specified path is absolute. + * @param {string} path Path to test + * @returns {boolean} `true` if path is absolute + */ + function isAbsolute(path: string): boolean; + + /** + * Normalizes the specified path. + * @param {string} path Path to normalize + * @returns {string} Normalized path + */ + function normalize(path: string): string; + + /** + * Resolves the specified include path against the specified origin path. + * @param {string} originPath Path to the origin file + * @param {string} includePath Include path relative to origin path + * @param {boolean} [alreadyNormalized=false] `true` if both paths are already known to be normalized + * @returns {string} Path to the include file + */ + function resolve(originPath: string, includePath: string, alreadyNormalized?: boolean): string; +} \ No newline at end of file diff --git a/src/util/pool/index.d.ts b/src/util/pool/index.d.ts new file mode 100644 index 000000000..1f902746c --- /dev/null +++ b/src/util/pool/index.d.ts @@ -0,0 +1,30 @@ +/** + * An allocator as used by {@link util.pool}. + * @typedef PoolAllocator + * @type {function} + * @param {number} size Buffer size + * @returns {Uint8Array} Buffer + */ +type PoolAllocator = (size: number) => Uint8Array; + +/** + * A slicer as used by {@link util.pool}. + * @typedef PoolSlicer + * @type {function} + * @param {number} start Start offset + * @param {number} end End offset + * @returns {Uint8Array} Buffer slice + * @this {Uint8Array} + */ +type PoolSlicer = (this: Uint8Array, start: number, end: number) => Uint8Array; + +/** + * A general purpose buffer pool. + * @memberof util + * @function + * @param {PoolAllocator} alloc Allocator + * @param {PoolSlicer} slice Slicer + * @param {number} [size=8192] Slab size + * @returns {PoolAllocator} Pooled allocator + */ +declare function pool(alloc: PoolAllocator, slice: PoolSlicer, size?: number): PoolAllocator; diff --git a/src/util/utf8/index.d.ts b/src/util/utf8/index.d.ts new file mode 100644 index 000000000..6fa07bf06 --- /dev/null +++ b/src/util/utf8/index.d.ts @@ -0,0 +1,32 @@ +/** + * A minimal UTF8 implementation for number arrays. + * @memberof util + * @namespace + */ +declare module utf8 { + + /** + * Calculates the UTF8 byte length of a string. + * @param {string} string String + * @returns {number} Byte length + */ + function length(string: string): number; + + /** + * Reads UTF8 bytes as a string. + * @param {Uint8Array} buffer Source buffer + * @param {number} start Source start + * @param {number} end Source end + * @returns {string} String read + */ + function read(buffer: Uint8Array, start: number, end: number): string; + + /** + * Writes a string as UTF8 bytes. + * @param {string} string Source string + * @param {Uint8Array} buffer Destination buffer + * @param {number} offset Destination offset + * @returns {number} Bytes written + */ + function write(string: string, buffer: Uint8Array, offset: number): number; +}