@jskit-ai/http-web 0.1.1

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

@@ -0,0 +1,19 @@
+import { unref } from "vue";
+
+function resolveEnabledRef(value) {
+  if (value === undefined) {
+    return true;
+  }
+
+  if (typeof value === "function") {
+    return Boolean(value());
+  }
+
+  return Boolean(unref(value));
+}
+
+function resolveTextRef(value) {
+  return String(unref(value) || "").trim();
+}
+
+export { resolveEnabledRef, resolveTextRef };

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

@@ -0,0 +1,141 @@
+import { computed, unref } from "vue";
+import {
+  buildJsonApiFieldsetsToken,
+  normalizeJsonApiFieldsets
+} from "@jskit-ai/kernel/shared/support/jsonApiFieldsets";
+import {
+  resolveQueryParamDescriptors,
+  resolveActiveQueryParamEntries,
+  buildQueryParamEntriesToken
+} from "./listQueryParamSupport.js";
+
+function resolveRequestQueryContext(context = null) {
+  const source = unref(context);
+  return source && typeof source === "object" && !Array.isArray(source) ? source : {};
+}
+
+function resolveRequestQueryBaseKey(sourceQueryKey = null) {
+  const source = unref(sourceQueryKey);
+  if (Array.isArray(source)) {
+    return [...source];
+  }
+  if (source == null) {
+    return [];
+  }
+  return [source];
+}
+
+function resolveRequestFieldsets(requestFieldsets = null, context = {}) {
+  const source = typeof requestFieldsets === "function"
+    ? requestFieldsets(context)
+    : unref(requestFieldsets);
+  return normalizeJsonApiFieldsets(source);
+}
+
+function appendRequestQueryValue(target = {}, key = "", values = []) {
+  const normalizedKey = String(key || "").trim();
+  const normalizedValues = (Array.isArray(values) ? values : [])
+    .map((value) => String(value ?? "").trim())
+    .filter(Boolean);
+  if (!normalizedKey || normalizedValues.length < 1) {
+    return;
+  }
+
+  const currentValue = target[normalizedKey];
+  if (currentValue === undefined) {
+    target[normalizedKey] = normalizedValues.length === 1 ? normalizedValues[0] : [...normalizedValues];
+    return;
+  }
+
+  const currentValues = Array.isArray(currentValue) ? [...currentValue] : [currentValue];
+  target[normalizedKey] = [...currentValues, ...normalizedValues];
+}
+
+function buildRequestQueryObject(entries = [], { fieldsets = null } = {}) {
+  const sourceEntries = Array.isArray(entries) ? entries : [];
+  const query = {};
+
+  for (const entry of sourceEntries) {
+    appendRequestQueryValue(query, entry?.key, entry?.values);
+  }
+
+  const normalizedFieldsets = normalizeJsonApiFieldsets(fieldsets);
+  return Object.freeze({
+    ...query,
+    ...(Object.keys(normalizedFieldsets).length > 0
+      ? { fields: normalizedFieldsets }
+      : {})
+  });
+}
+
+function createRequestQueryRuntime({
+  requestQueryParams = null,
+  requestFieldsets = null,
+  context = null,
+  sourceQueryKey = null
+} = {}) {
+  const requestQueryParamDescriptors = computed(() => {
+    return resolveQueryParamDescriptors(requestQueryParams, resolveRequestQueryContext(context));
+  });
+  const activeRequestQueryParamEntries = computed(() => {
+    return resolveActiveQueryParamEntries(requestQueryParamDescriptors.value);
+  });
+  const activeRequestQueryParamsToken = computed(() => {
+    return buildQueryParamEntriesToken(activeRequestQueryParamEntries.value);
+  });
+  const activeRequestFieldsets = computed(() => {
+    return resolveRequestFieldsets(
+      requestFieldsets,
+      resolveRequestQueryContext(context)
+    );
+  });
+  const activeRequestFieldsetsToken = computed(() => {
+    return buildJsonApiFieldsetsToken(activeRequestFieldsets.value);
+  });
+  const queryKeyParts = computed(() => {
+    const parts = [];
+    if (activeRequestQueryParamsToken.value) {
+      parts.push("__request_query__", activeRequestQueryParamsToken.value);
+    }
+    if (activeRequestFieldsetsToken.value) {
+      parts.push("__request_fieldsets__", activeRequestFieldsetsToken.value);
+    }
+    return Object.freeze(parts);
+  });
+  const queryKey = computed(() => {
+    if (queryKeyParts.value.length < 1) {
+      return unref(sourceQueryKey);
+    }
+
+    return [
+      ...resolveRequestQueryBaseKey(sourceQueryKey),
+      ...queryKeyParts.value
+    ];
+  });
+  const requestQuery = computed(() => {
+    const query = buildRequestQueryObject(activeRequestQueryParamEntries.value, {
+      fieldsets: activeRequestFieldsets.value
+    });
+    if (Object.keys(query).length < 1) {
+      return null;
+    }
+
+    return query;
+  });
+
+  return Object.freeze({
+    requestQueryParamDescriptors,
+    activeRequestQueryParamEntries,
+    activeRequestQueryParamsToken,
+    activeRequestFieldsets,
+    activeRequestFieldsetsToken,
+    queryKeyParts,
+    queryKey,
+    requestQuery
+  });
+}
+
+export {
+  buildRequestQueryObject,
+  createRequestQueryRuntime
+};

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

@@ -0,0 +1,208 @@
+import { unref } from "vue";
+
+function hasResolvedQueryData({ query = null, data = null } = {}) {
+  const querySucceeded = Boolean(unref(query?.isSuccess));
+  const hasDataPayload = unref(data) != null;
+
+  return querySucceeded || hasDataPayload;
+}
+
+function mergeQueryMeta(queryOptions = null, meta = {}) {
+  const sourceOptions =
+    queryOptions && typeof queryOptions === "object" && !Array.isArray(queryOptions) ? queryOptions : {};
+  const sourceMeta =
+    sourceOptions.meta && typeof sourceOptions.meta === "object" && !Array.isArray(sourceOptions.meta)
+      ? sourceOptions.meta
+      : {};
+  const sourceJskitMeta =
+    sourceMeta.jskit && typeof sourceMeta.jskit === "object" && !Array.isArray(sourceMeta.jskit)
+      ? sourceMeta.jskit
+      : {};
+  const nextJskitMeta =
+    meta.jskit && typeof meta.jskit === "object" && !Array.isArray(meta.jskit)
+      ? meta.jskit
+      : {};
+
+  return {
+    ...sourceOptions,
+    meta: {
+      ...sourceMeta,
+      ...meta,
+      jskit: {
+        ...sourceJskitMeta,
+        ...nextJskitMeta
+      }
+    }
+  };
+}
+
+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 = {}) {
+  return sourceJskitMeta.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 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)) {
+    return {};
+  }
+
+  const hasExplicitLabel = hasUsableMetaValue(sourceJskitMeta, "requestRecoveryLabel");
+  const hasExplicitSource = hasUsableMetaValue(sourceJskitMeta, "requestRecoverySource");
+  const hasExplicitDedupeKey = hasUsableMetaValue(sourceJskitMeta, "requestRecoveryDedupeKey");
+  const hasExplicitDedupeWindowMs = hasUsableMetaValue(sourceJskitMeta, "requestRecoveryDedupeWindowMs");
+  const hasExplicitMethod = hasUsableMetaValue(sourceJskitMeta, "requestRecoveryMethod");
+
+  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,
+  mergeRequestRecoveryQueryMeta
+};

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

@@ -0,0 +1,285 @@
+import { unref } from "vue";
+import { asPlainObject } from "./scopeHelpers.js";
+
+const ROUTE_PARAM_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+
+function normalizeRouteParamName(value = "", { context = "http-web route param" } = {}) {
+  const normalizedValue = String(value || "").trim();
+  if (!normalizedValue) {
+    throw new TypeError(`${context} must be a non-empty route parameter name.`);
+  }
+  if (!ROUTE_PARAM_NAME_PATTERN.test(normalizedValue)) {
+    throw new TypeError(
+      `${context} "${normalizedValue}" is invalid. Use letters, numbers, and underscores only.`
+    );
+  }
+
+  return normalizedValue;
+}
+
+function toRouteParamValue(value) {
+  if (Array.isArray(value)) {
+    return toRouteParamValue(value[0]);
+  }
+  if (value == null) {
+    return "";
+  }
+
+  return String(value).trim();
+}
+
+function resolveRouteSourceValue(source = null) {
+  if (typeof source === "function") {
+    return source();
+  }
+
+  return unref(source);
+}
+
+function resolveRouteParamsSource(source = null) {
+  return asPlainObject(resolveRouteSourceValue(source));
+}
+
+function normalizeRouteParamNameList(value = []) {
+  const source = Array.isArray(value) ? value : [];
+  return source
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean);
+}
+
+function resolveRouteParamNamesSource(source = []) {
+  return normalizeRouteParamNameList(resolveRouteSourceValue(source));
+}
+
+function normalizeRoutePathname(value = "") {
+  const rawPathname = String(value || "").trim();
+  const sanitizedPathname = rawPathname.split(/[?#]/u, 1)[0] || "";
+  if (!sanitizedPathname) {
+    return "/";
+  }
+
+  return sanitizedPathname.startsWith("/") ? sanitizedPathname : `/${sanitizedPathname}`;
+}
+
+function resolveRoutePathnameSource(source = "") {
+  return normalizeRoutePathname(resolveRouteSourceValue(source));
+}
+
+function segmentMatchesParamValue(segment = "", paramValue = "") {
+  const normalizedSegment = String(segment || "").trim();
+  const normalizedParamValue = toRouteParamValue(paramValue);
+  if (!normalizedSegment || !normalizedParamValue) {
+    return false;
+  }
+
+  const encodedParamValue = encodeURIComponent(normalizedParamValue);
+  if (normalizedSegment === encodedParamValue) {
+    return true;
+  }
+
+  try {
+    return decodeURIComponent(normalizedSegment) === normalizedParamValue;
+  } catch {
+    return false;
+  }
+}
+
+function findRouteParamSegmentIndex(segments = [], paramValue = "", fromIndex = 0) {
+  const source = Array.isArray(segments) ? segments : [];
+  const cursor = Number.isInteger(fromIndex) && fromIndex > 0 ? fromIndex : 0;
+  for (let index = cursor; index < source.length; index += 1) {
+    if (segmentMatchesParamValue(source[index], paramValue)) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function normalizePathPrefix(segments = [], endIndex = -1) {
+  const source = Array.isArray(segments) ? segments : [];
+  if (!Number.isInteger(endIndex) || endIndex < 0) {
+    return "/";
+  }
+  return `/${source.slice(0, endIndex + 1).join("/")}`;
+}
+
+function resolveAnchorEndIndex(segmentIndex = -1, totalSegments = 0, anchorMode = "at") {
+  const normalizedSegmentIndex = Number.isInteger(segmentIndex) ? segmentIndex : -1;
+  if (normalizedSegmentIndex < 0) {
+    return -1;
+  }
+
+  const normalizedTotalSegments = Number.isInteger(totalSegments) && totalSegments > 0 ? totalSegments : 0;
+  const normalizedMode = String(anchorMode || "at").trim().toLowerCase();
+  if (normalizedMode === "before") {
+    return normalizedSegmentIndex - 1;
+  }
+  if (normalizedMode === "after") {
+    return normalizedTotalSegments > 0
+      ? Math.min(normalizedSegmentIndex + 1, normalizedTotalSegments - 1)
+      : normalizedSegmentIndex + 1;
+  }
+
+  return normalizedSegmentIndex;
+}
+
+function resolveScopedRoutePathname({
+  currentPathname = "/",
+  params = {},
+  orderedParamNames = [],
+  anchorParamName = "",
+  anchorParamValue = "",
+  anchorMode = "at"
+} = {}) {
+  const normalizedCurrentPathname = resolveRoutePathnameSource(currentPathname);
+  const normalizedAnchorParamName = String(anchorParamName || "").trim();
+  if (!normalizedAnchorParamName) {
+    return normalizedCurrentPathname;
+  }
+
+  const sourceParams = asPlainObject(params);
+  const segments = normalizedCurrentPathname.split("/").filter(Boolean);
+  if (segments.length < 1) {
+    return normalizedCurrentPathname;
+  }
+
+  const paramNames = resolveRouteParamNamesSource(orderedParamNames);
+  let cursor = 0;
+  for (const paramName of paramNames) {
+    const segmentIndex = findRouteParamSegmentIndex(segments, sourceParams[paramName], cursor);
+    if (segmentIndex < 0) {
+      continue;
+    }
+
+    if (paramName === normalizedAnchorParamName) {
+      const endIndex = resolveAnchorEndIndex(segmentIndex, segments.length, anchorMode);
+      return normalizePathPrefix(segments, endIndex);
+    }
+
+    cursor = segmentIndex + 1;
+  }
+
+  const fallbackAnchorValue = toRouteParamValue(anchorParamValue) ||
+    toRouteParamValue(sourceParams[normalizedAnchorParamName]);
+  if (!fallbackAnchorValue) {
+    return normalizedCurrentPathname;
+  }
+
+  const fallbackSegmentIndex = findRouteParamSegmentIndex(segments, fallbackAnchorValue, 0);
+  if (fallbackSegmentIndex < 0) {
+    return normalizedCurrentPathname;
+  }
+
+  const fallbackEndIndex = resolveAnchorEndIndex(fallbackSegmentIndex, segments.length, anchorMode);
+  return normalizePathPrefix(segments, fallbackEndIndex);
+}
+
+function resolveRouteTemplatePath(routeTemplate = "", params = {}) {
+  const normalizedTemplate = String(routeTemplate || "").trim();
+  if (!normalizedTemplate) {
+    return "";
+  }
+
+  const source = asPlainObject(params);
+  const missingParams = [];
+  const resolvedPath = normalizedTemplate.replace(/:([A-Za-z][A-Za-z0-9_]*)/g, (_, key) => {
+    const value = toRouteParamValue(source[key]);
+    if (!value) {
+      missingParams.push(key);
+      return `:${key}`;
+    }
+
+    return encodeURIComponent(value);
+  });
+
+  if (missingParams.length > 0) {
+    return "";
+  }
+
+  return resolvedPath;
+}
+
+function resolveRouteTemplateLocation(routeTemplate = "", { params = {}, currentPathname = "/" } = {}) {
+  const resolvedTemplatePath = resolveRouteTemplatePath(routeTemplate, params);
+  if (!resolvedTemplatePath) {
+    return "";
+  }
+  if (resolvedTemplatePath.startsWith("/")) {
+    return resolvedTemplatePath;
+  }
+
+  const normalizedCurrentPathname = resolveRoutePathnameSource(currentPathname);
+  const basePathname = normalizedCurrentPathname.endsWith("/")
+    ? normalizedCurrentPathname
+    : `${normalizedCurrentPathname}/`;
+  const resolvedPathname = new URL(resolvedTemplatePath, `https://jskit.local${basePathname}`).pathname;
+  if (resolvedPathname.length > 1 && resolvedPathname.endsWith("/")) {
+    return resolvedPathname.slice(0, -1);
+  }
+
+  return resolvedPathname;
+}
+
+function extractRouteParamNames(pathTemplate = "") {
+  const normalizedTemplate = String(pathTemplate || "").trim();
+  if (!normalizedTemplate) {
+    return [];
+  }
+
+  const names = [];
+  const seen = new Set();
+  const pattern = /:([A-Za-z][A-Za-z0-9_]*)/g;
+  let match = null;
+  while ((match = pattern.exec(normalizedTemplate)) != null) {
+    const name = String(match[1] || "").trim();
+    if (!name || seen.has(name)) {
+      continue;
+    }
+    seen.add(name);
+    names.push(name);
+  }
+
+  return names;
+}
+
+function resolveRouteParamNamesInOrder(route = null) {
+  const sourceRoute = route && typeof route === "object" ? route : {};
+  const matched = Array.isArray(sourceRoute.matched) ? sourceRoute.matched : [];
+  const names = [];
+  const seen = new Set();
+
+  for (const entry of matched) {
+    const entryPath = String(entry?.path || "").trim();
+    if (!entryPath) {
+      continue;
+    }
+    for (const name of extractRouteParamNames(entryPath)) {
+      if (seen.has(name)) {
+        continue;
+      }
+      seen.add(name);
+      names.push(name);
+    }
+  }
+
+  if (names.length > 0) {
+    return names;
+  }
+
+  return Object.keys(asPlainObject(sourceRoute.params))
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean);
+}
+
+export {
+  normalizeRouteParamName,
+  toRouteParamValue,
+  resolveRouteParamsSource,
+  resolveRouteParamNamesSource,
+  resolveRoutePathnameSource,
+  resolveScopedRoutePathname,
+  resolveRouteTemplatePath,
+  resolveRouteTemplateLocation,
+  extractRouteParamNames,
+  resolveRouteParamNamesInOrder
+};