@jskit-ai/users-web 0.1.105 → 0.1.106

package/package.descriptor.mjs

@@ -3,7 +3,7 @@ import { HOME_COG_OUTLET } from "./src/shared/toolsOutletContracts.js";
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/users-web",
-  version: "0.1.105",
+  version: "0.1.106",
   kind: "runtime",
   description: "Users web module: account/profile UI plus shared users web widgets.",
   dependsOn: [
@@ -278,12 +278,12 @@ export default Object.freeze({
     dependencies: {
       runtime: {
         "@mdi/js": "^7.4.47",
-        "@jskit-ai/http-runtime": "0.1.89",
-        "@jskit-ai/realtime": "0.1.89",
-        "@jskit-ai/kernel": "0.1.90",
-        "@jskit-ai/shell-web": "0.1.89",
-        "@jskit-ai/uploads-image-web": "0.1.68",
-        "@jskit-ai/users-core": "0.1.100"
+        "@jskit-ai/http-runtime": "0.1.90",
+        "@jskit-ai/realtime": "0.1.90",
+        "@jskit-ai/kernel": "0.1.91",
+        "@jskit-ai/shell-web": "0.1.90",
+        "@jskit-ai/uploads-image-web": "0.1.69",
+        "@jskit-ai/users-core": "0.1.101"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/users-web",
-  "version": "0.1.105",
+  "version": "0.1.106",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -44,12 +44,12 @@
   },
   "dependencies": {
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/http-runtime": "0.1.89",
-    "@jskit-ai/kernel": "0.1.90",
-    "@jskit-ai/realtime": "0.1.89",
-    "@jskit-ai/shell-web": "0.1.89",
-    "@jskit-ai/uploads-image-web": "0.1.68",
-    "@jskit-ai/users-core": "0.1.100"
+    "@jskit-ai/http-runtime": "0.1.90",
+    "@jskit-ai/kernel": "0.1.91",
+    "@jskit-ai/realtime": "0.1.90",
+    "@jskit-ai/shell-web": "0.1.90",
+    "@jskit-ai/uploads-image-web": "0.1.69",
+    "@jskit-ai/users-core": "0.1.101"
   },
   "peerDependencies": {
     "@tanstack/vue-query": "^5.90.5",

package/src/client/composables/records/useAddEdit.js

@@ -30,6 +30,8 @@ function useAddEdit({
   readEnabled = true,
   writeMethod = "PATCH",
   transport = null,
+  requestRecovery = null,
+  requestRecoveryLabel = "Resource",
   placementSource = "users-web.add-edit",
   fallbackLoadError = "Unable to load resource.",
   fallbackSaveError = "Unable to save resource.",
@@ -121,6 +123,8 @@ function useAddEdit({
     writeMethod,
     readQuery: requestQueryRuntime.requestQuery,
     transport,
+    requestRecovery,
+    requestRecoveryLabel,
     fallbackLoadError,
     fallbackSaveError: String(fallbackSaveError || effectiveMessages.saveError || "Unable to save resource.")
   });

package/src/client/composables/records/useList.js

@@ -46,6 +46,8 @@ function useList({
   transport = null,
   requestOptions,
   queryOptions,
+  requestRecovery,
+  requestRecoveryLabel = "List",
   realtime = null,
   adapter = null,
   recordIdParam = "recordId",
@@ -228,6 +230,8 @@ function useList({
     selectItems,
     requestOptions: listRequestOptions,
     queryOptions,
+    requestRecovery,
+    requestRecoveryLabel,
     fallbackLoadError
   });
   const routeSyncHydrated = ref(routeSyncConfig.enabled !== true);

package/src/client/composables/records/useView.js

@@ -21,6 +21,8 @@ function useView({
   readMethod = "GET",
   readEnabled = true,
   transport = null,
+  requestRecovery = null,
+  requestRecoveryLabel = "Resource",
   placementSource = "users-web.view",
   fallbackLoadError = "Unable to load resource.",
   notFoundStatuses = [404],
@@ -104,6 +106,8 @@ function useView({
     readMethod,
     readQuery: requestQueryRuntime.requestQuery,
     transport,
+    requestRecovery,
+    requestRecoveryLabel,
     refreshOnPull: true,
     fallbackLoadError
   });

package/src/client/composables/runtime/useEndpointResource.js

@@ -7,7 +7,8 @@ import { toQueryErrorMessage } from "../support/errorMessageHelpers.js";
 import { useOperationRealtime } from "../useRealtimeQueryInvalidation.js";
 import {
   hasResolvedQueryData,
-  mergeQueryMeta
+  mergeQueryMeta,
+  mergeRequestRecoveryQueryMeta
 } from "../support/resourceLoadStateHelpers.js";
 
 function buildEndpointReadRequestOptions({
@@ -75,6 +76,8 @@ function useEndpointResource({
   realtime = null,
   queryOptions = null,
   mutationOptions = null,
+  requestRecovery = null,
+  requestRecoveryLabel = "Request",
   fallbackLoadError = "Unable to load resource.",
   fallbackSaveError = "Unable to save resource."
 } = {}) {
@@ -102,13 +105,20 @@ function useEndpointResource({
       });
     },
     enabled: queryEnabled,
-    ...(refreshOnPull
-      ? mergeQueryMeta(asPlainObject(queryOptions), {
-        jskit: {
-          refreshOnPull: true
-        }
-      })
-      : asPlainObject(queryOptions))
+    ...mergeRequestRecoveryQueryMeta(
+      refreshOnPull
+        ? mergeQueryMeta(asPlainObject(queryOptions), {
+          jskit: {
+            refreshOnPull: true
+          }
+        })
+        : asPlainObject(queryOptions),
+      requestRecovery,
+      {
+        label: requestRecoveryLabel,
+        method: readMethod
+      }
+    )
   });
   const realtimeBinding = useOperationRealtime({
     realtime,

package/src/client/composables/runtime/useListCore.js

@@ -3,6 +3,7 @@ import { usersWebHttpClient } from "../../lib/httpClient.js";
 import { asPlainObject } from "../support/scopeHelpers.js";
 import { resolveEnabledRef, resolveTextRef } from "../support/refValueHelpers.js";
 import { usePagedCollection } from "../usePagedCollection.js";
+import { mergeRequestRecoveryQueryMeta } from "../support/resourceLoadStateHelpers.js";
 
 const DEFAULT_LIST_LIMIT = 20;
 
@@ -47,6 +48,10 @@ function resolveRequestOptionsObject(value = null) {
   return asPlainObject(source);
 }
 
+function resolveListRequestMethod(requestOptions = null) {
+  return String(resolveRequestOptionsObject(requestOptions).method || "GET").toUpperCase();
+}
+
 function useListCore({
   queryKey,
   path = "",
@@ -58,6 +63,8 @@ function useListCore({
   selectItems,
   requestOptions = null,
   queryOptions = null,
+  requestRecovery = null,
+  requestRecoveryLabel = "List",
   fallbackLoadError = "Unable to load list."
 } = {}) {
   if (!client || typeof client.request !== "function") {
@@ -88,7 +95,10 @@ function useListCore({
     },
     getNextPageParam,
     selectItems,
-    queryOptions,
+    queryOptions: mergeRequestRecoveryQueryMeta(queryOptions, requestRecovery, {
+      label: requestRecoveryLabel,
+      method: resolveListRequestMethod(requestOptions)
+    }),
     fallbackLoadError
   });
 

package/src/client/composables/support/resourceLoadStateHelpers.js

@@ -36,7 +36,194 @@ function mergeQueryMeta(queryOptions = null, meta = {}) {
   };
 }
 
+function normalizeText(value = "") {
+  return String(value || "").trim();
+}
+
+function firstNormalizedText(...values) {
+  for (const value of values) {
+    const normalized = normalizeText(value);
+    if (normalized) {
+      return normalized;
+    }
+  }
+  return "";
+}
+
+function firstNonNegativeFiniteNumber(...values) {
+  for (const value of values) {
+    const numberValue = Number(value);
+    if (Number.isFinite(numberValue)) {
+      return Math.max(0, numberValue);
+    }
+  }
+  return null;
+}
+
+function normalizePlainObject(value = null) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function normalizeRequestRecoveryInput(requestRecovery = null) {
+  if (typeof requestRecovery === "string") {
+    return {
+      label: requestRecovery
+    };
+  }
+  return normalizePlainObject(requestRecovery);
+}
+
+function normalizeRequestRecoveryMethod(value = "") {
+  return normalizeText(value).toUpperCase();
+}
+
+function isRequestRecoveryMetaDisabled(sourceJskitMeta = {}, sourceMeta = {}) {
+  return Boolean(
+    sourceJskitMeta.requestRecovery === false ||
+      sourceMeta.jskitRequestRecovery === false ||
+      sourceMeta.requestRecovery === false
+  );
+}
+
+function hasUsableMetaValue(source = {}, key = "") {
+  return Object.hasOwn(source, key) && source[key] !== undefined && source[key] !== null && source[key] !== "";
+}
+
+function buildRequestRecoveryMeta(requestRecovery = null, defaults = {}) {
+  if (requestRecovery === false) {
+    return {
+      jskit: {
+        requestRecovery: false
+      }
+    };
+  }
+
+  const fallback = normalizePlainObject(defaults);
+  const source = normalizeRequestRecoveryInput(requestRecovery);
+  if (source.requestRecovery === false || source.enabled === false) {
+    return {
+      jskit: {
+        requestRecovery: false
+      }
+    };
+  }
+
+  const label = firstNormalizedText(
+    source.requestRecoveryLabel,
+    source.label,
+    fallback.requestRecoveryLabel,
+    fallback.label
+  );
+  const recoverySource = firstNormalizedText(
+    source.requestRecoverySource,
+    source.source,
+    fallback.requestRecoverySource,
+    fallback.source
+  );
+  const dedupeKey = firstNormalizedText(
+    source.requestRecoveryDedupeKey,
+    source.dedupeKey,
+    fallback.requestRecoveryDedupeKey,
+    fallback.dedupeKey
+  );
+  const method = normalizeRequestRecoveryMethod(
+    firstNormalizedText(
+      source.requestRecoveryMethod,
+      source.method,
+      fallback.requestRecoveryMethod,
+      fallback.method
+    )
+  );
+  const dedupeWindowMs = firstNonNegativeFiniteNumber(
+    source.requestRecoveryDedupeWindowMs,
+    source.dedupeWindowMs,
+    fallback.requestRecoveryDedupeWindowMs,
+    fallback.dedupeWindowMs
+  );
+
+  const jskit = {};
+  if (label) {
+    jskit.requestRecoveryLabel = label;
+  }
+  if (recoverySource) {
+    jskit.requestRecoverySource = recoverySource;
+  }
+  if (dedupeKey) {
+    jskit.requestRecoveryDedupeKey = dedupeKey;
+  }
+  if (method) {
+    jskit.requestRecoveryMethod = method;
+  }
+  if (dedupeWindowMs !== null) {
+    jskit.requestRecoveryDedupeWindowMs = dedupeWindowMs;
+  }
+
+  return Object.keys(jskit).length > 0 ? { jskit } : {};
+}
+
+function hasRequestRecoveryMetaValue(sourceJskitMeta = {}, sourceMeta = {}, key = "") {
+  const suffix = String(key || "").trim();
+  if (!suffix) {
+    return false;
+  }
+
+  const jskitKey = `requestRecovery${suffix}`;
+  const legacyJskitKey = `jskitRequestRecovery${suffix}`;
+  const legacyKey = `requestRecovery${suffix}`;
+
+  return Boolean(
+    hasUsableMetaValue(sourceJskitMeta, jskitKey) ||
+      hasUsableMetaValue(sourceMeta, legacyJskitKey) ||
+      hasUsableMetaValue(sourceMeta, legacyKey)
+  );
+}
+
+function resolveRequestRecoveryDefaults(queryOptions = null, defaults = {}) {
+  const sourceOptions = normalizePlainObject(queryOptions);
+  const sourceMeta = normalizePlainObject(sourceOptions.meta);
+  const sourceJskitMeta = normalizePlainObject(sourceMeta.jskit);
+  const fallback = normalizePlainObject(defaults);
+  if (isRequestRecoveryMetaDisabled(sourceJskitMeta, sourceMeta)) {
+    return {};
+  }
+
+  const hasExplicitLabel = hasRequestRecoveryMetaValue(sourceJskitMeta, sourceMeta, "Label");
+  const hasExplicitSource = hasRequestRecoveryMetaValue(sourceJskitMeta, sourceMeta, "Source");
+  const hasExplicitDedupeKey = hasRequestRecoveryMetaValue(sourceJskitMeta, sourceMeta, "DedupeKey");
+  const hasExplicitDedupeWindowMs = hasRequestRecoveryMetaValue(sourceJskitMeta, sourceMeta, "DedupeWindowMs");
+  const hasExplicitMethod = hasRequestRecoveryMetaValue(sourceJskitMeta, sourceMeta, "Method");
+
+  return {
+    ...fallback,
+    requestRecoveryLabel: hasExplicitLabel ? "" : fallback.requestRecoveryLabel,
+    label: hasExplicitLabel ? "" : fallback.label,
+    requestRecoverySource: hasExplicitSource ? "" : fallback.requestRecoverySource,
+    source: hasExplicitSource ? "" : fallback.source,
+    requestRecoveryDedupeKey: hasExplicitDedupeKey ? "" : fallback.requestRecoveryDedupeKey,
+    dedupeKey: hasExplicitDedupeKey ? "" : fallback.dedupeKey,
+    requestRecoveryDedupeWindowMs: hasExplicitDedupeWindowMs ? "" : fallback.requestRecoveryDedupeWindowMs,
+    dedupeWindowMs: hasExplicitDedupeWindowMs ? "" : fallback.dedupeWindowMs,
+    requestRecoveryMethod: hasExplicitMethod ? "" : fallback.requestRecoveryMethod,
+    method: hasExplicitMethod ? "" : fallback.method
+  };
+}
+
+function mergeRequestRecoveryQueryMeta(queryOptions = null, requestRecovery = null, defaults = {}) {
+  const sourceOptions = normalizePlainObject(queryOptions);
+  const effectiveDefaults =
+    requestRecovery == null
+      ? resolveRequestRecoveryDefaults(sourceOptions, defaults)
+      : normalizePlainObject(defaults);
+  const meta = buildRequestRecoveryMeta(requestRecovery, effectiveDefaults);
+  if (Object.keys(meta).length < 1) {
+    return sourceOptions;
+  }
+  return mergeQueryMeta(sourceOptions, meta);
+}
+
 export {
+  buildRequestRecoveryMeta,
   hasResolvedQueryData,
-  mergeQueryMeta
+  mergeQueryMeta,
+  mergeRequestRecoveryQueryMeta
 };

package/src/client/composables/useCrudListScreen.js

@@ -31,6 +31,7 @@ function useCrudListScreen({
   listFilters = {},
   listBulkActions = [],
   routeQueryBlacklist = Object.freeze(["include", "cursor", "limit"]),
+  requestRecoveryLabel = "Records",
   fallbackLoadError = "Unable to load records."
 } = {}) {
   const filterRuntime = useCrudListFilters(listFilters);
@@ -62,6 +63,7 @@ function useCrudListScreen({
       queryParamBlacklist: routeQueryBlacklist
     },
     placementSource: `ui-generator.${normalizedResourceNamespace}.list`,
+    requestRecoveryLabel,
     fallbackLoadError,
     recordIdParam,
     recordIdSelector,

package/src/client/composables/useCrudViewScreen.js

@@ -12,6 +12,7 @@ function useCrudViewScreen({
   listUrlTemplate = "",
   editUrlTemplate = "",
   recordChangedEvent = "",
+  requestRecoveryLabel = "Record",
   fallbackLoadError = "Unable to load record.",
   notFoundMessage = "Record not found."
 } = {}) {
@@ -31,6 +32,7 @@ function useCrudViewScreen({
       String(workspaceSlug || "")
     ],
     placementSource: `ui-generator.${normalizedResourceNamespace}.view`,
+    requestRecoveryLabel,
     fallbackLoadError,
     notFoundMessage,
     listUrlTemplate,

package/test/requestTransportOptions.test.js

@@ -249,3 +249,41 @@ test("endpoint resources invalidate their query key from configured realtime eve
     }
   ]);
 });
+
+test("endpoint resource reads attach request recovery metadata to query options", async () => {
+  const queryClient = new QueryClient();
+  const queryKey = ["project-access", "beepollen"];
+  const app = createSSRApp({
+    setup() {
+      useEndpointResource({
+        queryKey,
+        path: "/api/project-access",
+        client: {
+          async request() {
+            return {};
+          }
+        },
+        requestRecovery: {
+          label: "Project access",
+          source: "project-access.panel",
+          dedupeKey: "project-access"
+        }
+      });
+      return () => h("div");
+    }
+  });
+  app.use(VueQueryPlugin, {
+    queryClient
+  });
+  await renderToString(app);
+
+  const query = queryClient.getQueryCache().find({
+    queryKey
+  });
+  assert.deepEqual(query?.meta?.jskit, {
+    requestRecoveryLabel: "Project access",
+    requestRecoverySource: "project-access.panel",
+    requestRecoveryDedupeKey: "project-access",
+    requestRecoveryMethod: "GET"
+  });
+});

package/test/resourceLoadStateHelpers.test.js

@@ -2,8 +2,10 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import { ref } from "vue";
 import {
+  buildRequestRecoveryMeta,
   hasResolvedQueryData,
-  mergeQueryMeta
+  mergeQueryMeta,
+  mergeRequestRecoveryQueryMeta
 } from "../src/client/composables/support/resourceLoadStateHelpers.js";
 
 test("hasResolvedQueryData returns true when the query succeeded", () => {
@@ -71,3 +73,117 @@ test("mergeQueryMeta preserves caller metadata while adding JSKIT refresh policy
     }
   );
 });
+
+test("request recovery query metadata supports labels and disabling recovery", () => {
+  assert.deepEqual(
+    buildRequestRecoveryMeta("Project access"),
+    {
+      jskit: {
+        requestRecoveryLabel: "Project access"
+      }
+    }
+  );
+
+  assert.deepEqual(
+    buildRequestRecoveryMeta(false),
+    {
+      jskit: {
+        requestRecovery: false
+      }
+    }
+  );
+});
+
+test("mergeRequestRecoveryQueryMeta preserves caller metadata while adding recovery hints", () => {
+  assert.deepEqual(
+    mergeRequestRecoveryQueryMeta(
+      {
+        staleTime: 5000,
+        meta: {
+          owner: "project-access",
+          jskit: {
+            refreshOnPull: true
+          }
+        }
+      },
+      {
+        label: "Project access",
+        source: "app.project-access",
+        dedupeKey: "project-access",
+        method: "get",
+        dedupeWindowMs: 100
+      }
+    ),
+    {
+      staleTime: 5000,
+      meta: {
+        owner: "project-access",
+        jskit: {
+          refreshOnPull: true,
+          requestRecoveryLabel: "Project access",
+          requestRecoverySource: "app.project-access",
+          requestRecoveryDedupeKey: "project-access",
+          requestRecoveryMethod: "GET",
+          requestRecoveryDedupeWindowMs: 100
+        }
+      }
+    }
+  );
+});
+
+test("mergeRequestRecoveryQueryMeta does not overwrite explicit query recovery labels with defaults", () => {
+  assert.deepEqual(
+    mergeRequestRecoveryQueryMeta(
+      {
+        meta: {
+          jskit: {
+            requestRecoveryLabel: "Explicit label",
+            requestRecoveryMethod: "HEAD",
+            requestRecoveryDedupeWindowMs: 0
+          }
+        }
+      },
+      null,
+      {
+        label: "Default label",
+        method: "GET",
+        dedupeWindowMs: 5000
+      }
+    ),
+    {
+      meta: {
+        jskit: {
+          requestRecoveryLabel: "Explicit label",
+          requestRecoveryMethod: "HEAD",
+          requestRecoveryDedupeWindowMs: 0
+        }
+      }
+    }
+  );
+});
+
+test("mergeRequestRecoveryQueryMeta preserves disabled recovery metadata", () => {
+  assert.deepEqual(
+    mergeRequestRecoveryQueryMeta(
+      {
+        meta: {
+          jskit: {
+            requestRecovery: false
+          }
+        }
+      },
+      null,
+      {
+        label: "Default label",
+        method: "GET"
+      }
+    ),
+    {
+      meta: {
+        jskit: {
+          requestRecovery: false
+        }
+      }
+    }
+  );
+});