@scalar/helpers 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @scalar/helpers
 
+## 0.4.2
+
+### Patch Changes
+
+- [#8466](https://github.com/scalar/scalar/pull/8466): chore: new build pipeline
+
+## 0.4.1
+
+### Patch Changes
+
+- [#8420](https://github.com/scalar/scalar/pull/8420): fix TypeScript access to navigator.userAgentData in isMacOS without ts-expect-error
+
 ## 0.4.0
 
 ### Minor Changes

package/dist/array/add-to-map-array.js

@@ -1,9 +1,8 @@
-const addToMapArray = (map, key, value) => {
-  const prev = map.get(key) ?? [];
-  prev.push(value);
-  map.set(key, prev);
+/**
+ * A little helper to add a value to a map array where the type is Map<string, any[]>
+ */
+export const addToMapArray = (map, key, value) => {
+    const prev = map.get(key) ?? [];
+    prev.push(value);
+    map.set(key, prev);
 };
-export {
-  addToMapArray
-};
-//# sourceMappingURL=add-to-map-array.js.map

package/dist/array/is-defined.js

@@ -1,5 +1,12 @@
-const isDefined = (value) => value !== null && value !== void 0;
-export {
-  isDefined
-};
-//# sourceMappingURL=is-defined.js.map
+/**
+ * Type safe alternative to array.filter(Boolean)
+ *
+ * @example
+ *
+ * ```ts
+ * const dataArray = [1, null, 2, undefined, 3].filter(isDefined)
+ * ```
+ *
+ * @see https://jaketrent.com/post/typescript-type-safe-filter-boolean/
+ */
+export const isDefined = (value) => value !== null && value !== undefined;

package/dist/array/sort-by-order.js

@@ -1,19 +1,61 @@
-function sortByOrder(arr, order, getId) {
-  const orderMap = /* @__PURE__ */ new Map();
-  order.forEach((e, idx) => orderMap.set(e, idx));
-  const sorted = [];
-  const untagged = [];
-  arr.forEach((e) => {
-    const sortedIdx = orderMap.get(getId(e));
-    if (sortedIdx === void 0) {
-      untagged.push(e);
-      return;
-    }
-    sorted[sortedIdx] = e;
-  });
-  return [...sorted.filter((it) => it !== void 0), ...untagged];
+/**
+ * Immutably sorts an array based on a given custom order, as specified by a separate list of identifiers.
+ *
+ * Note: Make sure that the identifier is unique for each item in the array.
+ * If the identifier is not unique, only the last occurrence of the identifier will be sorted.
+ * Any other elements will be overridden by the last occurrence of the identifier.
+ *
+ * This function efficiently arranges elements of an input array so that items whose IDs (obtained via the `getId` callback)
+ * match the order array will appear first, strictly in the order specified. Items not found in the order array will be
+ * appended after, maintaining their original order.
+ *
+ * This is a flexible utility: the identifier can be extracted from any data structure via the `getId` callback,
+ * and any primitive (string, number, symbol, etc.) can serve as the identifier type.
+ * Sorting is O(n) with respect to the array size, making it performant even for large arrays.
+ *
+ * @template T - The type of array elements.
+ * @template N - The type of values in the order array and the identifier returned by the getId callback.
+ * @param arr - The array to be sorted.
+ * @param order - Array specifying the desired sequence (contains identifiers returned by getId).
+ * @param getId - A callback to extract the unique identifier from each array element.
+ * @returns A new array sorted according to the order provided, with unmatched elements following.
+ *
+ * @example
+ * // Sorting an array of objects:
+ * const items = [
+ *   { id: 'a', name: 'Alpha' },
+ *   { id: 'b', name: 'Bravo' },
+ *   { id: 'c', name: 'Charlie' }
+ * ];
+ * const order = ['c', 'a'];
+ * const sorted = sortByOrder(items, order, item => item.id);
+ * // Result:
+ * // [
+ * //   { id: 'c', name: 'Charlie' },
+ * //   { id: 'a', name: 'Alpha' },
+ * //   { id: 'b', name: 'Bravo' }
+ * // ]
+ *
+ * @example
+ * // Sorting an array of primitive values:
+ * const input = ['a', 'b', 'c', 'd'];
+ * const order = ['c', 'a'];
+ * sortByOrder(input, order, item => item);
+ * // Result: ['c', 'a', 'b', 'd']
+ */
+export function sortByOrder(arr, order, getId) {
+    // Map the order to keep a single lookup table
+    const orderMap = new Map();
+    order.forEach((e, idx) => orderMap.set(e, idx));
+    const sorted = [];
+    const untagged = [];
+    arr.forEach((e) => {
+        const sortedIdx = orderMap.get(getId(e));
+        if (sortedIdx === undefined) {
+            untagged.push(e);
+            return;
+        }
+        sorted[sortedIdx] = e;
+    });
+    return [...sorted.filter((it) => it !== undefined), ...untagged];
 }
-export {
-  sortByOrder
-};
-//# sourceMappingURL=sort-by-order.js.map

package/dist/consts/content-types.js

@@ -1,15 +1,14 @@
-const CONTENT_TYPES = {
-  "multipart/form-data": "Multipart Form",
-  "application/x-www-form-urlencoded": "Form URL Encoded",
-  "application/octet-stream": "Binary File",
-  "application/json": "JSON",
-  "application/xml": "XML",
-  "application/yaml": "YAML",
-  "application/edn": "EDN",
-  "other": "Other",
-  "none": "None"
+/**
+ * Content types that we automatically add in the client
+ */
+export const CONTENT_TYPES = {
+    'multipart/form-data': 'Multipart Form',
+    'application/x-www-form-urlencoded': 'Form URL Encoded',
+    'application/octet-stream': 'Binary File',
+    'application/json': 'JSON',
+    'application/xml': 'XML',
+    'application/yaml': 'YAML',
+    'application/edn': 'EDN',
+    'other': 'Other',
+    'none': 'None',
 };
-export {
-  CONTENT_TYPES
-};
-//# sourceMappingURL=content-types.js.map

package/dist/dom/freeze-element.js

@@ -1,45 +1,59 @@
-const freezeElement = (element) => {
-  if (!element) {
-    return () => null;
-  }
-  const rect = element.getBoundingClientRect();
-  const initialViewportTop = rect.top;
-  let rafId = null;
-  const observer = new MutationObserver((mutations) => {
-    const shouldProcess = mutations.some(
-      (mutation) => mutation.type === "childList" || mutation.type === "attributes" && (mutation.attributeName === "style" || mutation.attributeName === "class")
-    );
-    if (!shouldProcess) {
-      return;
+/**
+ * Scroll Freezing Utility
+ * "Freezes" the scroll position of an element, so that it doesn't move when the rest of the content changes
+ *
+ * @example
+ * const unfreeze = freezeElement(document.querySelector('#your-element'))
+ * ... content changes ...
+ * unfreeze()
+ */
+export const freezeElement = (element) => {
+    if (!element) {
+        return () => null;
     }
-    if (rafId !== null) {
-      cancelAnimationFrame(rafId);
-    }
-    rafId = requestAnimationFrame(() => {
-      const newRect = element.getBoundingClientRect();
-      const currentViewportTop = newRect.top;
-      if (currentViewportTop !== initialViewportTop) {
-        const diff = currentViewportTop - initialViewportTop;
-        window.scrollBy(0, diff);
-      }
-      rafId = null;
+    // Get initial position relative to viewport
+    const rect = element.getBoundingClientRect();
+    const initialViewportTop = rect.top;
+    let rafId = null;
+    // Create mutation observer to watch for DOM changes
+    const observer = new MutationObserver((mutations) => {
+        // Only process if we have mutations that might affect layout
+        const shouldProcess = mutations.some((mutation) => mutation.type === 'childList' ||
+            (mutation.type === 'attributes' && (mutation.attributeName === 'style' || mutation.attributeName === 'class')));
+        if (!shouldProcess) {
+            return;
+        }
+        // Cancel any pending animation frame
+        if (rafId !== null) {
+            cancelAnimationFrame(rafId);
+        }
+        // Schedule the scroll adjustment for the next frame
+        rafId = requestAnimationFrame(() => {
+            const newRect = element.getBoundingClientRect();
+            const currentViewportTop = newRect.top;
+            // If element has moved from its initial viewport position
+            if (currentViewportTop !== initialViewportTop) {
+                // Calculate how far it moved
+                const diff = currentViewportTop - initialViewportTop;
+                // Adjust scroll to maintain position
+                window.scrollBy(0, diff);
+            }
+            rafId = null;
+        });
     });
-  });
-  observer.observe(document.body, {
-    childList: true,
-    subtree: true,
-    attributes: true,
-    attributeFilter: ["style", "class"],
-    characterData: false
-  });
-  return () => {
-    if (rafId !== null) {
-      cancelAnimationFrame(rafId);
-    }
-    observer.disconnect();
-  };
-};
-export {
-  freezeElement
+    // Start observing with more specific configuration
+    observer.observe(document.body, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ['style', 'class'],
+        characterData: false,
+    });
+    // Return function to stop maintaining position
+    return () => {
+        if (rafId !== null) {
+            cancelAnimationFrame(rafId);
+        }
+        observer.disconnect();
+    };
 };
-//# sourceMappingURL=freeze-element.js.map

package/dist/dom/scroll-to-id.js

@@ -1,29 +1,35 @@
-const scrollToId = (id, focus) => {
-  const scrollToElement = (element2) => {
-    element2.scrollIntoView();
-    if (focus) {
-      element2.focus();
+/**
+ * Tiny wrapper around the scrollIntoView API
+ *
+ * Also focuses the element if the focus flag is true
+ */
+export const scrollToId = (id, focus) => {
+    const scrollToElement = (element) => {
+        element.scrollIntoView();
+        if (focus) {
+            element.focus();
+        }
+    };
+    // Try to find the element immediately
+    const element = document.getElementById(id);
+    if (element) {
+        scrollToElement(element);
+        return;
     }
-  };
-  const element = document.getElementById(id);
-  if (element) {
-    scrollToElement(element);
-    return;
-  }
-  const stopTime = Date.now() + 1e3;
-  const tryScroll = () => {
-    const element2 = document.getElementById(id);
-    if (element2) {
-      scrollToElement(element2);
-      return;
-    }
-    if (Date.now() < stopTime) {
-      requestAnimationFrame(tryScroll);
-    }
-  };
-  requestAnimationFrame(tryScroll);
-};
-export {
-  scrollToId
+    /** Try to find the element for up to 1 second
+     * allowing it to render for instance in markdown heading usage
+     */
+    const stopTime = Date.now() + 1000;
+    const tryScroll = () => {
+        const element = document.getElementById(id);
+        if (element) {
+            scrollToElement(element);
+            return;
+        }
+        if (Date.now() < stopTime) {
+            requestAnimationFrame(tryScroll);
+        }
+    };
+    // Start the retry process if the element doesn't exist yet
+    requestAnimationFrame(tryScroll);
 };
-//# sourceMappingURL=scroll-to-id.js.map

package/dist/file/json2xml.js

@@ -1,71 +1,89 @@
+/**
+ * Character map for XML escaping to prevent XML injection attacks.
+ */
 const XML_ESCAPE_MAP = {
-  "&": "&",
-  "<": "&lt;",
-  ">": "&gt;",
-  '"': "&quot;",
-  "'": "&apos;"
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&apos;',
 };
+/**
+ * Escapes special XML characters to prevent injection attacks.
+ */
 function escapeXml(str) {
-  return str.replace(/[&<>"']/g, (char) => XML_ESCAPE_MAP[char] ?? char);
+    return str.replace(/[&<>"']/g, (char) => XML_ESCAPE_MAP[char] ?? char);
 }
-function json2xml(data, options = {}) {
-  const { indent = "  ", format = true, xmlDeclaration = true } = options;
-  const toXml = (value, key, currentIndent) => {
-    let xml2 = "";
-    if (Array.isArray(value)) {
-      for (let i = 0, n = value.length; i < n; i++) {
-        xml2 += toXml(value[i], key, currentIndent);
-      }
-    } else if (typeof value === "object" && value !== null) {
-      let hasChild = false;
-      let attributes = "";
-      let children = "";
-      for (const attr in value) {
-        if (attr.charAt(0) === "@") {
-          attributes += " " + attr.substr(1) + '="' + escapeXml(value[attr].toString()) + '"';
+/**
+ * This function converts an object to XML.
+ * Values are automatically escaped to prevent XML injection attacks.
+ */
+export function json2xml(data, options = {}) {
+    const { indent = '  ', format = true, xmlDeclaration = true } = options;
+    const toXml = (value, key, currentIndent) => {
+        let xml = '';
+        if (Array.isArray(value)) {
+            for (let i = 0, n = value.length; i < n; i++) {
+                xml += toXml(value[i], key, currentIndent);
+            }
         }
-      }
-      for (const child in value) {
-        if (child === "#text") {
-          children += escapeXml(value[child]?.toString() ?? "");
-        } else if (child === "#cdata") {
-          const cdataContent = value[child]?.toString() ?? "";
-          children += "<![CDATA[" + cdataContent.replace(/]]>/g, "]]]]><![CDATA[>") + "]]>";
-        } else if (child.charAt(0) !== "@") {
-          hasChild = true;
-          children += toXml(value[child], child, currentIndent + indent);
+        else if (typeof value === 'object' && value !== null) {
+            let hasChild = false;
+            let attributes = '';
+            let children = '';
+            // Handle attributes (keys starting with @)
+            for (const attr in value) {
+                if (attr.charAt(0) === '@') {
+                    attributes += ' ' + attr.substr(1) + '="' + escapeXml(value[attr].toString()) + '"';
+                }
+            }
+            // Handle children and special content
+            for (const child in value) {
+                if (child === '#text') {
+                    children += escapeXml(value[child]?.toString() ?? '');
+                }
+                else if (child === '#cdata') {
+                    // Escape ]]> sequences to prevent CDATA injection
+                    const cdataContent = value[child]?.toString() ?? '';
+                    children += '<![CDATA[' + cdataContent.replace(/]]>/g, ']]]]><![CDATA[>') + ']]>';
+                }
+                else if (child.charAt(0) !== '@') {
+                    hasChild = true;
+                    children += toXml(value[child], child, currentIndent + indent);
+                }
+            }
+            if (hasChild || children) {
+                xml += currentIndent + '<' + key + attributes + '>\n';
+                xml += children;
+                xml += currentIndent + '</' + key + '>\n';
+            }
+            else {
+                xml += currentIndent + '<' + key + attributes + '/>\n';
+            }
+        }
+        else {
+            xml += currentIndent + '<' + key + '>' + escapeXml(value?.toString() || '') + '</' + key + '>\n';
+        }
+        return xml;
+    };
+    let xml = '';
+    // Add XML declaration if requested
+    if (xmlDeclaration) {
+        xml += '<?xml version="1.0" encoding="UTF-8"?>';
+        if (format) {
+            xml += '\n';
         }
-      }
-      if (hasChild || children) {
-        xml2 += currentIndent + "<" + key + attributes + ">\n";
-        xml2 += children;
-        xml2 += currentIndent + "</" + key + ">\n";
-      } else {
-        xml2 += currentIndent + "<" + key + attributes + "/>\n";
-      }
-    } else {
-      xml2 += currentIndent + "<" + key + ">" + escapeXml(value?.toString() || "") + "</" + key + ">\n";
     }
-    return xml2;
-  };
-  let xml = "";
-  if (xmlDeclaration) {
-    xml += '<?xml version="1.0" encoding="UTF-8"?>';
-    if (format) {
-      xml += "\n";
+    // Convert data to XML
+    for (const key in data) {
+        if (Object.hasOwn(data, key)) {
+            xml += toXml(data[key], key, '');
+        }
     }
-  }
-  for (const key in data) {
-    if (Object.hasOwn(data, key)) {
-      xml += toXml(data[key], key, "");
+    // Format or compact the output
+    if (format) {
+        return xml.trim();
     }
-  }
-  if (format) {
-    return xml.trim();
-  }
-  return xml.replace(/\n/g, "").replace(/>\s+</g, "><").trim();
+    // Remove all newlines and extra spaces, but keep the XML declaration clean
+    return xml.replace(/\n/g, '').replace(/>\s+</g, '><').trim();
 }
-export {
-  json2xml
-};
-//# sourceMappingURL=json2xml.js.map

package/dist/general/create-limiter.js

@@ -1,32 +1,48 @@
-import { Queue } from "../queue/queue.js";
-function createLimiter(maxConcurrent) {
-  let activeCount = 0;
-  const queue = new Queue();
-  const next = () => {
-    if (queue.isEmpty() || activeCount >= maxConcurrent) {
-      return;
-    }
-    const resolve = queue.dequeue();
-    if (resolve) {
-      resolve();
-    }
-  };
-  const run = async (fn) => {
-    if (activeCount >= maxConcurrent) {
-      await new Promise((resolve) => queue.enqueue(resolve));
-    }
-    activeCount++;
-    try {
-      const result = await fn();
-      return result;
-    } finally {
-      activeCount--;
-      next();
-    }
-  };
-  return run;
+import { Queue } from '../queue/queue.js';
+/**
+ * Creates a function that limits the number of concurrent executions of async functions.
+ *
+ * @param maxConcurrent - Maximum number of concurrent executions allowed
+ * @returns A function that wraps async functions to limit their concurrent execution
+ *
+ * @example
+ * ```ts
+ * const limiter = createLimiter(2) // Allow max 2 concurrent executions
+ *
+ * // These will run with max 2 at a time
+ * const results = await Promise.all([
+ *   limiter(() => fetch('/api/1')),
+ *   limiter(() => fetch('/api/2')),
+ *   limiter(() => fetch('/api/3')),
+ *   limiter(() => fetch('/api/4'))
+ * ])
+ * ```
+ */
+export function createLimiter(maxConcurrent) {
+    let activeCount = 0;
+    const queue = new Queue();
+    const next = () => {
+        if (queue.isEmpty() || activeCount >= maxConcurrent) {
+            return;
+        }
+        const resolve = queue.dequeue();
+        if (resolve) {
+            resolve();
+        }
+    };
+    const run = async (fn) => {
+        if (activeCount >= maxConcurrent) {
+            await new Promise((resolve) => queue.enqueue(resolve));
+        }
+        activeCount++;
+        try {
+            const result = await fn();
+            return result;
+        }
+        finally {
+            activeCount--;
+            next();
+        }
+    };
+    return run;
 }
-export {
-  createLimiter
-};
-//# sourceMappingURL=create-limiter.js.map