From 67ee08d1e39bb521bcba5a465adc0945f86bbb82 Mon Sep 17 00:00:00 2001 From: AlasDiablo <25723276+AlasDiablo@users.noreply.github.com> Date: Wed, 31 Jan 2024 14:55:11 +0100 Subject: [PATCH] refactor (analytics): reformat output doc --- docs/plugin-analytics.md | 75 +++++++++++++-------- packages/analytics/README.md | 75 +++++++++++++-------- packages/analytics/src/output.js | 110 +++++++++++++++++++++---------- 3 files changed, 169 insertions(+), 91 deletions(-) diff --git a/docs/plugin-analytics.md b/docs/plugin-analytics.md index 9f982a4e8..d741b7571 100644 --- a/docs/plugin-analytics.md +++ b/docs/plugin-analytics.md @@ -996,49 +996,66 @@ Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G ### output -Format the output with data a meta +Create an output string containing all incoming elements in a `data` array. +with given `meta` extracted into an object called `meta`. -#### Parameters - -- `indent` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** indent or not (optional, default `false`) -- `meta` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>?** fields to be considered as metadata - object +Créer une sortie en chain de caratere avec les element entrent mise dans un tableau nommé `data` +eyent les donnée `meta` extrais et mises dans un objet appelé `meta`. -#### Examples +##### Script / Scénario -Input +###### ini +```ini +; Import analytics plugin required to use "output" +; Importation du plugin analytique nécessaire pour utiliser "output" +[use] +plugin = analytics -```javascript -[ - { _id: 1, value: 2, total: 2 }, - { _id: 2, value: 4, total: 2 } -] +; Using "output" with 'indent' as true and 'meta' as total +; Utilisation de "output" avec 'indent' à vrai et total comme paramètres de 'meta' +[output] +indent = true +meta = total ``` -Script - +##### Input / Entrée -```javascript -.pipe(ezs('output', { meta: 'total' })) +```json + [ + { "_id": 1, "value": 2, "total": 2 }, + { "_id": 2, "value": 4, "total": 2 } + ] ``` -Output +##### Output / Sortie +!!! Attention: This is an output function that can only be used at the end of an EZS script. !!! +!!! The output is a string and can't be used with other EZS functions. !!! -```javascript -{ - data: [ - { _id: 1, value: 2 }, - { _id: 2, value: 4 } - ], - meta: { - total: 2 - } -} +!!! Attention : Ceci est une fonction de sortie, Elle peut uniquement etre utilisé à la fin d'un script ezs !!! +!!! Cette sortie est une chaine de carater et ne peut pas etre utilisé avec d'autre fonction ezs !!! + +```json + { + "data": [ + { "_id": 1, "value": 2 }, + { "_id": 2, "value": 4 } + ], + "meta": { + "total": 2 + } + } ``` -Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** +#### Parameters + +- `indent` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** + (optional, default `false`) +- `meta` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** + + +Returns **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** ### pair diff --git a/packages/analytics/README.md b/packages/analytics/README.md index 9f982a4e8..d741b7571 100644 --- a/packages/analytics/README.md +++ b/packages/analytics/README.md @@ -996,49 +996,66 @@ Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G ### output -Format the output with data a meta +Create an output string containing all incoming elements in a `data` array. +with given `meta` extracted into an object called `meta`. -#### Parameters - -- `indent` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** indent or not (optional, default `false`) -- `meta` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>?** fields to be considered as metadata - object +Créer une sortie en chain de caratere avec les element entrent mise dans un tableau nommé `data` +eyent les donnée `meta` extrais et mises dans un objet appelé `meta`. -#### Examples +##### Script / Scénario -Input +###### ini +```ini +; Import analytics plugin required to use "output" +; Importation du plugin analytique nécessaire pour utiliser "output" +[use] +plugin = analytics -```javascript -[ - { _id: 1, value: 2, total: 2 }, - { _id: 2, value: 4, total: 2 } -] +; Using "output" with 'indent' as true and 'meta' as total +; Utilisation de "output" avec 'indent' à vrai et total comme paramètres de 'meta' +[output] +indent = true +meta = total ``` -Script - +##### Input / Entrée -```javascript -.pipe(ezs('output', { meta: 'total' })) +```json + [ + { "_id": 1, "value": 2, "total": 2 }, + { "_id": 2, "value": 4, "total": 2 } + ] ``` -Output +##### Output / Sortie +!!! Attention: This is an output function that can only be used at the end of an EZS script. !!! +!!! The output is a string and can't be used with other EZS functions. !!! -```javascript -{ - data: [ - { _id: 1, value: 2 }, - { _id: 2, value: 4 } - ], - meta: { - total: 2 - } -} +!!! Attention : Ceci est une fonction de sortie, Elle peut uniquement etre utilisé à la fin d'un script ezs !!! +!!! Cette sortie est une chaine de carater et ne peut pas etre utilisé avec d'autre fonction ezs !!! + +```json + { + "data": [ + { "_id": 1, "value": 2 }, + { "_id": 2, "value": 4 } + ], + "meta": { + "total": 2 + } + } ``` -Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** +#### Parameters + +- `indent` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** + (optional, default `false`) +- `meta` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** + + +Returns **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** ### pair diff --git a/packages/analytics/src/output.js b/packages/analytics/src/output.js index 22ca16591..cdfa59cf2 100644 --- a/packages/analytics/src/output.js +++ b/packages/analytics/src/output.js @@ -1,48 +1,28 @@ import get from 'lodash.get'; import unset from 'lodash.unset'; + /** - * Format the output with data a meta - * - * @example Input - * [ - * { _id: 1, value: 2, total: 2 }, - * { _id: 2, value: 4, total: 2 } - * ] - * - * @example Script - * .pipe(ezs('output', { meta: 'total' })) - * - * @example Output - * { - * data: [ - * { _id: 1, value: 2 }, - * { _id: 2, value: 4 } - * ], - * meta: { - * total: 2 - * } - * } - * - * @name output - * @param {boolean} [indent=false] indent or not - * @param {string[]} [meta] fields to be considered as metadata - * object - * @returns {string} + * Pair function see documentation at the end. + * This part of the doc is used for jsdoc typing + * @private + * @param data {unknown} + * @param feed {Feed} + * @param ctx {import('../../core/src/engine').EngineScope} */ -function output(data, feed) { - const indent = this.getParam('indent', false); - const extract = this.getParam('meta'); +const output = (data, feed, ctx) => { + const indent = ctx.getParam('indent', false); + const extract = ctx.getParam('meta'); const extracts = Array.isArray(extract) ? extract : [extract]; const keys = extracts.filter((x) => x); const cr = indent ? '\n ' : ''; const json = (d) => JSON.stringify(d, null, indent ? ' ' : null); - if (this.isLast()) { + if (ctx.isLast()) { feed.write(`]}${cr}`); return feed.close(); } - if (this.isFirst() && !this.isLast()) { + if (ctx.isFirst() && !ctx.isLast()) { const values = keys.map((p) => get(data, p)); feed.write(`{${cr}"meta":{${cr}`); if (keys.length > 0) { @@ -64,7 +44,71 @@ function output(data, feed) { keys.forEach((p) => unset(data, p)); feed.write(json(data)); return feed.end(); -} +}; + +/** + * Create an output string containing all incoming elements in a `data` array. + * with given `meta` extracted into an object called `meta`. + * + * Créer une sortie en chain de caratere avec les element entrent mise dans un tableau nommé `data` + * eyent les donnée `meta` extrais et mises dans un objet appelé `meta`. + * + * #### Script / Scénario + * + * ##### ini + * + * ```ini + * ; Import analytics plugin required to use "output" + * ; Importation du plugin analytique nécessaire pour utiliser "output" + * [use] + * plugin = analytics + * + * ; Using "output" with 'indent' as true and 'meta' as total + * ; Utilisation de "output" avec 'indent' à vrai et total comme paramètres de 'meta' + * [output] + * indent = true + * meta = total + * + * ``` + * + * #### Input / Entrée + * + * ```json + * [ + * { "_id": 1, "value": 2, "total": 2 }, + * { "_id": 2, "value": 4, "total": 2 } + * ] + * ``` + * + * #### Output / Sortie + * + * !!! Attention: This is an output function that can only be used at the end of an EZS script. !!! + * !!! The output is a string and can't be used with other EZS functions. !!! + * + * !!! Attention : Ceci est une fonction de sortie, Elle peut uniquement etre utilisé à la fin d'un script ezs !!! + * !!! Cette sortie est une chaine de carater et ne peut pas etre utilisé avec d'autre fonction ezs !!! + * + * ```json + * { + * "data": [ + * { "_id": 1, "value": 2 }, + * { "_id": 2, "value": 4 } + * ], + * "meta": { + * "total": 2 + * } + * } + * ``` + * + * @name output + * @param {Boolean} [indent=false] + * + * + * @param {String} [meta] + * + * + * @returns {String} + */ export default { output, };