assign-gingerly 0.0.0 → 0.0.2

package/README.md

@@ -1,5 +1,10 @@
 # assign-gingerly
 
+[![Playwright Tests](https://github.com/bahrus/assign-gingerly/actions/workflows/CI.yml/badge.svg?branch=baseline)](https://github.com/bahrus/assign-gingerly/actions/workflows/CI.yml)
+[![NPM version](https://badge.fury.io/js/assign-gingerly.png)](http://badge.fury.io/js/assign-gingerly)
+[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/assign-gingerly?style=for-the-badge)](https://bundlephobia.com/result?p=assign-gingerly)
+<img src="http://img.badgesize.io/https://cdn.jsdelivr.net/npm/assign-gingerly?compression=gzip">
+
 This package provides a utility function for carefully merging one object into another.
 
 It builds on Object.assign.  It adds support for:
@@ -13,6 +18,7 @@ It builds on Object.assign.  It adds support for:
 const sourceObj = {hello: 'world'};
 assignGingerly(sourceObj, {hello: 'Venus', foo: 'bar'});
 // Because none of the keys of the second parameter start with "?.", 
+// nor includes any symbols keys,
 // assign gingerly produces identical results as Object.assign:
 console.log(sourceObj);
 //{hello: 'Venus', foo: 'bar'}
@@ -55,8 +61,84 @@ 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) 
 
-## Dependency injection based on a registry object
+## Dependency injection based on a registry object and a Symbolic reference
 
 ```Typescript
+interface IBaseRegistryItem<T = any> {
+    spawn: {new(): T} | Promise<{new(): T}>
+    map: {[key: string | symbol]: keyof T}
+}
+
+export const isHappy = Symbol.for('TFWsx0YH5E6eSfhE7zfLxA');
+class MyEnhancement extends ElementEnhancement(EventTarget){
+    get isHappy(){}
+    set isHappy(nv){}
+}
+
+export const isMellow = Symbol.for('BqnnTPWRHkWdVGWcGQoAiw');
+class YourEnhancement extends ElementEnhancement(EventTarget){
+    get isMellow(){}
+    set isMellow(nv){}
+    get madAboutFourteen(){}
+    set madAboutFourteen(nv){}
+}
+
+class BaseRegistry{
+    push(IBaseRegistryItem | IBaseRegistryItem[]){
+        ...
+    }
+}
+
+//Here's where the dependency injection mapping takes place
+const baseRegistry = new BaseRegistry;
+baseRegistry.push([
+    {
+        map: {
+            [isHappy]: 'isHappy'
+        },
+        spawn: MyEnhancement
+    },{
+       
+       map: {
+           [isMellow]: 'isMellow'
+       },
+       spawn: async () => {
+          return YourEnhancement;
+       } 
+    }
+]);
+//end of dependency injection
+
+const asyncResult = await assignGingerly({}, {
+    [isHappy]: true,
+    [isMellow]: true,
+    '?.style.height': '40px',
+    '?.enhancements?.mellowYellow?.madAboutFourteen': true
+}, {
+    registry: BaseRegistry
+});
+asyncResult.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.
+
+It also adds a lazy property to the first passed in parameter, "set", which returns a proxy, and that proxy watches for symbol references passed in a value, and sets the value from that spawned instance.  Again, if the spawned instance is not found, it respawns it.
+
+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({}, {
+    "[Symbol.for('TFWsx0YH5E6eSfhE7zfLxA')]": true,
+    "[Symbol.for('BqnnTPWRHkWdVGWcGQoAiw')]": true,
+    '?.style.height': '40px',
+    '?.enhancements?.mellowYellow?.madAboutFourteen': true
+}, {
+    registry: BaseRegistry
+});
 ```
+
+

package/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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;

package/index.js

@@ -0,0 +1,224 @@
+/**
+ * Map to store spawned instances associated with objects
+ */
+const instanceMap = new WeakMap();
+/**
+ * Base registry class for managing dependency injection
+ */
+export class BaseRegistry {
+    items = [];
+    push(items) {
+        if (Array.isArray(items)) {
+            this.items.push(...items);
+        }
+        else {
+            this.items.push(items);
+        }
+    }
+    getItems() {
+        return this.items;
+    }
+    findBySymbol(symbol) {
+        return this.items.find(item => {
+            const map = item.map;
+            return Object.keys(map).some(key => {
+                if (typeof key === 'symbol' || (typeof map[key] === 'symbol')) {
+                    return key === symbol || map[key] === symbol;
+                }
+                return false;
+            }) || Object.getOwnPropertySymbols(map).some(sym => sym === symbol);
+        });
+    }
+}
+/**
+ * Helper function to check if a string key represents a Symbol.for expression
+ */
+function isSymbolForKey(key) {
+    return key.startsWith('[Symbol.for(') && key.endsWith(')]');
+}
+/**
+ * Helper function to extract the symbol key from a Symbol.for string
+ */
+function parseSymbolForKey(key) {
+    const match = key.match(/^\[Symbol\.for\(['"](.+)['"]\)\]$/);
+    if (match && match[1]) {
+        return Symbol.for(match[1]);
+    }
+    return null;
+}
+/**
+ * Helper function to parse a path string with ?. notation
+ */
+function parsePath(path) {
+    return path
+        .split('.')
+        .map(part => part.replace(/\?/g, ''))
+        .filter(part => part.length > 0);
+}
+/**
+ * Helper function to check if a path starts with ?. notation
+ */
+function isNestedPath(path) {
+    return path.startsWith('?.');
+}
+/**
+ * Helper function to get or create a nested object
+ */
+function ensureNestedPath(obj, pathParts) {
+    let current = obj;
+    for (const part of pathParts.slice(0, -1)) {
+        if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Main assignGingerly function
+ */
+export async function assignGingerly(target, source, options) {
+    if (!target || typeof target !== 'object') {
+        return target;
+    }
+    const registry = options?.registry instanceof BaseRegistry
+        ? options.registry
+        : 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)) {
+        if (isSymbolForKey(key)) {
+            const symbol = parseSymbolForKey(key);
+            if (symbol) {
+                processedSource[symbol] = source[key];
+            }
+            else {
+                // Invalid Symbol.for format - treat as regular string key
+                processedSource[key] = source[key];
+            }
+        }
+        else {
+            processedSource[key] = source[key];
+        }
+    }
+    // Copy over actual symbol keys
+    for (const sym of Object.getOwnPropertySymbols(source)) {
+        processedSource[sym] = source[sym];
+    }
+    // First pass: handle all non-symbol keys and sync operations
+    for (const key of Object.keys(processedSource)) {
+        const value = processedSource[key];
+        if (isNestedPath(key)) {
+            const pathParts = parsePath(key);
+            const lastKey = pathParts[pathParts.length - 1];
+            const parent = ensureNestedPath(target, pathParts);
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                // Recursively apply assignGingerly for nested objects
+                if (!(lastKey in parent) || typeof parent[lastKey] !== 'object') {
+                    parent[lastKey] = {};
+                }
+                await assignGingerly(parent[lastKey], value, options);
+            }
+            else {
+                parent[lastKey] = value;
+            }
+        }
+        else {
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                // Recursively apply assignGingerly for nested objects
+                if (!(key in target) || typeof target[key] !== 'object') {
+                    target[key] = {};
+                }
+                await assignGingerly(target[key], value, options);
+            }
+            else {
+                target[key] = value;
+            }
+        }
+    }
+    // Second pass: handle symbol keys for dependency injection
+    const symbols = Object.getOwnPropertySymbols(processedSource);
+    for (const sym of symbols) {
+        const value = processedSource[sym];
+        if (registry) {
+            const registryItem = registry.findBySymbol(sym);
+            if (registryItem) {
+                // Get or initialize the instances map for this target
+                if (!instanceMap.has(target)) {
+                    instanceMap.set(target, new Map());
+                }
+                const instances = instanceMap.get(target);
+                // 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);
+                    instance = new SpawnClass();
+                    instances.set(sym, instance);
+                }
+                // Find the mapped property name
+                const mappedKey = registryItem.map[sym];
+                if (mappedKey && instance && typeof instance === 'object') {
+                    instance[mappedKey] = value;
+                }
+            }
+        }
+    }
+    // Add lazy 'set' property that returns a proxy
+    if (registry && !('set' in target)) {
+        Object.defineProperty(target, 'set', {
+            get() {
+                return new Proxy({}, {
+                    set: (_, prop, value) => {
+                        if (typeof prop === 'symbol') {
+                            const registryItem = registry.findBySymbol(prop);
+                            if (registryItem) {
+                                if (!instanceMap.has(target)) {
+                                    instanceMap.set(target, new Map());
+                                }
+                                const instances = instanceMap.get(target);
+                                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;
+                                        }
+                                    }
+                                }
+                                else {
+                                    const mappedKey = registryItem.map[prop];
+                                    if (mappedKey && instance && typeof instance === 'object') {
+                                        instance[mappedKey] = value;
+                                    }
+                                }
+                            }
+                        }
+                        return true;
+                    },
+                });
+            },
+            configurable: true,
+        });
+    }
+    return target;
+}
+export default assignGingerly;

package/package.json

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