assign-gingerly 0.0.21 → 0.0.23

package/assignGingerly.js

@@ -1,22 +1,3 @@
-// Polyfill for Map.prototype.getOrInsert and WeakMap.prototype.getOrInsert
-if (typeof Map.prototype.getOrInsertComputed !== 'function') {
-    Map.prototype.getOrInsertComputed = function (key, insert) {
-        if (this.has(key))
-            return this.get(key);
-        const value = insert();
-        this.set(key, value);
-        return value;
-    };
-}
-if (typeof WeakMap.prototype.getOrInsertComputed !== 'function') {
-    WeakMap.prototype.getOrInsertComputed = function (key, insert) {
-        if (this.has(key))
-            return this.get(key);
-        const value = insert();
-        this.set(key, value);
-        return value;
-    };
-}
 /**
  * GUID for global instance map storage to ensure uniqueness across package versions
  */
@@ -35,34 +16,126 @@ export function getInstanceMap() {
 /**
  * Base registry class for managing enhancement configurations
  */
-export class EnhancementRegistry {
-    #items = [];
+/**
+ * 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)) {
-            this.#items.push(...items);
+            items.forEach(item => this.#items.add(item));
         }
         else {
-            this.#items.push(items);
+            this.#items.add(items);
         }
+        // Dispatch event after adding items
+        this.dispatchEvent(new EnhancementRegisteredEvent(items));
     }
     getItems() {
-        return this.#items;
+        return Array.from(this.#items);
     }
     findBySymbol(symbol) {
-        return this.#items.find(item => {
+        for (const item of this.#items) {
             const symlinks = item.symlinks;
             if (!symlinks)
-                return false;
-            return Object.keys(symlinks).some(key => {
+                continue;
+            const hasSymbol = Object.keys(symlinks).some(key => {
                 if (typeof key === 'symbol' || (typeof symlinks[key] === 'symbol')) {
                     return key === symbol || symlinks[key] === symbol;
                 }
                 return false;
             }) || Object.getOwnPropertySymbols(symlinks).some(sym => sym === symbol);
-        });
+            if (hasSymbol)
+                return item;
+        }
+        return undefined;
     }
     findByEnhKey(enhKey) {
-        return this.#items.find(item => item.enhKey === enhKey);
+        for (const item of this.#items) {
+            if (item.enhKey === enhKey)
+                return item;
+        }
+        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);
+                }
+            }
+        });
     }
 }
 /**
@@ -187,6 +260,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];

package/assignGingerly.ts

@@ -2,34 +2,55 @@
 
 import { EnhancementConfig } from "./types/assign-gingerly/types";
 
-// Polyfill for Map.prototype.getOrInsert and WeakMap.prototype.getOrInsert
-if (typeof Map.prototype.getOrInsertComputed !== 'function') {
-  Map.prototype.getOrInsertComputed = function(key, insert) {
-    if (this.has(key)) return this.get(key);
-    const value = insert();
-    this.set(key, value);
-    return value;
-  };
-}
-if (typeof WeakMap.prototype.getOrInsertComputed !== 'function') {
-  WeakMap.prototype.getOrInsertComputed = function(key, insert) {
-    if (this.has(key)) return this.get(key);
-    const value = insert();
-    this.set(key, value);
-    return value;
-  };
+/**
+ * Constructor signature for ItemScope Manager classes
+ */
+export type ItemscopeManager<T = any> = {
+  new (element: HTMLElement, initVals?: Partial<T>): T;
 }
 
 /**
- * @deprecated Use EnhancementConfig instead
+ * Configuration for ItemScope Manager registration
  */
-export type IBaseRegistryItem<T = any> = EnhancementConfig<T>;
+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') {
+//   WeakMap.prototype.getOrInsertComputed = function(key, insert) {
+//     if (this.has(key)) return this.get(key);
+//     const value = insert();
+//     this.set(key, value);
+//     return value;
+//   };
+// }
+
+// /**
+//  * @deprecated Use EnhancementConfig instead
+//  */
+// export type IBaseRegistryItem<T = any> = EnhancementConfig<T>;
 
 /**
  * Interface for the options passed to assignGingerly
  */
 export interface IAssignGingerlyOptions {
   registry?: typeof EnhancementRegistry | EnhancementRegistry;
+  bypassChecks?: boolean;
 }
 
 /**
@@ -52,39 +73,142 @@ export function getInstanceMap(): WeakMap<object, Map<EnhancementConfig, any>> {
 /**
  * Base registry class for managing enhancement configurations
  */
-export class EnhancementRegistry {
-  #items: EnhancementConfig[] = [];
+/**
+ * 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 {
     if (Array.isArray(items)) {
-      this.#items.push(...items);
+      items.forEach(item => this.#items.add(item));
     } else {
-      this.#items.push(items);
+      this.#items.add(items);
     }
+    
+    // Dispatch event after adding items
+    this.dispatchEvent(new EnhancementRegisteredEvent(items));
   }
 
   getItems(): EnhancementConfig[] {
-    return this.#items;
+    return Array.from(this.#items);
   }
 
   findBySymbol(symbol: symbol | string): EnhancementConfig | undefined {
-    return this.#items.find(item => {
+    for (const item of this.#items) {
       const symlinks = item.symlinks;
-      if (!symlinks) return false;
-      return Object.keys(symlinks).some(key => {
+      if (!symlinks) continue;
+
+      const hasSymbol = Object.keys(symlinks).some(key => {
         if (typeof key === 'symbol' || (typeof symlinks[key as any] === 'symbol')) {
           return key === symbol || symlinks[key as any] === symbol;
         }
         return false;
       }) || Object.getOwnPropertySymbols(symlinks).some(sym => sym === symbol);
-    });
+
+      if (hasSymbol) return item;
+    }
+    return undefined;
   }
 
   findByEnhKey(enhKey: string | symbol): EnhancementConfig | undefined {
-    return this.#items.find(item => item.enhKey === enhKey);
+    for (const item of this.#items) {
+      if (item.enhKey === enhKey) return item;
+    }
+    return undefined;
   }
 }
 
+/**
+ * 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
  */
@@ -223,6 +347,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];

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,
+    });
+}

package/handleIshProperty.ts

@@ -0,0 +1,115 @@
+import type { IAssignGingerlyOptions, ItemscopeManagerConfig } from './assignGingerly.js';
+
+/**
+ * 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: HTMLElement,
+  value: any,
+  options: IAssignGingerlyOptions | undefined,
+  assignGingerlyFn: (target: any, source: any, options?: IAssignGingerlyOptions) => any
+): Promise<void> {
+  // 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: HTMLElement,
+  managerName: string,
+  options: IAssignGingerlyOptions | undefined,
+  assignGingerlyFn: (target: any, source: any, options?: IAssignGingerlyOptions) => any
+): Promise<void> {
+  // Determine which registry to use
+  const registry = (element as any).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: any = null;
+  const valueQueue: any[] = [];
+
+  // Define the 'ish' property
+  Object.defineProperty(element, 'ish', {
+    get() {
+      return managerInstance;
+    },
+    set(newValue: any) {
+      // 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,
+  });
+}

package/index.js

@@ -1,6 +1,6 @@
 export { assignGingerly } from './assignGingerly.js';
 export { assignTentatively } from './assignTentatively.js';
-export { EnhancementRegistry } from './assignGingerly.js';
+export { EnhancementRegistry, ItemscopeRegistry, EnhancementRegisteredEvent } from './assignGingerly.js';
 export { waitForEvent } from './waitForEvent.js';
 export { ParserRegistry, globalParserRegistry } from './parserRegistry.js';
 export { parseWithAttrs } from './parseWithAttrs.js';

package/index.ts

@@ -1,6 +1,6 @@
 export {assignGingerly} from './assignGingerly.js';
 export {assignTentatively} from './assignTentatively.js';
-export {EnhancementRegistry} from './assignGingerly.js';
+export {EnhancementRegistry, ItemscopeRegistry, EnhancementRegisteredEvent} from './assignGingerly.js';
 export {waitForEvent} from './waitForEvent.js';
 export {ParserRegistry, globalParserRegistry} from './parserRegistry.js';
 export {parseWithAttrs} from './parseWithAttrs.js';