@scalar/helpers 0.4.1 → 0.4.3

package/dist/object/is-object.js

@@ -1,11 +1,25 @@
-const isObject = (value) => {
-  if (value === null || typeof value !== "object") {
-    return false;
-  }
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
+/**
+ * Returns true if the provided value is a record object
+ * (i.e. not null, not an array, and has an actual object as the prototype).
+ *
+ * Differs from the previous isObject in that it returns false for Date,
+ * RegExp, Error, Map, Set, WeakMap, WeakSet, Promise, and other non-plain objects.
+ *
+ * Examples:
+ *   isObject({})                  // true
+ *   isObject({ a: 1 })            // true
+ *   isObject([])                  // false (Array)
+ *   isObject(null)                // false
+ *   isObject(123)                 // false
+ *   isObject('string')            // false
+ *   isObject(new Error('test'))   // false
+ *   isObject(new Date())          // false
+ *   isObject(Object.create(null)) // true
+ */
+export const isObject = (value) => {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
 };
-export {
-  isObject
-};
-//# sourceMappingURL=is-object.js.map

package/dist/object/local-storage.js

@@ -1,45 +1,53 @@
-const LS_KEYS = {
-  COLLECTION: "collection",
-  COOKIE: "cookie",
-  ENVIRONMENT: "environment",
-  REQUEST: "request",
-  REQUEST_EXAMPLE: "requestExample",
-  SECURITY_SCHEME: "securityScheme",
-  SERVER: "server",
-  TAG: "tag",
-  WORKSPACE: "workspace"
+/**
+ * localStorage keys for resources
+ * DO NOT CHANGE THESE AS IT WILL BREAK THE MIGRATION
+ */
+export const LS_KEYS = {
+    COLLECTION: 'collection',
+    COOKIE: 'cookie',
+    ENVIRONMENT: 'environment',
+    REQUEST: 'request',
+    REQUEST_EXAMPLE: 'requestExample',
+    SECURITY_SCHEME: 'securityScheme',
+    SERVER: 'server',
+    TAG: 'tag',
+    WORKSPACE: 'workspace',
 };
-const REFERENCE_LS_KEYS = {
-  /**
-   * Store the selected client as a string in localStorage
-   */
-  SELECTED_CLIENT: "scalar-reference-selected-client-v2",
-  /**
-   * Store the auth as a string in localStorage
-   */
-  AUTH: "scalar-reference-auth"
+/**
+ * localStorage keys for all reference resources
+ * to ensure we do not have any conflicts
+ */
+export const REFERENCE_LS_KEYS = {
+    /**
+     * Store the selected client as a string in localStorage
+     */
+    SELECTED_CLIENT: 'scalar-reference-selected-client-v2',
+    /**
+     * Store the auth as a string in localStorage
+     */
+    AUTH: 'scalar-reference-auth',
 };
-const CLIENT_LS_KEYS = {
-  /**
-   * @deprecated This key is deprecated and will be removed in a future release.
-   * We are now storing the entire document for the api-client instead.
-   */
-  AUTH: "scalar-client-auth",
-  /**
-   * @deprecated This key is deprecated and will be removed in a future release.
-   * We are now storing the entire document for the api-client instead.
-   */
-  SELECTED_SECURITY_SCHEMES: "scalar-client-selected-security-schemes"
+/**
+ * localStorage keys for all client resources
+ * to ensure we do not have any conflicts
+ */
+export const CLIENT_LS_KEYS = {
+    /**
+     * @deprecated This key is deprecated and will be removed in a future release.
+     * We are now storing the entire document for the api-client instead.
+     */
+    AUTH: 'scalar-client-auth',
+    /**
+     * @deprecated This key is deprecated and will be removed in a future release.
+     * We are now storing the entire document for the api-client instead.
+     */
+    SELECTED_SECURITY_SCHEMES: 'scalar-client-selected-security-schemes',
 };
-const safeLocalStorage = () => typeof window === "undefined" ? {
-  getItem: () => null,
-  setItem: () => null,
-  removeItem: () => null
-} : localStorage;
-export {
-  CLIENT_LS_KEYS,
-  LS_KEYS,
-  REFERENCE_LS_KEYS,
-  safeLocalStorage
-};
-//# sourceMappingURL=local-storage.js.map
+/** SSR safe alias for localStorage */
+export const safeLocalStorage = () => typeof window === 'undefined'
+    ? {
+        getItem: () => null,
+        setItem: () => null,
+        removeItem: () => null,
+    }
+    : localStorage;

package/dist/object/object-entries.js

@@ -1,5 +1,2 @@
-const objectEntries = (obj) => Object.entries(obj);
-export {
-  objectEntries
-};
-//# sourceMappingURL=object-entries.js.map
+/** Type safe version of Object.entries */
+export const objectEntries = (obj) => Object.entries(obj);

package/dist/object/object-keys.js

@@ -1,5 +1,5 @@
-const objectKeys = (obj) => Object.keys(obj);
-export {
-  objectKeys
-};
-//# sourceMappingURL=object-keys.js.map
+/**
+ * Type safe version of Object.keys
+ * Can probably remove this whenever typescript adds it
+ */
+export const objectKeys = (obj) => Object.keys(obj);

package/dist/object/object-replace.js

@@ -1,13 +1,14 @@
-const objectReplace = (target, replacement) => {
-  Object.keys(target).forEach((key) => {
-    if (!Object.hasOwn(replacement, key)) {
-      delete target[key];
-    }
-  });
-  Object.assign(target, replacement);
-  return target;
+// TODO: This is a copy of org/packages/helpers/src/objects/merge.ts
+/**
+ * Overwrite a target object a new replacement object handling removed keys
+ */
+export const objectReplace = (target, replacement) => {
+    // Clear any keys that have been removed in the replacement
+    Object.keys(target).forEach((key) => {
+        if (!Object.hasOwn(replacement, key)) {
+            delete target[key];
+        }
+    });
+    Object.assign(target, replacement);
+    return target;
 };
-export {
-  objectReplace
-};
-//# sourceMappingURL=object-replace.js.map

package/dist/object/omit-undefined-values.js

@@ -1,19 +1,19 @@
-const omitUndefinedValues = (data) => {
-  if (Array.isArray(data)) {
-    return data.map(
-      (item) => typeof item === "object" && item !== null ? omitUndefinedValues(item) : item
-    );
-  }
-  return Object.fromEntries(
-    Object.entries(data).filter(([_, value]) => value !== void 0).map(([key, value]) => {
-      if (typeof value === "object" && value !== null) {
-        return [key, omitUndefinedValues(value)];
-      }
-      return [key, value];
-    })
-  );
+/**
+ * Removes undefined values from an object.
+ *
+ * Can be used as a transform function for any Zod schema.
+ */
+export const omitUndefinedValues = (data) => {
+    // Handle arrays specially
+    if (Array.isArray(data)) {
+        return data.map((item) => typeof item === 'object' && item !== null ? omitUndefinedValues(item) : item);
+    }
+    return Object.fromEntries(Object.entries(data)
+        .filter(([_, value]) => value !== undefined)
+        .map(([key, value]) => {
+        if (typeof value === 'object' && value !== null) {
+            return [key, omitUndefinedValues(value)];
+        }
+        return [key, value];
+    }));
 };
-export {
-  omitUndefinedValues
-};
-//# sourceMappingURL=omit-undefined-values.js.map

package/dist/object/prevent-pollution.js

@@ -1,11 +1,28 @@
-const PROTOTYPE_POLLUTION_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
-const preventPollution = (key, context) => {
-  if (PROTOTYPE_POLLUTION_KEYS.has(key)) {
-    const errorMessage = context ? `Prototype pollution key detected: "${key}" in ${context}` : `Prototype pollution key detected: "${key}"`;
-    throw new Error(errorMessage);
-  }
+/**
+ * Set of dangerous keys that can be used for prototype pollution attacks.
+ * These keys should never be used as property names in dynamic object operations.
+ */
+const PROTOTYPE_POLLUTION_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+/**
+ * Validates that a key is safe to use and does not pose a prototype pollution risk.
+ * Throws an error if a dangerous key is detected.
+ *
+ * @param key - The key to validate
+ * @param context - Optional context string to help identify where the validation failed
+ * @throws {Error} If the key matches a known prototype pollution vector
+ *
+ * @example
+ * ```ts
+ * preventPollution('__proto__') // throws Error
+ * preventPollution('safeName') // passes
+ * preventPollution('constructor', 'operation update') // throws Error with context
+ * ```
+ */
+export const preventPollution = (key, context) => {
+    if (PROTOTYPE_POLLUTION_KEYS.has(key)) {
+        const errorMessage = context
+            ? `Prototype pollution key detected: "${key}" in ${context}`
+            : `Prototype pollution key detected: "${key}"`;
+        throw new Error(errorMessage);
+    }
 };
-export {
-  preventPollution
-};
-//# sourceMappingURL=prevent-pollution.js.map

package/dist/object/to-json-compatible.js

@@ -1,68 +1,77 @@
-import { escapeJsonPointer } from "../json/escape-json-pointer.js";
-import { Queue } from "../queue/queue.js";
-const toJsonCompatible = (obj, options = {}) => {
-  const { prefix = "", cache = /* @__PURE__ */ new WeakMap() } = options;
-  const toRef = (path) => ({ $ref: `#${path ?? ""}` });
-  if (typeof obj !== "object" || obj === null) {
-    return obj;
-  }
-  const rootPath = prefix;
-  cache.set(obj, rootPath);
-  const rootResult = Array.isArray(obj) ? new Array(obj.length) : {};
-  const queue = new Queue();
-  queue.enqueue({ node: obj, result: rootResult, path: rootPath });
-  while (!queue.isEmpty()) {
-    const frame = queue.dequeue();
-    if (!frame) {
-      continue;
+import { escapeJsonPointer } from '../json/escape-json-pointer.js';
+import { Queue } from '../queue/queue.js';
+/**
+ * Traverses an object or array, returning a deep copy in which circular references are replaced
+ * by JSON Reference objects of the form: `{ $ref: "#/path/to/original" }`.
+ * This allows safe serialization of objects with cycles, following the JSON Reference convention (RFC 6901).
+ * An optional `prefix` for the `$ref` path can be provided via options.
+ *
+ * @param obj - The input object or array to process
+ * @param options - Optional configuration; you can set a prefix for $ref pointers
+ * @returns A new object or array, with all circular references replaced by $ref pointers
+ */
+export const toJsonCompatible = (obj, options = {}) => {
+    const { prefix = '', cache = new WeakMap() } = options;
+    const toRef = (path) => ({ $ref: `#${path ?? ''}` });
+    // Primitives and null are returned as-is
+    if (typeof obj !== 'object' || obj === null) {
+        return obj;
     }
-    const { node, result, path } = frame;
-    if (Array.isArray(node)) {
-      const input = node;
-      const out2 = result;
-      for (let index = 0; index < input.length; index++) {
-        if (!(index in input)) {
-          continue;
+    const rootPath = prefix;
+    cache.set(obj, rootPath);
+    const rootResult = Array.isArray(obj) ? new Array(obj.length) : {};
+    const queue = new Queue();
+    queue.enqueue({ node: obj, result: rootResult, path: rootPath });
+    while (!queue.isEmpty()) {
+        const frame = queue.dequeue();
+        if (!frame) {
+            continue;
         }
-        const item = input[index];
-        const itemPath = `${path}/${index}`;
-        if (typeof item !== "object" || item === null) {
-          out2[index] = item;
-          continue;
+        const { node, result, path } = frame;
+        // Handle arrays (preserve sparse arrays like Array#map does)
+        if (Array.isArray(node)) {
+            const input = node;
+            const out = result;
+            for (let index = 0; index < input.length; index++) {
+                if (!(index in input)) {
+                    continue;
+                }
+                const item = input[index];
+                const itemPath = `${path}/${index}`;
+                if (typeof item !== 'object' || item === null) {
+                    out[index] = item;
+                    continue;
+                }
+                const existingPath = cache.get(item);
+                if (existingPath !== undefined) {
+                    out[index] = toRef(existingPath);
+                    continue;
+                }
+                cache.set(item, itemPath);
+                const childResult = Array.isArray(item) ? new Array(item.length) : {};
+                out[index] = childResult;
+                queue.enqueue({ node: item, result: childResult, path: itemPath });
+            }
+            continue;
         }
-        const existingPath = cache.get(item);
-        if (existingPath !== void 0) {
-          out2[index] = toRef(existingPath);
-          continue;
+        // Handle objects - create a new object with processed values
+        const out = result;
+        for (const [key, value] of Object.entries(node)) {
+            const valuePath = `${path}/${escapeJsonPointer(key)}`;
+            if (typeof value !== 'object' || value === null) {
+                out[key] = value;
+                continue;
+            }
+            const existingPath = cache.get(value);
+            if (existingPath !== undefined) {
+                out[key] = toRef(existingPath);
+                continue;
+            }
+            cache.set(value, valuePath);
+            const childResult = Array.isArray(value) ? new Array(value.length) : {};
+            out[key] = childResult;
+            queue.enqueue({ node: value, result: childResult, path: valuePath });
         }
-        cache.set(item, itemPath);
-        const childResult = Array.isArray(item) ? new Array(item.length) : {};
-        out2[index] = childResult;
-        queue.enqueue({ node: item, result: childResult, path: itemPath });
-      }
-      continue;
     }
-    const out = result;
-    for (const [key, value] of Object.entries(node)) {
-      const valuePath = `${path}/${escapeJsonPointer(key)}`;
-      if (typeof value !== "object" || value === null) {
-        out[key] = value;
-        continue;
-      }
-      const existingPath = cache.get(value);
-      if (existingPath !== void 0) {
-        out[key] = toRef(existingPath);
-        continue;
-      }
-      cache.set(value, valuePath);
-      const childResult = Array.isArray(value) ? new Array(value.length) : {};
-      out[key] = childResult;
-      queue.enqueue({ node: value, result: childResult, path: valuePath });
-    }
-  }
-  return rootResult;
-};
-export {
-  toJsonCompatible
+    return rootResult;
 };
-//# sourceMappingURL=to-json-compatible.js.map

package/dist/queue/queue.js

@@ -1,91 +1,110 @@
-class Node {
-  data;
-  next;
-  constructor(data) {
-    this.data = data;
-    this.next = null;
-  }
+/**
+ * Represents a node in a singly linked list structure, used internally by the Queue.
+ *
+ * Example:
+ *   const node = new Node<number>(42);
+ *   console.log(node.data); // 42
+ *   console.log(node.next); // null
+ */
+export class Node {
+    data;
+    next;
+    constructor(data) {
+        this.data = data;
+        this.next = null;
+    }
 }
-class Queue {
-  front;
-  rear;
-  size;
-  constructor() {
-    this.front = null;
-    this.rear = null;
-    this.size = 0;
-  }
-  /**
-   * Adds an element to the end of the queue.
-   * @param data - The data to add to the queue.
-   */
-  enqueue(data) {
-    const newNode = new Node(data);
-    if (this.isEmpty() || !this.rear) {
-      this.front = newNode;
-      this.rear = newNode;
-    } else {
-      this.rear.next = newNode;
-      this.rear = newNode;
+/**
+ * A generic queue implementation using a singly linked list.
+ *
+ * Example usage:
+ *
+ *   const q = new Queue<number>();
+ *   q.enqueue(1);
+ *   q.enqueue(2);
+ *   q.enqueue(3);
+ *   console.log(q.dequeue()); // 1
+ *   console.log(q.peek());    // 2
+ *   console.log(q.getSize()); // 2
+ *   console.log(q.toString()); // "2 -> 3"
+ *   console.log(q.isEmpty()); // false
+ */
+export class Queue {
+    front;
+    rear;
+    size;
+    constructor() {
+        this.front = null;
+        this.rear = null;
+        this.size = 0;
+    }
+    /**
+     * Adds an element to the end of the queue.
+     * @param data - The data to add to the queue.
+     */
+    enqueue(data) {
+        const newNode = new Node(data);
+        if (this.isEmpty() || !this.rear) {
+            this.front = newNode;
+            this.rear = newNode;
+        }
+        else {
+            this.rear.next = newNode;
+            this.rear = newNode;
+        }
+        this.size++;
+    }
+    /**
+     * Removes and returns the front element of the queue.
+     * @returns The data from the removed node, or null if the queue is empty.
+     */
+    dequeue() {
+        if (this.isEmpty() || !this.front) {
+            return null;
+        }
+        const removedNode = this.front;
+        this.front = this.front.next;
+        if (this.front === null) {
+            this.rear = null;
+        }
+        this.size--;
+        return removedNode.data;
     }
-    this.size++;
-  }
-  /**
-   * Removes and returns the front element of the queue.
-   * @returns The data from the removed node, or null if the queue is empty.
-   */
-  dequeue() {
-    if (this.isEmpty() || !this.front) {
-      return null;
+    /**
+     * Returns the front element of the queue without removing it.
+     * @returns The front data, or null if the queue is empty.
+     */
+    peek() {
+        if (this.isEmpty() || !this.front) {
+            return null;
+        }
+        return this.front.data;
     }
-    const removedNode = this.front;
-    this.front = this.front.next;
-    if (this.front === null) {
-      this.rear = null;
+    /**
+     * Checks whether the queue is empty.
+     * @returns True if the queue has no elements, false otherwise.
+     */
+    isEmpty() {
+        return this.size === 0;
     }
-    this.size--;
-    return removedNode.data;
-  }
-  /**
-   * Returns the front element of the queue without removing it.
-   * @returns The front data, or null if the queue is empty.
-   */
-  peek() {
-    if (this.isEmpty() || !this.front) {
-      return null;
+    /**
+     * Returns the number of elements in the queue.
+     * @returns The size of the queue.
+     */
+    getSize() {
+        return this.size;
     }
-    return this.front.data;
-  }
-  /**
-   * Checks whether the queue is empty.
-   * @returns True if the queue has no elements, false otherwise.
-   */
-  isEmpty() {
-    return this.size === 0;
-  }
-  /**
-   * Returns the number of elements in the queue.
-   * @returns The size of the queue.
-   */
-  getSize() {
-    return this.size;
-  }
-  /**
-   * Returns a string representation of the queue.
-   * @returns Elements of the queue separated by ' -> '.
-   */
-  toString() {
-    let current = this.front;
-    const elements = [];
-    while (current) {
-      elements.push(current.data);
-      current = current.next;
+    /**
+     * Returns a string representation of the queue.
+     * @returns Elements of the queue separated by ' -> '.
+     */
+    toString() {
+        let current = this.front;
+        const elements = [];
+        while (current) {
+            elements.push(current.data);
+            current = current.next;
+        }
+        return elements.join(' -> ');
     }
-    return elements.join(" -> ");
-  }
 }
-export {
-  Node,
-  Queue
-};
-//# sourceMappingURL=queue.js.map

package/dist/regex/find-variables.js

@@ -1,8 +1,13 @@
-import { REGEX } from "./regex-helpers.js";
-const findVariables = (value, { includePath = true, includeEnv = true } = {}) => [includePath && REGEX.PATH, includeEnv && REGEX.VARIABLES].flatMap(
-  (regex) => regex ? [...value.matchAll(regex)].map((match) => match[1]?.trim()).filter((variable) => variable !== void 0) : []
-);
-export {
-  findVariables
-};
-//# sourceMappingURL=find-variables.js.map
+import { REGEX } from './regex-helpers.js';
+/**
+ * Find all strings wrapped in {} or {{}} in value.
+ *
+ * @param value - The string to find variables in
+ * @param includePath - Whether to include path variables {single}
+ * @param includeEnv - Whether to include environment variables {{double}}
+ */
+export const findVariables = (value, { includePath = true, includeEnv = true } = {}) => [includePath && REGEX.PATH, includeEnv && REGEX.VARIABLES].flatMap((regex) => regex
+    ? [...value.matchAll(regex)]
+        .map((match) => match[1]?.trim())
+        .filter((variable) => variable !== undefined)
+    : []);