@jsenv/navi 0.0.1

package/src/store/tests/resource_graph_dependencies.test.js

@@ -0,0 +1,95 @@
+// Example test demonstrating the dependency system
+import { resource } from "../resource_graph.js";
+
+// Create test resources
+const role = resource("role", {
+  GET_MANY: () =>
+    Promise.resolve([
+      { id: 1, name: "admin" },
+      { id: 2, name: "user" },
+    ]),
+  POST: (data) => Promise.resolve({ id: Date.now(), ...data }),
+  DELETE: (id) => Promise.resolve(id),
+});
+
+const database = resource("database", {
+  GET_MANY: () =>
+    Promise.resolve([
+      { id: 1, name: "main_db" },
+      { id: 2, name: "test_db" },
+    ]),
+  POST: (data) => Promise.resolve({ id: Date.now(), ...data }),
+  DELETE: (id) => Promise.resolve(id),
+});
+
+const tables = resource("tables", {
+  GET_MANY: () =>
+    Promise.resolve([
+      { id: 1, name: "users", database_id: 1 },
+      { id: 2, name: "roles", database_id: 1 },
+    ]),
+  POST: (data) => Promise.resolve({ id: Date.now(), ...data }),
+  DELETE: (id) => Promise.resolve(id),
+});
+
+// Create parameterized resource with dependencies
+// This will autoreload when any of the dependency resources are modified
+const ROLE_WITH_OWNERSHIP = role.withParams(
+  { owners: true },
+  {
+    dependencies: [role, database, tables],
+  },
+);
+
+// Demonstrate the functionality
+console.log("🚀 Dependency system demo");
+console.log(
+  `✅ Created ROLE_WITH_OWNERSHIP with ${ROLE_WITH_OWNERSHIP.dependencies.length} dependencies`,
+);
+console.log(
+  `📋 Dependencies: ${ROLE_WITH_OWNERSHIP.dependencies.map((d) => d.name).join(", ")}`,
+);
+
+// Test the autoreload mechanism
+async function testAutoreload() {
+  console.log("\n🧪 Testing autoreload mechanism...");
+
+  try {
+    // Load the parameterized resource
+    const ownershipData = await ROLE_WITH_OWNERSHIP.GET_MANY.load();
+    console.log(
+      "✅ ROLE_WITH_OWNERSHIP.GET_MANY.load() executed:",
+      ownershipData.length,
+      "items",
+    );
+
+    // Trigger dependency changes that should cause autoreload
+    console.log("\n📝 Triggering dependency changes...");
+
+    await tables.POST.load({ name: "new_table", database_id: 1 });
+    console.log(
+      "✅ tables.POST.load() - should trigger ROLE_WITH_OWNERSHIP autoreload",
+    );
+
+    await database.POST.load({ name: "new_database" });
+    console.log(
+      "✅ database.POST.load() - should trigger ROLE_WITH_OWNERSHIP autoreload",
+    );
+
+    await role.POST.load({ name: "new_role" });
+    console.log(
+      "✅ role.POST.load() - should trigger ROLE_WITH_OWNERSHIP autoreload",
+    );
+
+    console.log("\n✅ Dependency system test completed successfully!");
+    console.log(
+      "💡 In a real application, these would automatically reload ROLE_WITH_OWNERSHIP.GET_MANY",
+    );
+  } catch (error) {
+    console.error("❌ Test failed:", error);
+  }
+}
+
+testAutoreload();
+
+export { database, role, ROLE_WITH_OWNERSHIP, tables };

package/src/store/value_in_local_storage.js

@@ -0,0 +1,187 @@
+export const valueInLocalStorage = (key, options = {}) => {
+  const { type = "string" } = options;
+  const converter = typeConverters[type];
+  if (converter === undefined) {
+    console.warn(
+      `Invalid type "${type}" for "${key}" in local storage, expected one of ${Object.keys(
+        typeConverters,
+      ).join(", ")}`,
+    );
+  }
+  const getValidityMessage = (
+    valueToCheck,
+    valueInLocalStorage = valueToCheck,
+  ) => {
+    if (!converter) {
+      return "";
+    }
+    if (!converter.checkValidity) {
+      return "";
+    }
+    const checkValidityResult = converter.checkValidity(valueToCheck);
+    if (checkValidityResult === false) {
+      return `${valueInLocalStorage}`;
+    }
+    if (!checkValidityResult) {
+      return "";
+    }
+    return `${checkValidityResult}, got "${valueInLocalStorage}"`;
+  };
+
+  const get = () => {
+    let valueInLocalStorage = window.localStorage.getItem(key);
+    if (valueInLocalStorage === null) {
+      return Object.hasOwn(options, "default") ? options.default : undefined;
+    }
+    if (converter && converter.decode) {
+      const valueDecoded = converter.decode(valueInLocalStorage);
+      const validityMessage = getValidityMessage(
+        valueDecoded,
+        valueInLocalStorage,
+      );
+      if (validityMessage) {
+        console.warn(
+          `The value found in localStorage "${key}" is invalid: ${validityMessage}`,
+        );
+        return undefined;
+      }
+      return valueDecoded;
+    }
+    const validityMessage = getValidityMessage(valueInLocalStorage);
+    if (validityMessage) {
+      console.warn(
+        `The value found in localStorage "${key}" is invalid: ${validityMessage}`,
+      );
+      return undefined;
+    }
+    return valueInLocalStorage;
+  };
+  const set = (value) => {
+    if (value === undefined) {
+      window.localStorage.removeItem(key);
+      return;
+    }
+    const validityMessage = getValidityMessage(value);
+    if (validityMessage) {
+      console.warn(
+        `The value to set in localStorage "${key}" is invalid: ${validityMessage}`,
+      );
+    }
+    if (converter && converter.encode) {
+      const valueEncoded = converter.encode(value);
+      window.localStorage.setItem(key, valueEncoded);
+      return;
+    }
+    window.localStorage.setItem(key, value);
+  };
+  const remove = () => {
+    window.localStorage.removeItem(key);
+  };
+
+  return [get, set, remove];
+};
+
+const typeConverters = {
+  boolean: {
+    checkValidity: (value) => {
+      if (typeof value !== "boolean") {
+        return `must be a boolean`;
+      }
+      return "";
+    },
+    decode: (value) => {
+      return value === "true";
+    },
+  },
+  string: {
+    checkValidity: (value) => {
+      if (typeof value !== "string") {
+        return `must be a string`;
+      }
+      return "";
+    },
+  },
+  number: {
+    decode: (value) => {
+      const valueParsed = parseFloat(value);
+      return valueParsed;
+    },
+    checkValidity: (value) => {
+      if (typeof value !== "number") {
+        return `must be a number`;
+      }
+      if (!Number.isFinite(value)) {
+        return `must be finite`;
+      }
+      return "";
+    },
+  },
+  positive_number: {
+    decode: (value) => {
+      const valueParsed = parseFloat(value);
+      return valueParsed;
+    },
+    checkValidity: (value) => {
+      if (typeof value !== "number") {
+        return `must be a number`;
+      }
+      if (value < 0) {
+        return `must be positive`;
+      }
+      return "";
+    },
+  },
+  positive_integer: {
+    decode: (value) => {
+      const valueParsed = parseInt(value, 10);
+      return valueParsed;
+    },
+    checkValidity: (value) => {
+      if (typeof value !== "number") {
+        return `must be a number`;
+      }
+      if (!Number.isInteger(value)) {
+        return `must be an integer`;
+      }
+      if (value < 0) {
+        return `must be positive`;
+      }
+      return "";
+    },
+  },
+  percentage: {
+    checkValidity: (value) => {
+      if (typeof value !== "string") {
+        return `must be a percentage`;
+      }
+      if (!value.endsWith("%")) {
+        return `must end with %`;
+      }
+      const percentageString = value.slice(0, -1);
+      const percentageFloat = parseFloat(percentageString);
+      if (typeof percentageFloat !== "number") {
+        return `must be a percentage`;
+      }
+      if (percentageFloat < 0 || percentageFloat > 100) {
+        return `must be between 0 and 100`;
+      }
+      return "";
+    },
+  },
+  object: {
+    decode: (value) => {
+      const valueParsed = JSON.parse(value);
+      return valueParsed;
+    },
+    encode: (value) => {
+      const valueStringified = JSON.stringify(value);
+      return valueStringified;
+    },
+    checkValidity: (value) => {
+      if (value === null || typeof value !== "object") {
+        return `must be an object`;
+      }
+      return "";
+    },
+  },
+};

package/src/symbol_object_signal.js

@@ -0,0 +1 @@
+export const SYMBOL_OBJECT_SIGNAL = Symbol.for("navi_object_signal");

package/src/use_action_data.js

@@ -0,0 +1,10 @@
+import { getActionPrivateProperties } from "./action_private_properties.js";
+
+export const useActionData = (action) => {
+  if (!action) {
+    return undefined;
+  }
+  const { computedDataSignal } = getActionPrivateProperties(action);
+  const data = computedDataSignal.value;
+  return data;
+};

package/src/use_action_status.js

@@ -0,0 +1,47 @@
+import { getActionPrivateProperties } from "./action_private_properties.js";
+import { ABORTED, COMPLETED, IDLE, RUNNING } from "./action_run_states.js";
+
+export const useActionStatus = (action) => {
+  if (!action) {
+    return {
+      params: undefined,
+      runningState: IDLE,
+      isPrerun: false,
+      idle: true,
+      loading: false,
+      aborted: false,
+      error: null,
+      completed: false,
+      data: undefined,
+    };
+  }
+  const {
+    paramsSignal,
+    runningStateSignal,
+    isPrerunSignal,
+    errorSignal,
+    computedDataSignal,
+  } = getActionPrivateProperties(action);
+
+  const params = paramsSignal.value;
+  const isPrerun = isPrerunSignal.value;
+  const runningState = runningStateSignal.value;
+  const idle = runningState === IDLE;
+  const aborted = runningState === ABORTED;
+  const error = errorSignal.value;
+  const loading = runningState === RUNNING;
+  const completed = runningState === COMPLETED;
+  const data = computedDataSignal.value;
+
+  return {
+    params,
+    runningState,
+    isPrerun,
+    idle,
+    loading,
+    aborted,
+    error,
+    completed,
+    data,
+  };
+};

package/src/utils/add_many_event_listeners.js

@@ -0,0 +1,15 @@
+export const addManyEventListeners = (element, events) => {
+  const cleanupCallbackSet = new Set();
+  for (const event of Object.keys(events)) {
+    const callback = events[event];
+    element.addEventListener(event, callback);
+    cleanupCallbackSet.add(() => {
+      element.removeEventListener(event, callback);
+    });
+  }
+  return () => {
+    for (const cleanupCallback of cleanupCallbackSet) {
+      cleanupCallback();
+    }
+  };
+};

package/src/utils/array_add_remove.js

@@ -0,0 +1,61 @@
+export const addIntoArray = (array, ...valuesToAdd) => {
+  if (valuesToAdd.length === 1) {
+    const [valueToAdd] = valuesToAdd;
+    const arrayWithThisValue = [];
+    for (const value of array) {
+      if (value === valueToAdd) {
+        return array;
+      }
+      arrayWithThisValue.push(value);
+    }
+    arrayWithThisValue.push(valueToAdd);
+    return arrayWithThisValue;
+  }
+
+  const existingValueSet = new Set();
+  const arrayWithTheseValues = [];
+  for (const existingValue of array) {
+    arrayWithTheseValues.push(existingValue);
+    existingValueSet.add(existingValue);
+  }
+  let hasNewValues = false;
+  for (const valueToAdd of valuesToAdd) {
+    if (existingValueSet.has(valueToAdd)) {
+      continue;
+    }
+    arrayWithTheseValues.push(valueToAdd);
+    hasNewValues = true;
+  }
+  return hasNewValues ? arrayWithTheseValues : array;
+};
+
+export const removeFromArray = (array, ...valuesToRemove) => {
+  if (valuesToRemove.length === 1) {
+    const [valueToRemove] = valuesToRemove;
+    const arrayWithoutThisValue = [];
+    let found = false;
+    for (const value of array) {
+      if (value === valueToRemove) {
+        found = true;
+        continue;
+      }
+      arrayWithoutThisValue.push(value);
+    }
+    if (!found) {
+      return array;
+    }
+    return arrayWithoutThisValue;
+  }
+
+  const valuesToRemoveSet = new Set(valuesToRemove);
+  const arrayWithoutTheseValues = [];
+  let hasRemovedValues = false;
+  for (const value of array) {
+    if (valuesToRemoveSet.has(value)) {
+      hasRemovedValues = true;
+      continue;
+    }
+    arrayWithoutTheseValues.push(value);
+  }
+  return hasRemovedValues ? arrayWithoutTheseValues : array;
+};

package/src/utils/array_signal.js

@@ -0,0 +1,15 @@
+import { signal } from "@preact/signals";
+import { addIntoArray, removeFromArray } from "./array_add_remove.js";
+
+export const arraySignal = (initialValue = []) => {
+  const theSignal = signal(initialValue);
+
+  const add = (...args) => {
+    theSignal.value = addIntoArray(theSignal.peek(), ...args);
+  };
+  const remove = (...args) => {
+    theSignal.value = removeFromArray(theSignal.peek(), ...args);
+  };
+
+  return [theSignal, add, remove];
+};

package/src/utils/compare_two_js_values.js

@@ -0,0 +1,172 @@
+/**
+ * Deep equality comparison for JavaScript values with cycle detection and identity optimization.
+ *
+ * This function performs a comprehensive deep comparison between two JavaScript values,
+ * handling all primitive types, objects, arrays, and edge cases that standard equality
+ * operators miss.
+ *
+ * Key features:
+ * - **Deep comparison**: Recursively compares nested objects and arrays
+ * - **Cycle detection**: Prevents infinite loops with circular references
+ * - **Identity optimization**: Uses SYMBOL_IDENTITY for fast comparison of objects with same identity
+ * - **Edge case handling**: Properly handles NaN, null, undefined, 0, false comparisons
+ * - **Type safety**: Ensures both values have same type before deep comparison
+ *
+ * Performance optimizations:
+ * - Early exit for reference equality (a === b)
+ * - Identity symbol check for objects (avoids deep comparison when possible)
+ * - Efficient array length check before element-by-element comparison
+ *
+ * **SYMBOL_IDENTITY explained**:
+ * This symbol allows recognizing objects as "conceptually the same" even when they are
+ * different object instances. When two objects share the same SYMBOL_IDENTITY value,
+ * they are considered equal without performing deep comparison.
+ *
+ * This is particularly useful for:
+ * - Copied objects that should be treated as the same entity
+ * - Objects reconstructed from serialization that represent the same data
+ * - Parameters passed through spread operator: `{ ...originalParams, newProp: value }`
+ * - Memoization scenarios where object content identity matters more than reference identity
+ *
+ * Use cases:
+ * - Memoization cache key comparison ({ id: 1 } should equal { id: 1 })
+ * - React/Preact dependency comparison for effects and memos
+ * - State change detection in signals and stores
+ * - Action parameter comparison for avoiding duplicate requests
+ * - Object recognition across serialization/deserialization boundaries
+ *
+ * Examples:
+ * ```js
+ * // Standard deep comparison
+ * compareTwoJsValues({ id: 1 }, { id: 1 }) // true (slow - deep comparison)
+ *
+ * // NaN edge case handling
+ * compareTwoJsValues(NaN, NaN) // true (unlike === which gives false)
+ *
+ * // Identity optimization - objects are different instances but same identity
+ * const originalParams = { userId: 123, filters: ['active'] };
+ * const copiedParams = { ...originalParams, newFlag: true };
+ *
+ * // Without SYMBOL_IDENTITY: slow deep comparison every time
+ * compareTwoJsValues(originalParams, copiedParams) // false (different content)
+ *
+ * // With SYMBOL_IDENTITY: fast path recognition
+ * const sharedIdentity = Symbol('params-identity');
+ * originalParams[SYMBOL_IDENTITY] = sharedIdentity;
+ * copiedParams[SYMBOL_IDENTITY] = sharedIdentity;
+ *
+ * compareTwoJsValues(originalParams, copiedParams) // true (fast - identity match)
+ * // ↑ This returns true immediately without comparing all properties
+ *
+ * // Real-world scenario: action memoization
+ * const params1 = { userId: 123 };
+ * const action1 = createAction(params1);
+ *
+ * const params2 = { ...params1, extra: 'data' }; // Different object reference
+ * params2[SYMBOL_IDENTITY] = params1[SYMBOL_IDENTITY]; // Same conceptual identity
+ *
+ * const action2 = createAction(params2);
+ * // action1 === action2 because params are recognized as conceptually identical
+ * ```
+ *
+ * @param {any} a - First value to compare
+ * @param {any} b - Second value to compare
+ * @param {Set} seenSet - Internal cycle detection set (automatically managed)
+ * @returns {boolean} true if values are deeply equal, false otherwise
+ */
+
+/**
+ * Symbol used to mark objects with a conceptual identity that transcends reference equality.
+ *
+ * When two different object instances share the same SYMBOL_IDENTITY value, they are
+ * considered equal by compareTwoJsValues without performing expensive deep comparison.
+ *
+ * This enables recognition of "the same logical object" even when:
+ * - The object has been copied via spread operator: `{ ...obj, newProp }`
+ * - The object has been reconstructed from serialization
+ * - The object is a different instance but represents the same conceptual entity
+ *
+ * Use Symbol.for() to ensure the same symbol across different modules/contexts.
+ */
+export const SYMBOL_IDENTITY = Symbol.for("navi_object_identity");
+
+export const compareTwoJsValues = (a, b, seenSet = new Set()) => {
+  if (a === b) {
+    return true;
+  }
+  const aIsIsTruthy = Boolean(a);
+  const bIsTruthy = Boolean(b);
+  if (aIsIsTruthy && !bIsTruthy) {
+    return false;
+  }
+  if (!aIsIsTruthy && !bIsTruthy) {
+    // null, undefined, 0, false, NaN
+    if (isNaN(a) && isNaN(b)) {
+      return true;
+    }
+    return a === b;
+  }
+  const aType = typeof a;
+  const bType = typeof b;
+  if (aType !== bType) {
+    return false;
+  }
+  const aIsPrimitive =
+    a === null || (aType !== "object" && aType !== "function");
+  const bIsPrimitive =
+    b === null || (bType !== "object" && bType !== "function");
+  if (aIsPrimitive !== bIsPrimitive) {
+    return false;
+  }
+  if (aIsPrimitive && bIsPrimitive) {
+    return a === b;
+  }
+  if (seenSet.has(a)) {
+    return false;
+  }
+  if (seenSet.has(b)) {
+    return false;
+  }
+  seenSet.add(a);
+  seenSet.add(b);
+  const aIsArray = Array.isArray(a);
+  const bIsArray = Array.isArray(b);
+  if (aIsArray !== bIsArray) {
+    return false;
+  }
+  if (aIsArray) {
+    // compare arrays
+    if (a.length !== b.length) {
+      return false;
+    }
+    let i = 0;
+    while (i < a.length) {
+      const aValue = a[i];
+      const bValue = b[i];
+      if (!compareTwoJsValues(aValue, bValue, seenSet)) {
+        return false;
+      }
+      i++;
+    }
+    return true;
+  }
+  // compare objects
+  const aIdentity = a[SYMBOL_IDENTITY];
+  const bIdentity = b[SYMBOL_IDENTITY];
+  if (aIdentity === bIdentity && SYMBOL_IDENTITY in a && SYMBOL_IDENTITY in b) {
+    return true;
+  }
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) {
+    return false;
+  }
+  for (const key of aKeys) {
+    const aValue = a[key];
+    const bValue = b[key];
+    if (!compareTwoJsValues(aValue, bValue, seenSet)) {
+      return false;
+    }
+  }
+  return true;
+};

package/src/utils/execute_with_cleanup.js

@@ -0,0 +1,21 @@
+export const executeWithCleanup = (fn, cleanup) => {
+  let isThenable;
+  try {
+    const result = fn();
+    isThenable = result && typeof result.then === "function";
+    if (isThenable) {
+      return (async () => {
+        try {
+          return await result;
+        } finally {
+          cleanup();
+        }
+      })();
+    }
+    return result;
+  } finally {
+    if (!isThenable) {
+      cleanup();
+    }
+  }
+};