assign-gingerly 0.0.22 → 0.0.24

package/assignGingerly.js

@@ -16,7 +16,22 @@ export function getInstanceMap() {
 /**
  * Base registry class for managing enhancement configurations
  */
-export class EnhancementRegistry {
+/**
+ * Event dispatched when enhancement configs are registered
+ */
+export class EnhancementRegisteredEvent extends Event {
+    config;
+    static eventName = 'register';
+    constructor(config) {
+        super(EnhancementRegisteredEvent.eventName);
+        this.config = config;
+    }
+}
+/**
+ * Registry for enhancement configurations
+ * Extends EventTarget to dispatch events when configs are registered
+ */
+export class EnhancementRegistry extends EventTarget {
     #items = new Set();
     push(items) {
         if (Array.isArray(items)) {
@@ -25,6 +40,8 @@ export class EnhancementRegistry {
         else {
             this.#items.add(items);
         }
+        // Dispatch event after adding items
+        this.dispatchEvent(new EnhancementRegisteredEvent(items));
     }
     getItems() {
         return Array.from(this.#items);
@@ -53,6 +70,74 @@ export class EnhancementRegistry {
         return undefined;
     }
 }
+/**
+ * Registry for ItemScope Manager configurations
+ * Extends EventTarget to support lazy registration via events
+ */
+export class ItemscopeRegistry extends EventTarget {
+    #configs = new Map();
+    #pendingSetups = new Map();
+    /**
+     * Define a new manager configuration
+     * @param name - Manager name (matches itemscope attribute value)
+     * @param config - Manager configuration object
+     * @throws Error if name is already registered
+     */
+    define(name, config) {
+        if (this.#configs.has(name)) {
+            throw new Error('Already registered');
+        }
+        this.#configs.set(name, config);
+        this.dispatchEvent(new Event(name));
+    }
+    /**
+     * Get a manager configuration by name
+     * @param name - Manager name
+     * @returns Manager configuration or undefined
+     */
+    get(name) {
+        return this.#configs.get(name);
+    }
+    /**
+     * Wait for a manager to be defined and all pending setups to complete
+     * @param name - Manager name to wait for
+     * @returns Promise that resolves when manager is defined and all setups are complete
+     */
+    async whenDefined(name) {
+        // If not yet defined, wait for definition
+        if (!this.#configs.has(name)) {
+            await new Promise((resolve) => {
+                this.addEventListener(name, () => resolve(), { once: true });
+            });
+        }
+        // Wait for all pending setups for this manager
+        const pending = this.#pendingSetups.get(name);
+        if (pending && pending.length > 0) {
+            await Promise.all(pending);
+        }
+    }
+    /**
+     * Internal method to track a pending setup
+     * @param name - Manager name
+     * @param promise - Promise representing the setup operation
+     */
+    _trackSetup(name, promise) {
+        if (!this.#pendingSetups.has(name)) {
+            this.#pendingSetups.set(name, []);
+        }
+        this.#pendingSetups.get(name).push(promise);
+        // Clean up after completion
+        promise.finally(() => {
+            const pending = this.#pendingSetups.get(name);
+            if (pending) {
+                const index = pending.indexOf(promise);
+                if (index > -1) {
+                    pending.splice(index, 1);
+                }
+            }
+        });
+    }
+}
 /**
  * Helper function to check if a string key represents a Symbol.for expression
  */
@@ -142,6 +227,49 @@ function ensureNestedPath(obj, pathParts) {
     }
     return current;
 }
+/**
+ * Helper function to check if a property is readonly
+ * A property is readonly if:
+ * - It's a data property with writable: false, OR
+ * - It's an accessor property with a getter but no setter
+ */
+function isReadonlyProperty(obj, propName) {
+    let descriptor = Object.getOwnPropertyDescriptor(obj, propName);
+    if (!descriptor) {
+        // Check prototype chain
+        let proto = Object.getPrototypeOf(obj);
+        while (proto) {
+            descriptor = Object.getOwnPropertyDescriptor(proto, propName);
+            if (descriptor)
+                break;
+            proto = Object.getPrototypeOf(proto);
+        }
+    }
+    if (!descriptor)
+        return false;
+    // If it's a data property, check writable flag
+    if ('value' in descriptor) {
+        return descriptor.writable === false;
+    }
+    // If it's an accessor property, check if it has only a getter (no setter)
+    if ('get' in descriptor) {
+        return descriptor.set === undefined;
+    }
+    return false;
+}
+/**
+ * Helper function to check if a value is a class instance (not a plain object)
+ * Returns true for instances of classes, false for plain objects, arrays, and primitives
+ */
+function isClassInstance(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    // Plain objects have Object.prototype or null as prototype
+    return proto !== Object.prototype && proto !== null;
+}
 /**
  * Main assignGingerly function
  */
@@ -175,6 +303,38 @@ export function assignGingerly(target, source, options) {
     for (const sym of Object.getOwnPropertySymbols(source)) {
         processedSource[sym] = source[sym];
     }
+    // Process 'ish' property for HTMLElements with itemscope (async, non-blocking)
+    if ('ish' in processedSource) {
+        if (typeof HTMLElement !== 'undefined' && target instanceof HTMLElement) {
+            // Capture the value before deleting
+            const ishValue = processedSource['ish'];
+            // Remove 'ish' from processedSource to prevent normal assignment
+            delete processedSource['ish'];
+            // Get the itemscope attribute to track the setup
+            const itemscopeValue = target.getAttribute('itemscope');
+            // Load handler on demand and process asynchronously
+            const setupPromise = (async () => {
+                try {
+                    const { handleIshProperty } = await import('./handleIshProperty.js');
+                    await handleIshProperty(target, ishValue, options, assignGingerly);
+                }
+                catch (err) {
+                    console.error('Error in handleIshProperty:', err);
+                    // Re-throw errors asynchronously so they're visible
+                    setTimeout(() => { throw err; }, 0);
+                }
+            })();
+            // Track the setup promise with the registry if we have an itemscope value
+            if (itemscopeValue && typeof itemscopeValue === 'string' && itemscopeValue.length > 0) {
+                const registry = target.customElementRegistry?.itemscopeRegistry
+                    ?? (typeof customElements !== 'undefined' ? customElements.itemscopeRegistry : undefined);
+                if (registry && typeof registry._trackSetup === 'function') {
+                    registry._trackSetup(itemscopeValue, setupPromise);
+                }
+            }
+        }
+        // For non-HTMLElement targets, 'ish' is processed as a normal property
+    }
     // First pass: handle all non-symbol keys and sync operations
     for (const key of Object.keys(processedSource)) {
         const value = processedSource[key];
@@ -280,11 +440,23 @@ export function assignGingerly(target, source, options) {
             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] = {};
+                // Check if property exists and is readonly OR is a class instance
+                if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+                    // Property is readonly or a class instance - check if current value is an object
+                    const currentValue = parent[lastKey];
+                    if (typeof currentValue !== 'object' || currentValue === null) {
+                        throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+                    }
+                    // Recursively apply assignGingerly to the readonly object or class instance
+                    assignGingerly(currentValue, value, options);
+                }
+                else {
+                    // Property is writable and not a class instance - normal recursive merge
+                    if (!(lastKey in parent) || typeof parent[lastKey] !== 'object') {
+                        parent[lastKey] = {};
+                    }
+                    assignGingerly(parent[lastKey], value, options);
                 }
-                assignGingerly(parent[lastKey], value, options);
             }
             else {
                 parent[lastKey] = value;
@@ -292,11 +464,23 @@ export function assignGingerly(target, source, options) {
         }
         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] = {};
+                // Check if property exists and is readonly OR is a class instance
+                if (key in target && (isReadonlyProperty(target, key) || isClassInstance(target[key]))) {
+                    // Property is readonly or a class instance - check if current value is an object
+                    const currentValue = target[key];
+                    if (typeof currentValue !== 'object' || currentValue === null) {
+                        throw new Error(`Cannot merge object into ${isReadonlyProperty(target, key) ? 'readonly ' : ''}primitive property '${String(key)}'`);
+                    }
+                    // Recursively apply assignGingerly to the readonly object or class instance
+                    assignGingerly(currentValue, value, options);
+                }
+                else {
+                    // Property is writable and not a class instance - normal recursive merge
+                    if (!(key in target) || typeof target[key] !== 'object') {
+                        target[key] = {};
+                    }
+                    assignGingerly(target[key], value, options);
                 }
-                assignGingerly(target[key], value, options);
             }
             else {
                 target[key] = value;

package/assignGingerly.ts

@@ -2,6 +2,33 @@
 
 import { EnhancementConfig } from "./types/assign-gingerly/types";
 
+/**
+ * Constructor signature for ItemScope Manager classes
+ */
+export type ItemscopeManager<T = any> = {
+  new (element: HTMLElement, initVals?: Partial<T>): T;
+}
+
+/**
+ * Configuration for ItemScope Manager registration
+ */
+export interface ItemscopeManagerConfig<T = any> {
+  /**
+   * Manager class constructor
+   */
+  manager: ItemscopeManager<T>;
+  
+  /**
+   * Optional lifecycle method keys
+   * - dispose: Method name to call when manager is disposed
+   * - resolved: Property/event name indicating manager is ready
+   */
+  lifecycleKeys?: {
+    dispose?: string | symbol;
+    resolved?: string | symbol;
+  };
+}
+
 // Polyfill for WeakMap.prototype.getOrInsert
 
 // if (typeof WeakMap.prototype.getOrInsertComputed !== 'function') {
@@ -23,6 +50,7 @@ import { EnhancementConfig } from "./types/assign-gingerly/types";
  */
 export interface IAssignGingerlyOptions {
   registry?: typeof EnhancementRegistry | EnhancementRegistry;
+  bypassChecks?: boolean;
 }
 
 /**
@@ -45,7 +73,24 @@ export function getInstanceMap(): WeakMap<object, Map<EnhancementConfig, any>> {
 /**
  * Base registry class for managing enhancement configurations
  */
-export class EnhancementRegistry {
+/**
+ * Event dispatched when enhancement configs are registered
+ */
+export class EnhancementRegisteredEvent extends Event {
+  static eventName = 'register';
+  
+  constructor(
+    public config: EnhancementConfig | EnhancementConfig[]
+  ) {
+    super(EnhancementRegisteredEvent.eventName);
+  }
+}
+
+/**
+ * Registry for enhancement configurations
+ * Extends EventTarget to dispatch events when configs are registered
+ */
+export class EnhancementRegistry extends EventTarget {
   #items: Set<EnhancementConfig> = new Set();
 
   push(items: EnhancementConfig | EnhancementConfig[]): void {
@@ -54,6 +99,9 @@ export class EnhancementRegistry {
     } else {
       this.#items.add(items);
     }
+    
+    // Dispatch event after adding items
+    this.dispatchEvent(new EnhancementRegisteredEvent(items));
   }
 
   getItems(): EnhancementConfig[] {
@@ -85,6 +133,81 @@ export class EnhancementRegistry {
   }
 }
 
+/**
+ * Registry for ItemScope Manager configurations
+ * Extends EventTarget to support lazy registration via events
+ */
+export class ItemscopeRegistry extends EventTarget {
+  #configs: Map<string, ItemscopeManagerConfig> = new Map();
+  #pendingSetups: Map<string, Promise<void>[]> = new Map();
+
+  /**
+   * Define a new manager configuration
+   * @param name - Manager name (matches itemscope attribute value)
+   * @param config - Manager configuration object
+   * @throws Error if name is already registered
+   */
+  define(name: string, config: ItemscopeManagerConfig): void {
+    if (this.#configs.has(name)) {
+      throw new Error('Already registered');
+    }
+    this.#configs.set(name, config);
+    this.dispatchEvent(new Event(name));
+  }
+
+  /**
+   * Get a manager configuration by name
+   * @param name - Manager name
+   * @returns Manager configuration or undefined
+   */
+  get(name: string): ItemscopeManagerConfig | undefined {
+    return this.#configs.get(name);
+  }
+
+  /**
+   * Wait for a manager to be defined and all pending setups to complete
+   * @param name - Manager name to wait for
+   * @returns Promise that resolves when manager is defined and all setups are complete
+   */
+  async whenDefined(name: string): Promise<void> {
+    // If not yet defined, wait for definition
+    if (!this.#configs.has(name)) {
+      await new Promise<void>((resolve) => {
+        this.addEventListener(name, () => resolve(), { once: true });
+      });
+    }
+
+    // Wait for all pending setups for this manager
+    const pending = this.#pendingSetups.get(name);
+    if (pending && pending.length > 0) {
+      await Promise.all(pending);
+    }
+  }
+
+  /**
+   * Internal method to track a pending setup
+   * @param name - Manager name
+   * @param promise - Promise representing the setup operation
+   */
+  _trackSetup(name: string, promise: Promise<void>): void {
+    if (!this.#pendingSetups.has(name)) {
+      this.#pendingSetups.set(name, []);
+    }
+    this.#pendingSetups.get(name)!.push(promise);
+
+    // Clean up after completion
+    promise.finally(() => {
+      const pending = this.#pendingSetups.get(name);
+      if (pending) {
+        const index = pending.indexOf(promise);
+        if (index > -1) {
+          pending.splice(index, 1);
+        }
+      }
+    });
+  }
+}
+
 
 /**
  * Helper function to check if a string key represents a Symbol.for expression
@@ -186,6 +309,53 @@ function ensureNestedPath(obj: any, pathParts: string[]): any {
   return current;
 }
 
+/**
+ * Helper function to check if a property is readonly
+ * A property is readonly if:
+ * - It's a data property with writable: false, OR
+ * - It's an accessor property with a getter but no setter
+ */
+function isReadonlyProperty(obj: any, propName: string | symbol): boolean {
+  let descriptor = Object.getOwnPropertyDescriptor(obj, propName);
+  
+  if (!descriptor) {
+    // Check prototype chain
+    let proto = Object.getPrototypeOf(obj);
+    while (proto) {
+      descriptor = Object.getOwnPropertyDescriptor(proto, propName);
+      if (descriptor) break;
+      proto = Object.getPrototypeOf(proto);
+    }
+  }
+  
+  if (!descriptor) return false;
+  
+  // If it's a data property, check writable flag
+  if ('value' in descriptor) {
+    return descriptor.writable === false;
+  }
+  
+  // If it's an accessor property, check if it has only a getter (no setter)
+  if ('get' in descriptor) {
+    return descriptor.set === undefined;
+  }
+  
+  return false;
+}
+
+/**
+ * Helper function to check if a value is a class instance (not a plain object)
+ * Returns true for instances of classes, false for plain objects, arrays, and primitives
+ */
+function isClassInstance(value: any): boolean {
+  if (!value || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return false;
+  
+  const proto = Object.getPrototypeOf(value);
+  // Plain objects have Object.prototype or null as prototype
+  return proto !== Object.prototype && proto !== null;
+}
+
 /**
  * Main assignGingerly function
  */
@@ -224,6 +394,42 @@ export function assignGingerly(
     processedSource[sym] = source[sym];
   }
 
+  // Process 'ish' property for HTMLElements with itemscope (async, non-blocking)
+  if ('ish' in processedSource) {
+    if (typeof HTMLElement !== 'undefined' && target instanceof HTMLElement) {
+      // Capture the value before deleting
+      const ishValue = processedSource['ish'];
+      // Remove 'ish' from processedSource to prevent normal assignment
+      delete processedSource['ish'];
+      
+      // Get the itemscope attribute to track the setup
+      const itemscopeValue = target.getAttribute('itemscope');
+      
+      // Load handler on demand and process asynchronously
+      const setupPromise = (async () => {
+        try {
+          const { handleIshProperty } = await import('./handleIshProperty.js');
+          await handleIshProperty(target, ishValue, options, assignGingerly);
+        } catch (err) {
+          console.error('Error in handleIshProperty:', err);
+          // Re-throw errors asynchronously so they're visible
+          setTimeout(() => { throw err; }, 0);
+        }
+      })();
+      
+      // Track the setup promise with the registry if we have an itemscope value
+      if (itemscopeValue && typeof itemscopeValue === 'string' && itemscopeValue.length > 0) {
+        const registry = (target as any).customElementRegistry?.itemscopeRegistry
+          ?? (typeof customElements !== 'undefined' ? customElements.itemscopeRegistry : undefined);
+        
+        if (registry && typeof registry._trackSetup === 'function') {
+          registry._trackSetup(itemscopeValue, setupPromise);
+        }
+      }
+    }
+    // For non-HTMLElement targets, 'ish' is processed as a normal property
+  }
+
   // First pass: handle all non-symbol keys and sync operations
   for (const key of Object.keys(processedSource)) {
     const value = processedSource[key];
@@ -338,21 +544,43 @@ export function assignGingerly(
       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] = {};
+        // Check if property exists and is readonly OR is a class instance
+        if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+          // Property is readonly or a class instance - check if current value is an object
+          const currentValue = parent[lastKey];
+          if (typeof currentValue !== 'object' || currentValue === null) {
+            throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+          }
+          // Recursively apply assignGingerly to the readonly object or class instance
+          assignGingerly(currentValue, value, options);
+        } else {
+          // Property is writable and not a class instance - normal recursive merge
+          if (!(lastKey in parent) || typeof parent[lastKey] !== 'object') {
+            parent[lastKey] = {};
+          }
+          assignGingerly(parent[lastKey], value, options);
         }
-        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] = {};
+        // Check if property exists and is readonly OR is a class instance
+        if (key in target && (isReadonlyProperty(target, key) || isClassInstance(target[key]))) {
+          // Property is readonly or a class instance - check if current value is an object
+          const currentValue = target[key];
+          if (typeof currentValue !== 'object' || currentValue === null) {
+            throw new Error(`Cannot merge object into ${isReadonlyProperty(target, key) ? 'readonly ' : ''}primitive property '${String(key)}'`);
+          }
+          // Recursively apply assignGingerly to the readonly object or class instance
+          assignGingerly(currentValue, value, options);
+        } else {
+          // Property is writable and not a class instance - normal recursive merge
+          if (!(key in target) || typeof target[key] !== 'object') {
+            target[key] = {};
+          }
+          assignGingerly(target[key], value, options);
         }
-        assignGingerly(target[key], value, options);
       } else {
         target[key] = value;
       }

package/handleIshProperty.js

@@ -0,0 +1,92 @@
+/**
+ * Handle the 'ish' property assignment for HTMLElements with itemscope attributes.
+ * This function validates the element and value, then defines or updates the 'ish' property.
+ *
+ * @param element - The HTMLElement to assign the 'ish' property to
+ * @param value - The value to assign (must be an object)
+ * @param options - Optional assignGingerly options
+ * @param assignGingerlyFn - Reference to the assignGingerly function for recursive calls
+ */
+export async function handleIshProperty(element, value, options, assignGingerlyFn) {
+    // Validate itemscope attribute
+    const itemscopeValue = element.getAttribute('itemscope');
+    if (typeof itemscopeValue !== 'string' || itemscopeValue.length === 0) {
+        throw new Error('Element must have itemscope attribute set to a non-empty string value');
+    }
+    // Validate value is an object
+    if (typeof value !== 'object' || value === null) {
+        throw new Error('ish property value must be an object');
+    }
+    // Get or create the 'ish' property on the element
+    if (!('ish' in element)) {
+        await defineIshProperty(element, itemscopeValue, options, assignGingerlyFn);
+    }
+    // Queue the value for assignment
+    const ishDescriptor = Object.getOwnPropertyDescriptor(element, 'ish');
+    if (ishDescriptor && ishDescriptor.set) {
+        ishDescriptor.set.call(element, value);
+    }
+}
+/**
+ * Define the 'ish' property on an HTMLElement with itemscope attribute.
+ * This function handles both immediate and lazy manager instantiation.
+ *
+ * @param element - The HTMLElement to define the 'ish' property on
+ * @param managerName - The name of the manager (from itemscope attribute)
+ * @param options - Optional assignGingerly options
+ * @param assignGingerlyFn - Reference to the assignGingerly function for recursive calls
+ */
+async function defineIshProperty(element, managerName, options, assignGingerlyFn) {
+    // Determine which registry to use
+    const registry = element.customElementRegistry?.itemscopeRegistry
+        ?? (typeof customElements !== 'undefined' ? customElements.itemscopeRegistry : undefined);
+    if (!registry) {
+        throw new Error('ItemscopeRegistry not available');
+    }
+    // Check if manager is registered
+    let config = registry.get(managerName);
+    // If not registered, wait for registration
+    if (!config) {
+        const { waitForEvent } = await import('./waitForEvent.js');
+        await waitForEvent(registry, managerName);
+        config = registry.get(managerName);
+        if (!config) {
+            throw new Error(`Manager "${managerName}" not found after registration event`);
+        }
+    }
+    // Create manager instance
+    let managerInstance = null;
+    const valueQueue = [];
+    // Define the 'ish' property
+    Object.defineProperty(element, 'ish', {
+        get() {
+            return managerInstance;
+        },
+        set(newValue) {
+            // If setting the same instance, do nothing
+            if (newValue === managerInstance) {
+                return;
+            }
+            // Queue the value
+            valueQueue.push(newValue);
+            // If manager not yet instantiated, create it
+            if (!managerInstance) {
+                // Merge all queued values for initVals
+                const initVals = Object.assign({}, ...valueQueue);
+                managerInstance = new config.manager(element, initVals);
+                valueQueue.length = 0; // Clear queue
+            }
+            else {
+                // Process queue asynchronously
+                (async () => {
+                    while (valueQueue.length > 0) {
+                        const queuedValue = valueQueue.shift();
+                        await assignGingerlyFn(managerInstance, queuedValue, options);
+                    }
+                })();
+            }
+        },
+        enumerable: true,
+        configurable: true,
+    });
+}