@jsenv/navi 0.0.1

package/src/store/resource_graph.js

@@ -0,0 +1,1303 @@
+import { computed, signal } from "@preact/signals";
+import { getActionPrivateProperties } from "../action_private_properties.js";
+import { createAction, getActionDispatcher } from "../actions.js";
+import { SYMBOL_OBJECT_SIGNAL } from "../symbol_object_signal.js";
+import {
+  SYMBOL_IDENTITY,
+  compareTwoJsValues,
+} from "../utils/compare_two_js_values.js";
+import { getCallerInfo } from "../utils/get_caller_info.js";
+import { createIterableWeakSet } from "../utils/iterable_weak_set.js";
+import { arraySignalStore, primitiveCanBeId } from "./array_signal_store.js";
+
+let DEBUG = false;
+
+// Resource Lifecycle Manager
+// This handles ALL resource lifecycle logic (rerun/reset) across all resources
+const createResourceLifecycleManager = () => {
+  const registeredResources = new Map(); // Map<resourceInstance, lifecycleConfig>
+  const resourceDependencies = new Map(); // Map<resourceInstance, Set<dependentResources>>
+
+  const registerResource = (resourceInstance, config) => {
+    const {
+      rerunOn,
+      paramScope = null,
+      dependencies = [],
+      mutableIdKeys = [],
+    } = config;
+
+    registeredResources.set(resourceInstance, {
+      rerunOn,
+      paramScope,
+      mutableIdKeys,
+      httpActions: new Set(),
+    });
+
+    // Register dependencies
+    if (dependencies.length > 0) {
+      for (const dependency of dependencies) {
+        if (!resourceDependencies.has(dependency)) {
+          resourceDependencies.set(dependency, new Set());
+        }
+        resourceDependencies.get(dependency).add(resourceInstance);
+      }
+    }
+  };
+
+  const registerAction = (resourceInstance, httpAction) => {
+    const config = registeredResources.get(resourceInstance);
+    if (config) {
+      config.httpActions.add(httpAction);
+    }
+  };
+
+  const shouldRerunAfter = (rerunConfig, httpVerb) => {
+    if (rerunConfig === false) return false;
+    if (rerunConfig === "*") return true;
+    if (Array.isArray(rerunConfig)) {
+      const verbSet = new Set(rerunConfig.map((v) => v.toUpperCase()));
+      if (verbSet.has("*")) return true;
+      return verbSet.has(httpVerb.toUpperCase());
+    }
+    return false;
+  };
+
+  const isParamSubset = (parentParams, childParams) => {
+    if (!parentParams || !childParams) return false;
+    for (const [key, value] of Object.entries(parentParams)) {
+      if (
+        !(key in childParams) ||
+        !compareTwoJsValues(childParams[key], value)
+      ) {
+        return false;
+      }
+    }
+    return true;
+  };
+
+  const findEffectOnActions = (triggeringAction) => {
+    // Determines which actions to rerun/reset when an action completes.
+
+    const actionsToRerun = new Set();
+    const actionsToReset = new Set();
+    const reasonSet = new Set();
+
+    for (const [resourceInstance, config] of registeredResources) {
+      const shouldRerunGetMany = shouldRerunAfter(
+        config.rerunOn.GET_MANY,
+        triggeringAction.meta.httpVerb,
+      );
+      const shouldRerunGet = shouldRerunAfter(
+        config.rerunOn.GET,
+        triggeringAction.meta.httpVerb,
+      );
+
+      // Skip if no rerun or reset rules apply
+      const hasMutableIdAutorerun =
+        (triggeringAction.meta.httpVerb === "POST" ||
+          triggeringAction.meta.httpVerb === "PUT" ||
+          triggeringAction.meta.httpVerb === "PATCH") &&
+        config.mutableIdKeys.length > 0;
+
+      if (
+        !shouldRerunGetMany &&
+        !shouldRerunGet &&
+        triggeringAction.meta.httpVerb !== "DELETE" &&
+        !hasMutableIdAutorerun
+      ) {
+        continue;
+      }
+
+      // Parameter scope predicate for config-driven rules
+      // Same scope ID or no scope = compatible, subset check for different scopes
+      const paramScopePredicate = config.paramScope
+        ? (candidateAction) => {
+            if (candidateAction.meta.paramScope?.id === config.paramScope.id)
+              return true;
+            if (!candidateAction.meta.paramScope) return true;
+            const candidateParams = candidateAction.meta.paramScope.params;
+            const currentParams = config.paramScope.params;
+            return isParamSubset(candidateParams, currentParams);
+          }
+        : (candidateAction) => !candidateAction.meta.paramScope;
+
+      for (const httpAction of config.httpActions) {
+        // Find all instances of this action
+        const actionCandidateArray = httpAction.matchAllSelfOrDescendant(
+          (action) =>
+            !action.isPrerun && action.completed && action !== triggeringAction,
+        );
+
+        for (const actionCandidate of actionCandidateArray) {
+          const triggerVerb = triggeringAction.meta.httpVerb;
+          const candidateVerb = actionCandidate.meta.httpVerb;
+          const candidateIsPlural = actionCandidate.meta.httpMany;
+          if (triggerVerb === candidateVerb) {
+            continue;
+          }
+
+          const triggeringResource = getResourceForAction(triggeringAction);
+          const isSameResource = triggeringResource === resourceInstance;
+
+          // Config-driven same-resource effects (respects param scope)
+          config_effect: {
+            if (
+              !isSameResource ||
+              triggerVerb === "GET" ||
+              candidateVerb !== "GET"
+            ) {
+              break config_effect;
+            }
+            const shouldRerun = candidateIsPlural
+              ? shouldRerunGetMany
+              : shouldRerunGet;
+            if (!shouldRerun) {
+              break config_effect;
+            }
+            if (!paramScopePredicate(actionCandidate)) {
+              break config_effect;
+            }
+            actionsToRerun.add(actionCandidate);
+            reasonSet.add("same-resource autorerun");
+            continue;
+          }
+
+          // DELETE effects on same resource (ignores param scope)
+          delete_effect: {
+            if (!isSameResource || triggerVerb !== "DELETE") {
+              break delete_effect;
+            }
+            if (candidateIsPlural) {
+              if (!shouldRerunGetMany) {
+                break delete_effect;
+              }
+              actionsToRerun.add(actionCandidate);
+              reasonSet.add("same-resource DELETE rerun GET_MANY");
+              continue;
+            }
+            // Get the ID(s) that were deleted
+            const { dataSignal } = getActionPrivateProperties(triggeringAction);
+            const deleteIdSet = triggeringAction.meta.httpMany
+              ? new Set(dataSignal.peek())
+              : new Set([dataSignal.peek()]);
+
+            const candidateId = actionCandidate.data;
+            const isAffected = deleteIdSet.has(candidateId);
+            if (!isAffected) {
+              break delete_effect;
+            }
+            if (candidateVerb === "GET" && shouldRerunGet) {
+              actionsToRerun.add(actionCandidate);
+              reasonSet.add("same-resource DELETE rerun GET");
+              continue;
+            }
+            actionsToReset.add(actionCandidate);
+            reasonSet.add("same-resource DELETE reset");
+            continue;
+          }
+
+          // MutableId effects: rerun GET when matching resource created/updated
+          mutable_id_effect: {
+            if (
+              hasMutableIdAutorerun &&
+              candidateVerb === "GET" &&
+              !candidateIsPlural &&
+              isSameResource
+            ) {
+              const { computedDataSignal } =
+                getActionPrivateProperties(triggeringAction);
+              const modifiedData = computedDataSignal.peek();
+
+              if (modifiedData && typeof modifiedData === "object") {
+                for (const mutableIdKey of config.mutableIdKeys) {
+                  const modifiedMutableId = modifiedData[mutableIdKey];
+                  const candidateParams = actionCandidate.params;
+
+                  if (
+                    modifiedMutableId !== undefined &&
+                    candidateParams &&
+                    typeof candidateParams === "object" &&
+                    candidateParams[mutableIdKey] === modifiedMutableId
+                  ) {
+                    actionsToRerun.add(actionCandidate);
+                    reasonSet.add(
+                      `${triggeringAction.meta.httpVerb}-mutableId autorerun`,
+                    );
+                    break;
+                  }
+                }
+              }
+            }
+          }
+
+          // Cross-resource dependency effects: rerun dependent GET_MANY
+          dependency_effect: {
+            if (
+              triggeringResource &&
+              resourceDependencies
+                .get(triggeringResource)
+                ?.has(resourceInstance) &&
+              triggerVerb !== "GET" &&
+              candidateVerb === "GET" &&
+              candidateIsPlural
+            ) {
+              actionsToRerun.add(actionCandidate);
+              reasonSet.add("dependency autorerun");
+              continue;
+            }
+          }
+        }
+      }
+    }
+
+    return {
+      actionsToRerun,
+      actionsToReset,
+      reasons: Array.from(reasonSet),
+    };
+  };
+
+  const onActionComplete = (httpAction) => {
+    const { actionsToRerun, actionsToReset, reasons } =
+      findEffectOnActions(httpAction);
+
+    if (actionsToRerun.size > 0 || actionsToReset.size > 0) {
+      const reason = `${httpAction} triggered ${reasons.join(" and ")}`;
+      const dispatchActions = getActionDispatcher();
+      dispatchActions({
+        rerunSet: actionsToRerun,
+        resetSet: actionsToReset,
+        reason,
+      });
+    }
+  };
+
+  // Helper to find which resource an action belongs to
+  const getResourceForAction = (action) => {
+    return action.meta.resourceInstance;
+  };
+
+  return {
+    registerResource,
+    registerAction,
+    onActionComplete,
+  };
+};
+
+// Global resource lifecycle manager instance
+const resourceLifecycleManager = createResourceLifecycleManager();
+
+// Cache for parameter scope identifiers
+const paramScopeWeakSet = createIterableWeakSet();
+let paramScopeIdCounter = 0;
+const getParamScope = (params) => {
+  for (const existingParamScope of paramScopeWeakSet) {
+    if (compareTwoJsValues(existingParamScope.params, params)) {
+      return existingParamScope;
+    }
+  }
+  const id = Symbol(`paramScope-${++paramScopeIdCounter}`);
+  const newParamScope = {
+    params,
+    id,
+  };
+  paramScopeWeakSet.add(newParamScope);
+  return newParamScope;
+};
+
+const createHttpHandlerForRootResource = (
+  name,
+  {
+    idKey,
+    store,
+    /*
+    Default autorerun behavior explanation:
+
+    GET: false (RECOMMENDED)
+    What happens:
+    - GET actions are reset by DELETE operations (not rerun)
+    - DELETE operation on the displayed item would display nothing in the UI (action is in IDLE state)
+    - PUT/PATCH operations update UI via signals, no rerun needed
+    - This approach minimizes unnecessary API calls
+
+    How to handle:
+    - Applications can provide custom UI for deleted items (e.g., "Item not found")
+    - Or redirect users to appropriate pages (e.g., back to list view)
+
+    Alternative (NOT RECOMMENDED):
+    - Use GET: ["DELETE"] to rerun and display 404 error received from backend
+    - Poor UX: users expect immediate feedback, not loading + error state
+
+    GET_MANY: ["POST"]
+    - POST: New items may or may not appear in lists (depends on filters, pagination, etc.)
+      Backend determines visibility better than client-side logic
+    - DELETE: Excluded by default because:
+      • UI handles deletions via store signals (selectAll filters out deleted items)
+      • DELETE operations rarely change list content beyond item removal
+      • Avoids unnecessary API calls (can be overridden if needed)
+    */
+    rerunOn = {
+      GET: false,
+      GET_MANY: [
+        "POST",
+        // "DELETE"
+      ],
+    },
+    paramScope,
+    dependencies = [],
+    resourceInstance,
+    mutableIdKeys = [],
+  },
+) => {
+  // Register this resource with the resource lifecycle manager
+  resourceLifecycleManager.registerResource(resourceInstance, {
+    rerunOn,
+    paramScope,
+    dependencies,
+    idKey,
+    mutableIdKeys,
+  });
+
+  const createActionAffectingOneItem = (httpVerb, { callback, ...options }) => {
+    const applyDataEffect =
+      httpVerb === "DELETE"
+        ? (itemIdOrItemProps) => {
+            const itemId = store.drop(itemIdOrItemProps);
+            return itemId;
+          }
+        : (data) => {
+            let item;
+            if (Array.isArray(data)) {
+              // the callback is returning something like [property, value, props]
+              // this is to support a case like:
+              // store.upsert("name", "currentName", { name: "newName" })
+              // where we want to update the name property of an existing item
+              item = store.upsert(...data);
+            } else {
+              item = store.upsert(data);
+            }
+            const itemId = item[idKey];
+            return itemId;
+          };
+
+    const callerInfo = getCallerInfo(null, 2);
+    // Provide more fallback options for better debugging
+    const locationInfo =
+      callerInfo.file && callerInfo.line && callerInfo.column
+        ? `${callerInfo.file}:${callerInfo.line}:${callerInfo.column}`
+        : callerInfo.raw || "unknown location";
+    const originalActionName = `${name}.${httpVerb}`;
+    const httpActionAffectingOneItem = createAction(callback, {
+      meta: { httpVerb, httpMany: false, paramScope, resourceInstance, store },
+      name: `${name}.${httpVerb}`,
+      dataEffect: (data, action) => {
+        const actionLabel = action.name;
+
+        if (httpVerb === "DELETE") {
+          if (!isProps(data) && !primitiveCanBeId(data)) {
+            throw new TypeError(
+              `${actionLabel} must return an object (that will be used to drop "${name}" resource), received ${data}.
+           ${originalActionName} source location: ${locationInfo}`,
+            );
+          }
+          return applyDataEffect(data);
+        }
+        if (!isProps(data)) {
+          throw new TypeError(
+            `${actionLabel} must return an object (that will be used to upsert "${name}" resource), received ${data}.
+           ${originalActionName} source location: ${locationInfo}`,
+          );
+        }
+        return applyDataEffect(data);
+      },
+      compute: (itemId) => store.select(itemId),
+      completeSideEffect: (actionCompleted) =>
+        resourceLifecycleManager.onActionComplete(actionCompleted),
+      ...options,
+    });
+    resourceLifecycleManager.registerAction(
+      resourceInstance,
+      httpActionAffectingOneItem,
+    );
+    return httpActionAffectingOneItem;
+  };
+  const GET = (callback, options) =>
+    createActionAffectingOneItem("GET", {
+      callback,
+      applyDataEffect: (data) => {
+        const item = store.upsert(data);
+        const itemId = item[idKey];
+        return itemId;
+      },
+      compute: (itemId) => store.select(itemId),
+      ...options,
+    });
+  const POST = (callback, options) =>
+    createActionAffectingOneItem("POST", {
+      callback,
+      applyDataEffect: (data) => {
+        const item = store.upsert(data);
+        const itemId = item[idKey];
+        return itemId;
+      },
+      compute: (itemId) => store.select(itemId),
+      ...options,
+    });
+  const PUT = (callback, options) =>
+    createActionAffectingOneItem("PUT", {
+      callback,
+      ...options,
+    });
+  const PATCH = (callback, options) =>
+    createActionAffectingOneItem("PATCH", {
+      callback,
+      ...options,
+    });
+  const DELETE = (callback, options) =>
+    createActionAffectingOneItem("DELETE", {
+      callback,
+      ...options,
+    });
+
+  const createActionAffectingManyItems = (
+    httpVerb,
+    { callback, ...options },
+  ) => {
+    const applyDataEffect =
+      httpVerb === "DELETE"
+        ? (idOrMutableIdArray) => {
+            const idArray = store.drop(idOrMutableIdArray);
+            return idArray;
+          }
+        : (dataArray) => {
+            const itemArray = store.upsert(dataArray);
+            const idArray = itemArray.map((item) => item[idKey]);
+            return idArray;
+          };
+
+    const httpActionAffectingManyItems = createAction(callback, {
+      meta: { httpVerb, httpMany: true, paramScope, resourceInstance, store },
+      name: `${name}.${httpVerb}_MANY`,
+      data: [],
+      dataEffect: applyDataEffect,
+      compute: (idArray) => store.selectAll(idArray),
+      completeSideEffect: (actionCompleted) =>
+        resourceLifecycleManager.onActionComplete(actionCompleted),
+      ...options,
+    });
+    resourceLifecycleManager.registerAction(
+      resourceInstance,
+      httpActionAffectingManyItems,
+    );
+    return httpActionAffectingManyItems;
+  };
+  const GET_MANY = (callback, options) =>
+    createActionAffectingManyItems("GET", { callback, ...options });
+  const POST_MANY = (callback, options) =>
+    createActionAffectingManyItems("POST", { callback, ...options });
+  const PUT_MANY = (callback, options) =>
+    createActionAffectingManyItems("PUT", { callback, ...options });
+  const PATCH_MANY = (callback, options) =>
+    createActionAffectingManyItems("PATCH", { callback, ...options });
+  const DELETE_MANY = (callback, options) =>
+    createActionAffectingManyItems("DELETE", { callback, ...options });
+
+  return {
+    GET,
+    POST,
+    PUT,
+    PATCH,
+    DELETE,
+    GET_MANY,
+    POST_MANY,
+    PUT_MANY,
+    PATCH_MANY,
+    DELETE_MANY,
+  };
+};
+const createHttpHandlerForRelationshipToOneResource = (
+  name,
+  {
+    idKey,
+    store,
+    propertyName,
+    childIdKey,
+    childStore,
+    resourceInstance,
+    resourceLifecycleManager,
+  },
+) => {
+  const createActionAffectingOneItem = (httpVerb, { callback, ...options }) => {
+    const applyDataEffect =
+      httpVerb === "DELETE"
+        ? (itemId) => {
+            const item = store.select(itemId);
+            const childItemId = item[propertyName][childIdKey];
+            store.upsert({
+              [idKey]: itemId,
+              [propertyName]: null,
+            });
+            return childItemId;
+          }
+        : // callback must return object with the following format:
+          // {
+          //   [idKey]: 123,
+          //   [propertyName]: {
+          //     [childIdKey]: 456, ...childProps
+          //   }
+          // }
+          // the following could happen too if there is no relationship
+          // {
+          //   [idKey]: 123,
+          //   [propertyName]: null
+          // }
+          (data) => {
+            const item = store.upsert(data);
+            const childItem = item[propertyName];
+            const childItemId = childItem ? childItem[childIdKey] : undefined;
+            return childItemId;
+          };
+
+    const callerInfo = getCallerInfo(null, 2);
+    // Provide more fallback options for better debugging
+    const locationInfo =
+      callerInfo.file && callerInfo.line && callerInfo.column
+        ? `${callerInfo.file}:${callerInfo.line}:${callerInfo.column}`
+        : callerInfo.raw || "unknown location";
+    const originalActionName = `${name}.${httpVerb}`;
+
+    const httpActionAffectingOneItem = createAction(callback, {
+      meta: { httpVerb, httpMany: false, resourceInstance, store },
+      name: `${name}.${httpVerb}`,
+      dataEffect: (data, action) => {
+        const actionLabel = action.name;
+
+        if (httpVerb === "DELETE") {
+          if (!isProps(data) && !primitiveCanBeId(data)) {
+            throw new TypeError(
+              `${actionLabel} must return an object (that will be used to drop "${name}" resource), received ${data}.
+           ${originalActionName} source location: ${locationInfo}`,
+            );
+          }
+          return applyDataEffect(data);
+        }
+        if (!isProps(data)) {
+          throw new TypeError(
+            `${actionLabel} must return an object (that will be used to upsert "${name}" resource), received ${data}.
+           ${originalActionName} source location: ${locationInfo}`,
+          );
+        }
+        return applyDataEffect(data);
+      },
+      compute: (childItemId) => childStore.select(childItemId),
+      completeSideEffect: (actionCompleted) =>
+        resourceLifecycleManager.onActionComplete(actionCompleted),
+      ...options,
+    });
+    resourceLifecycleManager.registerAction(
+      resourceInstance,
+      httpActionAffectingOneItem,
+    );
+    return httpActionAffectingOneItem;
+  };
+
+  const GET = (callback, options) =>
+    createActionAffectingOneItem("GET", {
+      callback,
+      ...options,
+    });
+  const PUT = (callback, options) =>
+    createActionAffectingOneItem("PUT", {
+      callback,
+      ...options,
+    });
+  const DELETE = (callback, options) =>
+    createActionAffectingOneItem("DELETE", {
+      callback,
+      ...options,
+    });
+
+  // il n'y a pas de many puisque on cible une seule resource
+  // genre table.owner -> c'est un seul owner qu'on peut
+  // GET -> recup les infos de l'objet
+  // PUT -> mettre a jour l'owner de la table
+  // DELETE -> supprimer l'owner de la table
+
+  return { GET, PUT, DELETE };
+};
+const createHttpHandlerRelationshipToManyResource = (
+  name,
+  {
+    idKey,
+    store,
+    propertyName,
+    childIdKey,
+    childStore,
+    resourceInstance,
+    resourceLifecycleManager,
+  } = {},
+) => {
+  // idéalement s'il y a un GET sur le store originel on voudrait ptet le reload
+  // parce que le store originel peut retourner cette liste ou etre impacté
+  // pour l'instant on ignore
+
+  // one item AND many child items
+  const createActionAffectingOneItem = (httpVerb, { callback, ...options }) => {
+    const applyDataEffect =
+      httpVerb === "DELETE"
+        ? ([itemId, childItemId]) => {
+            const item = store.select(itemId);
+            const childItemArray = item[propertyName];
+            const childItemArrayWithoutThisOne = [];
+            let found = false;
+            for (const childItemCandidate of childItemArray) {
+              const childItemCandidateId = childItemCandidate[childIdKey];
+              if (childItemCandidateId === childItemId) {
+                found = true;
+              } else {
+                childItemArrayWithoutThisOne.push(childItemCandidate);
+              }
+            }
+            if (found) {
+              store.upsert({
+                [idKey]: itemId,
+                [propertyName]: childItemArrayWithoutThisOne,
+              });
+            }
+            return childItemId;
+          }
+        : (childData) => {
+            const childItem = childStore.upsert(childData); // if the child item was used it will reload thanks to signals
+            const childItemId = childItem[childIdKey];
+            return childItemId;
+          };
+
+    const callerInfo = getCallerInfo(null, 2);
+    // Provide more fallback options for better debugging
+    const locationInfo =
+      callerInfo.file && callerInfo.line && callerInfo.column
+        ? `${callerInfo.file}:${callerInfo.line}:${callerInfo.column}`
+        : callerInfo.raw || "unknown location";
+    const originalActionName = `${name}.${httpVerb}`;
+
+    const httpActionAffectingOneItem = createAction(callback, {
+      meta: { httpVerb, httpMany: false, resourceInstance, store: childStore },
+      name: `${name}.${httpVerb}`,
+      dataEffect: (data, action) => {
+        const actionLabel = action.name;
+
+        if (httpVerb === "DELETE") {
+          // For DELETE in many relationship, we expect [itemId, childItemId] array
+          if (!Array.isArray(data) || data.length !== 2) {
+            throw new TypeError(
+              `${actionLabel} must return an array [itemId, childItemId] (that will be used to remove relationship), received ${data}.
+           ${originalActionName} source location: ${locationInfo}`,
+            );
+          }
+          return applyDataEffect(data);
+        }
+        if (!isProps(data)) {
+          throw new TypeError(
+            `${actionLabel} must return an object (that will be used to upsert child item), received ${data}.
+           ${originalActionName} source location: ${locationInfo}`,
+          );
+        }
+        return applyDataEffect(data);
+      },
+      compute: (childItemId) => childStore.select(childItemId),
+      completeSideEffect: (actionCompleted) =>
+        resourceLifecycleManager.onActionComplete(actionCompleted),
+      ...options,
+    });
+    resourceLifecycleManager.registerAction(
+      resourceInstance,
+      httpActionAffectingOneItem,
+    );
+    return httpActionAffectingOneItem;
+  };
+  const GET = (callback, options) =>
+    createActionAffectingOneItem("GET", {
+      callback,
+      ...options,
+    });
+  // le souci que je vois ici c'est que je n'ai pas la moindre idée d'ou
+  // inserer le childItem (ni meme s'il doit etre visible)
+  // je pense que la bonne chose a faire est de reload
+  // l'objet user.tables s'il en existe un
+  // TODO: find any GET action on "user" and reload it
+  const POST = (callback, options) =>
+    createActionAffectingOneItem("POST", {
+      callback,
+      ...options,
+    });
+  const PUT = (callback, options) =>
+    createActionAffectingOneItem("PUT", {
+      callback,
+      ...options,
+    });
+  const PATCH = (callback, options) =>
+    createActionAffectingOneItem("PATCH", {
+      callback,
+      ...options,
+    });
+  const DELETE = (callback, options) =>
+    createActionAffectingOneItem("DELETE", {
+      callback,
+      ...options,
+    });
+
+  const createActionAffectingManyItems = (
+    httpVerb,
+    { callback, ...options },
+  ) => {
+    const applyDataEffect =
+      httpVerb === "GET"
+        ? (data) => {
+            // callback must return object with the following format:
+            // {
+            //   [idKey]: 123,
+            //   [propertyName]: [
+            //      { [childIdKey]: 456, ...childProps },
+            //      { [childIdKey]: 789, ...childProps },
+            //      ...
+            //   ]
+            // }
+            // the array can be empty
+            const item = store.upsert(data);
+            const childItemArray = item[propertyName];
+            const childItemIdArray = childItemArray.map(
+              (childItem) => childItem[childIdKey],
+            );
+            return childItemIdArray;
+          }
+        : httpVerb === "DELETE"
+          ? ([itemIdOrMutableId, childItemIdOrMutableIdArray]) => {
+              const item = store.select(itemIdOrMutableId);
+              const childItemArray = item[propertyName];
+              const deletedChildItemIdArray = [];
+              const childItemArrayWithoutThoose = [];
+              let someFound = false;
+              const deletedChildItemArray = childStore.select(
+                childItemIdOrMutableIdArray,
+              );
+              for (const childItemCandidate of childItemArray) {
+                if (deletedChildItemArray.includes(childItemCandidate)) {
+                  someFound = true;
+                  deletedChildItemIdArray.push(childItemCandidate[childIdKey]);
+                } else {
+                  childItemArrayWithoutThoose.push(childItemCandidate);
+                }
+              }
+              if (someFound) {
+                store.upsert({
+                  [idKey]: item[idKey],
+                  [propertyName]: childItemArrayWithoutThoose,
+                });
+              }
+              return deletedChildItemIdArray;
+            }
+          : (childDataArray) => {
+              // hum ici aussi on voudra reload "user" pour POST
+              // les autres les signals se charge de reload si visible
+              const childItemArray = childStore.upsert(childDataArray);
+              const childItemIdArray = childItemArray.map(
+                (childItem) => childItem[childIdKey],
+              );
+              return childItemIdArray;
+            };
+
+    const callerInfo = getCallerInfo(null, 2);
+    // Provide more fallback options for better debugging
+    const locationInfo =
+      callerInfo.file && callerInfo.line && callerInfo.column
+        ? `${callerInfo.file}:${callerInfo.line}:${callerInfo.column}`
+        : callerInfo.raw || "unknown location";
+    const originalActionName = `${name}.${httpVerb}[many]`;
+
+    const httpActionAffectingManyItem = createAction(callback, {
+      meta: { httpVerb, httpMany: true, resourceInstance, store: childStore },
+      name: `${name}.${httpVerb}[many]`,
+      data: [],
+      dataEffect: (data, action) => {
+        const actionLabel = action.name;
+
+        if (httpVerb === "GET") {
+          if (!isProps(data)) {
+            throw new TypeError(
+              `${actionLabel} must return an object (that will be used to upsert "${name}" resource with many relationships), received ${data}.
+           ${originalActionName} source location: ${locationInfo}`,
+            );
+          }
+          return applyDataEffect(data);
+        }
+        if (httpVerb === "DELETE") {
+          // For DELETE_MANY in many relationship, we expect [itemId, childItemIdArray] array
+          if (
+            !Array.isArray(data) ||
+            data.length !== 2 ||
+            !Array.isArray(data[1])
+          ) {
+            throw new TypeError(
+              `${actionLabel} must return an array [itemId, childItemIdArray] (that will be used to remove relationships), received ${data}.
+           ${originalActionName} source location: ${locationInfo}`,
+            );
+          }
+          return applyDataEffect(data);
+        }
+        // For POST, PUT, PATCH - expect array of objects
+        if (!Array.isArray(data)) {
+          throw new TypeError(
+            `${actionLabel} must return an array of objects (that will be used to upsert child items), received ${data}.
+           ${originalActionName} source location: ${locationInfo}`,
+          );
+        }
+        return applyDataEffect(data);
+      },
+      compute: (childItemIdArray) => childStore.selectAll(childItemIdArray),
+      completeSideEffect: (actionCompleted) =>
+        resourceLifecycleManager.onActionComplete(actionCompleted),
+      ...options,
+    });
+    resourceLifecycleManager.registerAction(
+      resourceInstance,
+      httpActionAffectingManyItem,
+    );
+    return httpActionAffectingManyItem;
+  };
+
+  const GET_MANY = (callback, options) =>
+    createActionAffectingManyItems("GET", { callback, ...options });
+  const POST_MANY = (callback, options) =>
+    createActionAffectingManyItems("POST", { callback, ...options });
+  const PUT_MANY = (callback, options) =>
+    createActionAffectingManyItems("PUT", { callback, ...options });
+  const PATCH_MANY = (callback, options) =>
+    createActionAffectingManyItems("PATCH", { callback, ...options });
+  const DELETE_MANY = (callback, options) =>
+    createActionAffectingManyItems("DELETE", { callback, ...options });
+
+  return {
+    GET,
+    POST,
+    PUT,
+    PATCH,
+    DELETE,
+    GET_MANY,
+    POST_MANY,
+    PUT_MANY,
+    PATCH_MANY,
+    DELETE_MANY,
+  };
+};
+
+export const resource = (
+  name,
+  { idKey, mutableIdKeys = [], rerunOn, httpHandler, ...rest } = {},
+) => {
+  if (idKey === undefined) {
+    idKey = mutableIdKeys.length === 0 ? "id" : mutableIdKeys[0];
+  }
+  const resourceInstance = {
+    isResource: true,
+    name,
+    idKey,
+    httpActions: {},
+    addItemSetup: undefined,
+    httpHandler,
+  };
+  if (!httpHandler) {
+    const setupCallbackSet = new Set();
+    const addItemSetup = (callback) => {
+      setupCallbackSet.add(callback);
+    };
+    resourceInstance.addItemSetup = addItemSetup;
+
+    const itemPrototype = {
+      [Symbol.toStringTag]: name,
+      toString() {
+        let string = `${name}`;
+        if (mutableIdKeys.length) {
+          for (const mutableIdKey of mutableIdKeys) {
+            const mutableId = this[mutableIdKey];
+            if (mutableId !== undefined) {
+              string += `[${mutableIdKey}=${mutableId}]`;
+              return string;
+            }
+          }
+        }
+        const id = this[idKey];
+        if (id) {
+          string += `[${idKey}=${id}]`;
+        }
+        return string;
+      },
+    };
+
+    const store = arraySignalStore([], idKey, {
+      mutableIdKeys,
+      name: `${name} store`,
+      createItem: (props) => {
+        const item = Object.create(itemPrototype);
+        Object.assign(item, props);
+        Object.defineProperty(item, SYMBOL_IDENTITY, {
+          value: item[idKey],
+          writable: false,
+          enumerable: false,
+          configurable: false,
+        });
+        for (const setupCallback of setupCallbackSet) {
+          setupCallback(item);
+        }
+        return item;
+      },
+    });
+    const useArray = () => {
+      return store.arraySignal.value;
+    };
+    const useById = (id) => {
+      return store.select(idKey, id);
+    };
+
+    Object.assign(resourceInstance, {
+      useArray,
+      useById,
+      store,
+    });
+
+    httpHandler = createHttpHandlerForRootResource(name, {
+      idKey,
+      store,
+      rerunOn,
+      resourceInstance,
+      mutableIdKeys,
+    });
+  }
+  resourceInstance.httpHandler = httpHandler;
+
+  // Store the action callback definitions for withParams to use later
+  resourceInstance.httpActions = rest;
+
+  // Create HTTP actions
+  for (const key of Object.keys(rest)) {
+    const method = httpHandler[key];
+    if (!method) {
+      continue;
+    }
+    const action = method(rest[key]);
+    resourceInstance[key] = action;
+  }
+
+  resourceInstance.one = (propertyName, childResource, options) => {
+    const childIdKey = childResource.idKey;
+    const childName = `${name}.${propertyName}`;
+    resourceInstance.addItemSetup((item) => {
+      const childItemIdSignal = signal();
+      const updateChildItemId = (value) => {
+        const currentChildItemId = childItemIdSignal.peek();
+        if (isProps(value)) {
+          const childItem = childResource.store.upsert(value);
+          const childItemId = childItem[childIdKey];
+          if (currentChildItemId === childItemId) {
+            return false;
+          }
+          childItemIdSignal.value = childItemId;
+          return true;
+        }
+        if (primitiveCanBeId(value)) {
+          const childItemProps = { [childIdKey]: value };
+          const childItem = childResource.store.upsert(childItemProps);
+          const childItemId = childItem[childIdKey];
+          if (currentChildItemId === childItemId) {
+            return false;
+          }
+          childItemIdSignal.value = childItemId;
+          return true;
+        }
+        if (currentChildItemId === undefined) {
+          return false;
+        }
+        childItemIdSignal.value = undefined;
+        return true;
+      };
+      updateChildItemId(item[propertyName]);
+
+      const childItemSignal = computed(() => {
+        const childItemId = childItemIdSignal.value;
+        const childItem = childResource.store.select(childItemId);
+        return childItem;
+      });
+      const childItemFacadeSignal = computed(() => {
+        const childItem = childItemSignal.value;
+        if (childItem) {
+          const childItemCopy = Object.create(
+            Object.getPrototypeOf(childItem),
+            Object.getOwnPropertyDescriptors(childItem),
+          );
+          Object.defineProperty(childItemCopy, SYMBOL_OBJECT_SIGNAL, {
+            value: childItemSignal,
+            writable: false,
+            enumerable: false,
+            configurable: false,
+          });
+          return childItemCopy;
+        }
+        const nullItem = {
+          [SYMBOL_OBJECT_SIGNAL]: childItemSignal,
+          valueOf: () => null,
+        };
+        return nullItem;
+      });
+
+      if (DEBUG) {
+        console.debug(
+          `setup ${item}.${propertyName} is one "${childResource.name}" (current value: ${childItemSignal.peek()})`,
+        );
+      }
+
+      Object.defineProperty(item, propertyName, {
+        get: () => {
+          const childItemFacade = childItemFacadeSignal.value;
+          return childItemFacade;
+        },
+        set: (value) => {
+          if (!updateChildItemId(value)) {
+            return;
+          }
+          if (DEBUG) {
+            console.debug(
+              `${item}.${propertyName} updated to ${childItemSignal.peek()}`,
+            );
+          }
+        },
+      });
+    });
+    const httpHandlerForRelationshipToOneChild =
+      createHttpHandlerForRelationshipToOneResource(childName, {
+        idKey,
+        store: resourceInstance.store,
+        propertyName,
+        childIdKey,
+        childStore: childResource.store,
+        resourceInstance,
+        resourceLifecycleManager,
+      });
+    return resource(childName, {
+      idKey: childIdKey,
+      httpHandler: httpHandlerForRelationshipToOneChild,
+      ...options,
+    });
+  };
+  resourceInstance.many = (propertyName, childResource, options) => {
+    const childIdKey = childResource.idKey;
+    const childName = `${name}.${propertyName}`;
+    resourceInstance.addItemSetup((item) => {
+      const childItemIdArraySignal = signal([]);
+      const updateChildItemIdArray = (valueArray) => {
+        const currentIdArray = childItemIdArraySignal.peek();
+
+        if (!Array.isArray(valueArray)) {
+          if (currentIdArray.length === 0) {
+            return;
+          }
+          childItemIdArraySignal.value = [];
+          return;
+        }
+
+        let i = 0;
+        const idArray = [];
+        let modified = false;
+        while (i < valueArray.length) {
+          const value = valueArray[i];
+          const currentIdAtIndex = currentIdArray[idArray.length];
+          i++;
+          if (isProps(value)) {
+            const childItem = childResource.store.upsert(value);
+            const childItemId = childItem[childIdKey];
+            if (currentIdAtIndex !== childItemId) {
+              modified = true;
+            }
+            idArray.push(childItemId);
+            continue;
+          }
+          if (primitiveCanBeId(value)) {
+            const childItemProps = { [childIdKey]: value };
+            const childItem = childResource.store.upsert(childItemProps);
+            const childItemId = childItem[childIdKey];
+            if (currentIdAtIndex !== childItemId) {
+              modified = true;
+            }
+            idArray.push(childItemId);
+            continue;
+          }
+        }
+        if (modified || currentIdArray.length !== idArray.length) {
+          childItemIdArraySignal.value = idArray;
+        }
+      };
+      updateChildItemIdArray(item[propertyName]);
+
+      const childItemArraySignal = computed(() => {
+        const childItemIdArray = childItemIdArraySignal.value;
+        const childItemArray = childResource.store.selectAll(childItemIdArray);
+        Object.defineProperty(childItemArray, SYMBOL_OBJECT_SIGNAL, {
+          value: childItemArraySignal,
+          writable: false,
+          enumerable: false,
+          configurable: false,
+        });
+        return childItemArray;
+      });
+
+      if (DEBUG) {
+        const childItemArray = childItemArraySignal.peek();
+        console.debug(
+          `setup ${item}.${propertyName} is many "${childResource.name}" (current value: ${childItemArray.length ? childItemArray.join(",") : "[]"})`,
+        );
+      }
+
+      Object.defineProperty(item, propertyName, {
+        get: () => {
+          const childItemArray = childItemArraySignal.value;
+          if (DEBUG) {
+            console.debug(
+              `return ${childItemArray.length ? childItemArray.join(",") : "[]"} for ${item}.${propertyName}`,
+            );
+          }
+          return childItemArray;
+        },
+        set: (value) => {
+          updateChildItemIdArray(value);
+          if (DEBUG) {
+            console.debug(
+              `${item}.${propertyName} updated to ${childItemIdArraySignal.peek()}`,
+            );
+          }
+        },
+      });
+    });
+    const httpHandleForChildManyResource =
+      createHttpHandlerRelationshipToManyResource(childName, {
+        idKey,
+        store: resourceInstance.store,
+        propertyName,
+        childIdKey,
+        childStore: childResource.store,
+        resourceInstance,
+        resourceLifecycleManager,
+      });
+    return resource(childName, {
+      idKey: childIdKey,
+      httpHandler: httpHandleForChildManyResource,
+      ...options,
+    });
+  };
+
+  /**
+   * Creates a parameterized version of the resource with isolated resource lifecycle behavior.
+   *
+   * Actions from parameterized resources only trigger rerun/reset for other actions with
+   * identical parameters, preventing cross-contamination between different parameter sets.
+   *
+   * @param {Object} params - Parameters to bind to all actions of this resource (required)
+   * @param {Object} options - Additional options for the parameterized resource
+   * @param {Array} options.dependencies - Array of resources that should trigger autorerun when modified
+   * @param {Object} options.rerunOn - Configuration for when to rerun GET/GET_MANY actions
+   * @param {false|Array|string} options.rerunOn.GET - HTTP verbs that trigger GET rerun (false = reset on DELETE)
+   * @param {false|Array|string} options.rerunOn.GET_MANY - HTTP verbs that trigger GET_MANY rerun (false = reset on DELETE)
+   * @returns {Object} A new resource instance with parameter-bound actions and isolated lifecycle
+   * @see {@link ./docs/resource_with_params.md} for detailed documentation and examples
+   *
+   * @example
+   * const ROLE = resource("role", { GET: (params) => fetchRole(params) });
+   * const adminRoles = ROLE.withParams({ canlogin: true });
+   * const guestRoles = ROLE.withParams({ canlogin: false });
+   * // adminRoles and guestRoles have isolated autorerun behavior
+   *
+   * @example
+   * // Cross-resource dependencies
+   * const role = resource("role");
+   * const database = resource("database");
+   * const tables = resource("tables");
+   * const ROLE_WITH_OWNERSHIP = role.withParams({ owners: true }, {
+   *   dependencies: [role, database, tables],
+   * });
+   * // ROLE_WITH_OWNERSHIP.GET_MANY will autorerun when any table/database/role is POST/DELETE
+   */
+  const withParams = (params, options = {}) => {
+    // Require parameters
+    if (!params || Object.keys(params).length === 0) {
+      throw new Error(`resource(${name}).withParams() requires parameters`);
+    }
+
+    const { dependencies = [], rerunOn: customRerunOn } = options;
+
+    // Generate unique param scope for these parameters
+    const paramScopeObject = getParamScope(params);
+
+    // Use custom rerunOn settings if provided, otherwise use resource defaults
+    const finalRerunOn = customRerunOn || rerunOn;
+
+    // Create a new httpHandler with the param scope for isolated autorerun
+    const parameterizedHttpHandler = createHttpHandlerForRootResource(name, {
+      idKey,
+      store: resourceInstance.store,
+      rerunOn: finalRerunOn,
+      paramScope: paramScopeObject,
+      dependencies,
+      resourceInstance,
+      mutableIdKeys,
+    });
+
+    // Create parameterized resource
+    const parameterizedResource = {
+      isResource: true,
+      name,
+      idKey,
+      useArray: resourceInstance.useArray,
+      useById: resourceInstance.useById,
+      store: resourceInstance.store,
+      addItemSetup: resourceInstance.addItemSetup,
+      httpHandler: parameterizedHttpHandler,
+      one: resourceInstance.one,
+      many: resourceInstance.many,
+      dependencies, // Store dependencies for debugging/inspection
+      httpActions: resourceInstance.httpActions,
+    };
+
+    // Create HTTP actions from the parameterized handler and bind parameters
+    for (const key of Object.keys(resourceInstance.httpActions)) {
+      const method = parameterizedHttpHandler[key];
+      if (method) {
+        const action = method(resourceInstance.httpActions[key]);
+        // Bind the parameters to get a parameterized action instance
+        parameterizedResource[key] = action.bindParams(params);
+      }
+    }
+
+    // Add withParams method to the parameterized resource for chaining
+    parameterizedResource.withParams = (newParams, newOptions = {}) => {
+      if (!newParams || Object.keys(newParams).length === 0) {
+        throw new Error(`resource(${name}).withParams() requires parameters`);
+      }
+      // Merge current params with new ones for chaining
+      const mergedParams = { ...params, ...newParams };
+      // Merge options, with new options taking precedence
+      const mergedOptions = {
+        dependencies,
+        rerunOn: finalRerunOn,
+        ...newOptions,
+      };
+      return withParams(mergedParams, mergedOptions);
+    };
+
+    return parameterizedResource;
+  };
+
+  resourceInstance.withParams = withParams;
+
+  return resourceInstance;
+};
+
+const isProps = (value) => {
+  return value !== null && typeof value === "object";
+};