From cc13a4517879720cb77bfc24713e2a1bf58ccc8e Mon Sep 17 00:00:00 2001 From: windupbird144 <44092779+windupbird144@users.noreply.github.com> Date: Wed, 3 Nov 2021 08:36:31 +0100 Subject: [PATCH] fixes #27 Add TS types (#30) --- README.md | 13 ++++-- index.d.ts | 89 ++++++++++++++++++++++++++++++++++++++ package.json | 11 +++-- test/types/index.test-d.ts | 21 +++++++++ 4 files changed, 128 insertions(+), 6 deletions(-) create mode 100644 index.d.ts create mode 100644 test/types/index.test-d.ts diff --git a/README.md b/README.md index c9299b7..5a96f63 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ npm i pino-abstract-transport ```js import build from 'pino-abstract-transport' -exports default async function (opts) { +export default async function (opts) { return build(async function (source) { for await (let obj of source) { console.log(obj) @@ -43,6 +43,13 @@ module.exports = function (opts) { } ``` +## Typescript usage +Install the type definitions for node. Make sure the major version of the type definitions matches the node version you are using. +#### Node 16 +``` +npm i -D @types/node@16 +``` + ## API ### build(fn, opts) => Stream @@ -60,7 +67,7 @@ so they can be concatenated into multiple transports. In addition to all events emitted by a [`Readable`](https://nodejs.org/api/stream.html#stream_class_stream_readable) stream, it emits the following events: -* `unknown` where an unparsaeble line is found, both the line and optional error is emitted. +* `unknown` where an unparsable line is found, both the line and optional error is emitted. #### Options @@ -69,7 +76,7 @@ stream, it emits the following events: * `close(err, cb)` a function that is called to shutdown the transport. It's called both on error and non-error shutdowns. It can also return a promise. In this case discard the the `cb` argument. -* `parseLine(line)` a function that is used to parse line recieved from `pino`. +* `parseLine(line)` a function that is used to parse line received from `pino`. ## Example diff --git a/index.d.ts b/index.d.ts new file mode 100644 index 0000000..e7f0f78 --- /dev/null +++ b/index.d.ts @@ -0,0 +1,89 @@ +// Type definitions for pino-abstract-transport 0.4.0 +// Project: https://github.com/pinojs/pino-abstract-transport#readme +// Definitions by: Diyar Oktay + +/// + +import { Transform } from "stream"; + +type BuildOptions = { + /** + * `parseLine(line)` a function that is used to parse line received from pino. + * @default JSON.parse + */ + parseLine?: (line: string) => unknown; + + /** + * `parse` an option to change to data format passed to build function. + * @default undefined + * + */ + parse?: "lines"; + + /** + * `close(err, cb)` a function that is called to shutdown the transport. + * It's called both on error and non-error shutdowns. It can also return + * a promise. In this case discard the the cb argument. + * + * @example + * ```typescript + * { + * close: function (err, cb) { + * process.nextTick(cb, err) + * } + * } + * ``` + * */ + close?: (err: Error, cb: Function) => void | Promise; + + /** + * `metadata` If set to false, do not add metadata properties to the returned stream + */ + metadata?: false; +}; + +/** + * Pass these options to wrap the split2 stream and + * the returned stream into a Duplex + */ +type EnablePipelining = BuildOptions & { + enablePipelining: true; +}; + +interface OnUnknown { + /** + * `unknown` is the event emitted where an unparsable line is found + * + * @param event 'unknown' + * @param line the unparsable line + * @param error the error that was thrown when parsing the line + */ + on(event: "unknown", listener: (line: string, error: unknown) => void): void; +} + +/** + * Create a split2 instance and returns it. This same instance is also passed + * to the given function, which is called synchronously. + * + * @returns {Transform} the split2 instance + */ +declare function build( + fn: (transform: Transform & OnUnknown) => void | Promise, + opts?: BuildOptions +): Transform & OnUnknown; + +/** + * Creates a split2 instance and passes it to the given function, which is called + * synchronously. Then wraps the split2 instance and the returned stream into a + * Duplex, so they can be concatenated into multiple transports. + * + * @returns {Transform} the wrapped split2 instance + */ +declare function build( + fn: (transform: Transform & OnUnknown) => Transform & OnUnknown, + opts: EnablePipelining +): Transform; + +export { OnUnknown }; + +export default build; diff --git a/package.json b/package.json index 6cadc64..8dc77c2 100644 --- a/package.json +++ b/package.json @@ -5,8 +5,8 @@ "main": "index.js", "scripts": { "prepare": "husky install", - "test": "standard | snazzy && tap test/*.test.js", - "test-ci": "standard | snazzy && tap test/*.test.js --coverage-report=lcovonly" + "test": "standard | snazzy && tap test/*.test.js && tsd", + "test-ci": "standard | snazzy && tap test/*.test.js --coverage-report=lcovonly && tsd" }, "repository": { "type": "git", @@ -27,9 +27,14 @@ "split2": "^4.0.0" }, "devDependencies": { + "@types/node": "^16.11.6", "husky": "^7.0.0", "snazzy": "^9.0.0", "standard": "^16.0.3", - "tap": "^15.0.2" + "tap": "^15.0.2", + "tsd": "^0.18.0" + }, + "tsd": { + "directory": "./test/types" } } diff --git a/test/types/index.test-d.ts b/test/types/index.test-d.ts new file mode 100644 index 0000000..3fa9169 --- /dev/null +++ b/test/types/index.test-d.ts @@ -0,0 +1,21 @@ +import build, { OnUnknown } from "../../index"; +import { expectType } from "tsd"; +import { Transform } from "stream"; + +/** + * If enablePipelining is set to true, the function passed as an argument + * must return a transform. The unknown event should be listened to on the + * stream passed in the first argument. + */ +expectType(build((source) => source, { enablePipelining: true })); + +/** + * If enablePipelining is not set the unknown event can be listened to on + * the returned stream. + */ +expectType(build((source) => {})); + +/** + * build also accepts an async function + */ +expectType(build(async (source) => {}));