@domql/utils 3.6.3 → 3.6.6

package/README.md

@@ -0,0 +1,77 @@
+# @domql/utils
+
+Core utility functions for the DOMQL element system.
+
+## Propertization (`props.js`)
+
+The propertization system normalizes element definitions by sorting keys between the element root (child elements, framework keys) and `props` (CSS properties, design tokens, custom data).
+
+### Two-phase process
+
+1. **`pickupPropsFromElement`** — Scans element root keys and moves non-element, non-builtin keys into `props`
+2. **`pickupElementFromProps`** — Scans `props` keys and moves element-like or builtin keys back to the element root
+
+### Key classification rules
+
+| Pattern | Classification | Example |
+|---------|---------------|---------|
+| Starts with uppercase | Child element | `Header`, `Button`, `Nav` |
+| Numeric key | Child element | `0`, `1`, `2` |
+| In `DOMQ_PROPERTIES` | Framework builtin | `tag`, `extends`, `on` |
+| In `CSS_SELECTOR_PREFIXES` | CSS-in-props | `:hover`, `@mobileS`, `$isActive` |
+| Has define handler | Define key (stays at root) | `$router`, deprecated: `$propsCollection` |
+| `childProps` | Always in props | `childProps` |
+| `onXxx` + function | Event handler | `onClick`, `onSubmit` |
+| Everything else | Prop | `padding`, `theme`, `color` |
+
+### CSS_SELECTOR_PREFIXES
+
+```javascript
+const CSS_SELECTOR_PREFIXES = new Set([
+  ':', '@', '[', '*', '+', '~', '&', '>', '$', '-', '.', '!'
+])
+```
+
+These single-character prefixes identify keys that should be processed by `css-in-props` via `transformersByPrefix`. When a key starts with one of these characters, it gets moved into `props`.
+
+### Define-awareness
+
+The `$` prefix is shared between css-in-props conditionals (`$isActive`) and define handlers (built-in `$router`, plus deprecated v2 handlers like `$propsCollection`, `$collection` that some older projects still use). The propertization must check for define handlers **before** applying prefix rules:
+
+```javascript
+// Check define handlers first — these stay at root
+const defineValue = this.define?.[key]
+const globalDefineValue = this.context?.define?.[key]
+if (isFunction(defineValue) || isFunction(globalDefineValue)) continue
+
+// Only then apply prefix-based classification
+if (CSS_SELECTOR_PREFIXES.has(firstChar)) {
+  obj.props[key] = value
+}
+```
+
+Without this check, define keys like `$router` (or deprecated `$propsCollection` in older projects) get moved into `props` and become invisible to `throughInitialDefine`, breaking routing and collection-based rendering.
+
+### childProps handling
+
+`childProps` is a framework property that configures child element props. It must always stay in `props` (consumed by `inheritParentProps`) even though its value may contain uppercase keys that look like child elements:
+
+```javascript
+// childProps: { Icon: { name: 'star' }, Hgroup: { ... } }
+// The uppercase keys inside are NOT child elements
+if (key === 'childProps') {
+  obj.props[key] = value
+  delete obj[key]
+  continue
+}
+```
+
+### ignoreChildProps
+
+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).
+
+## Key Sets (`keys.js`)
+
+- **`DOMQ_PROPERTIES`** — Framework-level keys that stay at element root
+- **`PROPS_METHODS`** — Keys on the props prototype (update, __element)
+- **`STATE_METHODS`** — State management methods (update, parse, set, toggle, etc.)

package/dist/cjs/keys.js

@@ -63,6 +63,7 @@ const DOMQ_PROPERTIES = /* @__PURE__ */ new Set([
   "node",
   "variables",
   "on",
+  "fetch",
   "component",
   "context"
 ]);
@@ -161,6 +162,8 @@ const METHODS = /* @__PURE__ */ new Set([
   "getRootData",
   "getRootContext",
   "getContext",
+  "getQuery",
+  "getDB",
   "getChildren"
 ]);
 const METHODS_EXL = /* @__PURE__ */ new Set([
@@ -188,5 +191,7 @@ const DOMQL_EVENTS = /* @__PURE__ */ new Set([
   "create",
   "complete",
   "frame",
-  "update"
+  "update",
+  "fetchError",
+  "fetchComplete"
 ]);

package/dist/cjs/methods.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var methods_exports = {};
 __export(methods_exports, {
@@ -24,7 +34,9 @@ __export(methods_exports, {
   get: () => get,
   getChildren: () => getChildren,
   getContext: () => getContext,
+  getDB: () => getDB,
   getPath: () => getPath,
+  getQuery: () => getQuery,
   getRef: () => getRef,
   getRoot: () => getRoot,
   getRootContext: () => getRootContext,
@@ -55,6 +67,7 @@ var import_types = require("./types.js");
 var import_object = require("./object.js");
 var import_env = require("./env.js");
 var import_array = require("./array.js");
+var import_cache = require("./cache.js");
 const ENV = process.env.NODE_ENV;
 function spotByPath(path) {
   const element = this;
@@ -368,6 +381,219 @@ function call(fnKey, ...args) {
     if (context?.strictMode) throw err;
   }
 }
+async function getDB() {
+  const element = this;
+  const db = element.context?.db;
+  if (!db) return null;
+  if (typeof db.select === "function") {
+    if (!db.__authInitialized && db.getSession) {
+      const { initAdapterAuth } = await import("@symbo.ls/fetch");
+      await initAdapterAuth(db, element.context);
+    }
+    return db;
+  }
+  if (db.__resolved) {
+    if (!db.__resolved.__authInitialized && db.__resolved.getSession) {
+      const { initAdapterAuth } = await import("@symbo.ls/fetch");
+      await initAdapterAuth(db.__resolved, element.context);
+    }
+    return db.__resolved;
+  }
+  if (db.__resolving) return db.__resolving;
+  const resolvePromise = import("@symbo.ls/fetch").then(({ resolveDb }) => resolveDb(db));
+  db.__resolving = resolvePromise;
+  const resolved = await resolvePromise;
+  db.__resolved = resolved;
+  element.context.db = resolved;
+  delete db.__resolving;
+  if (resolved.getSession) {
+    const { initAdapterAuth } = await import("@symbo.ls/fetch");
+    await initAdapterAuth(resolved, element.context);
+  }
+  return resolved;
+}
+function getQuery(format) {
+  const element = this;
+  const useStateQuery = format || import_cache.OPTIONS.useStateQuery || element.context?.useStateQuery;
+  if (!useStateQuery) return null;
+  const query = {};
+  buildQueryFromElement(element, query);
+  if (useStateQuery === true) return query;
+  const formatter = QUERY_FORMATTERS[useStateQuery];
+  return formatter ? formatter(query) : query;
+}
+const buildQueryFromElement = (element, query) => {
+  const ref = element.__ref;
+  if (!ref) return;
+  const stateKey = ref.__state;
+  if (stateKey && typeof stateKey === "string") {
+    setQueryPath(query, stateKey);
+  }
+  const children = ref.__children;
+  if (children) {
+    for (let i = 0; i < children.length; i++) {
+      const child = element[children[i]];
+      if (child && child.__ref) {
+        buildQueryFromElement(child, query);
+      }
+    }
+  }
+  const contentKey = ref.contentElementKey || "content";
+  const content = element[contentKey];
+  if (content && content.__ref) {
+    buildQueryFromElement(content, query);
+  }
+};
+const setQueryPath = (query, path) => {
+  const clean = path.replaceAll("../", "").replaceAll("~/", "");
+  const parts = clean.split("/");
+  let current = query;
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (i === parts.length - 1) {
+      if (!current[part]) current[part] = true;
+    } else {
+      if (current[part] === true) current[part] = {};
+      if (!current[part]) current[part] = {};
+      current = current[part];
+    }
+  }
+};
+const queryToGraphQL = (query, indent = 0) => {
+  const pad = "  ".repeat(indent);
+  const entries = Object.entries(query);
+  if (!entries.length) return "";
+  const fields = entries.map(([key, value]) => {
+    if (value === true) return `${pad}${key}`;
+    return `${pad}${key} {
+${queryToGraphQL(value, indent + 1)}
+${pad}}`;
+  });
+  return fields.join("\n");
+};
+const formatGraphQL = (query) => {
+  return `{
+${queryToGraphQL(query, 1)}
+}`;
+};
+const formatJsonApi = (query) => {
+  const result = { fields: {}, include: [] };
+  const walk = (obj, prefix) => {
+    const fields = [];
+    for (const key in obj) {
+      if (obj[key] === true) {
+        fields.push(key);
+      } else {
+        const nested = prefix ? `${prefix}.${key}` : key;
+        result.include.push(nested);
+        walk(obj[key], nested);
+      }
+    }
+    if (fields.length) {
+      result.fields[prefix || "_root"] = fields;
+    }
+  };
+  walk(query, "");
+  return result;
+};
+const formatOData = (query) => {
+  const build = (obj) => {
+    const select2 = [];
+    const expand2 = [];
+    for (const key in obj) {
+      if (obj[key] === true) {
+        select2.push(key);
+      } else {
+        const nested = build(obj[key]);
+        const parts2 = [];
+        if (nested.select) parts2.push(`$select=${nested.select}`);
+        if (nested.expand) parts2.push(`$expand=${nested.expand}`);
+        expand2.push(parts2.length ? `${key}(${parts2.join(";")})` : key);
+      }
+    }
+    return {
+      select: select2.length ? select2.join(",") : "",
+      expand: expand2.length ? expand2.join(",") : ""
+    };
+  };
+  const { select, expand } = build(query);
+  const parts = [];
+  if (select) parts.push(`$select=${select}`);
+  if (expand) parts.push(`$expand=${expand}`);
+  return parts.join("&");
+};
+const formatSQL = (query, options) => {
+  const columns = [];
+  const joins = [];
+  const tables = /* @__PURE__ */ new Set();
+  const walk = (obj, table, parentTable) => {
+    tables.add(table);
+    if (parentTable) {
+      joins.push(
+        `LEFT JOIN ${table} ON ${table}.${parentTable}_id = ${parentTable}.id`
+      );
+    }
+    for (const key in obj) {
+      if (obj[key] === true) {
+        columns.push(`${table}.${key}`);
+      } else {
+        walk(obj[key], key, table);
+      }
+    }
+  };
+  const roots = Object.keys(query);
+  if (roots.length === 1 && query[roots[0]] !== true) {
+    walk(query[roots[0]], roots[0], null);
+  } else {
+    walk(query, "_root", null);
+  }
+  const from = [...tables][0] || "_root";
+  const select = columns.length ? columns.join(", ") : "*";
+  const joinStr = joins.length ? "\n" + joins.join("\n") : "";
+  return `SELECT ${select}
+FROM ${from}${joinStr}`;
+};
+const formatPaths = (query) => {
+  const paths = [];
+  const walk = (obj, prefix) => {
+    for (const key in obj) {
+      const path = prefix ? `${prefix}/${key}` : key;
+      if (obj[key] === true) {
+        paths.push(path);
+      } else {
+        walk(obj[key], path);
+      }
+    }
+  };
+  walk(query, "");
+  return paths;
+};
+const formatSupabase = (query) => {
+  const build = (obj) => {
+    const parts = [];
+    for (const key in obj) {
+      if (obj[key] === true) {
+        parts.push(key);
+      } else {
+        parts.push(`${key}(${build(obj[key])})`);
+      }
+    }
+    return parts.join(", ");
+  };
+  const roots = Object.keys(query);
+  if (roots.length === 1 && query[roots[0]] !== true) {
+    return { from: roots[0], select: build(query[roots[0]]) };
+  }
+  return { from: null, select: build(query) };
+};
+const QUERY_FORMATTERS = {
+  graphql: formatGraphQL,
+  "json-api": formatJsonApi,
+  odata: formatOData,
+  sql: formatSQL,
+  supabase: formatSupabase,
+  paths: formatPaths
+};
 function isMethod(param, element) {
   return Boolean(import_keys.METHODS.has(param) || element?.context?.methods?.[param]);
 }

package/dist/cjs/state.js

@@ -38,10 +38,7 @@ var import_types = require("./types.js");
 const checkForStateTypes = (element) => {
   const { state: orig, props, __ref: ref } = element;
   const state = props?.state || orig;
-  if ((0, import_types.isFunction)(state)) {
-    ref.__state = state;
-    return (0, import_object.exec)(state, element);
-  } else if ((0, import_types.is)(state)("string", "number")) {
+  if ((0, import_types.is)(state)("string", "number")) {
     ref.__state = state;
     return { value: state };
   } else if (state === true) {
@@ -144,7 +141,7 @@ const createNestedObjectByKeyPath = (path, value) => {
 };
 const applyDependentState = (element, state) => {
   const { __element } = state;
-  const origState = (0, import_object.exec)(__element?.state, element);
+  const origState = __element?.state;
   if (!origState) return;
   const dependentState = (0, import_object.deepClone)(origState, import_keys.STATE_METHODS);
   const newDepends = { [element.key]: dependentState };

package/dist/esm/keys.js

@@ -33,6 +33,7 @@ const DOMQ_PROPERTIES = /* @__PURE__ */ new Set([
   "node",
   "variables",
   "on",
+  "fetch",
   "component",
   "context"
 ]);
@@ -131,6 +132,8 @@ const METHODS = /* @__PURE__ */ new Set([
   "getRootData",
   "getRootContext",
   "getContext",
+  "getQuery",
+  "getDB",
   "getChildren"
 ]);
 const METHODS_EXL = /* @__PURE__ */ new Set([
@@ -158,7 +161,9 @@ const DOMQL_EVENTS = /* @__PURE__ */ new Set([
   "create",
   "complete",
   "frame",
-  "update"
+  "update",
+  "fetchError",
+  "fetchComplete"
 ]);
 export {
   DOMQL_EVENTS,

package/dist/esm/methods.js

@@ -4,6 +4,7 @@ import { isDefined, isFunction, isObject, isObjectLike } from "./types.js";
 import { deepClone } from "./object.js";
 import { isProduction } from "./env.js";
 import { removeValueFromArray } from "./array.js";
+import { OPTIONS } from "./cache.js";
 const ENV = process.env.NODE_ENV;
 function spotByPath(path) {
   const element = this;
@@ -317,6 +318,219 @@ function call(fnKey, ...args) {
     if (context?.strictMode) throw err;
   }
 }
+async function getDB() {
+  const element = this;
+  const db = element.context?.db;
+  if (!db) return null;
+  if (typeof db.select === "function") {
+    if (!db.__authInitialized && db.getSession) {
+      const { initAdapterAuth } = await import("@symbo.ls/fetch");
+      await initAdapterAuth(db, element.context);
+    }
+    return db;
+  }
+  if (db.__resolved) {
+    if (!db.__resolved.__authInitialized && db.__resolved.getSession) {
+      const { initAdapterAuth } = await import("@symbo.ls/fetch");
+      await initAdapterAuth(db.__resolved, element.context);
+    }
+    return db.__resolved;
+  }
+  if (db.__resolving) return db.__resolving;
+  const resolvePromise = import("@symbo.ls/fetch").then(({ resolveDb }) => resolveDb(db));
+  db.__resolving = resolvePromise;
+  const resolved = await resolvePromise;
+  db.__resolved = resolved;
+  element.context.db = resolved;
+  delete db.__resolving;
+  if (resolved.getSession) {
+    const { initAdapterAuth } = await import("@symbo.ls/fetch");
+    await initAdapterAuth(resolved, element.context);
+  }
+  return resolved;
+}
+function getQuery(format) {
+  const element = this;
+  const useStateQuery = format || OPTIONS.useStateQuery || element.context?.useStateQuery;
+  if (!useStateQuery) return null;
+  const query = {};
+  buildQueryFromElement(element, query);
+  if (useStateQuery === true) return query;
+  const formatter = QUERY_FORMATTERS[useStateQuery];
+  return formatter ? formatter(query) : query;
+}
+const buildQueryFromElement = (element, query) => {
+  const ref = element.__ref;
+  if (!ref) return;
+  const stateKey = ref.__state;
+  if (stateKey && typeof stateKey === "string") {
+    setQueryPath(query, stateKey);
+  }
+  const children = ref.__children;
+  if (children) {
+    for (let i = 0; i < children.length; i++) {
+      const child = element[children[i]];
+      if (child && child.__ref) {
+        buildQueryFromElement(child, query);
+      }
+    }
+  }
+  const contentKey = ref.contentElementKey || "content";
+  const content = element[contentKey];
+  if (content && content.__ref) {
+    buildQueryFromElement(content, query);
+  }
+};
+const setQueryPath = (query, path) => {
+  const clean = path.replaceAll("../", "").replaceAll("~/", "");
+  const parts = clean.split("/");
+  let current = query;
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (i === parts.length - 1) {
+      if (!current[part]) current[part] = true;
+    } else {
+      if (current[part] === true) current[part] = {};
+      if (!current[part]) current[part] = {};
+      current = current[part];
+    }
+  }
+};
+const queryToGraphQL = (query, indent = 0) => {
+  const pad = "  ".repeat(indent);
+  const entries = Object.entries(query);
+  if (!entries.length) return "";
+  const fields = entries.map(([key, value]) => {
+    if (value === true) return `${pad}${key}`;
+    return `${pad}${key} {
+${queryToGraphQL(value, indent + 1)}
+${pad}}`;
+  });
+  return fields.join("\n");
+};
+const formatGraphQL = (query) => {
+  return `{
+${queryToGraphQL(query, 1)}
+}`;
+};
+const formatJsonApi = (query) => {
+  const result = { fields: {}, include: [] };
+  const walk = (obj, prefix) => {
+    const fields = [];
+    for (const key in obj) {
+      if (obj[key] === true) {
+        fields.push(key);
+      } else {
+        const nested = prefix ? `${prefix}.${key}` : key;
+        result.include.push(nested);
+        walk(obj[key], nested);
+      }
+    }
+    if (fields.length) {
+      result.fields[prefix || "_root"] = fields;
+    }
+  };
+  walk(query, "");
+  return result;
+};
+const formatOData = (query) => {
+  const build = (obj) => {
+    const select2 = [];
+    const expand2 = [];
+    for (const key in obj) {
+      if (obj[key] === true) {
+        select2.push(key);
+      } else {
+        const nested = build(obj[key]);
+        const parts2 = [];
+        if (nested.select) parts2.push(`$select=${nested.select}`);
+        if (nested.expand) parts2.push(`$expand=${nested.expand}`);
+        expand2.push(parts2.length ? `${key}(${parts2.join(";")})` : key);
+      }
+    }
+    return {
+      select: select2.length ? select2.join(",") : "",
+      expand: expand2.length ? expand2.join(",") : ""
+    };
+  };
+  const { select, expand } = build(query);
+  const parts = [];
+  if (select) parts.push(`$select=${select}`);
+  if (expand) parts.push(`$expand=${expand}`);
+  return parts.join("&");
+};
+const formatSQL = (query, options) => {
+  const columns = [];
+  const joins = [];
+  const tables = /* @__PURE__ */ new Set();
+  const walk = (obj, table, parentTable) => {
+    tables.add(table);
+    if (parentTable) {
+      joins.push(
+        `LEFT JOIN ${table} ON ${table}.${parentTable}_id = ${parentTable}.id`
+      );
+    }
+    for (const key in obj) {
+      if (obj[key] === true) {
+        columns.push(`${table}.${key}`);
+      } else {
+        walk(obj[key], key, table);
+      }
+    }
+  };
+  const roots = Object.keys(query);
+  if (roots.length === 1 && query[roots[0]] !== true) {
+    walk(query[roots[0]], roots[0], null);
+  } else {
+    walk(query, "_root", null);
+  }
+  const from = [...tables][0] || "_root";
+  const select = columns.length ? columns.join(", ") : "*";
+  const joinStr = joins.length ? "\n" + joins.join("\n") : "";
+  return `SELECT ${select}
+FROM ${from}${joinStr}`;
+};
+const formatPaths = (query) => {
+  const paths = [];
+  const walk = (obj, prefix) => {
+    for (const key in obj) {
+      const path = prefix ? `${prefix}/${key}` : key;
+      if (obj[key] === true) {
+        paths.push(path);
+      } else {
+        walk(obj[key], path);
+      }
+    }
+  };
+  walk(query, "");
+  return paths;
+};
+const formatSupabase = (query) => {
+  const build = (obj) => {
+    const parts = [];
+    for (const key in obj) {
+      if (obj[key] === true) {
+        parts.push(key);
+      } else {
+        parts.push(`${key}(${build(obj[key])})`);
+      }
+    }
+    return parts.join(", ");
+  };
+  const roots = Object.keys(query);
+  if (roots.length === 1 && query[roots[0]] !== true) {
+    return { from: roots[0], select: build(query[roots[0]]) };
+  }
+  return { from: null, select: build(query) };
+};
+const QUERY_FORMATTERS = {
+  graphql: formatGraphQL,
+  "json-api": formatJsonApi,
+  odata: formatOData,
+  sql: formatSQL,
+  supabase: formatSupabase,
+  paths: formatPaths
+};
 function isMethod(param, element) {
   return Boolean(METHODS.has(param) || element?.context?.methods?.[param]);
 }
@@ -327,7 +541,9 @@ export {
   get,
   getChildren,
   getContext,
+  getDB,
   getPath,
+  getQuery,
   getRef,
   getRoot,
   getRootContext,

package/dist/esm/state.js

@@ -3,13 +3,11 @@ import { STATE_METHODS } from "./keys.js";
 import {
   deepClone,
   deepMerge,
-  exec,
   overwriteDeep,
   overwriteShallow
 } from "./object.js";
 import {
   is,
-  isFunction,
   isObject,
   isObjectLike,
   isString
@@ -17,10 +15,7 @@ import {
 const checkForStateTypes = (element) => {
   const { state: orig, props, __ref: ref } = element;
   const state = props?.state || orig;
-  if (isFunction(state)) {
-    ref.__state = state;
-    return exec(state, element);
-  } else if (is(state)("string", "number")) {
+  if (is(state)("string", "number")) {
     ref.__state = state;
     return { value: state };
   } else if (state === true) {
@@ -123,7 +118,7 @@ const createNestedObjectByKeyPath = (path, value) => {
 };
 const applyDependentState = (element, state) => {
   const { __element } = state;
-  const origState = exec(__element?.state, element);
+  const origState = __element?.state;
   if (!origState) return;
   const dependentState = deepClone(origState, STATE_METHODS);
   const newDepends = { [element.key]: dependentState };