@scalar/helpers 0.4.1 → 0.4.2

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)
+    : []);

package/dist/regex/regex-helpers.js

@@ -1,18 +1,18 @@
-const REGEX = {
-  /** Checks for a valid scheme */
-  PROTOCOL: /^(?:https?|ftp|file|mailto|tel|data|wss?)*:\/\//,
-  /** Finds multiple slashes after the scheme to replace with a single slash */
-  MULTIPLE_SLASHES: /(?<!:)\/{2,}/g,
-  /** Finds all variables wrapped in {{double}} */
-  VARIABLES: /{{((?:[^{}]|{[^{}]*})*)}}/g,
-  /** Finds all variables wrapped in {single} */
-  PATH: /(?:{)([^{}]+)}(?!})/g,
-  /** Finds the name of the schema from the ref path */
-  REF_NAME: /\/([^\/]+)$/,
-  /** Finds template variables in multiple formats: {{var}}, {var}, or :var */
-  TEMPLATE_VARIABLE: /{{\s*([^}\s]+?)\s*}}|{\s*([^}\s]+?)\s*}|:\b[\w.]+\b/g
+/**
+ * Collection of regular expressions used throughout the application.
+ * These patterns handle URL parsing, variable detection, and reference path extraction.
+ */
+export const REGEX = {
+    /** Checks for a valid scheme */
+    PROTOCOL: /^(?:https?|ftp|file|mailto|tel|data|wss?)*:\/\//,
+    /** Finds multiple slashes after the scheme to replace with a single slash */
+    MULTIPLE_SLASHES: /(?<!:)\/{2,}/g,
+    /** Finds all variables wrapped in {{double}} */
+    VARIABLES: /{{((?:[^{}]|{[^{}]*})*)}}/g,
+    /** Finds all variables wrapped in {single} */
+    PATH: /(?:{)([^{}]+)}(?!})/g,
+    /** Finds the name of the schema from the ref path */
+    REF_NAME: /\/([^\/]+)$/,
+    /** Finds template variables in multiple formats: {{var}}, {var}, or :var */
+    TEMPLATE_VARIABLE: /{{\s*([^}\s]+?)\s*}}|{\s*([^}\s]+?)\s*}|:\b[\w.]+\b/g,
 };
-export {
-  REGEX
-};
-//# sourceMappingURL=regex-helpers.js.map

package/dist/regex/replace-variables.js

@@ -1,20 +1,22 @@
-import { REGEX } from "../regex/regex-helpers.js";
-function replaceVariables(value, variablesOrCallback) {
-  const doubleCurlyBrackets = /{{\s*([\w.-]+)\s*}}/g;
-  const singleCurlyBrackets = /{\s*([\w.-]+)\s*}/g;
-  const callback = (_, match) => {
-    if (typeof variablesOrCallback === "function") {
-      return variablesOrCallback(match);
-    }
-    return variablesOrCallback[match]?.toString() || `{${match}}`;
-  };
-  return value.replace(doubleCurlyBrackets, callback).replace(singleCurlyBrackets, callback);
+import { REGEX } from '../regex/regex-helpers.js';
+/**
+ * This function takes a string and replaces both {single} and {{double}} curly brace variables with given values.
+ * Use the replacePathVariables and replaceEnvVariables functions if you only need to replace one type of variable.
+ */
+export function replaceVariables(value, variablesOrCallback) {
+    // Replace all variables (example: {{ baseurl }} with an HTML tag)
+    const doubleCurlyBrackets = /{{\s*([\w.-]+)\s*}}/g;
+    const singleCurlyBrackets = /{\s*([\w.-]+)\s*}/g;
+    const callback = (_, match) => {
+        if (typeof variablesOrCallback === 'function') {
+            return variablesOrCallback(match);
+        }
+        return variablesOrCallback[match]?.toString() || `{${match}}`;
+    };
+    // Loop through all matches and replace the match with the variable value
+    return value.replace(doubleCurlyBrackets, callback).replace(singleCurlyBrackets, callback);
 }
-const replacePathVariables = (path, variables = {}) => path.replace(REGEX.PATH, (match, key) => variables[key] ?? match);
-const replaceEnvVariables = (path, variables = {}) => path.replace(REGEX.VARIABLES, (match, key) => variables[key] ?? match);
-export {
-  replaceEnvVariables,
-  replacePathVariables,
-  replaceVariables
-};
-//# sourceMappingURL=replace-variables.js.map
+/** Replace {path} variables with their values */
+export const replacePathVariables = (path, variables = {}) => path.replace(REGEX.PATH, (match, key) => variables[key] ?? match);
+/** Replace {{env}} variables with their values */
+export const replaceEnvVariables = (path, variables = {}) => path.replace(REGEX.VARIABLES, (match, key) => variables[key] ?? match);

package/dist/string/camel-to-title.js

@@ -1,5 +1,10 @@
-const camelToTitleWords = (camelStr = "") => camelStr.replace(/([A-Z]{2,})/g, " $1").replace(/([A-Z])(?=[a-z])/g, " $1").replace(/^./, (str) => str.toUpperCase()).trim();
-export {
-  camelToTitleWords
-};
-//# sourceMappingURL=camel-to-title.js.map
+/**
+ * Converts a camelCase string to Title Words with spaces
+ *
+ * @param camelStr - MUST be in camelCase or this might not work
+ */
+export const camelToTitleWords = (camelStr = '') => camelStr
+    .replace(/([A-Z]{2,})/g, ' $1') // Add space before consecutive capitals
+    .replace(/([A-Z])(?=[a-z])/g, ' $1') // Add space before single capital followed by lowercase
+    .replace(/^./, (str) => str.toUpperCase()) // Capitalize first letter
+    .trim();

package/dist/string/capitalize.js

@@ -1,5 +1,5 @@
-const capitalize = (str = "") => (str[0]?.toUpperCase() ?? "") + str.slice(1);
-export {
-  capitalize
-};
-//# sourceMappingURL=capitalize.js.map
+/**
+ * Capitalize first letter
+ * You should normally do this in css, only use this if you have to
+ */
+export const capitalize = (str = '') => (str[0]?.toUpperCase() ?? '') + str.slice(1);

package/dist/string/create-hash.js

@@ -1,18 +1,21 @@
-const createHash = (input) => {
-  let chr = 0;
-  let hash = 0;
-  let i = 0;
-  if (!input?.length) {
+/**
+ * Simple 32 bit non-secure hash from a string input
+ *
+ * @deprecated Please use generateHash from ./generate-hash.ts instead
+ *
+ * @see https://stackoverflow.com/a/7616484/1624255
+ */
+export const createHash = (input) => {
+    let chr = 0;
+    let hash = 0;
+    let i = 0;
+    if (!input?.length) {
+        return hash;
+    }
+    for (i = 0; i < input.length; i++) {
+        chr = input.charCodeAt(i);
+        hash = (hash << 5) - hash + chr;
+        hash |= 0; // Convert to 32bit integer
+    }
     return hash;
-  }
-  for (i = 0; i < input.length; i++) {
-    chr = input.charCodeAt(i);
-    hash = (hash << 5) - hash + chr;
-    hash |= 0;
-  }
-  return hash;
 };
-export {
-  createHash
-};
-//# sourceMappingURL=create-hash.js.map