@appius-fr/apx 2.6.1 → 2.6.2

package/modules/tools/form-packer/README.md

@@ -123,12 +123,14 @@ The module intelligently handles mixed structures (objects with both numeric and
 
 ## API
 
-### `APX.tools.packFormToJSON(form)`
+### `APX.tools.packFormToJSON(form, options?)`
 
 Converts an HTML form element into a JSON object.
 
 **Parameters:**
 - `form` (HTMLFormElement): The form element to convert
+- `options` (Object, optional):
+  - `numericKeysAlwaysArray` (boolean, default `false`): If `true`, every numeric bracket key (e.g. `[26]`) is treated as an array index (pre-2.6.2 behaviour). If `false`, the heuristic applies: array only when indices are dense 0,1,2,…,n; otherwise object with string keys.
 
 **Returns:** (Object) The JSON object representation of the form data
 
@@ -137,30 +139,26 @@ Converts an HTML form element into a JSON object.
 **Example:**
 ```javascript
 const form = document.querySelector('#myForm');
-try {
-    const data = APX.tools.packFormToJSON(form);
-    console.log(data);
-} catch (error) {
-    console.error('Error:', error.message);
-}
+const data = APX.tools.packFormToJSON(form);
+// Legacy: always use arrays for numeric keys
+const dataLegacy = APX.tools.packFormToJSON(form, { numericKeysAlwaysArray: true });
 ```
 
-### `APX('form').pack()`
+### `APX('form').pack(options?)`
 
 Converts the first selected form element into a JSON object. This is a chainable method on APX objects.
 
+**Parameters:**
+- `options` (Object, optional): Same as the second argument of `packFormToJSON` (e.g. `{ numericKeysAlwaysArray: true }`).
+
 **Returns:** (Object) The JSON object representation of the form data
 
 **Throws:** (Error) If no element is found or the first element is not a form
 
 **Example:**
 ```javascript
-try {
-    const data = APX('form#myForm').pack();
-    console.log(data);
-} catch (error) {
-    console.error('Error:', error.message);
-}
+const data = APX('form#myForm').pack();
+const dataLegacy = APX('form#myForm').pack({ numericKeysAlwaysArray: true });
 ```
 
 ---

package/modules/tools/form-packer/augment-apx.mjs

@@ -8,12 +8,14 @@ import { packFormToJSON } from './packToJson.mjs';
 export default function (apx) {
     /**
      * Convertit le premier formulaire sélectionné en objet JSON
+     * @param {Object} [options] - Options passées à packFormToJSON (ex. { numericKeysAlwaysArray: true })
      * @returns {Object} L'objet JSON résultant
      * @throws {Error} Si aucun formulaire n'est trouvé ou si le premier élément n'est pas un formulaire
      * @example
      * const data = APX('form.myformclass').pack();
+     * const dataLegacy = APX('form').pack({ numericKeysAlwaysArray: true });
      */
-    apx.pack = function () {
+    apx.pack = function (options) {
         const firstElement = this.first();
         if (!firstElement) {
             throw new Error('No element found');
@@ -21,7 +23,7 @@ export default function (apx) {
         if (firstElement.tagName !== 'FORM') {
             throw new Error('Element is not a form');
         }
-        return packFormToJSON(firstElement);
+        return packFormToJSON(firstElement, options);
     };
     
     return apx;

package/modules/tools/form-packer/packToJson.mjs

@@ -1,15 +1,19 @@
 /**
  * Convertit un formulaire HTML en objet JSON
  * @param {HTMLFormElement} form - Le formulaire à convertir
+ * @param {Object} [options] - Options de conversion
+ * @param {boolean} [options.numericKeysAlwaysArray=false] - Si true, toute clé numérique est traitée comme index de tableau (comportement d'avant 2.6.2). Sinon, heuristique : tableau seulement si indices denses 0,1,2,…,n.
  * @returns {Object} L'objet JSON résultant
  * @throws {TypeError} Si form n'est pas un HTMLFormElement
  */
-export const packFormToJSON = (form) => {
+export const packFormToJSON = (form, options = {}) => {
     // Validation de l'entrée
     if (!form || !(form instanceof HTMLFormElement)) {
         throw new TypeError('packFormToJSON expects an HTMLFormElement');
     }
 
+    const numericKeysAlwaysArray = options.numericKeysAlwaysArray === true;
+
     const formData = new FormData(form);
     const jsonData = {};
     
@@ -48,6 +52,7 @@ export const packFormToJSON = (form) => {
     
     const pathUsage = new Map(); // Map<pathString, PathUsage>
     const keyAnalysis = new Map(); // Map<basePath, {hasNumeric: boolean, hasString: boolean}>
+    const numericIndicesByPath = new Map(); // Map<pathString, Set<number>> — indices under each parent path
     const allEntries = [];
     
     /**
@@ -100,6 +105,13 @@ export const packFormToJSON = (form) => {
             if (part.type === 'key') {
                 currentPath = currentPath ? `${currentPath}[${part.name}]` : part.name;
             } else if (part.type === 'numeric') {
+                const parentPath = currentPath;
+                let set = numericIndicesByPath.get(parentPath);
+                if (!set) {
+                    set = new Set();
+                    numericIndicesByPath.set(parentPath, set);
+                }
+                set.add(part.index);
                 currentPath = `${currentPath}[${part.index}]`;
             } else if (part.type === 'array') {
                 currentPath = `${currentPath}[]`;
@@ -190,6 +202,34 @@ export const packFormToJSON = (form) => {
         return analysis?.hasNumeric && analysis?.hasString;
     };
 
+    /**
+     * True if indices are exactly 0, 1, 2, ..., n (dense, sequential from 0).
+     * @param {number[]} indices - Sorted array of indices
+     * @returns {boolean}
+     */
+    const isDenseSequential = (indices) => {
+        if (indices.length === 0) return false;
+        const sorted = [...indices].sort((a, b) => a - b);
+        for (let j = 0; j < sorted.length; j++) {
+            if (sorted[j] !== j) return false;
+        }
+        return true;
+    };
+
+    /**
+     * True if numeric keys under this path should be treated as array indices.
+     * With numericKeysAlwaysArray: always true when path has numeric children.
+     * Otherwise: true only when indices are dense 0..n.
+     * @param {string} parentPath - Path to the container that has numeric children
+     * @returns {boolean}
+     */
+    const useArrayForNumericPath = (parentPath) => {
+        const set = numericIndicesByPath.get(parentPath);
+        if (!set || set.size === 0) return true;
+        if (numericKeysAlwaysArray) return true;
+        return isDenseSequential([...set]);
+    };
+
     /**
      * Convertit un tableau en objet en préservant les indices numériques comme propriétés
      * @param {Array} arr - Le tableau à convertir
@@ -285,8 +325,9 @@ export const packFormToJSON = (form) => {
      * @param {*} value - La valeur à assigner
      * @param {Object} parent - Le conteneur parent
      * @param {string} basePath - Le chemin de base pour la détection de conflit
+     * @param {string} parentPath - Chemin du conteneur actuel (pour heuristique numeric)
      */
-    const processFinalValue = (container, part, value, parent, basePath) => {
+    const processFinalValue = (container, part, value, parent, basePath, parentPath) => {
         if (part.type === 'array') {
             // Tableau explicite avec []
             container[part.name] ??= [];
@@ -296,13 +337,18 @@ export const packFormToJSON = (form) => {
                 container[part.name] = [container[part.name], value];
             }
         } else if (part.type === 'numeric') {
-            // Indice numérique final
             const { index } = part;
-            container = ensureArray(container, parent.key, parent.container);
-            while (container.length <= index) {
-                container.push(undefined);
+            const useArray = useArrayForNumericPath(parentPath);
+            if (useArray) {
+                container = ensureArray(container, parent.key, parent.container);
+                while (container.length <= index) {
+                    container.push(undefined);
+                }
+                container[index] = value;
+            } else {
+                container = ensureObject(container, parent.key, parent.container, true);
+                container[index] = value;
             }
-            container[index] = value;
         } else {
             // Clé simple finale
             const conflict = hasConflict(basePath);
@@ -348,16 +394,14 @@ export const packFormToJSON = (form) => {
      */
     const processIntermediatePart = (container, part, nextPart, parent, basePath, parts, i, key) => {
         if (part.type === 'numeric') {
-            // Indice numérique : le container doit être un tableau ou un objet (selon conflit)
             const { index } = part;
-            const conflict = hasConflict(basePath);
+            const parentPath = buildPathString(parts.slice(0, i));
+            const useArray = useArrayForNumericPath(parentPath) && !hasConflict(basePath);
             
-            if (conflict) {
-                // Conflit : utiliser un objet (les indices seront des propriétés)
+            if (!useArray) {
                 container = ensureObject(container, parent.key, parent.container, true);
                 container[index] ??= {};
                 if (typeof container[index] !== 'object' || container[index] === null) {
-                    // Cette erreur ne devrait jamais se produire si la détection fonctionne correctement
                     const pathParts = parts.slice(0, i + 1);
                     const currentPath = buildPathString(pathParts);
                     throw new Error(
@@ -367,14 +411,12 @@ export const packFormToJSON = (form) => {
                     );
                 }
             } else {
-                // Pas de conflit : utiliser un tableau
                 container = ensureArray(container, parent.key, parent.container);
                 while (container.length <= index) {
                     container.push(undefined);
                 }
                 container[index] ??= {};
                 if (typeof container[index] !== 'object' || container[index] === null) {
-                    // Cette erreur ne devrait jamais se produire si la détection fonctionne correctement
                     const pathParts = parts.slice(0, i + 1);
                     const currentPath = buildPathString(pathParts);
                     throw new Error(
@@ -459,8 +501,8 @@ export const packFormToJSON = (form) => {
             const parent = path[path.length - 1];
 
             if (isLast) {
-                // Dernière partie : assigner la valeur
-                processFinalValue(container, part, value, parent, basePath);
+                const parentPath = buildPathString(parts.slice(0, i));
+                processFinalValue(container, part, value, parent, basePath, parentPath);
             } else {
                 // Partie intermédiaire : créer la structure
                 const newContainer = processIntermediatePart(container, part, nextPart, parent, basePath, parts, i, key);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appius-fr/apx",
-  "version": "2.6.1",
+  "version": "2.6.2",
   "description": "Appius Extended JS - A powerful JavaScript extension library",
   "main": "dist/APX.prod.mjs",
   "module": "dist/APX.prod.mjs",