feat(core): Export FacetValueChecker promotion utility

packages/core/src/config/promotion/index.ts

@@ -15,6 +15,7 @@ export * from './conditions/has-facet-values-condition';
 export * from './conditions/min-order-amount-condition';
 export * from './conditions/contains-products-condition';
 export * from './conditions/customer-group-condition';
+export * from './utils/facet-value-checker';
 
 export const defaultPromotionActions = [
     orderPercentageDiscount,

packages/core/src/config/promotion/utils/facet-value-checker.ts

@@ -7,6 +7,44 @@ import { OrderLine } from '../../../entity/order-line/order-line.entity';
 import { ProductVariant } from '../../../entity/product-variant/product-variant.entity';
 import { TransactionalConnection } from '../../../service/transaction/transactional-connection';
 
+/**
+ * @description
+ * The FacetValueChecker is a helper class used to determine whether a given OrderLine consists
+ * of ProductVariants containing the given FacetValues.
+ *
+ * @example
+ * ```TypeScript
+ * import { FacetValueChecker, LanguageCode, PromotionCondition, TransactionalConnection } from '\@vendure/core';
+ *
+ * let facetValueChecker: FacetValueChecker;
+ *
+ * export const hasFacetValues = new PromotionCondition({
+ *   code: 'at_least_n_with_facets',
+ *   description: [
+ *     { languageCode: LanguageCode.en, value: 'Buy at least { minimum } products with the given facets' },
+ *   ],
+ *   args: {
+ *     minimum: { type: 'int' },
+ *     facets: { type: 'ID', list: true, ui: { component: 'facet-value-form-input' } },
+ *   },
+ *   init(injector) {
+ *     facetValueChecker = new FacetValueChecker(injector.get(TransactionalConnection));
+ *   },
+ *   // tslint:disable-next-line:no-shadowed-variable
+ *   async check(ctx, order, args) {
+ *     let matches = 0;
+ *     for (const line of order.lines) {
+ *       if (await facetValueChecker.hasFacetValues(line, args.facets)) {
+ *           matches += line.quantity;
+ *       }
+ *     }
+ *     return args.minimum <= matches;
+ *   },
+ * });
+ * ```
+ *
+ * @docsCategory Promotions
+ */
 export class FacetValueChecker {
     private variantCache = new TtlCache<ID, ProductVariant>({ ttl: 5000 });