vuerl 1.0.0

package/dist/index.cjs

@@ -0,0 +1,738 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  parseAsArrayOf: () => parseAsArrayOf,
+  parseAsBoolean: () => parseAsBoolean,
+  parseAsFloat: () => parseAsFloat,
+  parseAsHex: () => parseAsHex,
+  parseAsInteger: () => parseAsInteger,
+  parseAsIsoDate: () => parseAsIsoDate,
+  parseAsIsoDateTime: () => parseAsIsoDateTime,
+  parseAsJson: () => parseAsJson,
+  parseAsNativeArrayOf: () => parseAsNativeArrayOf,
+  parseAsNumberLiteral: () => parseAsNumberLiteral,
+  parseAsString: () => parseAsString,
+  parseAsStringEnum: () => parseAsStringEnum,
+  parseAsStringLiteral: () => parseAsStringLiteral,
+  useQueryState: () => useQueryState,
+  useQueryStates: () => useQueryStates,
+  withDefault: () => withDefault
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/useQueryState.ts
+var import_vue = require("vue");
+var import_vue_router = require("vue-router");
+
+// src/internal/rate-limiter.ts
+var cachedDelay = null;
+function detectBrowserDelay() {
+  if (typeof window === "undefined") {
+    return 50;
+  }
+  const userAgent = navigator.userAgent.toLowerCase();
+  const isSafari = /safari/i.test(userAgent) && !/chrome/i.test(userAgent) && !/chromium/i.test(userAgent) && !/firefox/i.test(userAgent);
+  return isSafari ? 120 : 50;
+}
+function getSafeBrowserDelay() {
+  if (cachedDelay === null) {
+    cachedDelay = detectBrowserDelay();
+  }
+  return cachedDelay;
+}
+
+// src/internal/utils.ts
+function normalizeQueryValue(value) {
+  if (value === void 0 || value === null) {
+    return null;
+  }
+  if (Array.isArray(value)) {
+    return value.filter((item) => typeof item === "string");
+  }
+  return typeof value === "string" ? value : null;
+}
+function buildQueryString(query) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (typeof value === "string") {
+      params.append(key, value);
+      continue;
+    }
+    if (Array.isArray(value)) {
+      for (const entry of value) {
+        if (typeof entry === "string") {
+          params.append(key, entry);
+        }
+      }
+    }
+  }
+  return params.toString();
+}
+function cloneValue(value) {
+  if (Array.isArray(value)) {
+    return value.slice();
+  }
+  if (value instanceof Date) {
+    return new Date(value);
+  }
+  if (value && typeof value === "object") {
+    return { ...value };
+  }
+  return value;
+}
+
+// src/useQueryState.ts
+function useQueryState(key, parser, options = {}) {
+  const route = (0, import_vue_router.useRoute)();
+  const router = (0, import_vue_router.useRouter)();
+  const parserOptions = parser.options ?? {};
+  const historyMode = options.history ?? parserOptions.history ?? "replace";
+  const clearOnDefault = options.clearOnDefault ?? parserOptions.clearOnDefault ?? true;
+  const shallowRouting = options.shallow ?? parserOptions.shallow ?? true;
+  const shouldScroll = options.scroll ?? parserOptions.scroll ?? false;
+  const browserSafeDelay = getSafeBrowserDelay();
+  const customDebounce = options.debounce ?? parserOptions.debounce ?? null;
+  const customThrottle = options.throttle ?? parserOptions.throttle ?? null;
+  const resolvedDebounce = customDebounce !== null ? Math.max(customDebounce, browserSafeDelay) : null;
+  const resolvedThrottle = resolvedDebounce === null && customThrottle !== null ? Math.max(customThrottle, browserSafeDelay) : null;
+  const fallbackDebounce = resolvedDebounce ?? browserSafeDelay;
+  const state = (0, import_vue.ref)(getStateFromQueryValue(route.query[key]));
+  let updateTimeout = null;
+  let isNavigating = false;
+  let lastThrottleTimestamp = 0;
+  function resolveDefaultValue() {
+    if (parser.default !== void 0) {
+      return cloneValue(parser.default);
+    }
+    return null;
+  }
+  function normalizeValue(value) {
+    if (value === void 0 || value === null) {
+      return resolveDefaultValue();
+    }
+    return value;
+  }
+  function getStateFromQueryValue(rawValue) {
+    const normalized = normalizeQueryValue(rawValue);
+    const parsed = parser.parse(normalized);
+    return normalizeValue(parsed ?? null);
+  }
+  function equalsDefault(value) {
+    if (parser.default === void 0) {
+      return value === null;
+    }
+    if (parser.eq) {
+      return parser.eq(value, parser.default);
+    }
+    return value === parser.default;
+  }
+  async function updateUrl() {
+    updateTimeout = null;
+    if (isNavigating) {
+      return;
+    }
+    const serialized = parser.serialize(state.value === null ? null : state.value);
+    const newQuery = {};
+    for (const [queryKey, queryValue] of Object.entries(route.query)) {
+      if (queryValue === null) {
+        continue;
+      }
+      newQuery[queryKey] = queryValue;
+    }
+    if (serialized === null || clearOnDefault && equalsDefault(state.value)) {
+      delete newQuery[key];
+    } else {
+      newQuery[key] = serialized;
+    }
+    const urlString = buildQueryString(newQuery);
+    if (urlString.length > 2e3) {
+      console.warn(
+        `URL length (${urlString.length}) exceeds recommended 2000 characters. Consider simplifying or moving state to session storage.`
+      );
+    }
+    const navigationTarget = shallowRouting ? { query: newQuery } : { path: route.path, hash: route.hash, query: newQuery };
+    await router[historyMode](navigationTarget);
+    if (shouldScroll && typeof window !== "undefined" && typeof window.scrollTo === "function") {
+      window.scrollTo({ top: 0, left: 0, behavior: "auto" });
+    }
+  }
+  function queueUrlUpdate() {
+    if (resolvedThrottle !== null) {
+      const now = Date.now();
+      const remaining = resolvedThrottle - (now - lastThrottleTimestamp);
+      if (remaining <= 0) {
+        if (updateTimeout) {
+          clearTimeout(updateTimeout);
+          updateTimeout = null;
+        }
+        lastThrottleTimestamp = now;
+        void updateUrl();
+        return;
+      }
+      if (updateTimeout) {
+        clearTimeout(updateTimeout);
+      }
+      updateTimeout = setTimeout(() => {
+        lastThrottleTimestamp = Date.now();
+        updateTimeout = null;
+        void updateUrl();
+      }, remaining);
+      return;
+    }
+    const delay = resolvedDebounce ?? fallbackDebounce;
+    if (updateTimeout) {
+      clearTimeout(updateTimeout);
+    }
+    updateTimeout = setTimeout(() => {
+      updateTimeout = null;
+      void updateUrl();
+    }, delay);
+  }
+  function setState(value) {
+    const computedValue = typeof value === "function" ? value(state.value) : value;
+    const newValue = normalizeValue(computedValue);
+    const hasChanged = parser.eq ? !parser.eq(newValue, state.value) : newValue !== state.value;
+    if (hasChanged) {
+      state.value = newValue;
+      queueUrlUpdate();
+    }
+  }
+  const urlWatcher = (0, import_vue.watch)(
+    () => route.query[key],
+    (newValue) => {
+      isNavigating = true;
+      if (updateTimeout) {
+        clearTimeout(updateTimeout);
+        updateTimeout = null;
+      }
+      state.value = getStateFromQueryValue(newValue);
+      setTimeout(() => {
+        isNavigating = false;
+      }, 0);
+    }
+  );
+  (0, import_vue.onBeforeUnmount)(() => {
+    urlWatcher();
+    if (updateTimeout) {
+      clearTimeout(updateTimeout);
+    }
+  });
+  return [state, setState];
+}
+
+// src/useQueryStates.ts
+var import_vue2 = require("vue");
+var import_vue_router2 = require("vue-router");
+function useQueryStates(parsers, options = {}) {
+  const route = (0, import_vue_router2.useRoute)();
+  const router = (0, import_vue_router2.useRouter)();
+  const keys = Object.keys(parsers);
+  function findParserOption(option) {
+    for (const key of keys) {
+      const parserOption = parsers[key].options?.[option];
+      if (parserOption !== void 0) {
+        return parserOption;
+      }
+    }
+    return void 0;
+  }
+  const historyMode = options.history ?? findParserOption("history") ?? "replace";
+  const shallowRouting = options.shallow ?? findParserOption("shallow") ?? true;
+  const shouldScroll = options.scroll ?? findParserOption("scroll") ?? false;
+  const globalClearOnDefault = options.clearOnDefault ?? true;
+  const browserSafeDelay = getSafeBrowserDelay();
+  const parserDebounce = findParserOption("debounce");
+  const parserThrottle = findParserOption("throttle");
+  const customDebounce = options.debounce ?? (parserDebounce ?? null);
+  const customThrottle = options.throttle ?? (parserThrottle ?? null);
+  const resolvedDebounce = customDebounce !== null ? Math.max(customDebounce, browserSafeDelay) : null;
+  const resolvedThrottle = resolvedDebounce === null && customThrottle !== null ? Math.max(customThrottle, browserSafeDelay) : null;
+  const fallbackDebounce = resolvedDebounce ?? browserSafeDelay;
+  const state = (0, import_vue2.reactive)({});
+  for (const key of keys) {
+    state[key] = getStateFromQueryValue(key, route.query[key]);
+  }
+  let updateTimeout = null;
+  let batchMicrotaskId = null;
+  let isNavigating = false;
+  let lastThrottleTimestamp = 0;
+  function shouldClearKey(key) {
+    const parserOption = parsers[key].options?.clearOnDefault;
+    return parserOption ?? globalClearOnDefault;
+  }
+  function resolveDefaultValue(key) {
+    const parser = parsers[key];
+    if (parser.default !== void 0) {
+      return cloneValue(parser.default);
+    }
+    return null;
+  }
+  function normalizeValue(key, value) {
+    if (value === void 0 || value === null) {
+      return resolveDefaultValue(key);
+    }
+    return value;
+  }
+  function getStateFromQueryValue(key, rawValue) {
+    const normalized = normalizeQueryValue(rawValue);
+    const parser = parsers[key];
+    const parsed = parser.parse(normalized);
+    return normalizeValue(key, parsed ?? null);
+  }
+  function equalsDefault(key, value) {
+    const parser = parsers[key];
+    if (parser.default === void 0) {
+      return value === null;
+    }
+    if (parser.eq) {
+      return parser.eq(value, parser.default);
+    }
+    return value === parser.default;
+  }
+  async function updateUrl() {
+    updateTimeout = null;
+    if (isNavigating) {
+      return;
+    }
+    const newQuery = {};
+    for (const [queryKey, queryValue] of Object.entries(route.query)) {
+      if (queryValue === null) {
+        continue;
+      }
+      newQuery[queryKey] = queryValue;
+    }
+    for (const key of keys) {
+      const parser = parsers[key];
+      const serialized = parser.serialize(state[key] === null ? null : state[key]);
+      if (serialized === null || shouldClearKey(key) && equalsDefault(key, state[key])) {
+        delete newQuery[key];
+      } else {
+        newQuery[key] = serialized;
+      }
+    }
+    const urlString = buildQueryString(newQuery);
+    if (urlString.length > 2e3) {
+      console.warn(
+        `URL length (${urlString.length}) exceeds recommended 2000 characters. Consider simplifying or moving state to session storage.`
+      );
+    }
+    const navigationTarget = shallowRouting ? { query: newQuery } : { path: route.path, hash: route.hash, query: newQuery };
+    await router[historyMode](navigationTarget);
+    if (shouldScroll && typeof window !== "undefined" && typeof window.scrollTo === "function") {
+      window.scrollTo({ top: 0, left: 0, behavior: "auto" });
+    }
+  }
+  function queueUrlUpdate() {
+    if (resolvedThrottle !== null) {
+      const now = Date.now();
+      const remaining = resolvedThrottle - (now - lastThrottleTimestamp);
+      if (remaining <= 0) {
+        if (updateTimeout) {
+          clearTimeout(updateTimeout);
+          updateTimeout = null;
+        }
+        lastThrottleTimestamp = now;
+        void updateUrl();
+        return;
+      }
+      if (updateTimeout) {
+        clearTimeout(updateTimeout);
+      }
+      updateTimeout = setTimeout(() => {
+        lastThrottleTimestamp = Date.now();
+        updateTimeout = null;
+        void updateUrl();
+      }, remaining);
+      return;
+    }
+    const delay = resolvedDebounce ?? fallbackDebounce;
+    if (updateTimeout) {
+      clearTimeout(updateTimeout);
+    }
+    updateTimeout = setTimeout(() => {
+      updateTimeout = null;
+      void updateUrl();
+    }, delay);
+  }
+  function queueBatchUrlUpdate() {
+    if (batchMicrotaskId !== null) {
+      return;
+    }
+    batchMicrotaskId = queueMicrotask(() => {
+      batchMicrotaskId = null;
+      queueUrlUpdate();
+    });
+  }
+  function setState(values) {
+    let hasChanges = false;
+    if (values === null) {
+      for (const key of keys) {
+        const parser = parsers[key];
+        const newValue = resolveDefaultValue(key);
+        const hasChanged = parser.eq ? !parser.eq(newValue, state[key]) : newValue !== state[key];
+        if (hasChanged) {
+          state[key] = newValue;
+          hasChanges = true;
+        }
+      }
+    } else {
+      for (const key of Object.keys(values)) {
+        const providedValue = values[key];
+        if (providedValue === void 0) {
+          continue;
+        }
+        const parser = parsers[key];
+        const newValue = normalizeValue(key, providedValue);
+        const hasChanged = parser.eq ? !parser.eq(newValue, state[key]) : newValue !== state[key];
+        if (hasChanged) {
+          state[key] = newValue;
+          hasChanges = true;
+        }
+      }
+    }
+    if (hasChanges) {
+      queueBatchUrlUpdate();
+    }
+  }
+  const watchers = keys.map((key) => {
+    return (0, import_vue2.watch)(
+      () => route.query[key],
+      (newValue) => {
+        isNavigating = true;
+        if (updateTimeout) {
+          clearTimeout(updateTimeout);
+          updateTimeout = null;
+        }
+        state[key] = getStateFromQueryValue(key, newValue);
+        setTimeout(() => {
+          isNavigating = false;
+        }, 0);
+      }
+    );
+  });
+  (0, import_vue2.onBeforeUnmount)(() => {
+    watchers.forEach((unwatch) => unwatch());
+    if (updateTimeout) {
+      clearTimeout(updateTimeout);
+    }
+  });
+  return [state, setState];
+}
+
+// src/parsers.ts
+function getSingleValue(value) {
+  if (value === null) {
+    return null;
+  }
+  if (Array.isArray(value)) {
+    return value[0] ?? null;
+  }
+  return value;
+}
+function getArrayValues(value) {
+  if (value === null) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value.filter((item) => typeof item === "string");
+  }
+  return value.length === 0 ? [] : [value];
+}
+function createBuildable(base) {
+  const buildable = {
+    ...base,
+    withDefault(defaultValue) {
+      return createBuildable({
+        ...base,
+        default: defaultValue
+      });
+    },
+    withOptions(options) {
+      return createBuildable({
+        ...base,
+        options: {
+          ...base.options ?? {},
+          ...options
+        }
+      });
+    }
+  };
+  return buildable;
+}
+var parseAsString = createBuildable({
+  parse: (value) => getSingleValue(value),
+  serialize: (value) => value ?? null
+});
+var parseAsInteger = createBuildable({
+  parse: (value) => {
+    const rawValue = getSingleValue(value);
+    if (!rawValue) return null;
+    const normalized = rawValue.trim();
+    if (!/^-?\d+$/.test(normalized)) {
+      return null;
+    }
+    const num = parseInt(normalized, 10);
+    return Number.isNaN(num) ? null : num;
+  },
+  serialize: (value) => {
+    if (value === null || value === void 0) return null;
+    return String(Math.floor(value));
+  }
+});
+var parseAsFloat = createBuildable({
+  parse: (value) => {
+    const rawValue = getSingleValue(value);
+    if (!rawValue) return null;
+    const normalized = rawValue.trim();
+    if (!/^[-+]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(normalized)) {
+      return null;
+    }
+    const num = parseFloat(normalized);
+    return Number.isFinite(num) ? num : null;
+  },
+  serialize: (value) => {
+    if (value === null || value === void 0) return null;
+    return String(value);
+  }
+});
+var parseAsBoolean = createBuildable({
+  parse: (value) => {
+    const rawValue = getSingleValue(value);
+    if (!rawValue) return null;
+    const lower = rawValue.toLowerCase();
+    if (lower === "true") return true;
+    if (lower === "false") return false;
+    return null;
+  },
+  serialize: (value) => {
+    if (value === null || value === void 0) return null;
+    return String(value);
+  }
+});
+function parseAsStringLiteral(values) {
+  const valueSet = new Set(values);
+  return createBuildable({
+    parse: (value) => {
+      const rawValue = getSingleValue(value);
+      if (!rawValue) return null;
+      return valueSet.has(rawValue) ? rawValue : null;
+    },
+    serialize: (value) => {
+      if (value === null || value === void 0) return null;
+      return String(value);
+    }
+  });
+}
+function parseAsNumberLiteral(values) {
+  const valueSet = new Set(values);
+  return createBuildable({
+    parse: (value) => {
+      const rawValue = getSingleValue(value);
+      if (!rawValue) return null;
+      const num = parseInt(rawValue, 10);
+      return !isNaN(num) && valueSet.has(num) ? num : null;
+    },
+    serialize: (value) => {
+      if (value === null || value === void 0) return null;
+      return String(Math.floor(value));
+    }
+  });
+}
+function parseAsStringEnum(enumObject) {
+  const enumValues = new Set(
+    Object.values(enumObject).filter((entry) => typeof entry === "string")
+  );
+  return createBuildable({
+    parse: (value) => {
+      const rawValue = getSingleValue(value);
+      if (!rawValue) return null;
+      return enumValues.has(rawValue) ? rawValue : null;
+    },
+    serialize: (value) => {
+      if (value === null || value === void 0) return null;
+      return String(value);
+    }
+  });
+}
+function parseAsArrayOf(itemParser, separator = ",") {
+  return createBuildable({
+    parse: (value) => {
+      const rawValue = getSingleValue(value);
+      if (!rawValue) return [];
+      return rawValue.split(separator).map((item) => itemParser.parse(item.trim())).filter((item) => item !== null);
+    },
+    serialize: (value) => {
+      if (!value || value.length === 0) return null;
+      const serialized = value.map((item) => itemParser.serialize(item)).flatMap((result) => {
+        if (result === null) {
+          return [];
+        }
+        return Array.isArray(result) ? result : [result];
+      }).filter((s) => typeof s === "string");
+      return serialized.length > 0 ? serialized.join(separator) : null;
+    },
+    eq: (a, b) => {
+      if (!a && !b) return true;
+      if (!a || !b) return false;
+      if (a.length !== b.length) return false;
+      return a.every((v, i) => {
+        const itemEq = itemParser.eq;
+        return itemEq ? itemEq(v, b[i]) : v === b[i];
+      });
+    },
+    default: []
+  });
+}
+function parseAsNativeArrayOf(itemParser) {
+  return createBuildable({
+    parse: (value) => {
+      const inputs = getArrayValues(value);
+      if (inputs.length === 0) return [];
+      return inputs.map((entry) => itemParser.parse(entry)).filter((item) => item !== null);
+    },
+    serialize: (value) => {
+      if (!value || value.length === 0) return null;
+      const serialized = value.map((item) => itemParser.serialize(item)).flatMap((result) => {
+        if (result === null) {
+          return [];
+        }
+        return Array.isArray(result) ? result : [result];
+      }).filter((entry) => typeof entry === "string");
+      return serialized.length > 0 ? serialized : null;
+    },
+    eq: (a, b) => {
+      if (!a && !b) return true;
+      if (!a || !b) return false;
+      if (a.length !== b.length) return false;
+      return a.every((v, i) => {
+        const itemEq = itemParser.eq;
+        return itemEq ? itemEq(v, b[i]) : v === b[i];
+      });
+    },
+    default: []
+  });
+}
+var parseAsIsoDate = createBuildable({
+  parse: (value) => {
+    const rawValue = getSingleValue(value);
+    if (!rawValue) return null;
+    const dateMatch = /^(\d{4})-(\d{2})-(\d{2})$/.test(rawValue);
+    if (!dateMatch) return null;
+    const date = /* @__PURE__ */ new Date(rawValue + "T00:00:00Z");
+    return isNaN(date.getTime()) ? null : date;
+  },
+  serialize: (value) => {
+    if (!value) return null;
+    const iso = value.toISOString();
+    return iso.split("T")[0];
+  },
+  eq: (a, b) => {
+    if (!a && !b) return true;
+    if (!a || !b) return false;
+    return a.getTime() === b.getTime();
+  }
+});
+var parseAsIsoDateTime = createBuildable({
+  parse: (value) => {
+    const rawValue = getSingleValue(value);
+    if (!rawValue) return null;
+    const dateTimeMatch = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/.test(rawValue);
+    if (!dateTimeMatch) return null;
+    const date = new Date(rawValue);
+    return isNaN(date.getTime()) ? null : date;
+  },
+  serialize: (value) => {
+    if (!value) return null;
+    return value.toISOString();
+  },
+  eq: (a, b) => {
+    if (!a && !b) return true;
+    if (!a || !b) return false;
+    return a.getTime() === b.getTime();
+  }
+});
+function parseAsJson(schema) {
+  return createBuildable({
+    parse: (value) => {
+      const rawValue = getSingleValue(value);
+      if (!rawValue) return null;
+      try {
+        const parsed = JSON.parse(rawValue);
+        if (schema) {
+          const result = schema.safeParse ? schema.safeParse(parsed) : schema.parse?.(parsed);
+          if (result && !result.success) return null;
+          return result?.data ?? parsed;
+        }
+        return parsed;
+      } catch {
+        return null;
+      }
+    },
+    serialize: (value) => {
+      if (value === null || value === void 0) return null;
+      try {
+        return JSON.stringify(value);
+      } catch {
+        return null;
+      }
+    }
+  });
+}
+var parseAsHex = createBuildable({
+  parse: (value) => {
+    const rawValue = getSingleValue(value);
+    if (!rawValue) return null;
+    const hex = rawValue.startsWith("#") ? rawValue.slice(1) : rawValue;
+    if (!/^[0-9a-fA-F]{6}$/.test(hex)) return null;
+    return hex.toLowerCase();
+  },
+  serialize: (value) => {
+    if (!value) return null;
+    return value;
+  }
+});
+function withDefault(parser, defaultValue) {
+  return createBuildable({
+    ...parser,
+    default: defaultValue
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseAsArrayOf,
+  parseAsBoolean,
+  parseAsFloat,
+  parseAsHex,
+  parseAsInteger,
+  parseAsIsoDate,
+  parseAsIsoDateTime,
+  parseAsJson,
+  parseAsNativeArrayOf,
+  parseAsNumberLiteral,
+  parseAsString,
+  parseAsStringEnum,
+  parseAsStringLiteral,
+  useQueryState,
+  useQueryStates,
+  withDefault
+});
+//# sourceMappingURL=index.cjs.map