@scalar/workspace-store 0.40.2 → 0.40.3

package/dist/helpers/detect-changes-proxy.js

@@ -1,63 +1,101 @@
-import { isObject } from "@scalar/helpers/object/is-object";
-const isDetectChangesProxy = Symbol("isDetectChangesProxy");
-const detectChangesProxyTarget = Symbol("detectChangesProxyTarget");
-const createDetectChangesProxy = (target, options, args = {
-  proxyCache: /* @__PURE__ */ new WeakMap(),
-  path: []
+import { isObject } from '@scalar/helpers/object/is-object';
+const isDetectChangesProxy = Symbol('isDetectChangesProxy');
+const detectChangesProxyTarget = Symbol('detectChangesProxyTarget');
+/**
+ * createDetectChangesProxy - Creates a proxy for an object or array that detects and triggers hooks on changes.
+ *
+ * This proxy enables detection of set operations, triggering optional hooks (onBeforeChange, onAfterChange) with the path and value changed.
+ * The proxy can be applied recursively to all nested objects/arrays, and caches proxies to prevent creating multiple proxies for the same object.
+ *
+ * Example usage:
+ *
+ * const obj = { foo: 1, bar: { baz: 2 } };
+ * const proxy = createDetectChangesProxy(obj, {
+ *   hooks: {
+ *     onBeforeChange: (path, value) => console.log('Before', path, value),
+ *     onAfterChange: (path, value) => console.log('After', path, value),
+ *   }
+ * });
+ * proxy.foo = 42; // Console: Before ['foo'] '42', After ['foo'] '42'
+ * proxy.bar.baz = 99; // Console: Before ['bar', 'baz'] '99', After ['bar', 'baz'] '99'
+ *
+ * @param target The target object or array to wrap in a proxy
+ * @param options Optional: hooks for change detection
+ * @param args Internal: proxy cache and current property path (used for recursion)
+ * @returns The proxied object/array with change detection capabilities
+ */
+export const createDetectChangesProxy = (target, options, args = {
+    proxyCache: new WeakMap(),
+    path: [],
 }) => {
-  if (!isObject(target) && !Array.isArray(target)) {
-    return target;
-  }
-  if (args.proxyCache.has(target)) {
-    return args.proxyCache.get(target);
-  }
-  const proxy = new Proxy(target, {
-    get(target2, prop, receiver) {
-      if (prop === isDetectChangesProxy) {
-        return true;
-      }
-      if (prop === detectChangesProxyTarget) {
-        return target2;
-      }
-      const value = Reflect.get(target2, prop, receiver);
-      if (isDetectChangesProxyObject(value)) {
-        return value;
-      }
-      return createDetectChangesProxy(value, options, { ...args, path: [...args.path, String(prop)] });
-    },
-    set(target2, prop, value, receiver) {
-      const path = [...args.path, String(prop)];
-      options?.hooks?.onBeforeChange?.(path, value);
-      const result = Reflect.set(target2, prop, value, receiver);
-      options?.hooks?.onAfterChange?.(path, value);
-      return result;
-    },
-    deleteProperty(target2, prop) {
-      const path = [...args.path, String(prop)];
-      options?.hooks?.onBeforeChange?.(path);
-      const result = Reflect.deleteProperty(target2, prop);
-      options?.hooks?.onAfterChange?.(path);
-      return result;
+    // Only wrap objects or arrays
+    if (!isObject(target) && !Array.isArray(target)) {
+        return target;
     }
-  });
-  args.proxyCache.set(target, proxy);
-  return proxy;
+    // Return cached proxy if already created for this target
+    if (args.proxyCache.has(target)) {
+        return args.proxyCache.get(target);
+    }
+    const proxy = new Proxy(target, {
+        get(target, prop, receiver) {
+            // Allow identifying if an object is a detect changes proxy
+            if (prop === isDetectChangesProxy) {
+                return true;
+            }
+            // Allow access to the original target
+            if (prop === detectChangesProxyTarget) {
+                return target;
+            }
+            // Recursively wrap property values in the detect changes proxy
+            const value = Reflect.get(target, prop, receiver);
+            if (isDetectChangesProxyObject(value)) {
+                return value;
+            }
+            return createDetectChangesProxy(value, options, { ...args, path: [...args.path, String(prop)] });
+        },
+        set(target, prop, value, receiver) {
+            const path = [...args.path, String(prop)];
+            // Call before-change hook if provided
+            options?.hooks?.onBeforeChange?.(path, value);
+            const result = Reflect.set(target, prop, value, receiver);
+            // Call after-change hook if provided
+            options?.hooks?.onAfterChange?.(path, value);
+            return result;
+        },
+        deleteProperty(target, prop) {
+            const path = [...args.path, String(prop)];
+            options?.hooks?.onBeforeChange?.(path);
+            const result = Reflect.deleteProperty(target, prop);
+            options?.hooks?.onAfterChange?.(path);
+            return result;
+        },
+    });
+    // Cache the proxy for this target
+    args.proxyCache.set(target, proxy);
+    return proxy;
 };
-const isDetectChangesProxyObject = (obj) => {
-  return typeof obj === "object" && obj !== null && obj[isDetectChangesProxy] === true;
+export const isDetectChangesProxyObject = (obj) => {
+    return (typeof obj === 'object' &&
+        obj !== null &&
+        obj[isDetectChangesProxy] === true);
 };
-const unpackDetectChangesProxy = (obj) => {
-  if (typeof obj !== "object" || obj === null) {
+/**
+ * Returns the raw/original (non-proxy) object if the passed object is a detect-changes proxy.
+ * If the object is not a proxy, it returns the same object.
+ *
+ * @example
+ * const proxy = createDetectChangesProxy({ a: 1 });
+ * const raw = unpackDetectChangesProxy(proxy); // Gets the original object { a: 1 }
+ * const notProxy = { b: 2 };
+ * const stillRaw = unpackDetectChangesProxy(notProxy); // Returns { b: 2 }, unchanged
+ */
+export const unpackDetectChangesProxy = (obj) => {
+    if (typeof obj !== 'object' || obj === null) {
+        return obj;
+    }
+    // If object is a detect-changes proxy, return its underlying target
+    if (obj[isDetectChangesProxy]) {
+        return obj[detectChangesProxyTarget];
+    }
     return obj;
-  }
-  if (obj[isDetectChangesProxy]) {
-    return obj[detectChangesProxyTarget];
-  }
-  return obj;
-};
-export {
-  createDetectChangesProxy,
-  isDetectChangesProxyObject,
-  unpackDetectChangesProxy
 };
-//# sourceMappingURL=detect-changes-proxy.js.map

package/dist/helpers/general.js

@@ -1,28 +1,83 @@
-function isLocalRef(value) {
-  return value.startsWith("#");
+/**
+ * Checks if a string is a local reference (starts with #)
+ * @param value - The reference string to check
+ * @returns true if the string is a local reference, false otherwise
+ * @example
+ * ```ts
+ * isLocalRef('#/components/schemas/User') // true
+ * isLocalRef('https://example.com/schema.json') // false
+ * isLocalRef('./local-schema.json') // false
+ * ```
+ */
+export function isLocalRef(value) {
+    return value.startsWith('#');
 }
-function keyOf(value) {
-  return Object.keys(value);
+export function keyOf(value) {
+    return Object.keys(value);
 }
-const deepClone = (value) => {
-  return JSON.parse(JSON.stringify(value));
+/**
+ * Deep clones a value using JSON serialization.
+ *
+ * @param value - The value to deep clone
+ * @template T - The type of the value
+ * @returns A deep clone of the value
+ */
+export const deepClone = (value) => {
+    return JSON.parse(JSON.stringify(value));
 };
-const split = (array, condition) => {
-  return array.reduce(
-    ([pass, fail], item) => {
-      return condition(item) ? [[...pass, item], fail] : [pass, [...fail, item]];
-    },
-    [[], []]
-  );
+/**
+ * Splits an array into two arrays based on a condition.
+ *
+ * This function takes an array and a predicate function, then returns a tuple containing
+ * two arrays: the first contains elements that pass the condition, and the second contains
+ * elements that fail the condition.
+ *
+ * @param array - The array to split
+ * @param condition - A predicate function that determines which array each element belongs to
+ * @returns A tuple of two arrays: [passingElements, failingElements]
+ *
+ * @example
+ * ```ts
+ * const numbers = [1, 2, 3, 4, 5, 6]
+ * const [evens, odds] = split(numbers, (n) => n % 2 === 0)
+ * // evens: [2, 4, 6]
+ * // odds: [1, 3, 5]
+ *
+ * const words = ['apple', 'banana', 'cherry', 'date']
+ * const [longWords, shortWords] = split(words, (word) => word.length > 5)
+ * // longWords: ['banana', 'cherry']
+ * // shortWords: ['apple', 'date']
+ * ```
+ */
+export const split = (array, condition) => {
+    return array.reduce(([pass, fail], item) => {
+        return condition(item) ? [[...pass, item], fail] : [pass, [...fail, item]];
+    }, [[], []]);
 };
-const safeAssign = (target, source) => {
-  Object.assign(target, source);
+/**
+ * Safely assigns properties from a source object to a target object.
+ *
+ * This function uses Object.assign to copy enumerable properties from the source object
+ * to the target object. It's a type-safe wrapper around Object.assign that ensures
+ * the source object is compatible with the target object's type.
+ *
+ * @param target - The target object to assign properties to
+ * @param source - The source object containing properties to assign
+ * @template T - The type of the target object
+ *
+ * @example
+ * ```ts
+ * const target = { name: 'John', age: 30 }
+ * const source = { age: 31, city: 'New York' }
+ * safeAssign(target, source)
+ * // target is now: { name: 'John', age: 31, city: 'New York' }
+ *
+ * const config = { theme: 'dark', language: 'en' }
+ * const updates = { theme: 'light' }
+ * safeAssign(config, updates)
+ * // config is now: { theme: 'light', language: 'en' }
+ * ```
+ */
+export const safeAssign = (target, source) => {
+    Object.assign(target, source);
 };
-export {
-  deepClone,
-  isLocalRef,
-  keyOf,
-  safeAssign,
-  split
-};
-//# sourceMappingURL=general.js.map

package/dist/helpers/generate-unique-value.js

@@ -1,47 +1,79 @@
-async function generateUniqueValue({
-  defaultValue,
-  /** Check function to verify the uniqueness of the value */
-  validation,
-  /** Transformation function to transform the default value (such as into a slug) */
-  transformation,
-  /** The maximum number of attempts to create a unique value by incrementing. */
-  maxRetries = 5
-}) {
-  const transformed = transformation?.(defaultValue) ?? defaultValue;
-  if (await validation(transformed)) {
-    return transformed;
-  }
-  return incrementValue({
-    value: [transformed, 1],
-    validation,
-    maxRetries,
-    transformation
-  });
+/**
+ * Generates a unique value based on a given default value and a validation function.
+ *
+ * The process works as follows:
+ * 1. Optionally transform (e.g., slugify) the default value using a transformation function.
+ * 2. Check if this value is unique by executing the provided validation function.
+ * 3. If not unique, repeatedly append an incrementing integer (e.g., "my-name 1", "my-name 2", ...) and re-check uniqueness,
+ *    up to a maximum number of attempts (maxRetries).
+ * 4. Returns the first unique value found or undefined if a unique value cannot be generated within the maximum retries.
+ *
+ * Example:
+ * ```ts
+ * // Existing names in use
+ * const existing = new Set(['foo', 'foo 1', 'foo 2']);
+ * const uniqueName = generateUniqueValue({
+ *   defaultValue: 'foo',
+ *   validation: (value) => !existing.has(value),
+ *   // transformation is optional, e.g. (val) => val.toLowerCase().replace(/[^\w]+/g, '-'),
+ *   maxRetries: 10,
+ * });
+ * // uniqueName === 'foo 3'
+ * ```
+ */
+export async function generateUniqueValue({ defaultValue, 
+/** Check function to verify the uniqueness of the value */
+validation, 
+/** Transformation function to transform the default value (such as into a slug) */
+transformation, 
+/** The maximum number of attempts to create a unique value by incrementing. */
+maxRetries = 5, }) {
+    const transformed = transformation?.(defaultValue) ?? defaultValue;
+    if (await validation(transformed)) {
+        return transformed;
+    }
+    return incrementValue({
+        value: [transformed, 1],
+        validation,
+        maxRetries,
+        transformation,
+    });
 }
-async function incrementValue({
-  value,
-  validation,
-  maxRetries,
-  attempts = 0,
-  transformation
-}) {
-  if (attempts >= maxRetries) {
-    return;
-  }
-  const incremented = value.join(" ");
-  const transformed = transformation?.(incremented) ?? incremented;
-  if (await validation(transformed)) {
-    return transformed;
-  }
-  return incrementValue({
-    value: [value[0], value[1] + 1],
-    validation,
-    maxRetries,
-    transformation,
-    attempts: attempts + 1
-  });
+/**
+ * Attempts to generate a unique value by appending and incrementing a counter to a base string.
+ *
+ * On each attempt, appends the next incrementing integer (e.g. "foo 1", "foo 2", etc.) to the original value,
+ * and checks with the validation function whether the candidate value is unique.
+ *
+ * Continues until a unique value is found, or the maximum number of attempts is reached.
+ *
+ * Returns the first unique value found, or undefined if a unique value cannot be generated within maxRetries.
+ *
+ * Example:
+ * ```ts
+ * const existing = new Set(['bar', 'bar 1']);
+ * const result = incrementValue({
+ *   value: ['bar', 1],
+ *   validation: (val) => !existing.has(val),
+ *   maxRetries: 5,
+ * });
+ * // result === "bar 2"
+ * ```
+ */
+async function incrementValue({ value, validation, maxRetries, attempts = 0, transformation, }) {
+    if (attempts >= maxRetries) {
+        return;
+    }
+    const incremented = value.join(' ');
+    const transformed = transformation?.(incremented) ?? incremented;
+    if (await validation(transformed)) {
+        return transformed;
+    }
+    return incrementValue({
+        value: [value[0], value[1] + 1],
+        validation,
+        maxRetries,
+        transformation,
+        attempts: attempts + 1,
+    });
 }
-export {
-  generateUniqueValue
-};
-//# sourceMappingURL=generate-unique-value.js.map

package/dist/helpers/get-fetch.js

@@ -1,11 +1,13 @@
-import { redirectToProxy } from "@scalar/helpers/url/redirect-to-proxy";
-const getFetch = (config) => {
-  if (config.fetch) {
-    return config.fetch;
-  }
-  return (input, init) => fetch(redirectToProxy(config.proxyUrl, input.toString()), init);
+import { redirectToProxy } from '@scalar/helpers/url/redirect-to-proxy';
+/**
+ * Get the fetch function from the configuration
+ *
+ * @param config - The API reference configuration.
+ * @returns The fetch function.
+ */
+export const getFetch = (config) => {
+    if (config.fetch) {
+        return config.fetch;
+    }
+    return ((input, init) => fetch(redirectToProxy(config.proxyUrl, input.toString()), init));
 };
-export {
-  getFetch
-};
-//# sourceMappingURL=get-fetch.js.map

package/dist/helpers/get-resolved-ref.js

@@ -1,13 +1,14 @@
 const defaultTransform = (node) => {
-  return node["$ref-value"];
+    return node['$ref-value'];
 };
-const getResolvedRef = (node, transform = defaultTransform) => {
-  if (typeof node === "object" && node !== null && "$ref" in node) {
-    return transform(node);
-  }
-  return node;
+/**
+ * Resolves a node that may be a $ref object to its actual value.
+ * If the node contains a $ref, applies the provided transform (default: returns '$ref-value').
+ * Otherwise, returns the node as-is.
+ */
+export const getResolvedRef = (node, transform = defaultTransform) => {
+    if (typeof node === 'object' && node !== null && '$ref' in node) {
+        return transform(node);
+    }
+    return node;
 };
-export {
-  getResolvedRef
-};
-//# sourceMappingURL=get-resolved-ref.js.map

package/dist/helpers/is-non-optional-security-requirement.js

@@ -1,7 +1,4 @@
-const isNonOptionalSecurityRequirement = (securityRequirement) => {
-  return securityRequirement !== void 0 && Object.keys(securityRequirement).length > 0;
+/** Type guard to determine if a security requirement is non-optional */
+export const isNonOptionalSecurityRequirement = (securityRequirement) => {
+    return securityRequirement !== undefined && Object.keys(securityRequirement).length > 0;
 };
-export {
-  isNonOptionalSecurityRequirement
-};
-//# sourceMappingURL=is-non-optional-security-requirement.js.map

package/dist/helpers/merge-object.js

@@ -1,34 +1,75 @@
-import { getRaw } from "@scalar/json-magic/magic-proxy";
-const mergeObjects = (a, b, replaceArrays = false, cache = /* @__PURE__ */ new Set()) => {
-  for (const key in b) {
-    if (!(key in a)) {
-      a[key] = b[key];
-    } else {
-      const aValue = a[key];
-      const bValue = b[key];
-      const shouldReplaceArrays = replaceArrays && (Array.isArray(aValue) || Array.isArray(bValue));
-      if (typeof aValue === "object" && aValue !== null && typeof bValue === "object" && bValue !== null && !shouldReplaceArrays) {
-        const rawA = getRaw(aValue);
-        const rawB = getRaw(bValue);
-        if (cache.has(rawA) || cache.has(rawB)) {
-          continue;
+import { getRaw } from '@scalar/json-magic/magic-proxy';
+/**
+ * Deep merges two objects, combining their properties recursively.
+ * Handles circular references by tracking visited objects to prevent infinite recursion.
+ *
+ * ⚠️ Note: This operation assumes there are no key collisions between the objects.
+ * Use isKeyCollisions() to check for collisions before merging.
+ *
+ * @param a - Target object to merge into
+ * @param b - Source object to merge from
+ * @param cache - Set of visited objects to prevent circular reference issues
+ * @returns The merged object (mutates and returns a)
+ *
+ * @example
+ * // Simple merge
+ * const a = { name: 'John' }
+ * const b = { age: 30 }
+ * mergeObjects(a, b) // { name: 'John', age: 30 }
+ *
+ * // Nested merge
+ * const a = { user: { name: 'John' } }
+ * const b = { user: { age: 30 } }
+ * mergeObjects(a, b) // { user: { name: 'John', age: 30 } }
+ *
+ * // Circular reference safe
+ * const obj = { name: 'John' }
+ * obj.self = obj
+ * const target = { age: 30 }
+ * mergeObjects(target, obj) // Safely merges without infinite recursion
+ */
+export const mergeObjects = (a, b, 
+/**
+ * By default we overwrite array indexes, our store is built on this assumption when coercing the document
+ * Alternatively we may want to prevent this behaviour when merging with defaults and replace the whole array instead
+ */
+replaceArrays = false, cache = new Set()) => {
+    for (const key in b) {
+        if (!(key in a)) {
+            a[key] = b[key];
         }
-        cache.add(rawA);
-        cache.add(rawB);
-        mergeObjects(aValue, bValue, replaceArrays, cache);
-      } else {
-        try {
-          a[key] = bValue;
-        } catch (error) {
-          console.warn(`Issue setting ${key} on object`);
-          console.warn(error);
+        else {
+            const aValue = a[key];
+            const bValue = b[key];
+            /** Replace whole array instead of replacing each index */
+            const shouldReplaceArrays = replaceArrays && (Array.isArray(aValue) || Array.isArray(bValue));
+            if (typeof aValue === 'object' &&
+                aValue !== null &&
+                typeof bValue === 'object' &&
+                bValue !== null &&
+                !shouldReplaceArrays) {
+                const rawA = getRaw(aValue);
+                const rawB = getRaw(bValue);
+                // Check for circular references before recursive merge
+                if (cache.has(rawA) || cache.has(rawB)) {
+                    // Skip merging this branch to prevent infinite recursion
+                    continue;
+                }
+                // Add objects to cache before recursive call
+                cache.add(rawA);
+                cache.add(rawB);
+                mergeObjects(aValue, bValue, replaceArrays, cache);
+            }
+            else {
+                try {
+                    a[key] = bValue; // Overwrite with b's value if not an object
+                }
+                catch (error) {
+                    console.warn(`Issue setting ${key} on object`);
+                    console.warn(error);
+                }
+            }
         }
-      }
     }
-  }
-  return a;
+    return a;
 };
-export {
-  mergeObjects
-};
-//# sourceMappingURL=merge-object.js.map