@domql/utils 3.7.5 → 3.7.6

package/README.md

@@ -70,6 +70,50 @@ if (key === 'childProps') {
 
 When set on `element.props`, prevents the element from inheriting `childProps` from its parent via `inheritParentProps`. Used by fragment elements to avoid double-application of childProps (since fragments explicitly forward childProps to their children).
 
+## Scope (`scope.js`)
+
+### `createScope(element, parent)`
+
+Creates the scope for an element with prototype-chain inheritance:
+
+```
+el.scope → parent.scope → grandparent.scope → ... → root.scope → context.globalScope
+```
+
+**Behavior:**
+- **No own scope** — element inherits `parent.scope` directly (same reference)
+- **Own scope defined** (`scope: { myVar: 1 }`) — prototype is set to parent's scope, chaining up to `globalScope`
+- **No parent/root scope** — new scope created with `Object.create(context.globalScope)`
+- **No context** — plain `{}`
+
+### `globalScope`
+
+Automatically initialized as `context.globalScope = {}` if context exists. Sits at the bottom of every scope prototype chain, making its properties accessible from any element via `el.scope.X`.
+
+```js
+// In context or set by the serialization pipeline:
+context.globalScope = {
+  API_URL: 'https://api.example.com',
+  helpers: { capitalize: (s) => s[0].toUpperCase() + s.slice(1) }
+}
+
+// Accessible from any element — no import needed:
+onClick: (e, el) => fetch(el.scope.API_URL)
+
+// Also directly accessible:
+el.context.globalScope.API_URL
+```
+
+When a component defines its own scope, properties shadow parent/global values but the chain remains walkable:
+
+```js
+// Parent: scope = { theme: 'dark' }
+// Child:  scope = { count: 0 }
+// el.scope.count → 0      (own)
+// el.scope.theme → 'dark'  (parent, via prototype)
+// el.scope.API_URL → '...' (globalScope, via prototype chain)
+```
+
 ## Key Sets (`keys.js`)
 
 - **`DOMQ_PROPERTIES`** — Framework-level keys that stay at element root

package/dist/cjs/object.js

@@ -26,6 +26,7 @@ __export(object_exports, {
   deepDestringifyFunctions: () => deepDestringifyFunctions,
   deepMerge: () => deepMerge,
   deepStringifyFunctions: () => deepStringifyFunctions,
+  destringifyGlobalScope: () => destringifyGlobalScope,
   detectInfiniteLoop: () => detectInfiniteLoop,
   excludeKeysFromObject: () => excludeKeysFromObject,
   exec: () => exec,
@@ -337,6 +338,35 @@ const deepDestringifyFunctions = (obj, destringified = {}) => {
   }
   return destringified;
 };
+const destringifyGlobalScope = (gs) => {
+  if (!gs || typeof gs !== "object") return gs;
+  const result = {};
+  const fnEntries = [];
+  for (const key of Object.keys(gs)) {
+    const val = gs[key];
+    if ((0, import_types.isString)(val) && hasFunction(val)) {
+      fnEntries.push([key, val]);
+    } else {
+      result[key] = val;
+    }
+  }
+  for (const [key, fnStr] of fnEntries) {
+    try {
+      const varDecls = Object.keys(result).map((k) => `var ${k} = __gs__[${JSON.stringify(k)}];`).join("\n");
+      result[key] = import_globals.window.eval(
+        `(function(__gs__) { ${varDecls}
+ return (${fnStr}); })`
+      )(result);
+    } catch (e) {
+      try {
+        result[key] = import_globals.window.eval(`(${fnStr})`);
+      } catch (_) {
+        result[key] = fnStr;
+      }
+    }
+  }
+  return result;
+};
 const stringToObject = (str, opts = { verbose: true }) => {
   try {
     return str ? import_globals.window.eval("(" + str + ")") : {};

package/dist/cjs/scope.js

@@ -23,5 +23,22 @@ __export(scope_exports, {
 module.exports = __toCommonJS(scope_exports);
 const createScope = (element, parent) => {
   const { __ref: ref } = element;
-  if (!element.scope) element.scope = parent.scope || ref.root?.scope || {};
+  const context = element.context || parent.context || ref.root?.context;
+  if (context && !context.globalScope) context.globalScope = {};
+  const parentScope = parent.scope || ref.root?.scope;
+  const globalScope = context?.globalScope;
+  if (!element.scope) {
+    if (parentScope) {
+      element.scope = parentScope;
+    } else if (globalScope) {
+      element.scope = Object.create(globalScope);
+    } else {
+      element.scope = {};
+    }
+  } else if (typeof element.scope === "object" && element.scope !== null) {
+    if (Object.getPrototypeOf(element.scope) === Object.prototype) {
+      const proto = parentScope || globalScope;
+      if (proto) Object.setPrototypeOf(element.scope, proto);
+    }
+  }
 };

package/dist/esm/object.js

@@ -293,6 +293,35 @@ const deepDestringifyFunctions = (obj, destringified = {}) => {
   }
   return destringified;
 };
+const destringifyGlobalScope = (gs) => {
+  if (!gs || typeof gs !== "object") return gs;
+  const result = {};
+  const fnEntries = [];
+  for (const key of Object.keys(gs)) {
+    const val = gs[key];
+    if (isString(val) && hasFunction(val)) {
+      fnEntries.push([key, val]);
+    } else {
+      result[key] = val;
+    }
+  }
+  for (const [key, fnStr] of fnEntries) {
+    try {
+      const varDecls = Object.keys(result).map((k) => `var ${k} = __gs__[${JSON.stringify(k)}];`).join("\n");
+      result[key] = window.eval(
+        `(function(__gs__) { ${varDecls}
+ return (${fnStr}); })`
+      )(result);
+    } catch (e) {
+      try {
+        result[key] = window.eval(`(${fnStr})`);
+      } catch (_) {
+        result[key] = fnStr;
+      }
+    }
+  }
+  return result;
+};
 const stringToObject = (str, opts = { verbose: true }) => {
   try {
     return str ? window.eval("(" + str + ")") : {};
@@ -546,6 +575,7 @@ export {
   deepDestringifyFunctions,
   deepMerge,
   deepStringifyFunctions,
+  destringifyGlobalScope,
   detectInfiniteLoop,
   excludeKeysFromObject,
   exec,

package/dist/esm/scope.js

@@ -1,6 +1,23 @@
 const createScope = (element, parent) => {
   const { __ref: ref } = element;
-  if (!element.scope) element.scope = parent.scope || ref.root?.scope || {};
+  const context = element.context || parent.context || ref.root?.context;
+  if (context && !context.globalScope) context.globalScope = {};
+  const parentScope = parent.scope || ref.root?.scope;
+  const globalScope = context?.globalScope;
+  if (!element.scope) {
+    if (parentScope) {
+      element.scope = parentScope;
+    } else if (globalScope) {
+      element.scope = Object.create(globalScope);
+    } else {
+      element.scope = {};
+    }
+  } else if (typeof element.scope === "object" && element.scope !== null) {
+    if (Object.getPrototypeOf(element.scope) === Object.prototype) {
+      const proto = parentScope || globalScope;
+      if (proto) Object.setPrototypeOf(element.scope, proto);
+    }
+  }
 };
 export {
   createScope

package/dist/iife/index.js

@@ -1631,6 +1631,7 @@ var DomqlUtils = (() => {
     deepMergeExtends: () => deepMergeExtends,
     deepStringifyFunctions: () => deepStringifyFunctions,
     defineSetter: () => defineSetter,
+    destringifyGlobalScope: () => destringifyGlobalScope,
     detectInfiniteLoop: () => detectInfiniteLoop,
     document: () => document2,
     encodeNewlines: () => encodeNewlines,
@@ -2556,6 +2557,35 @@ var DomqlUtils = (() => {
     }
     return destringified;
   };
+  var destringifyGlobalScope = (gs) => {
+    if (!gs || typeof gs !== "object") return gs;
+    const result = {};
+    const fnEntries = [];
+    for (const key of Object.keys(gs)) {
+      const val = gs[key];
+      if (isString(val) && hasFunction(val)) {
+        fnEntries.push([key, val]);
+      } else {
+        result[key] = val;
+      }
+    }
+    for (const [key, fnStr] of fnEntries) {
+      try {
+        const varDecls = Object.keys(result).map((k) => `var ${k} = __gs__[${JSON.stringify(k)}];`).join("\n");
+        result[key] = window2.eval(
+          `(function(__gs__) { ${varDecls}
+ return (${fnStr}); })`
+        )(result);
+      } catch (e) {
+        try {
+          result[key] = window2.eval(`(${fnStr})`);
+        } catch (_) {
+          result[key] = fnStr;
+        }
+      }
+    }
+    return result;
+  };
   var stringToObject = (str, opts = { verbose: true }) => {
     try {
       return str ? window2.eval("(" + str + ")") : {};
@@ -4078,7 +4108,24 @@ var DomqlUtils = (() => {
   // scope.js
   var createScope = (element, parent) => {
     const { __ref: ref } = element;
-    if (!element.scope) element.scope = parent.scope || ref.root?.scope || {};
+    const context = element.context || parent.context || ref.root?.context;
+    if (context && !context.globalScope) context.globalScope = {};
+    const parentScope = parent.scope || ref.root?.scope;
+    const globalScope = context?.globalScope;
+    if (!element.scope) {
+      if (parentScope) {
+        element.scope = parentScope;
+      } else if (globalScope) {
+        element.scope = Object.create(globalScope);
+      } else {
+        element.scope = {};
+      }
+    } else if (typeof element.scope === "object" && element.scope !== null) {
+      if (Object.getPrototypeOf(element.scope) === Object.prototype) {
+        const proto = parentScope || globalScope;
+        if (proto) Object.setPrototypeOf(element.scope, proto);
+      }
+    }
   };
 
   // triggerEvent.js

package/object.js

@@ -348,6 +348,49 @@ export const deepDestringifyFunctions = (obj, destringified = {}) => {
   return destringified
 }
 
+/**
+ * Destringify a globalScope object so that function strings become real functions.
+ * All globalScope values are made available as local variables when eval'ing each
+ * function, so helpers can reference constants and other helpers naturally.
+ */
+export const destringifyGlobalScope = (gs) => {
+  if (!gs || typeof gs !== 'object') return gs
+
+  // First pass: collect non-function values (constants, arrays, objects)
+  const result = {}
+  const fnEntries = []
+  for (const key of Object.keys(gs)) {
+    const val = gs[key]
+    if (isString(val) && hasFunction(val)) {
+      fnEntries.push([key, val])
+    } else {
+      result[key] = val
+    }
+  }
+
+  // Second pass: eval functions in a closure with all values in scope
+  for (const [key, fnStr] of fnEntries) {
+    try {
+      // Build a closure that exposes all current globalScope values
+      const varDecls = Object.keys(result)
+        .map(k => `var ${k} = __gs__[${JSON.stringify(k)}];`)
+        .join('\n')
+      result[key] = window.eval(
+        `(function(__gs__) { ${varDecls}\n return (${fnStr}); })`
+      )(result)
+    } catch (e) {
+      // Fallback: try plain eval
+      try {
+        result[key] = window.eval(`(${fnStr})`)
+      } catch (_) {
+        result[key] = fnStr
+      }
+    }
+  }
+
+  return result
+}
+
 export const stringToObject = (str, opts = { verbose: true }) => {
   try {
     return str ? window.eval('(' + str + ')') : {} // eslint-disable-line

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domql/utils",
-  "version": "3.7.5",
+  "version": "3.7.6",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "module": "./dist/esm/index.js",
@@ -38,7 +38,7 @@
   },
   "gitHead": "9fc1b79b41cdc725ca6b24aec64920a599634681",
   "peerDependencies": {
-    "@symbo.ls/fetch": "^3.7.5"
+    "@symbo.ls/fetch": "^3.7.6"
   },
   "peerDependenciesMeta": {
     "@symbo.ls/fetch": {

package/scope.js

@@ -1,8 +1,32 @@
 'use strict'
 
 // Create scope - shared object across the elements to the own or the nearest parent
+// Prototype chain: own scope → parent scope → ... → root scope → globalScope
 export const createScope = (element, parent) => {
   const { __ref: ref } = element
-  // If the element doesn't have a scope, initialize it using the parent's scope or the root's scope.
-  if (!element.scope) element.scope = parent.scope || ref.root?.scope || {}
+  const context = element.context || parent.context || ref.root?.context
+
+  // Ensure globalScope exists on context
+  if (context && !context.globalScope) context.globalScope = {}
+
+  const parentScope = parent.scope || ref.root?.scope
+  const globalScope = context?.globalScope
+
+  if (!element.scope) {
+    // No own scope defined — inherit parent scope directly
+    if (parentScope) {
+      element.scope = parentScope
+    } else if (globalScope) {
+      // No parent scope either — create root-level scope with globalScope as prototype
+      element.scope = Object.create(globalScope)
+    } else {
+      element.scope = {}
+    }
+  } else if (typeof element.scope === 'object' && element.scope !== null) {
+    // Element defines its own scope — chain prototype to parent scope (or globalScope)
+    if (Object.getPrototypeOf(element.scope) === Object.prototype) {
+      const proto = parentScope || globalScope
+      if (proto) Object.setPrototypeOf(element.scope, proto)
+    }
+  }
 }