assign-gingerly 0.0.54 → 0.0.55

package/resolveIdRef.js

@@ -1,125 +1,144 @@
-/**
- * resolveIdRef.js — Cached element resolution via #[x] syntax.
- *
- * Dynamically imported by assignFrom when `withIds` is provided or `#[x]` patterns are detected.
- * Provides lazy, WeakRef-cached element lookups keyed by variable name.
- *
- * First access: runs the query against the target, auto-assigns an ID if needed, caches via WeakRef.
- * Subsequent access: WeakRef.deref() (~10ns) or getElementById fallback (~20-100ns).
- */
-
-/**
- * Module-level cache: rootNode → Map<varName, { id, WeakRef }>
- * WeakMap ensures cleanup when rootNode is GC'd.
- */
-const idCacheMap = new WeakMap();
-
-/**
- * Counter per rootNode for generating unique IDs.
- */
-const idCounterMap = new WeakMap();
-
-/**
- * Generate a unique ID within a rootNode.
- * Format: _ag0, _ag1, _ag2, ...
- */
-function generateUniqueId(rootNode) {
-    let counter = idCounterMap.get(rootNode) ?? 0;
-    let id;
-    // Ensure uniqueness (skip if ID already exists in the document)
-    do {
-        id = `_ag${counter}`;
-        counter++;
-    } while (rootNode.getElementById?.(id));
-    idCounterMap.set(rootNode, counter);
-    return id;
-}
-
-/**
- * Resolve a single #[varName] reference lazily.
- *
- * @param varName - The variable name (e.g., 'x' from '#[x]')
- * @param target - The target element to query against
- * @param withIds - The withIds configuration map
- * @returns The resolved element, or undefined if not found
- */
-export function resolveIdVariable(varName, target, withIds) {
-    const config = withIds[varName];
-    if (config === undefined) return undefined;
-
-    const rootNode = target.getRootNode?.() ?? target;
-
-    // Get or create cache for this rootNode
-    let cache = idCacheMap.get(rootNode);
-    if (!cache) {
-        cache = new Map();
-        idCacheMap.set(rootNode, cache);
-    }
-
-    // Check cache first
-    const cached = cache.get(varName);
-    if (cached) {
-        const el = cached.ref.deref();
-        if (el) return el;
-
-        // WeakRef was collected — try getElementById fallback
-        const el2 = rootNode.getElementById?.(cached.id);
-        if (el2) {
-            cache.set(varName, { id: cached.id, ref: new WeakRef(el2) });
-            return el2;
-        }
-        // Element no longer exists — fall through to re-query
-    }
-
-    // First time or cache miss — resolve the element
-    let el = null;
-
-    if (typeof config === 'string') {
-        // String form: existing ID — use getElementById directly
-        el = rootNode.getElementById?.(config) ?? null;
-    } else {
-        // Object form: { qry } — run querySelector against target
-        el = target.querySelector?.(config.qry) ?? null;
-    }
-
-    if (!el) return undefined;
-
-    // Ensure the element has an ID
-    let id = el.id;
-    if (!id) {
-        id = generateUniqueId(rootNode);
-        el.id = id;
-    }
-
-    // Cache it
-    cache.set(varName, { id, ref: new WeakRef(el) });
-    return el;
-}
-
-/**
- * Check if a key starts with #[...] syntax.
- */
-export function hasIdRef(key) {
-    return key.startsWith('#[');
-}
-
-/**
- * Extract the variable name and remaining path from a #[x]... key.
- * Returns { varName, remainingPath } or null if not valid.
- */
-export function parseIdRef(key) {
-    const closeIdx = key.indexOf(']');
-    if (closeIdx === -1) return null;
-
-    const varName = key.substring(2, closeIdx); // skip '#['
-    if (!varName) return null;
-
-    let remainingPath = key.substring(closeIdx + 1);
-
-    // Remove handler suffix if present (caller handles it separately)
-    if (remainingPath.endsWith(' =>')) {
-        remainingPath = remainingPath.substring(0, remainingPath.length - 3);
-    }
-
-    return { varName, remainingPath };
-}
+/**
+ * resolveIdRef.ts — Cached element resolution via #[x] syntax.
+ *
+ * Dynamically imported by assignFrom when `withIds` is provided or `#[x]` patterns are detected.
+ * Provides lazy, WeakRef-cached element lookups keyed by variable name.
+ *
+ * First access: runs the query against the target, auto-assigns an ID if needed, caches via WeakRef.
+ * Subsequent access: WeakRef.deref() (~10ns) or getElementById fallback (~20-100ns).
+ */
+/**
+ * Module-level cache: rootNode → Map<varName, { id, WeakRef }>
+ * WeakMap ensures cleanup when rootNode is GC'd.
+ */
+const idCacheMap = new WeakMap();
+/**
+ * Counter per rootNode for generating unique IDs.
+ */
+const idCounterMap = new WeakMap();
+/**
+ * Generate a unique ID within a rootNode.
+ * Format: _ag0, _ag1, _ag2, ...
+ */
+function generateUniqueId(rootNode) {
+    let counter = idCounterMap.get(rootNode) ?? 0;
+    let id;
+    // Ensure uniqueness (skip if ID already exists in the document)
+    do {
+        id = `_ag${counter}`;
+        counter++;
+    } while (rootNode.getElementById?.(id));
+    idCounterMap.set(rootNode, counter);
+    return id;
+}
+/**
+ * Resolve a single #[varName] reference lazily.
+ *
+ * @param varName - The variable name (e.g., 'x' from '#[x]')
+ * @param target - The target element to query against
+ * @param withIds - The withIds configuration map
+ * @returns The resolved element, or undefined if not found
+ */
+export function resolveIdVariable(varName, target, withIds) {
+    const config = withIds[varName];
+    if (config === undefined)
+        return undefined;
+    const rootNode = target.getRootNode?.() ?? target;
+    // Get or create cache for this rootNode
+    let cache = idCacheMap.get(rootNode);
+    if (!cache) {
+        cache = new Map();
+        idCacheMap.set(rootNode, cache);
+    }
+    // Check cache first
+    const cached = cache.get(varName);
+    if (cached) {
+        const el = cached.ref.deref();
+        if (el)
+            return el;
+        // WeakRef was collected — try getElementById fallback
+        const el2 = rootNode.getElementById?.(cached.id);
+        if (el2) {
+            cache.set(varName, { id: cached.id, ref: new WeakRef(el2) });
+            return el2;
+        }
+        // Element no longer exists — fall through to re-query
+    }
+    // First time or cache miss — resolve the element
+    let el = null;
+    if (typeof config === 'string') {
+        // String form: existing ID — use getElementById directly
+        el = rootNode.getElementById?.(config) ?? null;
+    }
+    else {
+        // Object form: { qry } — run querySelector against target
+        el = target.querySelector?.(config.qry) ?? null;
+    }
+    if (!el)
+        return undefined;
+    // Ensure the element has an ID
+    let id = el.id;
+    if (!id) {
+        id = generateUniqueId(rootNode);
+        el.id = id;
+    }
+    // Cache it
+    cache.set(varName, { id, ref: new WeakRef(el) });
+    return el;
+}
+/**
+ * Check if a key starts with #[...] syntax.
+ */
+export function hasIdRef(key) {
+    return key.startsWith('#[');
+}
+/**
+ * Extract the variable name and remaining path from a #[x]... key.
+ * Returns [varName, remainingPath] or null if not a valid #[x] reference.
+ *
+ * Examples:
+ *   '#[x]' → ['x', '']
+ *   '#[x] =>' → ['x', '']  (handler suffix handled separately)
+ *   '#[x]?.querySelector?..child' → ['x', '?.querySelector?..child']
+ *   '#[x]?.textContent =>' → ['x', '?.textContent']  (handler suffix handled separately)
+ */
+export function parseIdRef(key) {
+    const closeIdx = key.indexOf(']');
+    if (closeIdx === -1)
+        return null;
+    const varName = key.substring(2, closeIdx); // skip '#['
+    if (!varName)
+        return null;
+    let remainingPath = key.substring(closeIdx + 1);
+    // Remove handler suffix if present (caller handles it separately)
+    if (remainingPath.endsWith(' =>')) {
+        remainingPath = remainingPath.substring(0, remainingPath.length - 3);
+    }
+    return { varName, remainingPath };
+}
+/**
+ * Register an element in the WeakRef cache for fast subsequent access.
+ * Auto-assigns an ID if the element doesn't have one.
+ *
+ * Used by beVigilant to cache newly discovered elements so that future
+ * assignFrom calls can resolve them via getElementById/WeakRef.
+ *
+ * @param target - The target element (used to determine rootNode)
+ * @param varName - The cache key (typically the itemprop name)
+ * @param element - The element to cache
+ */
+export function registerInCache(target, varName, element) {
+    const rootNode = target.getRootNode?.() ?? target;
+    let cache = idCacheMap.get(rootNode);
+    if (!cache) {
+        cache = new Map();
+        idCacheMap.set(rootNode, cache);
+    }
+    // Ensure the element has an ID
+    let id = element.id;
+    if (!id) {
+        id = generateUniqueId(rootNode);
+        element.id = id;
+    }
+    cache.set(varName, { id, ref: new WeakRef(element) });
+}

package/resolveIdRef.ts

@@ -138,3 +138,33 @@ export function parseIdRef(key: string): { varName: string; remainingPath: strin
 
     return { varName, remainingPath };
 }
+
+/**
+ * Register an element in the WeakRef cache for fast subsequent access.
+ * Auto-assigns an ID if the element doesn't have one.
+ * 
+ * Used by beVigilant to cache newly discovered elements so that future
+ * assignFrom calls can resolve them via getElementById/WeakRef.
+ * 
+ * @param target - The target element (used to determine rootNode)
+ * @param varName - The cache key (typically the itemprop name)
+ * @param element - The element to cache
+ */
+export function registerInCache(target: any, varName: string, element: Element): void {
+    const rootNode = target.getRootNode?.() ?? target;
+
+    let cache = idCacheMap.get(rootNode);
+    if (!cache) {
+        cache = new Map();
+        idCacheMap.set(rootNode, cache);
+    }
+
+    // Ensure the element has an ID
+    let id = element.id;
+    if (!id) {
+        id = generateUniqueId(rootNode);
+        element.id = id;
+    }
+
+    cache.set(varName, { id, ref: new WeakRef(element) });
+}

package/types/assign-gingerly/types.d.ts

@@ -64,6 +64,12 @@ export interface EnhancementConfig<T = any, Obj = Element> extends EnhancementCo
 
   //only applicable when spawning from a DOM Element reference
   enhKey?: EnhKey;
+
+  /**
+   * Optional features to associate with the spawn class.
+   * Calls assignFeatures(spawn, features) automatically on registration.
+   */
+  features?: FeatureConfigsMap;
     
 }
 
@@ -300,6 +306,12 @@ export interface ItemscopeManagerConfig<T = any> {
     dispose?: string | symbol;
     resolved?: string | symbol;
   };
+
+  /**
+   * Optional features to associate with the manager class.
+   * Calls assignFeatures(manager, features) automatically on registration.
+   */
+  features?: FeatureConfigsMap;
 }
 
 /**