@jskit-ai/http-web 0.1.1

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

@@ -0,0 +1,123 @@
+import { useQueryClient } from "@tanstack/vue-query";
+import { resolveFieldErrors } from "@jskit-ai/http-runtime/client";
+import { validateOperationInput } from "./operationValidationHelpers.js";
+
+function useCommandCore({
+  model,
+  resource,
+  writeMethod = "POST",
+  canRun,
+  fieldBag,
+  feedback,
+  input,
+  buildRawPayload,
+  buildCommandPayload,
+  buildCommandOptions,
+  onRunSuccess,
+  onRunError,
+  suppressSuccessMessage = false,
+  messages = {}
+} = {}) {
+  const queryClient = useQueryClient();
+  const normalizedWriteMethod = String(writeMethod || "POST").trim().toUpperCase();
+
+  const running = resource?.isSaving;
+  const fieldErrors = fieldBag?.errors;
+  const message = feedback?.message;
+  const messageType = feedback?.messageType;
+
+  async function run(context = {}) {
+    if (!canRun?.value || running?.value) {
+      return null;
+    }
+
+    feedback?.clear?.();
+    fieldBag?.clear?.();
+
+    const rawPayload = typeof buildRawPayload === "function"
+      ? buildRawPayload(model, {
+          queryClient,
+          resource,
+          context
+        })
+      : {};
+
+    const validationResult = validateOperationInput({
+      input,
+      rawPayload,
+      fieldBag,
+      feedback,
+      validationMessage: String(messages.validation || "Validation failed.")
+    });
+    if (!validationResult.ok) {
+      return null;
+    }
+
+    const { parsedInput } = validationResult;
+    const payload = typeof buildCommandPayload === "function"
+      ? buildCommandPayload(parsedInput, {
+          rawPayload,
+          queryClient,
+          resource,
+          context
+        })
+      : (normalizedWriteMethod === "DELETE" ? undefined : parsedInput);
+
+    const options = typeof buildCommandOptions === "function"
+      ? buildCommandOptions(parsedInput, {
+          rawPayload,
+          queryClient,
+          resource,
+          context
+        })
+      : {};
+
+    try {
+      const response = await resource.save(payload, options);
+
+      if (typeof onRunSuccess === "function") {
+        await onRunSuccess(response, {
+          parsed: parsedInput,
+          rawPayload,
+          payload,
+          options,
+          queryClient,
+          resource,
+          context
+        });
+      }
+
+      if (!suppressSuccessMessage) {
+        feedback?.success?.(String(messages.success || "Completed."));
+      }
+      return response;
+    } catch (error) {
+      fieldBag?.apply?.(resolveFieldErrors(error));
+
+      if (typeof onRunError === "function") {
+        await onRunError(error, {
+          parsed: parsedInput,
+          rawPayload,
+          payload,
+          options,
+          queryClient,
+          resource,
+          context
+        });
+      }
+
+      feedback?.error?.(error, String(messages.error || "Unable to complete action."));
+      throw error;
+    }
+  }
+
+  return Object.freeze({
+    running,
+    fieldErrors,
+    message,
+    messageType,
+    run
+  });
+}
+
+export { useCommandCore };

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

@@ -0,0 +1,199 @@
+import { computed, unref } from "vue";
+import { useMutation, useQuery } from "@tanstack/vue-query";
+import { getHttpWebClient } from "../../lib/httpClient.js";
+import { asPlainObject } from "../support/scopeHelpers.js";
+import { resolveEnabledRef, resolveTextRef } from "../support/refValueHelpers.js";
+import { toQueryErrorMessage } from "../support/errorMessageHelpers.js";
+import { useOperationRealtime } from "../useRealtimeQueryInvalidation.js";
+import {
+  hasResolvedQueryData,
+  mergeQueryMeta,
+  mergeRequestRecoveryQueryMeta
+} from "../support/resourceLoadStateHelpers.js";
+
+function buildEndpointReadRequestOptions({
+  method = "GET",
+  query = null,
+  transport = null
+} = {}) {
+  const requestOptions = {
+    method: String(method || "GET").toUpperCase()
+  };
+
+  const normalizedQuery = resolveRequestQuery(query);
+  if (normalizedQuery) {
+    requestOptions.query = normalizedQuery;
+  }
+
+  if (transport && typeof transport === "object") {
+    requestOptions.transport = transport;
+  }
+
+  return requestOptions;
+}
+
+function resolveRequestQuery(value = null) {
+  const source = unref(value);
+  if (!source || typeof source !== "object" || Array.isArray(source)) {
+    return null;
+  }
+
+  return source;
+}
+
+function buildEndpointWriteRequestOptions({
+  method = "PATCH",
+  body = undefined,
+  options = null,
+  transport = null
+} = {}) {
+  const requestOptions = {
+    method: String(method || "PATCH").toUpperCase(),
+    ...(asPlainObject(options))
+  };
+
+  if (body !== undefined) {
+    requestOptions.body = body;
+  }
+
+  if (transport && typeof transport === "object") {
+    requestOptions.transport = transport;
+  }
+
+  return requestOptions;
+}
+
+function useEndpointResource({
+  queryKey,
+  path = "",
+  enabled = true,
+  client = null,
+  readMethod = "GET",
+  writeMethod = "PATCH",
+  readQuery = null,
+  transport = null,
+  refreshOnPull = false,
+  realtime = null,
+  queryOptions = null,
+  mutationOptions = null,
+  requestRecovery = null,
+  requestRecoveryLabel = "Request",
+  fallbackLoadError = "Unable to load resource.",
+  fallbackSaveError = "Unable to save resource."
+} = {}) {
+  const activeClient = client || getHttpWebClient();
+  if (!activeClient || typeof activeClient.request !== "function") {
+    throw new TypeError("useEndpointResource requires a client with request().");
+  }
+
+  const normalizedPath = computed(() => resolveTextRef(path));
+  const queryEnabled = computed(() => resolveEnabledRef(enabled) && Boolean(normalizedPath.value));
+
+  const query = useQuery({
+    queryKey,
+    queryFn: () => {
+      const requestPath = normalizedPath.value;
+      if (!requestPath) {
+        throw new Error("Resource path is required.");
+      }
+
+      return activeClient.request(requestPath, {
+        ...buildEndpointReadRequestOptions({
+          method: readMethod,
+          query: readQuery,
+          transport
+        })
+      });
+    },
+    enabled: queryEnabled,
+    ...mergeRequestRecoveryQueryMeta(
+      refreshOnPull
+        ? mergeQueryMeta(asPlainObject(queryOptions), {
+          jskit: {
+            refreshOnPull: true
+          }
+        })
+        : asPlainObject(queryOptions),
+      requestRecovery,
+      {
+        label: requestRecoveryLabel,
+        method: readMethod
+      }
+    )
+  });
+  const realtimeBinding = useOperationRealtime({
+    realtime,
+    queryKey,
+    enabled: queryEnabled
+  });
+
+  const mutation = useMutation({
+    mutationFn: async (request = {}) => {
+      const options = asPlainObject(request);
+      const requestPath = resolveTextRef(options.path || normalizedPath.value);
+      if (!requestPath) {
+        throw new Error("Resource path is required.");
+      }
+
+      const method = String(options.method || writeMethod || "PATCH").toUpperCase();
+      const hasBody = Object.hasOwn(options, "body");
+      const body = hasBody ? options.body : options.payload;
+      return activeClient.request(
+        requestPath,
+        buildEndpointWriteRequestOptions({
+          method,
+          body,
+          options: options.options,
+          transport
+        })
+      );
+    },
+    ...(asPlainObject(mutationOptions))
+  });
+
+  const data = computed(() => query.data.value);
+  const hasResolvedData = computed(() => hasResolvedQueryData({
+    query,
+    data
+  }));
+  const isInitialLoading = computed(() => Boolean(queryEnabled.value && query.isPending.value && !hasResolvedData.value));
+  const isFetching = computed(() => Boolean(queryEnabled.value && query.isFetching.value));
+  const isRefetching = computed(() => Boolean(isFetching.value && !isInitialLoading.value));
+  const isLoading = computed(() => Boolean(isInitialLoading.value || isFetching.value));
+  const isSaving = computed(() => Boolean(mutation.isPending.value));
+  const loadError = computed(() => toQueryErrorMessage(query.error.value, fallbackLoadError, "Request failed."));
+  const saveError = computed(() => toQueryErrorMessage(mutation.error.value, fallbackSaveError, "Request failed."));
+
+  async function reload() {
+    return query.refetch();
+  }
+
+  async function save(payload, options = {}) {
+    return mutation.mutateAsync({
+      ...asPlainObject(options),
+      payload
+    });
+  }
+
+  return Object.freeze({
+    query,
+    mutation,
+    data,
+    isInitialLoading,
+    isFetching,
+    isRefetching,
+    isLoading,
+    isSaving,
+    loadError,
+    saveError,
+    realtime: realtimeBinding,
+    reload,
+    save
+  });
+}
+
+export {
+  buildEndpointReadRequestOptions,
+  buildEndpointWriteRequestOptions,
+  useEndpointResource
+};

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

@@ -0,0 +1,61 @@
+import { reactive } from "vue";
+
+function normalizeKeys(keys) {
+  return Array.isArray(keys)
+    ? keys.map((entry) => String(entry || "").trim()).filter(Boolean)
+    : [];
+}
+
+function useFieldErrorBag(keys = []) {
+  const normalizedKeys = normalizeKeys(keys);
+  const hasFixedKeys = normalizedKeys.length > 0;
+  const errors = reactive(
+    Object.fromEntries(normalizedKeys.map((key) => [key, ""]))
+  );
+
+  function clear() {
+    const keysToClear = hasFixedKeys ? normalizedKeys : Object.keys(errors);
+    for (const key of keysToClear) {
+      errors[key] = "";
+    }
+  }
+
+  function apply(source = {}) {
+    const fieldErrorMap = source && typeof source === "object" ? source : {};
+    if (hasFixedKeys) {
+      for (const key of normalizedKeys) {
+        errors[key] = String(fieldErrorMap[key] || "");
+      }
+      return;
+    }
+
+    clear();
+    for (const [field, message] of Object.entries(fieldErrorMap)) {
+      const key = String(field || "").trim();
+      if (!key) {
+        continue;
+      }
+      errors[key] = String(message || "");
+    }
+  }
+
+  function set(field, message) {
+    const key = String(field || "").trim();
+    if (!key) {
+      return;
+    }
+    if (hasFixedKeys && !(key in errors)) {
+      return;
+    }
+    errors[key] = String(message || "");
+  }
+
+  return Object.freeze({
+    errors,
+    clear,
+    apply,
+    set
+  });
+}
+
+export { useFieldErrorBag };

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

@@ -0,0 +1,112 @@
+import { computed, unref } from "vue";
+import { getHttpWebClient } 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;
+
+function buildListRequestOptions({
+  requestOptions = null,
+  transport = null,
+  pageParam = null
+} = {}) {
+  const resolvedOptions = {
+    method: "GET",
+    ...(resolveRequestOptionsObject(requestOptions))
+  };
+
+  const sourceQuery =
+    resolvedOptions.query && typeof resolvedOptions.query === "object" && !Array.isArray(resolvedOptions.query)
+      ? { ...resolvedOptions.query }
+      : {};
+  if (
+    !Object.hasOwn(sourceQuery, "limit") &&
+    !Object.hasOwn(sourceQuery, "page[limit]")
+  ) {
+    sourceQuery.limit = DEFAULT_LIST_LIMIT;
+  }
+  if (pageParam !== null && pageParam !== undefined && pageParam !== "") {
+    sourceQuery.cursor = String(pageParam);
+  }
+  if (Object.keys(sourceQuery).length > 0) {
+    resolvedOptions.query = sourceQuery;
+  } else {
+    delete resolvedOptions.query;
+  }
+
+  if (transport && typeof transport === "object") {
+    resolvedOptions.transport = transport;
+  }
+
+  return resolvedOptions;
+}
+
+function resolveRequestOptionsObject(value = null) {
+  const source = unref(value);
+  return asPlainObject(source);
+}
+
+function resolveListRequestMethod(requestOptions = null) {
+  return String(resolveRequestOptionsObject(requestOptions).method || "GET").toUpperCase();
+}
+
+function useListCore({
+  queryKey,
+  path = "",
+  enabled = true,
+  client = null,
+  transport = null,
+  initialPageParam = null,
+  getNextPageParam,
+  selectItems,
+  requestOptions = null,
+  queryOptions = null,
+  requestRecovery = null,
+  requestRecoveryLabel = "List",
+  fallbackLoadError = "Unable to load list."
+} = {}) {
+  const activeClient = client || getHttpWebClient();
+  if (!activeClient || typeof activeClient.request !== "function") {
+    throw new TypeError("useListCore requires a client with request().");
+  }
+
+  const normalizedPath = computed(() => resolveTextRef(path));
+  const queryEnabled = computed(() => resolveEnabledRef(enabled) && Boolean(normalizedPath.value));
+
+  const collection = usePagedCollection({
+    queryKey,
+    initialPageParam,
+    enabled: queryEnabled,
+    queryFn: async ({ pageParam }) => {
+      const requestPath = normalizedPath.value;
+      if (!requestPath) {
+        throw new Error("List path is required.");
+      }
+
+      return activeClient.request(
+        requestPath,
+        buildListRequestOptions({
+          requestOptions,
+          transport,
+          pageParam
+        })
+      );
+    },
+    getNextPageParam,
+    selectItems,
+    queryOptions: mergeRequestRecoveryQueryMeta(queryOptions, requestRecovery, {
+      label: requestRecoveryLabel,
+      method: resolveListRequestMethod(requestOptions)
+    }),
+    fallbackLoadError
+  });
+
+  return collection;
+}
+
+export {
+  buildListRequestOptions,
+  useListCore
+};

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

@@ -0,0 +1,98 @@
+import { ref } from "vue";
+import { useShellWebErrorRuntime } from "@jskit-ai/shell-web/client/error";
+import { toUiErrorMessage } from "../support/errorMessageHelpers.js";
+
+function useUiFeedback({
+  initialType = "success",
+  source = "http-web.ui-feedback",
+  successChannel = "",
+  errorChannel = "",
+  dedupeWindowMs = 2000
+} = {}) {
+  const message = ref("");
+  const messageType = ref(String(initialType || "success"));
+  const errorRuntime = useShellWebErrorRuntime();
+  const normalizedSource = String(source || "").trim() || "http-web.ui-feedback";
+  let lastErrorPresentation = null;
+
+  function rememberErrorPresentation(reportResult = null) {
+    const presentationId = String(reportResult?.presentationId || "").trim();
+    const presenterId = String(reportResult?.decision?.presenterId || "").trim();
+    if (!presentationId || !presenterId) {
+      return;
+    }
+
+    lastErrorPresentation = Object.freeze({
+      presentationId,
+      presenterId
+    });
+  }
+
+  function dismissLastErrorPresentation() {
+    if (!lastErrorPresentation) {
+      return;
+    }
+
+    errorRuntime.dismiss(lastErrorPresentation.presentationId, {
+      presenterId: lastErrorPresentation.presenterId
+    });
+    lastErrorPresentation = null;
+  }
+
+  function clear() {
+    message.value = "";
+  }
+
+  function success(nextMessage = "") {
+    messageType.value = "success";
+    const normalizedMessage = String(nextMessage || "").trim();
+    message.value = normalizedMessage;
+    dismissLastErrorPresentation();
+    if (!normalizedMessage) {
+      return;
+    }
+
+    errorRuntime.report({
+      source: normalizedSource,
+      message: normalizedMessage,
+      intent: "action-feedback",
+      severity: "success",
+      channel: successChannel,
+      dedupeKey: `${normalizedSource}:success:${normalizedMessage}`,
+      dedupeWindowMs
+    });
+  }
+
+  function error(errorValue, fallbackMessage = "") {
+    messageType.value = "error";
+    message.value = toUiErrorMessage(errorValue, fallbackMessage, "Request failed.");
+    if (!message.value) {
+      return;
+    }
+
+    const reportResult = errorRuntime.report({
+      source: normalizedSource,
+      message: message.value,
+      cause: errorValue || null,
+      intent: "action-feedback",
+      severity: "error",
+      channel: errorChannel,
+      dedupeKey: `${normalizedSource}:error:${message.value}`,
+      dedupeWindowMs
+    });
+
+    if (!reportResult?.skipped) {
+      rememberErrorPresentation(reportResult);
+    }
+  }
+
+  return Object.freeze({
+    message,
+    messageType,
+    clear,
+    success,
+    error
+  });
+}
+
+export { useUiFeedback };

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

@@ -0,0 +1,93 @@
+import { computed } from "vue";
+import { watchResourceModelState } from "./modelStateHelpers.js";
+
+function normalizeStatusList(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => Number(entry)).filter((entry) => Number.isInteger(entry) && entry > 0);
+  }
+
+  return [404];
+}
+
+function useViewCore({
+  resource,
+  model,
+  canView,
+  mapLoadedToModel,
+  notFoundStatuses = [404],
+  notFoundMessage = "Record not found."
+} = {}) {
+  const statusList = normalizeStatusList(notFoundStatuses);
+  watchResourceModelState({
+    resource,
+    model,
+    mapLoadedToModel,
+    resolveMapContext() {
+      return {
+        resource
+      };
+    }
+  });
+
+  const data = resource?.data;
+  const record = computed(() => (model !== undefined ? model : data?.value));
+  const isLoading = computed(() => {
+    if (resource?.isInitialLoading?.value !== undefined) {
+      return Boolean(resource.isInitialLoading.value);
+    }
+    return Boolean(resource?.query?.isPending?.value);
+  });
+  const isFetching = computed(() => {
+    if (resource?.isFetching?.value !== undefined) {
+      return Boolean(resource.isFetching.value);
+    }
+    return Boolean(resource?.query?.isFetching?.value);
+  });
+  const error = computed(() => resource?.query?.error?.value || null);
+
+  const isNotFound = computed(() => {
+    const status = Number(error.value?.status || 0);
+    return statusList.includes(status);
+  });
+
+  const notFoundError = computed(() => {
+    if (!isNotFound.value) {
+      return "";
+    }
+
+    return String(notFoundMessage || "Record not found.");
+  });
+
+  const loadError = computed(() => {
+    if (isNotFound.value) {
+      return "";
+    }
+
+    return String(resource?.loadError?.value || "").trim();
+  });
+
+  const resolvedCanView = computed(() => {
+    if (canView === undefined) {
+      return true;
+    }
+
+    return Boolean(canView?.value);
+  });
+
+  async function refresh() {
+    return resource?.reload?.();
+  }
+
+  return Object.freeze({
+    record,
+    isLoading,
+    isFetching,
+    isNotFound,
+    notFoundError,
+    loadError,
+    canView: resolvedCanView,
+    refresh
+  });
+}
+
+export { useViewCore };