diff --git a/.npmignore b/.npmignore index 96746f7..58b1a7b 100644 --- a/.npmignore +++ b/.npmignore @@ -11,4 +11,5 @@ test/ .editorconfig .jsdoc.json proxy-benchmark.js -TODO.md \ No newline at end of file +TODO.md +yarn.lock \ No newline at end of file diff --git a/.travis.yml b/.travis.yml index cdbce28..9163243 100644 --- a/.travis.yml +++ b/.travis.yml @@ -2,4 +2,4 @@ language: node_js node_js: - node after_script: - - npm run submit-coverage \ No newline at end of file + - yarn submit-coverage \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index c1bc86a..255d7a8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ # Changelog ## Unreleased +#### Added +- Support for Buffer and Stream parameters and results +- Validates exposed API metadata such as `validate`, `validateResponse` or `responseSchema` +- Usage of Yarn + #### Changed - Reformat CHANGELOG to follow [Keep a Changelog](https://keepachangelog.com) recommandations - New documentation with latest docma v2.0.0 diff --git a/FAQ.md b/FAQ.md index 9e37cb9..b4a63ff 100644 --- a/FAQ.md +++ b/FAQ.md @@ -2,6 +2,7 @@ - [What are deployment modes?](#what-are-deployment-modes-) - [Can exposed API be asynchronous?](#can-exposed-api-be-asynchronous-) +- [Are there limitations on exposed API signatures?](#are-there-limitations-on-exposed-api-signatures-) - [Where to put asynchronous initialization?](#where-to-put-asynchronous-initialization-) - [Can initialization code be configured?](#can-initialization-code-be-configured-) - [How can service definition be more modular?](#how-can-service-definition-be-more-modular-) @@ -83,6 +84,60 @@ startService({ ``` +## Are there limitations on exposed API signatures? + +Despite all our efforts, yes. Hopefully main cases are covered. + +Because parameters will be stringified when sent to server: +- they could be `null` or `undefined` +- they could be booleans, numbers, strings, arrays, and plain object (contains only properties of the previous types) +- they could be of other types (Date, Error, RegExp, custom classes...) but will boils down to the output of their `toString()` method +- they could be `Buffer` or `Stream` (see bellow). All paremeter but the first will be ignored + +In particular, don't use functions as parameters. + +Same limitations applies to API returned object. + +You can use destructuring, rest parameters and even default values: +```js +async withExoticParameters ([a, b], {c: {d}} = {}, ...other) { + return [a, b, d, ...other] +} +``` + +To use `Buffer` input parameter: +- decorate API with `hasBufferInput` +- use only one parameter (others will be set to `undefined`) + ```js + const api = { + async bufferHandling (buffer) { + assert(Buffer.isBuffer(buffer)) + return Buffer.concat([buffer, new Uint8Array([3, 4])]) + } + } + // decorate + apis.bufferHandling.hasBufferInput = true + ``` + +To use `Stream` input parameter: +- decorate API with `hasStreamInput` +- use only one parameter (others will be set to `undefined`) + ```js + const api = { + async streamHandling (stream) { + assert(stream instanceof Readable) + const prefix = new BufferList() + prefix.append('here is a prefix -- ', 'utf8') + return multistream([prefix, stream]) + } + } + // decorate + apis.streamHandling.hasStreamInput = true + ``` + +You can return `Stream` and `Buffer` without any decoration, but don't nest them in objects (they will be stringified). + + ## Where to put asynchronous initialization? To serve this purpose, the `init()` function can be either synchronous or return a Promise. diff --git a/docs/content/changelog.html b/docs/content/changelog.html index deb0ba1..fd5c9ff 100644 --- a/docs/content/changelog.html +++ b/docs/content/changelog.html @@ -3,6 +3,12 @@

Unreleased

+

Added

+

Changed