assign-gingerly 0.0.2 → 0.0.3

package/README.md

@@ -61,6 +61,176 @@ console.log(obj);
 
 When the right hand side of an expression is an object, assignGingerly is recursively applied (passing the third argument in if applicable, which will be discussed below) 
 
+## Example 4 - Incrementing values with !inc command
+
+The `!inc` command allows you to increment numeric values:
+
+```TypeScript
+const obj = {
+    a: {
+        b: {
+            c: 2
+        }
+    }
+};
+assignGingerly(obj, {
+    '!inc ?.a?.b?.c': 3,
+    '!inc ?.a?.d?.e': -2
+});
+console.log(obj);
+// {
+//   a: {
+//     b: { c: 5 },      // 2 + 3 = 5
+//     d: { e: -2 }      // non-existent path created with value -2
+//   }
+// }
+```
+
+The `!inc` command syntax is `!inc <path>` where the path can use the `?.` nested notation. The right-hand side value is added to the existing value using `+=`. If the path doesn't exist, it's created and set directly to the value. Non-numeric increments will allow JavaScript to throw its natural error.
+
+## Example 5 - Toggling boolean values with !toggle command
+
+The `!toggle` command allows you to toggle boolean values either immediately or after a delay:
+
+```TypeScript
+const obj = {
+    a: {
+        b: {
+            c: true
+        }
+    }
+};
+assignGingerly(obj, {
+    '!toggle ?.a?.b?.c': 0,      // Toggle immediately
+    '!toggle ?.a?.d?.e': 20      // Toggle after 20ms
+});
+console.log(obj);
+// {
+//   a: {
+//     b: { c: false }           // Toggled immediately
+//     // d doesn't exist yet
+//   }
+// }
+
+setTimeout(() => {
+    console.log(obj);
+    // {
+    //   a: {
+    //     b: { c: false },
+    //     d: { e: true }         // Created and toggled after 20ms
+    //   }
+    // }
+}, 40);
+```
+
+The `!toggle` command syntax is `!toggle <path>` where the path can use the `?.` nested notation. The right-hand side value determines the behavior:
+- **RHS = 0**: Toggle the existing value immediately (non-existent paths are not created)
+- **RHS > 0**: Schedule the toggle to happen after N milliseconds (non-existent paths are created and initialized to `true`)
+
+For existing values, the toggle is performed using JavaScript's logical NOT operator (`!value`). Non-numeric delay values will be passed to `setTimeout` and may throw an error.
+
+## Example 6 - Deleting properties with !delete command
+
+The `!delete` command allows you to delete properties either immediately or after a delay:
+
+```TypeScript
+const obj = {
+    a: {
+        b: {
+            c: true,
+            d: 'hello'
+        }
+    }
+};
+assignGingerly(obj, {
+    '!delete ?.a?.b?.c': 0,      // Delete immediately
+    '!delete ?.a?.b': 20         // Delete after 20ms
+});
+console.log(obj);
+// {
+//   a: {
+//     b: { d: 'hello' }          // c deleted immediately
+//   }
+// }
+
+setTimeout(() => {
+    console.log(obj);
+    // {
+    //   a: {}                     // b deleted after 20ms
+    // }
+}, 40);
+```
+
+The `!delete` command syntax is `!delete <path>` where the path can use the `?.` nested notation. The right-hand side value determines the behavior:
+- **RHS = 0**: Delete the final property immediately (non-existent paths are silently skipped)
+- **RHS > 0**: Schedule the deletion to happen after N milliseconds (non-existent paths are silently skipped)
+
+**Important**: The `!delete` command only deletes the **final property** in the path. The entire nested chain is not deleted. For example, `'!delete ?.a?.b?.c': 0` only deletes property `c`, leaving the structure `a.b` intact. If any intermediate path doesn't exist, the command is silently skipped without error.
+
+## Example 7 - Reversible assignments with assignTentatively
+
+The `assignTentatively` function works like `assignGingerly` but with a powerful addition: **reversibility**. It tracks changes and generates a reversal object that can undo all modifications:
+
+```TypeScript
+import assignTentatively from 'assign-gingerly/assignTentatively';
+
+const obj = { f: { g: 'hello' } };
+const reversal = {};
+
+assignTentatively(obj, {
+    '?.style?.height': '15px',
+    '?.a?.b?.c': {
+        d: 'hello',
+        e: 'world'
+    },
+    '?.f?.g': 'bye'
+}, { reversal });
+
+console.log(obj);
+// {
+//   f: { g: 'bye' },
+//   style: { height: '15px' },
+//   a: { b: { c: { d: 'hello', e: 'world' } } }
+// }
+
+console.log(reversal);
+// {
+//   '!delete ?.a': 0,
+//   '!delete ?.style': 0,
+//   '?.f?.g': 'hello'
+// }
+
+// Later, restore to original state:
+assignTentatively(obj, reversal);
+console.log(obj);
+// {
+//   f: { g: 'hello' }
+// }
+```
+
+**Key differences from assignGingerly:**
+- **No setTimeout support**: All `!toggle`, `!inc`, and `!delete` commands execute immediately, regardless of the RHS value
+- **No registry/DI support**: Dependency injection features are not available (pass it in and it will be ignored)
+- **Reversal tracking**: Maintains a reversal object that records:
+  - **Original values** of modified existing properties
+  - **!delete commands** for newly created top-level paths (e.g., `!delete ?.a` for paths created under `a`)
+  - **Original values** for deleted properties
+
+**Reversal guarantee:**
+```JavaScript
+const reversal = {};
+const obj = {...originalObj};
+const string1 = JSON.stringify(obj);
+
+assignTentatively(obj, sourceChanges, { reversal });
+assignTentatively(obj, reversal);
+
+const string2 = JSON.stringify(obj);
+console.log(string1 === string2); // true
+```
+
+This guarantees that applying the reversal object restores the object to its exact original state.
+
 ## Dependency injection based on a registry object and a Symbolic reference
 
 ```Typescript
@@ -96,20 +266,18 @@ baseRegistry.push([
         map: {
             [isHappy]: 'isHappy'
         },
-        spawn: MyEnhancement
+        spawn: MyEnhancement,
     },{
        
        map: {
            [isMellow]: 'isMellow'
        },
-       spawn: async () => {
-          return YourEnhancement;
-       } 
+       spawn: YourEnhancement,
     }
 ]);
 //end of dependency injection
 
-const asyncResult = await assignGingerly({}, {
+const result = assignGingerly({}, {
     [isHappy]: true,
     [isMellow]: true,
     '?.style.height': '40px',
@@ -117,7 +285,7 @@ const asyncResult = await assignGingerly({}, {
 }, {
     registry: BaseRegistry
 });
-asyncResult.set[isMellow] = false;
+result.set[isMellow] = false;
 ```
 
 The assignGingerly searches the registry for any items that has a mapping with a matching symbol of isHappy and isMellow, and if found, sees if it already has an instance of the spawn class associated with the first passed in parameter.  If no such instance is found, it instantiates one, associates the instance with the first parameter, then sets the property value.
@@ -126,12 +294,10 @@ It also adds a lazy property to the first passed in parameter, "set", which retu
 
 The suggestion to use Symbol.for with a guid, as opposed to just Symbol(), is based on some negative experiences I've had with multiple versions of the same library being referenced, but is not required. Regular symbols could also be used when that risk can be avoided.
 
-Note that the example above is the first time we mention async.  This is only necessary if you wish to work directly with the merged object.  This allows for lazy loading of the spawning class, which can be useful for large applications that don't need to download all the classes at once.  If you are just "depositing" values into the object, no need to await for anything.  Also, the assignGingerly should first do all the class instantiations that are already loaded (where the class constructor is specified in spawn), and then does all the lazy loaded ones.
-
 ## Support for JSON assignment with Symbol.for symbols
 
 ```JavaScript
-const asyncResult = await assignGingerly({}, {
+const result = assignGingerly({}, {
     "[Symbol.for('TFWsx0YH5E6eSfhE7zfLxA')]": true,
     "[Symbol.for('BqnnTPWRHkWdVGWcGQoAiw')]": true,
     '?.style.height': '40px',

package/{index.js → assignGingerly.js}

@@ -46,6 +46,51 @@ function parseSymbolForKey(key) {
     }
     return null;
 }
+/**
+ * Helper function to check if a key represents an !inc command
+ */
+function isIncCommand(key) {
+    return key.startsWith('!inc ');
+}
+/**
+ * Helper function to parse an !inc command and extract the path
+ */
+function parseIncCommand(key) {
+    if (!isIncCommand(key)) {
+        return null;
+    }
+    return key.substring(5); // Remove '!inc ' prefix
+}
+/**
+ * Helper function to check if a key represents a !toggle command
+ */
+function isToggleCommand(key) {
+    return key.startsWith('!toggle ');
+}
+/**
+ * Helper function to parse a !toggle command and extract the path
+ */
+function parseToggleCommand(key) {
+    if (!isToggleCommand(key)) {
+        return null;
+    }
+    return key.substring(8); // Remove '!toggle ' prefix
+}
+/**
+ * Helper function to check if a key represents a !delete command
+ */
+function isDeleteCommand(key) {
+    return key.startsWith('!delete ');
+}
+/**
+ * Helper function to parse a !delete command and extract the path
+ */
+function parseDeleteCommand(key) {
+    if (!isDeleteCommand(key)) {
+        return null;
+    }
+    return key.substring(8); // Remove '!delete ' prefix
+}
 /**
  * Helper function to parse a path string with ?. notation
  */
@@ -77,7 +122,7 @@ function ensureNestedPath(obj, pathParts) {
 /**
  * Main assignGingerly function
  */
-export async function assignGingerly(target, source, options) {
+export function assignGingerly(target, source, options) {
     if (!target || typeof target !== 'object') {
         return target;
     }
@@ -86,8 +131,6 @@ export async function assignGingerly(target, source, options) {
         : options?.registry
             ? new options.registry()
             : undefined;
-    // Track promises for async spawning
-    const asyncSpawns = [];
     // Convert Symbol.for string keys to actual symbols
     const processedSource = {};
     for (const key of Object.keys(source)) {
@@ -112,6 +155,111 @@ export async function assignGingerly(target, source, options) {
     // First pass: handle all non-symbol keys and sync operations
     for (const key of Object.keys(processedSource)) {
         const value = processedSource[key];
+        // Handle !inc commands
+        if (isIncCommand(key)) {
+            const path = parseIncCommand(key);
+            if (path) {
+                const pathParts = parsePath(path);
+                const lastKey = pathParts[pathParts.length - 1];
+                const parent = ensureNestedPath(target, pathParts);
+                // If the path doesn't exist, set it directly to the value
+                if (!(lastKey in parent)) {
+                    parent[lastKey] = value;
+                }
+                else {
+                    // Path exists, apply increment: oldValue += newValue
+                    parent[lastKey] += value;
+                }
+            }
+            continue;
+        }
+        // Handle !toggle commands
+        if (isToggleCommand(key)) {
+            const path = parseToggleCommand(key);
+            if (path) {
+                const delay = value;
+                if (delay === 0) {
+                    // Immediate toggle
+                    const pathParts = parsePath(path);
+                    const lastKey = pathParts[pathParts.length - 1];
+                    const parent = ensureNestedPath(target, pathParts);
+                    if (lastKey in parent) {
+                        // Path exists, toggle it
+                        parent[lastKey] = !parent[lastKey];
+                    }
+                    // If path doesn't exist, don't create it for immediate toggle
+                }
+                else {
+                    // Delayed toggle using setTimeout
+                    setTimeout(() => {
+                        const pathParts = parsePath(path);
+                        const lastKey = pathParts[pathParts.length - 1];
+                        const parent = ensureNestedPath(target, pathParts);
+                        if (lastKey in parent) {
+                            // Path exists, toggle it
+                            parent[lastKey] = !parent[lastKey];
+                        }
+                        else {
+                            // Path doesn't exist, initialize to true
+                            parent[lastKey] = true;
+                        }
+                    }, delay);
+                }
+            }
+            continue;
+        }
+        // Handle !delete commands
+        if (isDeleteCommand(key)) {
+            const path = parseDeleteCommand(key);
+            if (path) {
+                const delay = value;
+                if (delay === 0) {
+                    // Immediate delete
+                    const pathParts = parsePath(path);
+                    if (pathParts.length > 0) {
+                        const lastKey = pathParts[pathParts.length - 1];
+                        const parentPathParts = pathParts.slice(0, -1);
+                        // Navigate to parent without creating intermediate paths
+                        let parent = target;
+                        let canDelete = true;
+                        for (const part of parentPathParts) {
+                            if (!(part in parent) || typeof parent[part] !== 'object' || parent[part] === null) {
+                                canDelete = false;
+                                break;
+                            }
+                            parent = parent[part];
+                        }
+                        if (canDelete && lastKey in parent) {
+                            delete parent[lastKey];
+                        }
+                    }
+                }
+                else {
+                    // Delayed delete using setTimeout
+                    setTimeout(() => {
+                        const pathParts = parsePath(path);
+                        if (pathParts.length > 0) {
+                            const lastKey = pathParts[pathParts.length - 1];
+                            const parentPathParts = pathParts.slice(0, -1);
+                            // Navigate to parent without creating intermediate paths
+                            let parent = target;
+                            let canDelete = true;
+                            for (const part of parentPathParts) {
+                                if (!(part in parent) || typeof parent[part] !== 'object' || parent[part] === null) {
+                                    canDelete = false;
+                                    break;
+                                }
+                                parent = parent[part];
+                            }
+                            if (canDelete && lastKey in parent) {
+                                delete parent[lastKey];
+                            }
+                        }
+                    }, delay);
+                }
+            }
+            continue;
+        }
         if (isNestedPath(key)) {
             const pathParts = parsePath(key);
             const lastKey = pathParts[pathParts.length - 1];
@@ -121,7 +269,7 @@ export async function assignGingerly(target, source, options) {
                 if (!(lastKey in parent) || typeof parent[lastKey] !== 'object') {
                     parent[lastKey] = {};
                 }
-                await assignGingerly(parent[lastKey], value, options);
+                assignGingerly(parent[lastKey], value, options);
             }
             else {
                 parent[lastKey] = value;
@@ -133,7 +281,7 @@ export async function assignGingerly(target, source, options) {
                 if (!(key in target) || typeof target[key] !== 'object') {
                     target[key] = {};
                 }
-                await assignGingerly(target[key], value, options);
+                assignGingerly(target[key], value, options);
             }
             else {
                 target[key] = value;
@@ -155,8 +303,7 @@ export async function assignGingerly(target, source, options) {
                 // Check if instance already exists
                 let instance = instances.get(sym);
                 if (!instance) {
-                    // Check if spawn is a constructor or a promise
-                    const SpawnClass = await Promise.resolve(registryItem.spawn);
+                    const SpawnClass = registryItem.spawn;
                     instance = new SpawnClass();
                     instances.set(sym, instance);
                 }
@@ -184,31 +331,12 @@ export async function assignGingerly(target, source, options) {
                                 let instance = instances.get(prop);
                                 if (!instance) {
                                     const SpawnClass = registryItem.spawn;
-                                    if (SpawnClass instanceof Promise) {
-                                        // Handle async case - would need to be awaited externally
-                                        SpawnClass.then((SC) => {
-                                            instance = new SC();
-                                            instances.set(prop, instance);
-                                            const mappedKey = registryItem.map[prop];
-                                            if (mappedKey && instance && typeof instance === 'object') {
-                                                instance[mappedKey] = value;
-                                            }
-                                        });
-                                    }
-                                    else {
-                                        instance = new SpawnClass();
-                                        instances.set(prop, instance);
-                                        const mappedKey = registryItem.map[prop];
-                                        if (mappedKey && instance && typeof instance === 'object') {
-                                            instance[mappedKey] = value;
-                                        }
-                                    }
+                                    instance = new SpawnClass();
+                                    instances.set(prop, instance);
                                 }
-                                else {
-                                    const mappedKey = registryItem.map[prop];
-                                    if (mappedKey && instance && typeof instance === 'object') {
-                                        instance[mappedKey] = value;
-                                    }
+                                const mappedKey = registryItem.map[prop];
+                                if (mappedKey && instance && typeof instance === 'object') {
+                                    instance[mappedKey] = value;
                                 }
                             }
                         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -13,20 +13,20 @@
   "license": "MIT",
   "author": "Bruce B. Anderson <andeson.bruce.b@gmail.com>",
   "type": "module",
-  "types": "index.d.ts",
+  "types": "types.d.ts",
   "files": [
-    "index.js",
+    "assignGingerly.js",
     "index.d.ts",
     "README.md",
     "LICENSE"
   ],
   "exports": {
     ".": {
-      "import": "./index.js",
-      "types": "./index.d.ts"
+      "import": "./assignGingerly.js",
+      "types": "./types.d.ts"
     }
   },
-  "main": "index.js",
+  "main": "assignGingerly.js",
   "scripts": {
     "serve": "node ./node_modules/spa-ssi/serve.js",
     "test": "playwright test",

package/index.d.ts

@@ -1,35 +0,0 @@
-/**
- * Interface for registry items that define dependency injection mappings
- */
-export interface IBaseRegistryItem<T = any> {
-  spawn: { new (): T } | Promise<{ new (): T }>;
-  map: { [key: string | symbol]: keyof T };
-}
-
-/**
- * Interface for the options passed to assignGingerly
- */
-export interface IAssignGingerlyOptions {
-  registry?: typeof BaseRegistry | BaseRegistry;
-}
-
-/**
- * Base registry class for managing dependency injection
- */
-export declare class BaseRegistry {
-  private items;
-  push(items: IBaseRegistryItem | IBaseRegistryItem[]): void;
-  getItems(): IBaseRegistryItem[];
-  findBySymbol(symbol: symbol | string): IBaseRegistryItem | undefined;
-}
-
-/**
- * Main assignGingerly function
- */
-export declare function assignGingerly(
-  target: any,
-  source: Record<string | symbol, any>,
-  options?: IAssignGingerlyOptions
-): Promise<any>;
-
-export default assignGingerly;