docs (analytics): add reducing documentation

Inist-CNRS · Jan 30, 2024 · e0c1920 · e0c1920
1 parent 164c119
commit e0c1920
Show file tree

Hide file tree

Showing 3 changed files with 110 additions and 65 deletions.
diff --git a/docs/plugin-analytics.md b/docs/plugin-analytics.md
@@ -1134,33 +1134,45 @@ Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 
 ### reducing
 
-Take `Object` group value of `{ id, value }` objectpath
+Merges the `id`, `value` pairs into a new pair, associating the identifier with the values.
 
-```json
-[{
-         { id: 'x', value: 2 },
-         { id: 't', value: 2 },
-         { id: 'x', value: 3 },
-         { id: 'x', value: 5 },
-}]
-```
+Fusionne les couple `id`, `value`, en un nouveau couple associent l'identifient au valeurs.
 
-Script:
+#### Example / Exemple
+
+##### Script / Scénario
 
 ```ini
+; Import analytics plugin required to use "reducing"
+; Importation du plugin analytique nécessaire pour utiliser "reducing"
 [use]
 plugin = analytics
 
+; Using "reducing" with default settings
+; Utilisation de "reducing" avec les paramètres par défaut
 [reducing]
+; id = id
+; value = value
 ```
 
-Output:
+##### Input / Entrée
 
 ```json
-[
-         { id: 'x', value: [2, 3, 5] },
-         { id: 't', value: [2] },
-]
+ [
+     { "id": "x", "value": 2 },
+     { "id": "t", "value": 2 },
+     { "id": "x", "value": 3 },
+     { "id": "x", "value": 5 }
+ ]
+```
+
+##### Output / Sortie
+
+```json
+ [
+     { "id": "x", "value": [2, 3, 5] },
+     { "id": "t", "value": [2] }
+ ]
 ```
 
 #### Parameters

diff --git a/packages/analytics/README.md b/packages/analytics/README.md
@@ -1134,33 +1134,45 @@ Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 
 ### reducing
 
-Take `Object` group value of `{ id, value }` objectpath
+Merges the `id`, `value` pairs into a new pair, associating the identifier with the values.
 
-```json
-[{
-         { id: 'x', value: 2 },
-         { id: 't', value: 2 },
-         { id: 'x', value: 3 },
-         { id: 'x', value: 5 },
-}]
-```
+Fusionne les couple `id`, `value`, en un nouveau couple associent l'identifient au valeurs.
 
-Script:
+#### Example / Exemple
+
+##### Script / Scénario
 
 ```ini
+; Import analytics plugin required to use "reducing"
+; Importation du plugin analytique nécessaire pour utiliser "reducing"
 [use]
 plugin = analytics
 
+; Using "reducing" with default settings
+; Utilisation de "reducing" avec les paramètres par défaut
 [reducing]
+; id = id
+; value = value
 ```
 
-Output:
+##### Input / Entrée
 
 ```json
-[
-         { id: 'x', value: [2, 3, 5] },
-         { id: 't', value: [2] },
-]
+ [
+     { "id": "x", "value": 2 },
+     { "id": "t", "value": 2 },
+     { "id": "x", "value": 3 },
+     { "id": "x", "value": 5 }
+ ]
+```
+
+##### Output / Sortie
+
+```json
+ [
+     { "id": "x", "value": [2, 3, 5] },
+     { "id": "t", "value": [2] }
+ ]
 ```
 
 #### Parameters

diff --git a/packages/analytics/src/reducing.js b/packages/analytics/src/reducing.js
@@ -2,58 +2,79 @@ import get from 'lodash.get';
 import { createStore } from '@ezs/store';
 
 /**
- * Take `Object` group value of `{ id, value }` objectpath
+ * Reducing 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}
+ */
+const reducing = async (data, feed, ctx) => {
+    if (!ctx.store) {
+        const location = ctx.getParam('location');
+        ctx.store = createStore(ctx.ezs, 'reducing', location);
+    }
+    if (ctx.isLast()) {
+        const stream = await ctx.store.empty();
+        stream
+            .on('data', (item) => feed.write(item))
+            .on('end', async () => {
+                await ctx.store.close();
+                feed.close();
+            });
+    } else {
+        const id = get(data, ctx.getParam('id', 'id')) || ctx.getIndex();
+        const value = get(data, ctx.getParam('value', 'value'));
+        await ctx.store.add(id, value);
+        feed.end();
+    }
+};
+
+/**
+ * Merges the `id`, `value` pairs into a new pair, associating the identifier with the values.
  *
- * ```json
- * [{
- *          { id: 'x', value: 2 },
- *          { id: 't', value: 2 },
- *          { id: 'x', value: 3 },
- *          { id: 'x', value: 5 },
- * }]
- * ```
+ * Fusionne les couple `id`, `value`, en un nouveau couple associent l'identifient au valeurs.
  *
- * Script:
+ * ### Example / Exemple
+ *
+ * #### Script / Scénario
  *
  * ```ini
+ * ; Import analytics plugin required to use "reducing"
+ * ; Importation du plugin analytique nécessaire pour utiliser "reducing"
  * [use]
  * plugin = analytics
  *
+ * ; Using "reducing" with default settings
+ * ; Utilisation de "reducing" avec les paramètres par défaut
  * [reducing]
+ * ; id = id
+ * ; value = value
  *
  * ```
  *
- * Output:
+ * #### Input / Entrée
+ *
+ * ```json
+ *  [
+ *      { "id": "x", "value": 2 },
+ *      { "id": "t", "value": 2 },
+ *      { "id": "x", "value": 3 },
+ *      { "id": "x", "value": 5 }
+ *  ]
+ * ```
+ * #### Output / Sortie
  *
  * ```json
- * [
- *          { id: 'x', value: [2, 3, 5] },
- *          { id: 't', value: [2] },
- * ]
+ *  [
+ *      { "id": "x", "value": [2, 3, 5] },
+ *      { "id": "t", "value": [2] }
+ *  ]
  * ```
  *
  * @name reducing
  * @param {String} [id=id] path to use for id
  * @param {String} [value=value] path to use for value
  * @returns {Object}
  */
-export default async function reducing(data, feed) {
-    if (!this.store) {
-        const location = this.getParam('location');
-        this.store = createStore(this.ezs, 'reducing', location);
-    }
-    if (this.isLast()) {
-        const stream = await this.store.empty();
-        stream
-            .on('data', (item) => feed.write(item))
-            .on('end', async () => {
-                await this.store.close();
-                feed.close();
-            });
-    } else {
-        const id = get(data, this.getParam('id', 'id')) || this.getIndex();
-        const value = get(data, this.getParam('value', 'value'));
-        await this.store.add(id, value)
-        feed.end();
-    }
-}
+export default reducing;