atmx-web 0.42.0

package/src/core/wasm.ts

@@ -0,0 +1,223 @@
+// FILE: src/core/wasm.ts
+import { setupWebCallback } from "./callback";
+import { AtmxConfig } from "../core/types";
+import { initRouter } from "./router";
+import { InitResult } from "./types";
+
+// @ts-ignore
+import wasmGlueCode from "./vendor/axiom_runtime.js?raw";
+
+export let wasmEngine: any = null;
+
+export function allocBytes(bytes: Uint8Array): number {
+  if (bytes.length === 0) return 0;
+  const ptr = wasmEngine.axiom_malloc(bytes.length);
+  const mem = new Uint8Array(wasmEngine.memory.buffer);
+  mem.set(bytes, ptr);
+  return ptr;
+}
+
+export function allocString(str: string): { ptr: number; len: number } {
+  if (!str) return { ptr: 0, len: 0 };
+  const bytes = new TextEncoder().encode(str);
+  const ptr = allocBytes(bytes);
+  return { ptr, len: bytes.length };
+}
+
+function getWasmUrl(): string {
+  return "https://atmx.axiomcore.dev/latest/axiom_runtime.wasm";
+}
+
+export async function initWasm(config: AtmxConfig): Promise<InitResult> {
+  const startTime = performance.now();
+  const result: InitResult = {
+    ok: false,
+    contracts: {},
+    initDurationMs: 0,
+  };
+
+  try {
+    if (!(window as any).wasm_bindgen) {
+      const script = document.createElement("script");
+      script.type = "text/javascript";
+      script.text = `${wasmGlueCode}\nwindow.wasm_bindgen = wasm_bindgen;`;
+      document.head.appendChild(script);
+    }
+
+    const wasmBindgen = (window as any).wasm_bindgen;
+    const wasmLocation = getWasmUrl();
+    const fetchUrl = `${wasmLocation}?t=${Date.now()}`;
+
+    try {
+      wasmEngine = await wasmBindgen(fetch(fetchUrl));
+    } catch (e: any) {
+      throw {
+        stage: "ffiBoundary",
+        category: "network",
+        code: "WasmFetchFailed",
+        message: `Failed to download WASM engine: ${e.message}`,
+        retryable: true,
+      };
+    }
+
+    setupWebCallback(wasmEngine);
+
+    setInterval(() => {
+      if (wasmEngine) wasmEngine.axiom_process_responses();
+    }, 16);
+
+    const dbPath = allocString("");
+    const initResultCode = wasmEngine.axiom_wasm_initialize(
+      dbPath.ptr,
+      dbPath.len,
+    );
+    wasmEngine.axiom_free_memory(dbPath.ptr, dbPath.len);
+
+    if (initResultCode !== 0) {
+      throw {
+        stage: "runtime",
+        category: "server",
+        code: "InitFailed",
+        message: `Engine init failed (Code: ${initResultCode})`,
+        retryable: false,
+      };
+    }
+
+    for (const [namespace, contractConfig] of Object.entries(
+      config.contracts,
+    )) {
+      try {
+        const contractRes = await fetch(contractConfig.contractUrl);
+        if (!contractRes.ok) {
+          throw new Error(`HTTP ${contractRes.status}`);
+        }
+
+        const contractArrayBuffer = await contractRes.arrayBuffer();
+        let endpointCount = 0;
+
+        try {
+          const jsonStr = new TextDecoder().decode(contractArrayBuffer);
+          const contractJson = JSON.parse(jsonStr);
+          const endpoints = contractJson?.ir?.endpoints;
+          if (endpoints) {
+            endpointCount = Array.isArray(endpoints)
+              ? endpoints.length
+              : Object.keys(endpoints).length;
+          }
+          initRouter(namespace, contractJson);
+        } catch (e) {
+          console.error(
+            `ATMX: Failed to parse .axiom contract for '${namespace}'`,
+            e,
+          );
+        }
+
+        const contractBytes = new Uint8Array(contractArrayBuffer);
+        const cPtr = allocBytes(contractBytes);
+        const nsStr = allocString(namespace);
+        const urlStr = allocString(contractConfig.baseUrl);
+
+        const loadResult = wasmEngine.axiom_wasm_load_contract(
+          nsStr.ptr,
+          nsStr.len,
+          urlStr.ptr,
+          urlStr.len,
+          cPtr,
+          contractBytes.length,
+          0,
+          0,
+          0,
+          0,
+        );
+
+        wasmEngine.axiom_free_memory(cPtr, contractBytes.length);
+        wasmEngine.axiom_free_memory(nsStr.ptr, nsStr.len);
+        wasmEngine.axiom_free_memory(urlStr.ptr, urlStr.len);
+
+        if (loadResult !== 0 && loadResult !== -1) {
+          throw new Error(`Load error (Code: ${loadResult})`);
+        }
+
+        if (config.debug) {
+          console.log(
+            `%c🔒 Axiom Contract Loaded: ${namespace} (${endpointCount} endpoints)`,
+            "color: #10b981; font-weight: bold;",
+          );
+        }
+
+        result.contracts[namespace] = { loaded: true, endpointCount };
+
+        // ✨ EVENT: Emit contract loaded
+        document.dispatchEvent(
+          new CustomEvent("atmx:contract-loaded", {
+            detail: { namespace, endpointCount },
+          }),
+        );
+      } catch (contractErr: any) {
+        result.contracts[namespace] = {
+          loaded: false,
+          endpointCount: 0,
+          error: contractErr.message,
+        };
+        console.error(`ATMX: Contract failed for ${namespace}`, contractErr);
+      }
+    }
+
+    result.ok = true;
+  } catch (fatalError: any) {
+    result.ok = false;
+    // Map native JS errors into structured AxiomErrors
+    result.error = fatalError.stage
+      ? fatalError
+      : {
+          stage: "runtime",
+          category: "unknown",
+          code: "FatalError",
+          message: fatalError.message || String(fatalError),
+          retryable: false,
+        };
+  }
+
+  result.initDurationMs = Math.round(performance.now() - startTime);
+  return result;
+}
+
+export function setAuthToken(
+  namespace: string,
+  methodName: string,
+  token: string,
+) {
+  if (!wasmEngine) return;
+  const nStr = allocString(namespace);
+  const mStr = allocString(methodName);
+  const tStr = allocString(token);
+
+  wasmEngine.axiom_wasm_set_auth_token(
+    nStr.ptr,
+    nStr.len,
+    mStr.ptr,
+    mStr.len,
+    tStr.ptr,
+    tStr.len,
+  );
+
+  wasmEngine.axiom_free_memory(nStr.ptr, nStr.len);
+  wasmEngine.axiom_free_memory(mStr.ptr, mStr.len);
+  wasmEngine.axiom_free_memory(tStr.ptr, tStr.len);
+}
+
+export function clearAuthToken(namespace: string, methodName: string) {
+  if (!wasmEngine) return;
+  const nStr = allocString(namespace);
+  const mStr = allocString(methodName);
+
+  wasmEngine.axiom_wasm_clear_auth_token(
+    nStr.ptr,
+    nStr.len,
+    mStr.ptr,
+    mStr.len,
+  );
+
+  wasmEngine.axiom_free_memory(nStr.ptr, nStr.len);
+  wasmEngine.axiom_free_memory(mStr.ptr, mStr.len);
+}

package/src/dom/components/engine-status.ts

@@ -0,0 +1,62 @@
+// FILE: src/dom/components/engine-status.ts
+
+export class AxEngineStatusElement extends HTMLElement {
+  constructor() {
+    super();
+  }
+
+  connectedCallback() {
+    const loadingText = this.getAttribute("loading-text") || "Initializing...";
+    const readyText = this.getAttribute("ready-text") || "Online";
+    const errorText = this.getAttribute("error-text") || "Failed to Connect";
+
+    // Initial state
+    this.renderState("loading", loadingText, "text-amber-500 animate-pulse");
+
+    // Listen for ATMX engine events globally
+    document.addEventListener("atmx:ready", () => {
+      this.renderState("ready", readyText, "text-green-600");
+    });
+
+    document.addEventListener("atmx:error", (e: Event) => {
+      const customEvent = e as CustomEvent;
+      // Check if this is a fatal initialization error vs a normal query error
+      if (customEvent.detail && customEvent.detail.stage === "runtime") {
+        this.renderState(
+          "error",
+          `${errorText}: ${customEvent.detail.message}`,
+          "text-red-600",
+        );
+      }
+    });
+  }
+
+  private renderState(state: string, text: string, defaultClasses: string) {
+    this.setAttribute("data-state", state);
+
+    // If developer is using raw ax-engine-status directly with inner HTML template matching, we allow it.
+    // Otherwise, we just swap the raw text node.
+    const stateElements = this.querySelectorAll(`[data-ax-when]`);
+
+    if (stateElements.length > 0) {
+      stateElements.forEach((el) => {
+        if (el.getAttribute("data-ax-when") === state) {
+          el.removeAttribute("hidden");
+        } else {
+          el.setAttribute("hidden", "");
+        }
+      });
+    } else {
+      // No custom inner templates, just replace text
+      this.innerText = text;
+      if (!this.getAttribute("class")) {
+        this.className = `text-xs font-bold ${defaultClasses}`;
+      }
+    }
+  }
+}
+
+// Automatically register the web component
+if (typeof window !== "undefined" && !customElements.get("ax-engine-status")) {
+  customElements.define("ax-engine-status", AxEngineStatusElement);
+}

package/src/dom/indicators.ts

@@ -0,0 +1,36 @@
+const activeRequests = new Map<number, { trigger: HTMLElement, indicators: HTMLElement[] }>();
+
+export function startRequest(reqId: number, triggerEl: HTMLElement) {
+    // 1. Add 'ax-request' to the element that triggered the call (e.g., the button)
+    triggerEl.classList.add('ax-request');
+
+    // 2. Find any associated loading indicators
+    let indicators: HTMLElement[] = [];
+    const indicatorSelector = triggerEl.getAttribute('ax-indicator');
+
+    if (indicatorSelector) {
+        // If ax-indicator="#spinner" is explicitly defined
+        indicators = Array.from(document.querySelectorAll(indicatorSelector));
+    } else {
+        // Fallback: Look for any children inside the trigger with the class 'ax-indicator'
+        indicators = Array.from(triggerEl.querySelectorAll('.ax-indicator'));
+    }
+
+    // 3. Turn on the indicators
+    indicators.forEach(el => el.classList.add('ax-loading'));
+
+    // 4. Save state so we can turn them off later
+    activeRequests.set(reqId, { trigger: triggerEl, indicators });
+}
+
+export function endRequest(reqId: number) {
+    const req = activeRequests.get(reqId);
+    if (!req) return;
+
+    // Turn off all classes
+    req.trigger.classList.remove('ax-request');
+    req.indicators.forEach(el => el.classList.remove('ax-loading'));
+
+    // Clean up
+    activeRequests.delete(reqId);
+}

package/src/dom/lifecycle.ts

@@ -0,0 +1,379 @@
+// FILE: src/dom/lifecycle.ts
+import { wasmEngine, allocString, allocBytes } from "../core/wasm";
+import { pendingRequests } from "../core/callback";
+import { resolveRoute, buildRequestPath } from "../core/router";
+import {
+  getContext,
+  updateContext,
+  getClosestData,
+  AtmxContextData,
+} from "../core/context";
+import { EventType } from "../core/types";
+import { executeAction, evaluateExpression } from "../resolver/evaluator";
+import { queryRegistry, ActiveQuery } from "../core/query";
+import { atmx } from "../index";
+
+let globalReqCounter = 0;
+
+function triggerEscapeHatch(element: HTMLElement, eventName: string) {
+  const attrName = `ax-on:${eventName}`;
+  if (element.hasAttribute(attrName)) {
+    const expr = element.getAttribute(attrName)!;
+    const ctx = getContext(element);
+    executeAction(expr, ctx);
+  }
+}
+
+function logTransaction(direction: "OUT" | "IN", reqId: number, details: any) {
+  if (!atmx.debug) return;
+  const color = direction === "OUT" ? "#7c3aed" : "#059669";
+  const label = direction === "OUT" ? "➔ WASM CALL" : "← WASM RESP";
+  console.groupCollapsed(
+    `%c${label} [#${reqId}]`,
+    `color: ${color}; font-weight: bold;`,
+  );
+  console.log("Details:", details);
+  console.groupEnd();
+}
+
+export function parseRpcCall(
+  element: HTMLElement,
+  attrValue: string,
+): { target: string; args: Record<string, any> } | null {
+  const match = attrValue.trim().match(/^([\w\.]+)(?:\((.*)\))?$/);
+  if (!match) return null;
+
+  const target = match[1];
+  let args = {};
+
+  if (match[2] && match[2].trim() !== "") {
+    try {
+      const ctx = getContext(element);
+      const availableData = ctx.data || getClosestData(element);
+      const fn = new Function("$data", "$state", `return (${match[2]});`);
+      args = fn(availableData, ctx) || {};
+    } catch (e) {
+      console.error(`ATMX Scope Error in "${attrValue}":`, e);
+    }
+  }
+  return { target, args };
+}
+
+export function connectQuery(element: HTMLElement) {
+  const attrVal = element.getAttribute("ax-query");
+  if (!attrVal) return;
+
+  const parsed = parseRpcCall(element, attrVal);
+  if (!parsed) return;
+
+  const route = resolveRoute(parsed.target);
+  if (!route) {
+    updateContext(element, {
+      state: "error",
+      error: { message: `Route not found: ${parsed.target}` },
+    });
+    return;
+  }
+
+  const queryKey = `${route.namespace}:${route.id}:${JSON.stringify(parsed.args)}`;
+
+  let activeQuery = queryRegistry.get(queryKey);
+  if (!activeQuery) {
+    activeQuery = new ActiveQuery(queryKey, route, parsed.args);
+    queryRegistry.set(queryKey, activeQuery);
+  }
+
+  if (!(element as any)._axListener) {
+    (element as any)._axListener = (newState: Partial<AtmxContextData>) => {
+      updateContext(element, newState);
+      if (newState.state === "data" || newState.state === "error") {
+        triggerEscapeHatch(element, newState.state);
+        element.dispatchEvent(
+          new CustomEvent(`atmx:${newState.state}`, {
+            bubbles: true,
+            detail: newState.data || newState.error,
+          }),
+        );
+      }
+    };
+    activeQuery.subscribe((element as any)._axListener);
+  }
+
+  activeQuery.fetch();
+}
+
+export function executeMutation(element: HTMLElement) {
+  const attrVal = element.getAttribute("ax-mutate");
+  if (!attrVal) return;
+
+  const parsed = parseRpcCall(element, attrVal);
+  if (!parsed) return;
+
+  const route = resolveRoute(parsed.target);
+  if (!route) {
+    updateContext(element, {
+      state: "error",
+      error: { message: `Route not found: ${parsed.target}` },
+    });
+    triggerEscapeHatch(element, "error");
+    return;
+  }
+
+  updateContext(element, { state: "mutating", error: null, data: null });
+  triggerEscapeHatch(element, "mutating");
+
+  const formDataObj: Record<string, any> = {};
+  if (element instanceof HTMLFormElement) {
+    const formData = new FormData(element);
+    formData.forEach((value, key) => {
+      const input = element.elements.namedItem(key);
+      let isNumber = false;
+
+      if (input instanceof HTMLInputElement) {
+        isNumber = input.type === "number";
+      } else if (input instanceof RadioNodeList && input.length > 0) {
+        isNumber = (input[0] as HTMLInputElement).type === "number";
+      }
+
+      const finalVal = isNumber && value !== "" ? Number(value) : value;
+
+      // ✨ NEW: Un-flatten dot notation! (e.g. "user.email" -> { user: { email: ... } })
+      if (key.includes(".")) {
+        const parts = key.split(".");
+        let current = formDataObj;
+        for (let i = 0; i < parts.length - 1; i++) {
+          if (!current[parts[i]]) current[parts[i]] = {};
+          current = current[parts[i]];
+        }
+        current[parts[parts.length - 1]] = finalVal;
+      } else {
+        formDataObj[key] = finalVal;
+      }
+    });
+  }
+
+  const mergedArgs = { ...formDataObj, ...parsed.args };
+  const { path, remainingArgs } = buildRequestPath(route, mergedArgs);
+
+  // ✨ NEW: Smart Body Extraction for FastAPI!
+  let payloadObj = remainingArgs;
+  if (route.bodyParam && remainingArgs[route.bodyParam] !== undefined) {
+    // If the developer passed the data inside the wrapper (e.g., args.user), extract it so it's flat!
+    payloadObj = remainingArgs[route.bodyParam];
+  }
+
+  let customHeaders: Record<string, string> = {};
+  const headersAttr = element.getAttribute("ax-headers");
+  if (headersAttr) {
+    try {
+      const fn = new Function("return (" + headersAttr + ");");
+      customHeaders = fn() || {};
+    } catch (e) {
+      console.error("ATMX: Invalid ax-headers syntax", e);
+    }
+  }
+
+  const isFormUrlEncoded = Object.entries(customHeaders).some(
+    ([k, v]) =>
+      k.toLowerCase() === "content-type" &&
+      v.includes("application/x-www-form-urlencoded"),
+  );
+
+  let payloadBytes = new Uint8Array(0);
+  if (Object.keys(payloadObj).length > 0) {
+    if (isFormUrlEncoded) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(payloadObj)) {
+        params.append(k, String(v));
+      }
+      payloadBytes = new TextEncoder().encode(params.toString());
+    } else {
+      payloadBytes = new TextEncoder().encode(JSON.stringify(payloadObj));
+    }
+  }
+
+  executeWasmCall(
+    element,
+    route.namespace,
+    route.id,
+    route.method,
+    path,
+    payloadBytes,
+    route.isStream,
+    true,
+    customHeaders,
+    isFormUrlEncoded,
+  );
+}
+
+function executeWasmCall(
+  element: HTMLElement,
+  namespace: string,
+  endpointId: number,
+  method: string,
+  path: string,
+  payloadBytes: Uint8Array,
+  isStream: boolean,
+  isMutation: boolean,
+  customHeaders: Record<string, string> = {},
+  isFormUrlEncoded: boolean = false,
+) {
+  const reqId = ++globalReqCounter;
+
+  logTransaction("OUT", reqId, {
+    namespace,
+    endpointId,
+    method,
+    path,
+    headers: customHeaders,
+    payload:
+      payloadBytes.length > 0
+        ? isFormUrlEncoded
+          ? new TextDecoder().decode(payloadBytes)
+          : JSON.parse(new TextDecoder().decode(payloadBytes))
+        : null,
+  });
+
+  pendingRequests.set(reqId, {
+    isStream: isStream,
+    onResponse: (res) => handleResponse(element, res, isMutation, reqId),
+    onComplete: () => {
+      if (atmx.debug)
+        console.log(`%c✔ Stream Complete [#${reqId}]`, "color: #94a3b8;");
+    },
+  });
+
+  const nsStr = allocString(namespace);
+  const mStr = allocString(method);
+  const pStr = allocString(path);
+  const tpStr = allocString("");
+  const hStr = allocString(
+    Object.keys(customHeaders).length > 0 ? JSON.stringify(customHeaders) : "",
+  );
+  const payloadPtr = allocBytes(payloadBytes);
+
+  wasmEngine.axiom_wasm_call(
+    reqId,
+    nsStr.ptr,
+    nsStr.len,
+    endpointId,
+    mStr.ptr,
+    mStr.len,
+    pStr.ptr,
+    pStr.len,
+    tpStr.ptr,
+    tpStr.len,
+    hStr.ptr,
+    hStr.len,
+    payloadPtr,
+    payloadBytes.length,
+  );
+
+  wasmEngine.axiom_free_memory(nsStr.ptr, nsStr.len);
+  wasmEngine.axiom_free_memory(mStr.ptr, mStr.len);
+  wasmEngine.axiom_free_memory(pStr.ptr, pStr.len);
+  wasmEngine.axiom_free_memory(tpStr.ptr, tpStr.len);
+  wasmEngine.axiom_free_memory(hStr.ptr, hStr.len);
+  if (payloadPtr) wasmEngine.axiom_free_memory(payloadPtr, payloadBytes.length);
+}
+
+function handleResponse(
+  element: HTMLElement,
+  res: any,
+  isMutation: boolean,
+  reqId: number,
+) {
+  logTransaction("IN", reqId, {
+    eventType: EventType[res.eventType],
+    data: res.data,
+    error: res.error,
+  });
+
+  if (res.eventType === EventType.Error) {
+    updateContext(element, {
+      state: "error",
+      error: res.error,
+      isFetching: false,
+      isMutating: false,
+    });
+    triggerEscapeHatch(element, "error");
+    element.dispatchEvent(
+      new CustomEvent("atmx:error", { bubbles: true, detail: res.error }),
+    );
+    return;
+  }
+
+  if (res.data) {
+    let source: "cache" | "network" = "network";
+    let isFetching = false;
+
+    if (res.eventType === EventType.CacheHit) {
+      source = "cache";
+    } else if (res.eventType === EventType.CacheHitAndFetching) {
+      source = "cache";
+      isFetching = true;
+    } else if (res.eventType === EventType.NetworkSuccess) {
+      source = "network";
+    }
+
+    const nextState = isMutation ? "success" : "data";
+
+    updateContext(element, {
+      state: nextState,
+      data: res.data,
+      source,
+      isFetching,
+      isMutating: false,
+    });
+
+    // ✨ PHASE 1: Declarative Auth
+    if (isMutation) {
+      const storeTokenAttr = element.getAttribute("ax-store-token");
+      if (storeTokenAttr) {
+        const tokenVal = evaluateExpression(
+          storeTokenAttr,
+          getContext(element),
+        );
+        if (tokenVal) {
+          const rpcAttr = element.getAttribute("ax-mutate");
+          const route = resolveRoute(parseRpcCall(element, rpcAttr!)!.target);
+          const headerName =
+            element.getAttribute("ax-token-header") || "Authorization";
+          atmx.setAuthToken(
+            route?.namespace || "default",
+            headerName,
+            tokenVal,
+          );
+        }
+      }
+
+      if (element.hasAttribute("ax-clear-token")) {
+        const rpcAttr = element.getAttribute("ax-mutate");
+        const route = resolveRoute(parseRpcCall(element, rpcAttr!)!.target);
+        const headerName =
+          element.getAttribute("ax-token-header") || "Authorization";
+        atmx.clearAuthToken(route?.namespace || "default", headerName);
+      }
+
+      // ✨ PHASE 1: Declarative Refresh
+      const refreshAttr = element.getAttribute("ax-refresh");
+      if (refreshAttr) {
+        const targets = refreshAttr.split(",").map((s) => s.trim());
+        for (const [_, activeQuery] of queryRegistry.entries()) {
+          const routeName = `${activeQuery.route.namespace}.${activeQuery.route.name}`;
+          if (targets.includes(routeName)) {
+            activeQuery.fetch(true); // Force refresh
+          }
+        }
+      }
+    }
+
+    triggerEscapeHatch(element, nextState);
+    element.dispatchEvent(
+      new CustomEvent(isMutation ? "atmx:success" : "atmx:data", {
+        bubbles: true,
+        detail: res.data,
+      }),
+    );
+  }
+}