@scayle/storefront-core 8.7.0 → 8.8.0

package/dist/cache/cached.d.ts

@@ -1,25 +1,118 @@
 import type { Log } from '../utils';
 import type { Cache as CacheInterface } from './cache';
+/**
+ * Number of seconds in a minute, used for calculating cache TTL.
+ */
 export declare const MINUTE = 60;
+/**
+ * Options for configuring the caching behavior.
+ */
 export type CacheOptions = Partial<{
+    /**
+     * The TTL (Time-To-Live) of the cache entry in seconds.
+     * Defaults to one hour if not set.
+     */
     ttl: number;
+    /**
+     * Custom cache key. If not provided, one will be generated automatically.
+     */
     cacheKey: string;
+    /**
+     * Prefix for the generated cache key. Defaults to the function name.
+     */
     cacheKeyPrefix: string;
+    /**
+     * Timeout in milliseconds for cache operations (get and set).
+     */
     timeout: number;
 }>;
+/**
+ * Type representing an asynchronous function.
+ *
+ * @template TArgs The type of the function's arguments.
+ * @template TResult The return type of the function.
+ */
 type Fn<TArgs extends unknown[], TResult> = (...args: TArgs) => Promise<TResult>;
+/**
+ * A class for caching the results of asynchronous function calls.
+ */
 export declare class Cached {
     private cache;
     private log;
     private prefix;
     private enabled;
+    /**
+     * Creates a new Cached instance.
+     *
+     * @param cache The cache implementation to use.
+     * @param log The logger instance.
+     * @param prefix An optional prefix for cache keys.
+     * @param enabled Whether caching is enabled.
+     *
+     * @throws {Error} If the cache is not initialized.
+     */
     constructor(cache: CacheInterface, log: Log, prefix: string | number | undefined, enabled: boolean);
+    /**
+     * Whether caching is enabled.
+     */
     get isCacheEnabled(): boolean | undefined;
+    /**
+     * Executes a function and caches its result.
+     *
+     * @param fn The asynchronous function to execute.
+     * @param options Optional cache options.
+     *
+     * @returns A wrapped function that handles caching.
+     *
+     * @template TArgs The type of the function's arguments.
+     * @template TResult The return type of the function.
+     */
     execute<TArgs extends unknown[], TResult>(fn: Fn<TArgs, TResult>, options?: CacheOptions): Awaited<Fn<TArgs, TResult>>;
+    /**
+     * Retrieves a cached value from the cache.
+     *
+     * @param cacheKey The key of the cached value.
+     * @param options Optional cache options.
+     *
+     * @returns A promise that resolves with the cached value or undefined if not found or caching is disabled.
+     *
+     * @private
+     */
     private getCacheValue;
+    /**
+     * Sets a value in the cache.
+     *
+     * @param cacheKey The key to store the value under.
+     * @param value The value to store in the cache.
+     * @param options Optional cache options.
+     *
+     * @returns A promise that resolves when the value is set or undefined if caching is disabled.
+     *
+     * @private
+     */
     private setCacheValue;
+    /**
+     * Creates a cache key from the given parameters and prefix.
+     *
+     * @param params The parameters to use for generating the key.
+     * @param prefix An optional prefix for the key.
+     *
+     * @returns The generated cache key.
+     *
+     * @private
+     */
     private createCacheKey;
+    /**
+     * Handles errors during cache operations.
+     *
+     * @param error The error that occurred.
+     *
+     * @private
+     */
     private handleError;
 }
 export type { Cache as CacheInterface } from './cache';
+/**
+ * Type representing the `execute` method of the `Cached` class.
+ */
 export type CachedType = Cached['execute'];

package/dist/cache/cached.mjs

@@ -8,6 +8,16 @@ export class Cached {
   log;
   prefix;
   enabled;
+  /**
+   * Creates a new Cached instance.
+   *
+   * @param cache The cache implementation to use.
+   * @param log The logger instance.
+   * @param prefix An optional prefix for cache keys.
+   * @param enabled Whether caching is enabled.
+   *
+   * @throws {Error} If the cache is not initialized.
+   */
   constructor(cache, log, prefix = "", enabled) {
     if (!cache) {
       log.error(CACHE_NOT_INITIALIZED_MSG);
@@ -18,9 +28,23 @@ export class Cached {
     this.prefix = prefix;
     this.enabled = enabled;
   }
+  /**
+   * Whether caching is enabled.
+   */
   get isCacheEnabled() {
     return this.enabled;
   }
+  /**
+   * Executes a function and caches its result.
+   *
+   * @param fn The asynchronous function to execute.
+   * @param options Optional cache options.
+   *
+   * @returns A wrapped function that handles caching.
+   *
+   * @template TArgs The type of the function's arguments.
+   * @template TResult The return type of the function.
+   */
   execute(fn, options) {
     return async (...args) => {
       const prefix = options?.cacheKeyPrefix ?? fn.name;
@@ -53,6 +77,16 @@ export class Cached {
       return response;
     };
   }
+  /**
+   * Retrieves a cached value from the cache.
+   *
+   * @param cacheKey The key of the cached value.
+   * @param options Optional cache options.
+   *
+   * @returns A promise that resolves with the cached value or undefined if not found or caching is disabled.
+   *
+   * @private
+   */
   async getCacheValue(cacheKey, options) {
     if (!this.isCacheEnabled) {
       return;
@@ -65,6 +99,17 @@ export class Cached {
       return data;
     }
   }
+  /**
+   * Sets a value in the cache.
+   *
+   * @param cacheKey The key to store the value under.
+   * @param value The value to store in the cache.
+   * @param options Optional cache options.
+   *
+   * @returns A promise that resolves when the value is set or undefined if caching is disabled.
+   *
+   * @private
+   */
   async setCacheValue(cacheKey, value, options) {
     if (!this.isCacheEnabled) {
       return;
@@ -74,9 +119,26 @@ export class Cached {
       await timeout(CACHE_TIMEOUT, this.cache.set(cacheKey, value, ttl));
     }
   }
+  /**
+   * Creates a cache key from the given parameters and prefix.
+   *
+   * @param params The parameters to use for generating the key.
+   * @param prefix An optional prefix for the key.
+   *
+   * @returns The generated cache key.
+   *
+   * @private
+   */
   async createCacheKey(params, prefix = "") {
     return [prefix, await sha256(JSON.stringify(params))].join(":");
   }
+  /**
+   * Handles errors during cache operations.
+   *
+   * @param error The error that occurred.
+   *
+   * @private
+   */
   handleError(error) {
     if (error.message === "timeout") {
       return this.log.error("Cache timeout");

package/dist/cache/providers/unstorage.d.ts

@@ -1,16 +1,80 @@
 import type { Storage } from 'unstorage';
 import type { Cache as CacheInterface } from '../cache';
 export declare class UnstorageCache implements CacheInterface {
+    /**
+     * The underlying Unstorage storage instance.
+     */
     storage: Storage;
+    /**
+     * Key prefix used for namespacing cache entries.
+     */
     prefix: string;
+    /**
+     * Creates a new UnstorageCache instance.
+     *
+     * @param storage The Unstorage storage instance.
+     * @param prefix Optional key prefix for namespacing. Defaults to an empty string.
+     */
     constructor(storage: Storage, prefix?: string);
+    /**
+     * Retrieves a cached value by key.
+     *
+     * @param key The cache key.
+     * @returns The cached value or null if not found.
+     */
     get(key: string): Promise<any | null>;
+    /**
+     * Checks if a key exists in the cache.
+     *
+     * @param key The cache key.
+     * @returns True if the key exists, false otherwise.
+     */
     has(key: string): Promise<boolean>;
+    /**
+     * Purges cache entries associated with the given tags.
+     *
+     * @param tags An array of tags to purge.
+     */
     purgeTags(tags: string[]): Promise<void>;
+    /**
+     * Purges cache entries associated with a specific tag.
+     *
+     * @param tag The tag to purge.
+     */
     purgeTag(tag: string): Promise<void>;
+    /**
+     * Purges cache entries by their keys.
+     *
+     * @param keys An array of keys to purge.
+     */
     purgeKeys(keys: string[]): Promise<void>;
+    /**
+     * Purges all cache entries.
+     */
     purgeAll(): Promise<void>;
+    /**
+     * Sets a value in the cache.
+     *
+     * @param key The cache key.
+     * @param value The value to cache.
+     * @param ttl Time-to-live in milliseconds.
+     * @param tags Optional tags to associate with the cache entry.
+     */
     set(key: string, value: any, ttl: number, tags?: string[]): Promise<void>;
+    /**
+     * Adds a key to a tag's list of associated keys.
+     *
+     * @param tag The tag.
+     * @param key The key to add.
+     * @private
+     */
     private addKeyToTag;
+    /**
+     * Generates a namespaced key.
+     *
+     * @param key The key to namespace.
+     * @returns The namespaced key.
+     * @private
+     */
     private getKey;
 }

package/dist/cache/providers/unstorage.mjs

@@ -1,10 +1,28 @@
 export class UnstorageCache {
+  /**
+   * The underlying Unstorage storage instance.
+   */
   storage;
+  /**
+   * Key prefix used for namespacing cache entries.
+   */
   prefix;
+  /**
+   * Creates a new UnstorageCache instance.
+   *
+   * @param storage The Unstorage storage instance.
+   * @param prefix Optional key prefix for namespacing. Defaults to an empty string.
+   */
   constructor(storage, prefix = "") {
     this.storage = storage;
     this.prefix = prefix;
   }
+  /**
+   * Retrieves a cached value by key.
+   *
+   * @param key The cache key.
+   * @returns The cached value or null if not found.
+   */
   async get(key) {
     const value = await this.storage.getItem(this.getKey(key));
     if (value === null) {
@@ -12,36 +30,82 @@ export class UnstorageCache {
     }
     return value;
   }
+  /**
+   * Checks if a key exists in the cache.
+   *
+   * @param key The cache key.
+   * @returns True if the key exists, false otherwise.
+   */
   async has(key) {
     return await this.storage.hasItem(this.getKey(key));
   }
+  /**
+   * Purges cache entries associated with the given tags.
+   *
+   * @param tags An array of tags to purge.
+   */
   async purgeTags(tags) {
     await Promise.all(tags.map((tag) => this.purgeTag(tag)));
   }
+  /**
+   * Purges cache entries associated with a specific tag.
+   *
+   * @param tag The tag to purge.
+   */
   async purgeTag(tag) {
     const keys = await this.storage.getItem(this.getKey(`tag:${tag}`));
     await this.purgeKeys(keys ?? []);
     await this.storage.removeItem(this.getKey(`tag:${tag}`));
   }
+  /**
+   * Purges cache entries by their keys.
+   *
+   * @param keys An array of keys to purge.
+   */
   async purgeKeys(keys) {
     await Promise.all(keys.map((k) => this.storage.removeItem(k)));
   }
+  /**
+   * Purges all cache entries.
+   */
   async purgeAll() {
     const keys = await this.storage.getKeys(this.prefix);
     await Promise.all(keys.map((k) => this.storage.removeItem(k)));
   }
+  /**
+   * Sets a value in the cache.
+   *
+   * @param key The cache key.
+   * @param value The value to cache.
+   * @param ttl Time-to-live in milliseconds.
+   * @param tags Optional tags to associate with the cache entry.
+   */
   async set(key, value, ttl, tags = []) {
     await this.storage.setItem(this.getKey(key), value, { ttl });
     await Promise.all(
       tags.map((tag) => this.addKeyToTag(tag, this.getKey(key)))
     );
   }
+  /**
+   * Adds a key to a tag's list of associated keys.
+   *
+   * @param tag The tag.
+   * @param key The key to add.
+   * @private
+   */
   async addKeyToTag(tag, key) {
     const keys = await this.storage.getItem(tag);
     const set = new Set(keys ?? []);
     set.add(key);
     await this.storage.setItem(this.getKey(`tag:${tag}`), Array.from(set));
   }
+  /**
+   * Generates a namespaced key.
+   *
+   * @param key The key to namespace.
+   * @returns The namespaced key.
+   * @private
+   */
   getKey(key) {
     return [this.prefix, key].join(":");
   }

package/dist/constants/cache.d.ts

@@ -1 +1,5 @@
+/**
+ * Default cache timeout duration in milliseconds.
+ * Initially set to 300ms, currently 500ms.
+ */
 export declare const CACHE_TIMEOUT = 500;

package/dist/constants/hash.d.ts

@@ -1,5 +1,9 @@
 import type { ValuesType } from 'utility-types';
+/**
+ * Available hash algorithms.
+ */
 export declare const HashAlgorithm: {
+    /** @deprecated */
     readonly MD5: "md5";
     readonly SHA256: "sha256";
     readonly NONE: "none";

package/dist/constants/hash.mjs

@@ -1,4 +1,5 @@
 export const HashAlgorithm = {
+  /** @deprecated */
   MD5: "md5",
   SHA256: "sha256",
   NONE: "none"

package/dist/constants/httpStatus.d.ts

@@ -1,4 +1,9 @@
 import type { ValuesType } from 'utility-types';
+/**
+ * HTTP Status Codes.  See {@link HttpStatusMessage} for the corresponding status text.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
+ */
 declare const HttpStatusCode: {
     /**
      * The server has received the request headers and the client should proceed to send the request body
@@ -85,7 +90,7 @@ declare const HttpStatusCode: {
      * The HTTP/1.0 specification (RFC 1945) required the client to perform a temporary redirect
      * (the original describing phrase was "Moved Temporarily"), but popular browsers implemented 302
      * with the functionality of a 303 See Other. Therefore, HTTP/1.1 added status codes 303 and 307
-     * to distinguish between the two behaviours. However, some Web applications and frameworks
+     * to distinguish between the two behaviors. However, some Web applications and frameworks
      * use the 302 status code as if it were the 303.
      */
     readonly FOUND: 302;
@@ -313,6 +318,11 @@ declare const HttpStatusCode: {
      */
     readonly NETWORK_AUTHENTICATION_REQUIRED: 511;
 };
+/**
+ * HTTP Status Messages corresponding to the {@link HttpStatusCode} codes.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
+ */
 declare const HttpStatusMessage: {
     /**
      * The server has received the request headers and the client should proceed to send the request body
@@ -399,7 +409,7 @@ declare const HttpStatusMessage: {
      * The HTTP/1.0 specification (RFC 1945) required the client to perform a temporary redirect
      * (the original describing phrase was "Moved Temporarily"), but popular browsers implemented 302
      * with the functionality of a 303 See Other. Therefore, HTTP/1.1 added status codes 303 and 307
-     * to distinguish between the two behaviours. However, some Web applications and frameworks
+     * to distinguish between the two behaviors. However, some Web applications and frameworks
      * use the 302 status code as if it were the 303.
      */
     readonly FOUND: "FOUND";

package/dist/constants/httpStatus.mjs

@@ -84,7 +84,7 @@ const HttpStatusCode = {
    * The HTTP/1.0 specification (RFC 1945) required the client to perform a temporary redirect
    * (the original describing phrase was "Moved Temporarily"), but popular browsers implemented 302
    * with the functionality of a 303 See Other. Therefore, HTTP/1.1 added status codes 303 and 307
-   * to distinguish between the two behaviours. However, some Web applications and frameworks
+   * to distinguish between the two behaviors. However, some Web applications and frameworks
    * use the 302 status code as if it were the 303.
    */
   FOUND: 302,
@@ -398,7 +398,7 @@ const HttpStatusMessage = {
    * The HTTP/1.0 specification (RFC 1945) required the client to perform a temporary redirect
    * (the original describing phrase was "Moved Temporarily"), but popular browsers implemented 302
    * with the functionality of a 303 See Other. Therefore, HTTP/1.1 added status codes 303 and 307
-   * to distinguish between the two behaviours. However, some Web applications and frameworks
+   * to distinguish between the two behaviors. However, some Web applications and frameworks
    * use the 302 status code as if it were the 303.
    */
   FOUND: "FOUND",

package/dist/constants/product.d.ts

@@ -1,4 +1,7 @@
 import type { ValuesType } from 'utility-types';
+/**
+ * Types of product images.
+ */
 export declare const ProductImageType: {
     readonly MODEL: "model";
     readonly BUST: "bust";

package/dist/constants/promotion.d.ts

@@ -1,2 +1,8 @@
+/**
+ * The default page number for promotion listings.
+ */
 export declare const PROMOTION_PAGE_DEFAULT = 1;
+/**
+ * The default number of promotions per page.
+ */
 export declare const PROMOTION_PER_PAGE_DEFAULT = 100;

package/dist/constants/sorting.d.ts

@@ -1,4 +1,7 @@
 import type { ValuesType } from 'utility-types';
+/**
+ * Enumeration of sort options by internal name.
+ */
 declare const SortName: {
     readonly TOPSELLER: "topseller";
     readonly DATE_NEWEST: "date_newest";
@@ -7,6 +10,9 @@ declare const SortName: {
     readonly REDUCTION_DESC: "reduction_desc";
     readonly REDUCTION_ASC: "reduction_asc";
 };
+/**
+ * Enumeration of sort options as used in query parameters.
+ */
 declare const SortQuery: {
     readonly TOPSELLER: "topseller";
     readonly DATE_NEWEST: "date-newest";

package/dist/constants/withParameters.d.ts

@@ -1,4 +1,9 @@
 import type { BasketWith, ProductWith, SearchWith, WishlistWith } from '../types';
+/**
+ * Default `with` parameters for product listings.
+ * Requests all available attributes, advanced attributes, variants, images,
+ * category properties, and price range information.
+ */
 declare const DEFAULT_WITH_LISTING: {
     items: {
         product: {
@@ -19,9 +24,32 @@ declare const DEFAULT_WITH_LISTING: {
         };
     };
 };
+/**
+ * Minimum required `with` parameters for search requests.
+ * Includes essential product attributes, variant attributes, and category properties.
+ */
 declare const MIN_WITH_PARAMS_SEARCH: SearchWith;
+/**
+ * Minimum required `with` parameters for single product requests.
+ * Includes essential product attributes, variant attributes, images,
+ * category properties, and sibling information.
+ */
 declare const MIN_WITH_PARAMS_PRODUCT: ProductWith;
+/**
+ * Minimum required `with` parameters for basket requests.
+ * Includes essential product and variant information, images, categories,
+ * price range, and lowest prior price.
+ */
 declare const MIN_WITH_PARAMS_BASKET: BasketWith;
+/**
+ * Minimum required `with` parameters for wishlist requests.
+ * Includes essential product and variant attributes, images, categories,
+ * price range, and lowest prior price.
+ */
 declare const MIN_WITH_PARAMS_WISHLIST: WishlistWith;
+/**
+ * Minimum required `with` parameters for variant requests.
+ * Includes size-related attributes.
+ */
 declare const MIN_WITH_PARAMS_VARIANT: ProductWith;
 export { DEFAULT_WITH_LISTING, MIN_WITH_PARAMS_BASKET, MIN_WITH_PARAMS_SEARCH, MIN_WITH_PARAMS_PRODUCT, MIN_WITH_PARAMS_WISHLIST, MIN_WITH_PARAMS_VARIANT, };

package/dist/errors/errorResponse.d.ts

@@ -1,12 +1,49 @@
+/**
+ * Interface representing details of an error response. Conforms to RFC 7807.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7807
+ */
 interface ErrorResponseDetails {
+    /**
+     * A human-readable explanation specific to this occurrence of the problem.
+     */
     detail?: string;
+    /**
+     * A URI reference that identifies the specific occurrence of the problem.
+     */
     instance?: string;
+    /**
+     * A URI reference that identifies the general problem type.
+     */
     type?: string;
+    /**
+     * Allows for additional properties as needed.
+     */
     [s: string]: unknown | undefined;
 }
+/**
+ * Error response based on RFC 9457 (Problem Details for HTTP APIs).
+ * Extends the standard Response object to include structured error information.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc9457
+ */
 export declare class ErrorResponse extends Response {
+    /**
+     * A short, human-readable summary of the problem type.  SHOULD NOT change from occurrence to occurrence of the problem.
+     */
     title: string;
+    /**
+     * Additional details about the error.
+     */
     details?: ErrorResponseDetails;
+    /**
+     * Creates a new ErrorResponse.
+     *
+     * @param statusCode The HTTP status code.
+     * @param statusMessage  The HTTP status message.
+     * @param title A short, human-readable summary of the problem type.
+     * @param detail Optional details about the error.
+     */
     constructor(statusCode: number, statusMessage: string, title: string, detail?: ErrorResponseDetails);
 }
 export {};

package/dist/errors/errorResponse.mjs

@@ -1,6 +1,20 @@
 export class ErrorResponse extends Response {
+  /**
+   * A short, human-readable summary of the problem type.  SHOULD NOT change from occurrence to occurrence of the problem.
+   */
   title;
+  /**
+   * Additional details about the error.
+   */
   details;
+  /**
+   * Creates a new ErrorResponse.
+   *
+   * @param statusCode The HTTP status code.
+   * @param statusMessage  The HTTP status message.
+   * @param title A short, human-readable summary of the problem type.
+   * @param detail Optional details about the error.
+   */
   constructor(statusCode, statusMessage, title, detail) {
     const response = {
       title,

package/dist/helpers/filterHelper.mjs

@@ -135,7 +135,7 @@ export const getFilterablePriceValue = (filterableValues, key = "min") => {
 };
 export const serializeFilters = (filter) => {
   if (Object.keys(filter).length === 0) {
-    return void 0;
+    return;
   }
   return Object.assign(
     {},