@umbraci/jsmind 0.9.13 → 0.10.0

package/types/generated/plugins/history/history-diff.d.ts

@@ -1,22 +1,40 @@
 /**
  * Flatten a tree into a Map of nodes keyed by id.
+ *
+ * Note: When using custom fieldNames, make sure to pass the correct field names in opts.fields.
+ * For example, if you configured fieldNames: { topic: 'name' }, you should pass fields: ['name', 'data', 'id'].
+ *
  * @param {NodeTreeFormat|NodeTreeData} tree - The tree to flatten
  * @param {FlattenOptions} [opts] - Flatten options
  * @returns {Map<string, FlatNode>} Map of node id -> flattened node object
+ *
  * @example
+ * // With default fieldNames
  * const tree = { data: { id: 'root', topic: 'Root', children: [...] } };
  * const flatMap = flatten(tree);
  * const rootNode = flatMap.get('root'); // { id: 'root', topic: 'Root', data: {...}, _parentid: null, _order: 0 }
+ *
+ * @example
+ * // With custom fieldNames: { topic: 'name' }
+ * const tree = { data: { id: 'root', name: 'Root', children: [...] } };
+ * const flatMap = flatten(tree, { fields: ['name', 'data', 'id'] });
+ * const rootNode = flatMap.get('root'); // { id: 'root', name: 'Root', data: {...}, _parentid: null, _order: 0 }
  */
 export function flatten(tree: NodeTreeFormat | NodeTreeData, opts?: FlattenOptions): Map<string, FlatNode>;
 /**
- * Compute diff between two snapshots
+ * Compute diff between two snapshots.
+ *
+ * Note: When using custom fieldNames, make sure to pass the correct field names in opts.fields.
+ * For example, if you configured fieldNames: { topic: 'name' }, you should pass fields: ['name', 'data', 'id'].
+ * When using jm.history.diff(), this is automatically handled for you.
+ *
  * @param {NodeTreeFormat|NodeTreeData} a - First snapshot (before)
  * @param {NodeTreeFormat|NodeTreeData} b - Second snapshot (after)
  * @param {DiffOptions} [opts] - Diff options
  * @returns {DiffResult} Diff result with created, updated, deleted nodes, and optionally categorized updates
+ *
  * @example
- * // Basic usage
+ * // Basic usage with default fieldNames
  * const result = diff(snapshot1, snapshot2);
  * console.log(result.created); // Newly created nodes
  * console.log(result.updated); // Updated nodes with changes
@@ -30,8 +48,17 @@ export function flatten(tree: NodeTreeFormat | NodeTreeData, opts?: FlattenOptio
  * console.log(result.movedAndModified); // Nodes that were both moved and modified
  *
  * @example
- * // Custom fields
- * const result = diff(snapshot1, snapshot2, { fields: ['id', 'topic'] });
+ * // With custom fieldNames: { topic: 'name' }
+ * const result = diff(snapshot1, snapshot2, { fields: ['name', 'data', 'id'] });
+ * // Now the diff will correctly detect changes in the 'name' field
+ *
+ * @example
+ * // Using jm.history.diff() (recommended - automatically handles fieldNames)
+ * const before = jm.get_data('node_tree');
+ * // ... make changes ...
+ * const after = jm.get_data('node_tree');
+ * const result = jm.history.diff(before, after);
+ * // fieldNames are automatically applied, no need to specify fields manually
  */
 export function diff(a: NodeTreeFormat | NodeTreeData, b: NodeTreeFormat | NodeTreeData, opts?: DiffOptions): DiffResult;
 export type NodeTreeFormat = {
@@ -218,9 +245,21 @@ export type DiffResult = {
 };
 export type FlattenOptions = {
     /**
-     * - Array of field names to include. Defaults to ['topic', 'data', 'id']
+     * - Array of field names to include. Defaults to ['topic', 'data', 'id'].
+     *     When using custom fieldNames (e.g., { id: 'key', topic: 'name' }), this should be
+     *     ['name', 'data', 'key'] to match the actual field names in the data.
      */
     fields?: string[];
+    /**
+     * - The field name to use as the node ID. Defaults to 'id'.
+     *     When using custom fieldNames (e.g., { id: 'key' }), this should be 'key'.
+     */
+    idKey?: string;
+    /**
+     * - The field name to use for children array. Defaults to 'children'.
+     *     When using custom fieldNames (e.g., { children: 'items' }), this should be 'items'.
+     */
+    childrenKey?: string;
     /**
      * - Whether to include _parentid and _order. Defaults to true
      */
@@ -228,9 +267,25 @@ export type FlattenOptions = {
 };
 export type DiffOptions = {
     /**
-     * - Array of field names to compare. Defaults to ['topic', 'data', 'id']
+     * - Array of field names to compare. Defaults to ['topic', 'data', 'id'].
+     *     When using custom fieldNames (e.g., { id: 'key', topic: 'name' }), this should be
+     *     ['name', 'data', 'key'] to match the actual field names in the data.
+     *     Note: When using jm.history.diff(), this is automatically handled based
+     *     on the configured fieldNames, so you don't need to specify it manually.
      */
     fields?: string[];
+    /**
+     * - The field name to use as the node ID. Defaults to 'id'.
+     *     When using custom fieldNames (e.g., { id: 'key' }), this should be 'key'.
+     *     Note: When using jm.history.diff(), this is automatically handled.
+     */
+    idKey?: string;
+    /**
+     * - The field name to use for children array. Defaults to 'children'.
+     *     When using custom fieldNames (e.g., { children: 'items' }), this should be 'items'.
+     *     Note: When using jm.history.diff(), this is automatically handled.
+     */
+    childrenKey?: string;
     /**
      * - Whether to include _parentid and _order in comparison. Defaults to true
      */

package/types/generated/plugins/history/jsmind.history.d.ts

@@ -1,5 +1,7 @@
 export default HistoryPlugin;
 export type JsMind = import("../../jsmind.js").default;
+export type DiffResult = import("./history-diff.js").DiffResult;
+export type DiffOptions = import("./history-diff.js").DiffOptions;
 /**
  * HistoryPlugin skeleton (Task 1)
  */