docs(core): Add docs for service helpers

Relates to #1707

packages/core/src/service/helpers/order-calculator/order-calculator.ts

@@ -20,6 +20,17 @@ import { ShippingCalculator } from '../shipping-calculator/shipping-calculator';
 
 import { prorate } from './prorate';
 
+/**
+ * @description
+ * This helper is used when making changes to an Order, to apply all applicable price adjustments to that Order,
+ * including:
+ *
+ * - Promotions
+ * - Taxes
+ * - Shipping
+ *
+ * @docsCategory service-helpers
+ */
 @Injectable()
 export class OrderCalculator {
     constructor(
@@ -32,6 +43,7 @@ export class OrderCalculator {
     ) {}
 
     /**
+     * @description
      * Applies taxes and promotions to an Order. Mutates the order object.
      * Returns an array of any OrderItems which had new adjustments
      * applied, either tax or promotions.
@@ -95,6 +107,7 @@ export class OrderCalculator {
     }
 
     /**
+     * @description
      * Applies the correct TaxRate to each OrderItem in the order.
      */
     private async applyTaxes(ctx: RequestContext, order: Order, activeZone: Zone) {
@@ -106,6 +119,7 @@ export class OrderCalculator {
     }
 
     /**
+     * @description
      * Applies the correct TaxRate to an OrderLine
      */
     private async applyTaxesToOrderLine(
@@ -129,6 +143,7 @@ export class OrderCalculator {
     }
 
     /**
+     * @description
      * Returns a memoized function for performing an efficient
      * lookup of the correct TaxRate for a given TaxCategory.
      */
@@ -150,6 +165,7 @@ export class OrderCalculator {
     }
 
     /**
+     * @description
      * Applies any eligible promotions to each OrderItem in the order. Returns an array of
      * any OrderItems which had their Adjustments modified.
      */
@@ -168,6 +184,7 @@ export class OrderCalculator {
     }
 
     /**
+     * @description
      * Applies promotions to OrderItems. This is a quite complex function, due to the inherent complexity
      * of applying the promotions, and also due to added complexity in the name of performance
      * optimization. Therefore it is heavily annotated so that the purpose of each step is clear.
@@ -253,6 +270,7 @@ export class OrderCalculator {
     }
 
     /**
+     * @description
      * An OrderLine may have promotion adjustments from Promotions which are no longer applicable.
      * For example, a coupon code might have caused a discount to be applied, and now that code has
      * been removed from the order. The adjustment will still be there on each OrderItem it was applied

packages/core/src/service/helpers/order-modifier/order-modifier.ts

@@ -61,6 +61,8 @@ import { translateDeep } from '../utils/translate-entity';
  * So this helper was mainly extracted to isolate the huge `modifyOrder` method since the
  * OrderService was just growing too large. Future refactoring could improve the organization
  * of these Order-related methods into a more clearly-delineated set of classes.
+ *
+ * @docsCategory service-helpers
  */
 @Injectable()
 export class OrderModifier {
@@ -80,6 +82,7 @@ export class OrderModifier {
     ) {}
 
     /**
+     * @description
      * Ensure that the ProductVariant has sufficient saleable stock to add the given
      * quantity to an Order.
      */
@@ -97,6 +100,11 @@ export class OrderModifier {
         return correctedQuantity;
     }
 
+    /**
+     * @description
+     * Given a ProductVariant ID and optional custom fields, this method will return an existing OrderLine that
+     * matches, or `undefined` if no match is found.
+     */
     async getExistingOrderLine(
         ctx: RequestContext,
         order: Order,
@@ -114,6 +122,7 @@ export class OrderModifier {
     }
 
     /**
+     * @description
      * Returns the OrderLine to which a new OrderItem belongs, creating a new OrderLine
      * if no existing line is found.
      */
@@ -162,6 +171,7 @@ export class OrderModifier {
     }
 
     /**
+     * @description
      * Updates the quantity of an OrderLine, taking into account the available saleable stock level.
      * Returns the actual quantity that the OrderLine was updated to (which may be less than the
      * `quantity` argument if insufficient stock was available.

packages/core/src/service/helpers/product-price-applicator/product-price-applicator.ts

@@ -13,7 +13,30 @@ import { ZoneService } from '../../services/zone.service';
 /**
  * @description
  * This helper is used to apply the correct price to a ProductVariant based on the current context
- * including active Channel, any current Order, etc.
+ * including active Channel, any current Order, etc. If you use the {@link TransactionalConnection} to
+ * directly query ProductVariants, you will find that the `price` and `priceWithTax` properties will
+ * always be `0` until you use the `applyChannelPriceAndTax()` method:
+ *
+ * @example
+ * ```TypeScript
+ * export class MyCustomService {
+ *   constructor(private connection: TransactionalConnection,
+ *               private productPriceApplicator: ProductPriceApplicator) {}
+ *
+ *   getVariant(ctx: RequestContext, id: ID) {
+ *     const productVariant = await this.connection
+ *       .getRepository(ctx, ProductVariant)
+ *       .findOne(id);
+ *
+ *     await this.productPriceApplicator
+ *       .applyChannelPriceAndTax(productVariant, ctx);
+ *
+ *     return productVariant;
+ *   }
+ * }
+ * ```
+ *
+ * @docsCategory service-helpers
  */
 @Injectable()
 export class ProductPriceApplicator {

packages/core/src/service/helpers/slug-validator/slug-validator.ts

@@ -8,6 +8,10 @@ import { TransactionalConnection } from '../../../connection/transactional-conne
 import { VendureEntity } from '../../../entity/base/base.entity';
 import { ProductOptionGroup } from '../../../entity/product-option-group/product-option-group.entity';
 
+/**
+ * @docsCategory service-helpers
+ * @docsPage SlugValidator
+ */
 export type InputWithSlug = {
     id?: ID | null;
     translations?: Array<{
@@ -17,6 +21,10 @@ export type InputWithSlug = {
     }> | null;
 };
 
+/**
+ * @docsCategory service-helpers
+ * @docsPage SlugValidator
+ */
 export type TranslationEntity = VendureEntity & {
     id: ID;
     languageCode: LanguageCode;
@@ -24,6 +32,14 @@ export type TranslationEntity = VendureEntity & {
     base: any;
 };
 
+/**
+ * @description
+ * Used to validate slugs to ensure they are URL-safe and unique. Designed to be used with translatable
+ * entities such as {@link Product} and {@link Collection}.
+ *
+ * @docsCategory service-helpers
+ * @docsWeight 0
+ */
 @Injectable()
 export class SlugValidator {
     constructor(private connection: TransactionalConnection) {}
@@ -53,7 +69,7 @@ export class SlugValidator {
                             .where(`translation.slug = :slug`, { slug: t.slug })
                             .andWhere(`translation.languageCode = :languageCode`, {
                                 languageCode: t.languageCode,
-                            })
+                            });
                         if (input.id) {
                             qb.andWhere(`translation.base != :id`, { id: input.id });
                         }

packages/core/src/service/helpers/translatable-saver/translatable-saver.ts

@@ -25,13 +25,39 @@ export interface UpdateTranslatableOptions<T extends Translatable> extends Creat
 }
 
 /**
- * A helper which contains methods for creating and updating entities which implement the Translatable interface.
+ * @description
+ * A helper which contains methods for creating and updating entities which implement the {@link Translatable} interface.
+ *
+ * @example
+ * ```TypeScript
+ * export class MyService {
+ *   constructor(private translatableSaver: TranslatableSaver) {}
+ *
+ *   async create(ctx: RequestContext, input: CreateFacetInput): Promise<Translated<Facet>> {
+ *     const facet = await this.translatableSaver.create({
+ *       ctx,
+ *       input,
+ *       entityType: Facet,
+ *       translationType: FacetTranslation,
+ *       beforeSave: async f => {
+ *           f.code = await this.ensureUniqueCode(ctx, f.code);
+ *       },
+ *     });
+ *     return facet;
+ *   }
+ *
+ *   // ...
+ * }
+ * ```
+ *
+ * @docsCategory service-helpers
  */
 @Injectable()
 export class TranslatableSaver {
     constructor(private connection: TransactionalConnection) {}
 
     /**
+     * @description
      * Create a translatable entity, including creating any translation entities according
      * to the `translations` array.
      */
@@ -59,6 +85,7 @@ export class TranslatableSaver {
     }
 
     /**
+     * @description
      * Update a translatable entity. Performs a diff of the `translations` array in order to
      * perform the correct operation on the translations.
      */