@jay-framework/stack-client-runtime 0.9.0 → 0.10.0

package/dist/index.cjs

@@ -1,38 +1,128 @@
 "use strict";
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const component = require("@jay-framework/component");
-function makeSignals(carryForward) {
-  return Object.keys(carryForward).reduce((signals, key) => {
-    signals[key] = component.createSignal(carryForward[key]);
+function deepMergeViewStates(base, overlay, trackByMap, path = "") {
+  if (!base && !overlay)
+    return {};
+  if (!base)
+    return overlay || {};
+  if (!overlay)
+    return base || {};
+  const result = {};
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(base), ...Object.keys(overlay)]);
+  for (const key of allKeys) {
+    const baseValue = base[key];
+    const overlayValue = overlay[key];
+    const currentPath = path ? `${path}.${key}` : key;
+    if (overlayValue === void 0) {
+      result[key] = baseValue;
+    } else if (baseValue === void 0) {
+      result[key] = overlayValue;
+    } else if (Array.isArray(baseValue) && Array.isArray(overlayValue)) {
+      const trackByField = trackByMap[currentPath];
+      if (trackByField) {
+        result[key] = mergeArraysByTrackBy(
+          baseValue,
+          overlayValue,
+          trackByField,
+          trackByMap,
+          currentPath
+        );
+      } else {
+        result[key] = overlayValue;
+      }
+    } else if (typeof baseValue === "object" && baseValue !== null && typeof overlayValue === "object" && overlayValue !== null && !Array.isArray(baseValue) && !Array.isArray(overlayValue)) {
+      result[key] = deepMergeViewStates(baseValue, overlayValue, trackByMap, currentPath);
+    } else {
+      result[key] = overlayValue;
+    }
+  }
+  return result;
+}
+function mergeArraysByTrackBy(baseArray, overlayArray, trackByField, trackByMap, arrayPath) {
+  const baseByKey = /* @__PURE__ */ new Map();
+  for (const item of baseArray) {
+    const key = item[trackByField];
+    if (key !== void 0 && key !== null) {
+      if (baseByKey.has(key)) {
+        console.warn(
+          `Duplicate trackBy key [${key}] in base array at path [${arrayPath}]. This may cause incorrect merging.`
+        );
+      }
+      baseByKey.set(key, item);
+    }
+  }
+  const overlayByKey = /* @__PURE__ */ new Map();
+  for (const item of overlayArray) {
+    const key = item[trackByField];
+    if (key !== void 0 && key !== null) {
+      overlayByKey.set(key, item);
+    }
+  }
+  return baseArray.map((baseItem) => {
+    const key = baseItem[trackByField];
+    if (key === void 0 || key === null) {
+      return baseItem;
+    }
+    const overlayItem = overlayByKey.get(key);
+    if (overlayItem) {
+      return deepMergeViewStates(baseItem, overlayItem, trackByMap, arrayPath);
+    } else {
+      return baseItem;
+    }
+  });
+}
+function makeSignals(obj) {
+  return Object.keys(obj).reduce((signals, key) => {
+    signals[key] = component.createSignal(obj[key]);
     return signals;
   }, {});
 }
-function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward, parts) {
+function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward, parts, trackByMap = {}) {
+  const hasFastRendering = defaultViewState !== null && defaultViewState !== void 0;
   const comp = (props, refs, ...contexts) => {
     const instances = parts.map((part) => {
       const partRefs = part.key ? refs[part.key] : refs;
-      let partCarryForward;
-      if (part.key && fastCarryForward?.[part.key])
-        partCarryForward = makeSignals(fastCarryForward[part.key]);
-      else if (fastCarryForward)
-        partCarryForward = makeSignals(fastCarryForward);
-      const partContexts = [
-        partCarryForward,
-        ...contexts.splice(0, part.contextMarkers.length)
-      ];
+      let partContexts;
+      if (hasFastRendering) {
+        const partViewState = part.key ? defaultViewState?.[part.key] : defaultViewState;
+        const partFastViewState = partViewState ? makeSignals(partViewState) : void 0;
+        const partCarryForward = part.key ? fastCarryForward?.[part.key] : fastCarryForward;
+        partContexts = [
+          partFastViewState,
+          partCarryForward,
+          ...contexts.splice(0, part.contextMarkers.length)
+        ];
+      } else {
+        partContexts = [...contexts.splice(0, part.contextMarkers.length)];
+      }
       return [part.key, part.comp(props, partRefs, ...partContexts)];
     });
     return {
       render: () => {
         let viewState = defaultViewState;
         instances.forEach(([key, instance]) => {
-          if (key)
-            viewState[key] = {
-              ...defaultViewState[key],
-              ...component.materializeViewState(instance.render())
-            };
-          else
-            viewState = { ...viewState, ...instance.render() };
+          const rendered = component.materializeViewState(instance.render());
+          if (key) {
+            viewState[key] = deepMergeViewStates(
+              defaultViewState[key],
+              rendered,
+              trackByMap,
+              key
+            );
+          } else {
+            viewState = deepMergeViewStates(
+              viewState,
+              rendered,
+              trackByMap
+            );
+          }
         });
         return viewState;
       }
@@ -47,4 +137,100 @@ function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward
     ...contextMarkers
   );
 }
+const ACTION_ENDPOINT_BASE = "/_jay/actions";
+class ActionError extends Error {
+  constructor(code, message) {
+    super(message);
+    __publicField(this, "name", "ActionError");
+    this.code = code;
+  }
+}
+let globalOptions = {};
+function setActionCallerOptions(options) {
+  globalOptions = { ...globalOptions, ...options };
+}
+function createActionCaller(actionName, method = "POST") {
+  return async (input) => {
+    const baseUrl = globalOptions.baseUrl ?? "";
+    const url = buildActionUrl(baseUrl, actionName, method, input);
+    const fetchOptions = {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        ...globalOptions.headers
+      }
+    };
+    if (method !== "GET") {
+      fetchOptions.body = JSON.stringify(input);
+    }
+    const timeout = globalOptions.timeout ?? 3e4;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    fetchOptions.signal = controller.signal;
+    try {
+      const response = await fetch(url, fetchOptions);
+      clearTimeout(timeoutId);
+      const data = await response.json();
+      if (data.success) {
+        return data.data;
+      } else {
+        if (data.error) {
+          throw new ActionError(data.error.code, data.error.message);
+        }
+        throw new ActionError("UNKNOWN_ERROR", "Unknown error occurred");
+      }
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof ActionError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new ActionError(
+          "TIMEOUT",
+          `Action '${actionName}' timed out after ${timeout}ms`
+        );
+      }
+      if (error instanceof TypeError) {
+        throw new ActionError(
+          "NETWORK_ERROR",
+          `Network error calling '${actionName}': ${error.message}`
+        );
+      }
+      throw error;
+    }
+  };
+}
+function buildActionUrl(baseUrl, actionName, method, input) {
+  const path = `${ACTION_ENDPOINT_BASE}/${actionName}`;
+  const fullUrl = `${baseUrl}${path}`;
+  if (method === "GET" && input !== void 0 && input !== null) {
+    const params = new URLSearchParams();
+    if (isSimpleObject(input)) {
+      for (const [key, value] of Object.entries(input)) {
+        if (value !== void 0) {
+          params.append(key, String(value));
+        }
+      }
+    } else {
+      params.append("_input", JSON.stringify(input));
+    }
+    const queryString = params.toString();
+    return queryString ? `${fullUrl}?${queryString}` : fullUrl;
+  }
+  return fullUrl;
+}
+function isSimpleObject(obj) {
+  if (typeof obj !== "object" || obj === null) {
+    return false;
+  }
+  for (const value of Object.values(obj)) {
+    if (typeof value === "object" && value !== null) {
+      return false;
+    }
+  }
+  return true;
+}
+exports.ActionError = ActionError;
+exports.createActionCaller = createActionCaller;
 exports.makeCompositeJayComponent = makeCompositeJayComponent;
+exports.setActionCallerOptions = setActionCallerOptions;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import * as _jay_framework_component from '@jay-framework/component';
 import { ComponentConstructor, ContextMarkers, JayComponentCore } from '@jay-framework/component';
 import { JayElement, PreRenderElement } from '@jay-framework/runtime';
+import { TrackByMap } from '@jay-framework/view-state-merge';
 
 interface CompositePart {
     comp: ComponentConstructor<any, any, any, any, any>;
@@ -8,6 +9,71 @@ interface CompositePart {
     key?: string;
 }
 
-declare function makeCompositeJayComponent<PropsT extends object, ViewState extends object, Refs extends object, JayElementT extends JayElement<ViewState, Refs>, CompCore extends JayComponentCore<PropsT, ViewState>>(preRender: PreRenderElement<ViewState, Refs, JayElementT>, defaultViewState: ViewState, fastCarryForward: object, parts: Array<CompositePart>): (props: PropsT) => _jay_framework_component.ConcreteJayComponent<PropsT, ViewState, Refs, CompCore, JayElementT>;
+declare function makeCompositeJayComponent<PropsT extends object, ViewState extends object, Refs extends object, JayElementT extends JayElement<ViewState, Refs>, CompCore extends JayComponentCore<PropsT, ViewState>>(preRender: PreRenderElement<ViewState, Refs, JayElementT>, defaultViewState: ViewState, fastCarryForward: object, parts: Array<CompositePart>, trackByMap?: TrackByMap): (props: PropsT) => _jay_framework_component.ConcreteJayComponent<PropsT, ViewState, Refs, CompCore, JayElementT>;
 
-export { type CompositePart, makeCompositeJayComponent };
+/**
+ * Client-side action caller for Jay Stack.
+ *
+ * This module provides the client-side implementation for calling server actions.
+ * It replaces the server-side action handler when the action is imported in client code.
+ */
+/**
+ * HTTP method types supported by actions.
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Error thrown when an action fails on the server.
+ * Recreated on the client from the error response.
+ */
+declare class ActionError extends Error {
+    readonly code: string;
+    readonly name = "ActionError";
+    constructor(code: string, message: string);
+}
+/**
+ * Options for configuring the action caller.
+ */
+interface ActionCallerOptions {
+    /** Base URL for action endpoints (default: '') */
+    baseUrl?: string;
+    /** Custom headers to include with requests */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Sets global options for all action callers.
+ *
+ * @param options - Options to apply globally
+ *
+ * @example
+ * ```typescript
+ * setActionCallerOptions({
+ *     baseUrl: 'https://api.example.com',
+ *     headers: { 'X-Custom-Header': 'value' },
+ * });
+ * ```
+ */
+declare function setActionCallerOptions(options: ActionCallerOptions): void;
+/**
+ * Creates a client-side action caller that makes HTTP requests to the server.
+ *
+ * This function is used by the build transform to replace server-side action handlers
+ * with client-side HTTP callers.
+ *
+ * @param actionName - The unique action name (matches server registration)
+ * @param method - The HTTP method (default: POST)
+ * @returns A callable function that makes the HTTP request
+ *
+ * @example
+ * ```typescript
+ * // Build transform replaces:
+ * import { addToCart } from './actions/cart.actions';
+ *
+ * // With:
+ * const addToCart = createActionCaller<{productId: string}, {cartCount: number}>('cart.addToCart', 'POST');
+ * ```
+ */
+declare function createActionCaller<Input, Output>(actionName: string, method?: HttpMethod): (input: Input) => Promise<Output>;
+
+export { type ActionCallerOptions, ActionError, type CompositePart, type HttpMethod, createActionCaller, makeCompositeJayComponent, setActionCallerOptions };

package/dist/index.js

@@ -1,36 +1,126 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
 import { makeJayComponent, materializeViewState, createSignal } from "@jay-framework/component";
-function makeSignals(carryForward) {
-  return Object.keys(carryForward).reduce((signals, key) => {
-    signals[key] = createSignal(carryForward[key]);
+function deepMergeViewStates(base, overlay, trackByMap, path = "") {
+  if (!base && !overlay)
+    return {};
+  if (!base)
+    return overlay || {};
+  if (!overlay)
+    return base || {};
+  const result = {};
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(base), ...Object.keys(overlay)]);
+  for (const key of allKeys) {
+    const baseValue = base[key];
+    const overlayValue = overlay[key];
+    const currentPath = path ? `${path}.${key}` : key;
+    if (overlayValue === void 0) {
+      result[key] = baseValue;
+    } else if (baseValue === void 0) {
+      result[key] = overlayValue;
+    } else if (Array.isArray(baseValue) && Array.isArray(overlayValue)) {
+      const trackByField = trackByMap[currentPath];
+      if (trackByField) {
+        result[key] = mergeArraysByTrackBy(
+          baseValue,
+          overlayValue,
+          trackByField,
+          trackByMap,
+          currentPath
+        );
+      } else {
+        result[key] = overlayValue;
+      }
+    } else if (typeof baseValue === "object" && baseValue !== null && typeof overlayValue === "object" && overlayValue !== null && !Array.isArray(baseValue) && !Array.isArray(overlayValue)) {
+      result[key] = deepMergeViewStates(baseValue, overlayValue, trackByMap, currentPath);
+    } else {
+      result[key] = overlayValue;
+    }
+  }
+  return result;
+}
+function mergeArraysByTrackBy(baseArray, overlayArray, trackByField, trackByMap, arrayPath) {
+  const baseByKey = /* @__PURE__ */ new Map();
+  for (const item of baseArray) {
+    const key = item[trackByField];
+    if (key !== void 0 && key !== null) {
+      if (baseByKey.has(key)) {
+        console.warn(
+          `Duplicate trackBy key [${key}] in base array at path [${arrayPath}]. This may cause incorrect merging.`
+        );
+      }
+      baseByKey.set(key, item);
+    }
+  }
+  const overlayByKey = /* @__PURE__ */ new Map();
+  for (const item of overlayArray) {
+    const key = item[trackByField];
+    if (key !== void 0 && key !== null) {
+      overlayByKey.set(key, item);
+    }
+  }
+  return baseArray.map((baseItem) => {
+    const key = baseItem[trackByField];
+    if (key === void 0 || key === null) {
+      return baseItem;
+    }
+    const overlayItem = overlayByKey.get(key);
+    if (overlayItem) {
+      return deepMergeViewStates(baseItem, overlayItem, trackByMap, arrayPath);
+    } else {
+      return baseItem;
+    }
+  });
+}
+function makeSignals(obj) {
+  return Object.keys(obj).reduce((signals, key) => {
+    signals[key] = createSignal(obj[key]);
     return signals;
   }, {});
 }
-function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward, parts) {
+function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward, parts, trackByMap = {}) {
+  const hasFastRendering = defaultViewState !== null && defaultViewState !== void 0;
   const comp = (props, refs, ...contexts) => {
     const instances = parts.map((part) => {
       const partRefs = part.key ? refs[part.key] : refs;
-      let partCarryForward;
-      if (part.key && fastCarryForward?.[part.key])
-        partCarryForward = makeSignals(fastCarryForward[part.key]);
-      else if (fastCarryForward)
-        partCarryForward = makeSignals(fastCarryForward);
-      const partContexts = [
-        partCarryForward,
-        ...contexts.splice(0, part.contextMarkers.length)
-      ];
+      let partContexts;
+      if (hasFastRendering) {
+        const partViewState = part.key ? defaultViewState?.[part.key] : defaultViewState;
+        const partFastViewState = partViewState ? makeSignals(partViewState) : void 0;
+        const partCarryForward = part.key ? fastCarryForward?.[part.key] : fastCarryForward;
+        partContexts = [
+          partFastViewState,
+          partCarryForward,
+          ...contexts.splice(0, part.contextMarkers.length)
+        ];
+      } else {
+        partContexts = [...contexts.splice(0, part.contextMarkers.length)];
+      }
       return [part.key, part.comp(props, partRefs, ...partContexts)];
     });
     return {
       render: () => {
         let viewState = defaultViewState;
         instances.forEach(([key, instance]) => {
-          if (key)
-            viewState[key] = {
-              ...defaultViewState[key],
-              ...materializeViewState(instance.render())
-            };
-          else
-            viewState = { ...viewState, ...instance.render() };
+          const rendered = materializeViewState(instance.render());
+          if (key) {
+            viewState[key] = deepMergeViewStates(
+              defaultViewState[key],
+              rendered,
+              trackByMap,
+              key
+            );
+          } else {
+            viewState = deepMergeViewStates(
+              viewState,
+              rendered,
+              trackByMap
+            );
+          }
         });
         return viewState;
       }
@@ -45,6 +135,102 @@ function makeCompositeJayComponent(preRender, defaultViewState, fastCarryForward
     ...contextMarkers
   );
 }
+const ACTION_ENDPOINT_BASE = "/_jay/actions";
+class ActionError extends Error {
+  constructor(code, message) {
+    super(message);
+    __publicField(this, "name", "ActionError");
+    this.code = code;
+  }
+}
+let globalOptions = {};
+function setActionCallerOptions(options) {
+  globalOptions = { ...globalOptions, ...options };
+}
+function createActionCaller(actionName, method = "POST") {
+  return async (input) => {
+    const baseUrl = globalOptions.baseUrl ?? "";
+    const url = buildActionUrl(baseUrl, actionName, method, input);
+    const fetchOptions = {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        ...globalOptions.headers
+      }
+    };
+    if (method !== "GET") {
+      fetchOptions.body = JSON.stringify(input);
+    }
+    const timeout = globalOptions.timeout ?? 3e4;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    fetchOptions.signal = controller.signal;
+    try {
+      const response = await fetch(url, fetchOptions);
+      clearTimeout(timeoutId);
+      const data = await response.json();
+      if (data.success) {
+        return data.data;
+      } else {
+        if (data.error) {
+          throw new ActionError(data.error.code, data.error.message);
+        }
+        throw new ActionError("UNKNOWN_ERROR", "Unknown error occurred");
+      }
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof ActionError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new ActionError(
+          "TIMEOUT",
+          `Action '${actionName}' timed out after ${timeout}ms`
+        );
+      }
+      if (error instanceof TypeError) {
+        throw new ActionError(
+          "NETWORK_ERROR",
+          `Network error calling '${actionName}': ${error.message}`
+        );
+      }
+      throw error;
+    }
+  };
+}
+function buildActionUrl(baseUrl, actionName, method, input) {
+  const path = `${ACTION_ENDPOINT_BASE}/${actionName}`;
+  const fullUrl = `${baseUrl}${path}`;
+  if (method === "GET" && input !== void 0 && input !== null) {
+    const params = new URLSearchParams();
+    if (isSimpleObject(input)) {
+      for (const [key, value] of Object.entries(input)) {
+        if (value !== void 0) {
+          params.append(key, String(value));
+        }
+      }
+    } else {
+      params.append("_input", JSON.stringify(input));
+    }
+    const queryString = params.toString();
+    return queryString ? `${fullUrl}?${queryString}` : fullUrl;
+  }
+  return fullUrl;
+}
+function isSimpleObject(obj) {
+  if (typeof obj !== "object" || obj === null) {
+    return false;
+  }
+  for (const value of Object.values(obj)) {
+    if (typeof value === "object" && value !== null) {
+      return false;
+    }
+  }
+  return true;
+}
 export {
-  makeCompositeJayComponent
+  ActionError,
+  createActionCaller,
+  makeCompositeJayComponent,
+  setActionCallerOptions
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/stack-client-runtime",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -27,13 +27,14 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/component": "^0.9.0",
-    "@jay-framework/fullstack-component": "^0.9.0",
-    "@jay-framework/runtime": "^0.9.0"
+    "@jay-framework/component": "^0.10.0",
+    "@jay-framework/fullstack-component": "^0.10.0",
+    "@jay-framework/runtime": "^0.10.0",
+    "@jay-framework/view-state-merge": "^0.10.0"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.9.0",
-    "@jay-framework/jay-cli": "^0.9.0",
+    "@jay-framework/dev-environment": "^0.10.0",
+    "@jay-framework/jay-cli": "^0.10.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",