chore: added and improved TSDoc of pricing module (#5335)

* adjusted tsdoc of methods and types in pricing module

* finished adding tsdocs

* small fixes

* remove reference files

* added github action

* fix typo in outPath

* Update packages/types/src/shared-context.ts

Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>

* fix sharedContext description

* changed branch name of action

* added ignore for is_dynamic

* added private remark

---------

Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>

packages/types/src/common/common.ts

@@ -40,6 +40,22 @@ export type Writable<T> = {
     | FindOperator<string[]>
 }
 
+/**
+ * @interface
+ * 
+ * An object that is used to configure how an entity is retrieved from the database. It accepts as a typed parameter an `Entity` class, 
+ * which provides correct typing of field names in its properties.
+ * 
+ * @prop select - An array of strings, each being attribute names of the entity to retrieve in the result.
+ * @prop skip - A number indicating the number of records to skip before retrieving the results.
+ * @prop take - A number indicating the number of records to return in the result.
+ * @prop relations - An array of strings, each being relation names of the entity to retrieve in the result.
+ * @prop order - 
+ * An object used to specify how to sort the returned records. Its keys are the names of attributes of the entity, and a key's value can either be `ASC` 
+ * to sort retrieved records in an ascending order, or `DESC` to sort retrieved records in a descending order.
+ * @prop withDeleted - A boolean indicating whether deleted records should also be retrieved as part of the result. This only works if the entity extends the
+ * `SoftDeletableEntity` class.
+ */
 export interface FindConfig<Entity> {
   select?: (keyof Entity | string)[]
   skip?: number

packages/types/src/dal/index.ts

@@ -1,6 +1,15 @@
 import { Dictionary, FilterQuery, Order } from "./utils"
 
 export { FilterQuery } from "./utils"
+
+/**
+ * @interface
+ * 
+ * An object used to allow specifying flexible queries with and/or conditions.
+ * 
+ * @prop $and - An array of filters to apply on the entity, where each item in the array is joined with an "and" condition.
+ * @prop $or - An array of filters to apply on the entity, where each item in the array is joined with an "or" condition.
+ */
 export interface BaseFilterable<T> {
   $and?: (T | BaseFilterable<T>)[]
   $or?: (T | BaseFilterable<T>)[]

packages/types/src/pricing/common/currency.ts

@@ -1,5 +1,17 @@
 import { BaseFilterable } from "../../dal"
 
+/**
+ * @interface
+ * 
+ * An object representing a currency.
+ * 
+ * @prop code - a string indicating the code of the currency.
+ * @prop symbol - a string indicating the symbol of the currency.
+ * @prop symbol_native - 
+ * a string indicating the symbol of the currecy in its native form.
+ * This is typically the symbol used when displaying a price.
+ * @prop name - a string indicating the name of the currency.
+ */
 export interface CurrencyDTO {
   code: string
   symbol?: string
@@ -7,6 +19,18 @@ export interface CurrencyDTO {
   name?: string
 }
 
+/**
+ * @interface
+ * 
+ * An object that holds data to create a currency.
+ * 
+ * @prop code - a string indicating the code of the currency.
+ * @prop symbol - a string indicating the symbol of the currency.
+ * @prop symbol_native - 
+ * a string indicating the symbol of the currecy in its native form.
+ * This is typically the symbol used when displaying a price.
+ * @prop name - a string indicating the name of the currency.
+ */
 export interface CreateCurrencyDTO {
   code: string
   symbol: string
@@ -14,6 +38,18 @@ export interface CreateCurrencyDTO {
   name: string
 }
 
+/**
+ * @interface
+ * 
+ * An object that holds data to update a currency. The currency code must be provided to identify which currency to update.
+ * 
+ * @prop code - a string indicating the code of the currency to update.
+ * @prop symbol - a string indicating the symbol of the currency.
+ * @prop symbol_native - 
+ * a string indicating the symbol of the currecy in its native form.
+ * This is typically the symbol used when displaying a price.
+ * @prop name - a string indicating the name of the currency.
+ */
 export interface UpdateCurrencyDTO {
   code: string
   symbol?: string
@@ -21,6 +57,13 @@ export interface UpdateCurrencyDTO {
   name?: string
 }
 
+/**
+ * @interface
+ * 
+ * An object used to filter retrieved currencies.
+ * 
+ * @prop code - an array of strings, each being a currency code to filter the currencies.
+ */
 export interface FilterableCurrencyProps
   extends BaseFilterable<FilterableCurrencyProps> {
   code?: string[]

packages/types/src/pricing/common/money-amount.ts

@@ -1,6 +1,18 @@
 import { BaseFilterable } from "../../dal"
 import { CreateCurrencyDTO, CurrencyDTO } from "./currency"
 
+/**
+ * @interface
+ * 
+ * An object that holds prices, which typically belong to a price set.
+ * 
+ * @prop id - A string that indicates the ID of the money amount. A money amount represents a price.
+ * @prop currency_code - A string that indicates the currency code of this price.
+ * @prop currency - An object of type {@link CurrencyDTO} that holds the details of the price's currency. Since this is a relation, it will only be retrieved if it's passed to the `relations` array of the find-configuration options.
+ * @prop amount - A number indicating the amount of this price.
+ * @prop min_quantity - A number that indicates the minimum quantity required to be purchased for this price to be applied.
+ * @prop max_quantity - A number that indicates the maximum quantity required to be purchased for this price to be applied.
+ */
 export interface MoneyAmountDTO {
   id: string
   currency_code?: string
@@ -10,6 +22,18 @@ export interface MoneyAmountDTO {
   max_quantity?: number
 }
 
+/**
+ *  * @interface
+ * 
+ * An object that holds data to create a money amount.
+ * 
+ * @prop id - A string that indicates the ID of the money amount.
+ * @prop currency_code - A string that indicates the currency code of this money amount.
+ * @prop currency - An object of type {@link CurrencyDTO} that holds the details of the money amount's currency. Since this is a relation, it will only be retrieved if it's passed to the `relations` array of the find-configuration options.
+ * @prop amount - A number indicating the amount of this money amount.
+ * @prop min_quantity - A number that indicates the minimum quantity required to be purchased for this money amount to be applied.
+ * @prop max_quantity - A number that indicates the maximum quantity required to be purchased for this money amount to be applied.
+ */
 export interface CreateMoneyAmountDTO {
   id?: string
   currency_code: string
@@ -19,6 +43,18 @@ export interface CreateMoneyAmountDTO {
   max_quantity?: number
 }
 
+/**
+ *  * @interface
+ * 
+ * An object that holds data to update a money amount.
+ * 
+ * @prop id - A string that indicates the ID of the money amount to update.
+ * @prop currency_code - A string that indicates the currency code of the money amount.
+ * @prop currency - An object of type {@link CurrencyDTO} that holds the details of the money amount's currency. Since this is a relation, it will only be retrieved if it's passed to the `relations` array of the find-configuration options.
+ * @prop amount - A number indicating the amount of this money amount.
+ * @prop min_quantity - A number that indicates the minimum quantity required to be purchased for this money amount to be applied.
+ * @prop max_quantity - A number that indicates the maximum quantity required to be purchased for this money amount to be applied.
+ */
 export interface UpdateMoneyAmountDTO {
   id: string
   currency_code?: string
@@ -27,6 +63,14 @@ export interface UpdateMoneyAmountDTO {
   max_quantity?: number
 }
 
+/**
+ * @interface
+ * 
+ * An object that can be used to filter money amounts.
+ * 
+ * @prop id - An array of strings, each being an ID to filter money amounts.
+ * @prop currency_code - A string or an array of strings, each being a currency code to filter money amounts.
+ */
 export interface FilterableMoneyAmountProps
   extends BaseFilterable<FilterableMoneyAmountProps> {
   id?: string[]

packages/types/src/pricing/common/price-rule.ts

@@ -2,6 +2,22 @@ import { BaseFilterable } from "../../dal"
 import { PriceSetDTO } from "./price-set"
 import { RuleTypeDTO } from "./rule-type"
 
+/**
+ * @interface
+ * 
+ * An object that represents a price rule.
+ * 
+ * @prop id - A string indicating the ID of the price rule.
+ * @prop price_set_id - A string indicating the ID of the associated price set.
+ * @prop price_set - An object of type {@link PriceSetDTO} that holds the data of the associated price set. It may only be available if the relation `price_set` is expanded.
+ * @prop rule_type_id - A string indicating the ID of the associated rule type.
+ * @prop rule_type - An object of type {@link RuleTypeDTO} that holds the data of the associated rule type. It may only be available if the relation `rule_type` is expanded.
+ * @prop is_dynamic - A boolean indicating whether the price rule is dynamic.
+ * @prop value - A string indicating the value of the price rule.
+ * @prop priority - A number indicating the priority of the price rule in comparison to other applicable price rules.
+ * @prop price_set_money_amount_id - A string indicating the ID of the associated price set money amount.
+ * @prop price_list_id - A string indicating the ID of the associated price list.
+ */
 export interface PriceRuleDTO {
   id: string
   price_set_id: string
@@ -15,6 +31,21 @@ export interface PriceRuleDTO {
   price_list_id: string
 }
 
+/**
+ * 
+ * @interface
+ * 
+ * An object used to specify the necessary data to create a price rule.
+ * 
+ * @prop id - A string indicating the ID of the price rule.
+ * @prop price_set_id - A string indicating the ID of the associated price set.
+ * @prop rule_type_id - A string indicating the ID of the associated rule type.
+ * @prop is_dynamic - A boolean indicating whether the price rule is dynamic.
+ * @prop value - A string indicating the value of the price rule.
+ * @prop priority - A number indicating the priority of the price rule in comparison to other applicable price rules.
+ * @prop price_set_money_amount_id - A string indicating the ID of the associated price set money amount.
+ * @prop price_list_id - A string indicating the ID of the associated price list.
+ */
 export interface CreatePriceRuleDTO {
   id: string
   price_set_id: string
@@ -26,10 +57,30 @@ export interface CreatePriceRuleDTO {
   price_list_id: string
 }
 
+/**
+ * 
+ * @interface
+ * 
+ * An object used to specify the necessary data to update a price rule.
+ * 
+ * @prop id - A string indicating the ID of the price rule to update.
+ * @prop price_set_id - A string indicating the ID of the associated price set.
+ * @prop rule_type_id - A string indicating the ID of the associated rule type.
+ * @prop value - A string indicating the value of the price rule.
+ * @prop priority - A number indicating the priority of the price rule in comparison to other applicable price rules.
+ * @prop price_set_money_amount_id - A string indicating the ID of the associated price set money amount.
+ * @prop price_list_id - A string indicating the ID of the associated price list.
+ */
 export interface UpdatePriceRuleDTO {
   id: string
   price_set_id?: string
   rule_type_id?: string
+  /** 
+   * @ignore
+   * @privateRemark
+   * 
+   * Behavior behind this property is not implemented yet.
+   */
   is_dynamic?: boolean
   value?: string
   priority?: number
@@ -37,6 +88,16 @@ export interface UpdatePriceRuleDTO {
   price_list_id?: string
 }
 
+/**
+ * @interface
+ * 
+ * An object used to filter price rules when retrieving them.
+ * 
+ * @prop id - An array of strings, each indicating an ID to filter price rules.
+ * @prop name - An array of strings, each indicating a name to filter price rules.
+ * @prop price_set_id - An array of strings, each indicating a price set ID to filter price rules.
+ * @prop rule_type_id - An array of strings, each indicating a rule type ID to filter rule types.
+ */
 export interface FilterablePriceRuleProps
   extends BaseFilterable<FilterablePriceRuleProps> {
   id?: string[]

packages/types/src/pricing/common/price-set-money-amount-rules.ts

@@ -2,6 +2,16 @@ import { BaseFilterable } from "../../dal"
 import { PriceSetMoneyAmountDTO } from "./price-set-money-amount"
 import { RuleTypeDTO } from "./rule-type"
 
+/**
+ * @interface
+ * 
+ * An object representing a price set money amount rule, which holds data related to the association between a price set money amount and a rule.
+ * 
+ * @prop id - A string indicating the ID of the price set money amount.
+ * @prop price_set_money_amount - an object of type {@link PriceSetMoneyAmountDTO} holding the data of the associated price set money amount.
+ * @prop rule_type - an object of type {@link RuleTypeDTO} holding the data of the associated rule type.
+ * @prop value - a string indicating the value of the price set money amount rule.
+ */
 export interface PriceSetMoneyAmountRulesDTO {
   id: string
   price_set_money_amount: PriceSetMoneyAmountDTO
@@ -9,12 +19,31 @@ export interface PriceSetMoneyAmountRulesDTO {
   value: string
 }
 
+/**
+ * @interface
+ * 
+ * An object used to create a price set money amount rule, which represents an association between a price set money amount and a rule type.
+ * 
+ * @prop price_set_money_amount - A string indicating the ID of a price set money amount.
+ * @prop rule_type - A string indicating the ID of a rule type.
+ * @prop value - A string indicating the value of the price set money amount rule.
+ */
 export interface CreatePriceSetMoneyAmountRulesDTO {
   price_set_money_amount: string
   rule_type: string
   value: string
 }
 
+/**
+ * @interface
+ * 
+ * An object used to update a price set money amount rule. The price set money amount rule is identified by the provided `id`.
+ * 
+ * @prop id - A string indicating the ID of the price set money amount rule to update.
+ * @prop price_set_money_amount - A string indicating the ID of a price set money amount.
+ * @prop rule_type - A string indicating the ID of a rule type.
+ * @prop value - A string indicating the value of the price set money amount rule.
+ */
 export interface UpdatePriceSetMoneyAmountRulesDTO {
   id: string
   price_set_money_amount?: string
@@ -22,6 +51,16 @@ export interface UpdatePriceSetMoneyAmountRulesDTO {
   value?: string
 }
 
+/**
+ * @interface
+ * 
+ * An object used to filter price set money amount rules when listing them.
+ * 
+ * @prop id - An array of strings, each string indicating an ID to filter the price set money amount rules.
+ * @prop rule_type_id - An array of strings, each string indicating the ID of a rule type to filter the price set money amount rules.
+ * @prop price_set_money_amount_id - an array of strings, each string indicating the ID of a price set money amount to filter the price set money amount rules.
+ * @prop value - an array of strings, each string indicating a value to filter the price set money amount rules.
+ */
 export interface FilterablePriceSetMoneyAmountRulesProps
   extends BaseFilterable<FilterablePriceSetMoneyAmountRulesProps> {
   id?: string[]

packages/types/src/pricing/common/price-set-money-amount.ts

@@ -1,6 +1,16 @@
 import { MoneyAmountDTO } from "./money-amount"
 import { PriceSetDTO } from "./price-set"
 
+/**
+ * @interface
+ * 
+ * An object representing a price set money amount, which holds the data related to the association between a price set and a money amount.
+ * 
+ * @prop id - a string indicating the ID of a price set money amount.
+ * @prop title - a string indicating the title of the price set money amount.
+ * @prop price_set - an object of type {@link PriceSetDTO} holding the data of the associated price set.
+ * @prop money_amount - an object of type {@link MoneyAmountDTO} holding the data of the associated money amount.
+ */
 export interface PriceSetMoneyAmountDTO {
   id: string
   title?: string

packages/types/src/pricing/common/price-set.ts

@@ -6,20 +6,61 @@ import {
 } from "./money-amount"
 import { RuleTypeDTO } from "./rule-type"
 
+/**
+ * @interface
+ * 
+ * Used to specify the context to calculate prices. For example, you can specify the currency code to calculate prices in.
+ * 
+ * @prop context - 
+ * an object whose keys are the name of the context attribute. Its value can be a string or a number. For example, you can pass the `currency_code` property with its value being the currency code to calculate the price in.
+ * Another example is passing the `quantity` property to calculate the price for that specified quantity, which finds a price set whose `min_quantity` and `max_quantity` conditions match the specified quantity.
+ * 
+ * @example
+ * 
+ * To calculate prices 
+ */
 export interface PricingContext {
   context?: Record<string, string | number>
 }
 
+/**
+ * @interface
+ * 
+ * Used to filter prices when calculating them.
+ * 
+ * @prop id - An array of strings, each being an ID of a price set.
+ */
 export interface PricingFilters {
   id: string[]
 }
 
+/**
+ * @interface
+ * 
+ * An object that holds the details of a retrieved price set.
+ * 
+ * @prop id - A string indicating the ID of the price set.
+ * @prop money_amounts - An array of objects of type {@link MoneyAmountDTO}, which holds the prices that belong to this price set.
+ * @prop rule_types - An array of objects of type {@link RuleTypeDTO}, which holds the rule types applied on this price set.
+ * 
+ */
 export interface PriceSetDTO {
   id: string
   money_amounts?: MoneyAmountDTO[]
   rule_types?: RuleTypeDTO[]
 }
 
+/**
+ * @interface
+ * 
+ * An object that holds the details of a calculated price set.
+ * 
+ * @prop id - a string indicating the ID of the price set.
+ * @prop amount - a number indicating the calculated amount. It can possibly be `null` if there's no price set up for the provided context.
+ * @prop currency_code - a string indicating the currency code of the calculated price. It can possibly be `null`.
+ * @prop min_quantity - a number indicaitng the minimum quantity required to be purchased for this price to apply. It's set if the `quantity` property is provided in the context. Otherwise, its value will be `null`.
+ * @prop max_quantity - a number indicaitng the maximum quantity required to be purchased for this price to apply. It's set if the `quantity` property is provided in the context. Otherwise, its value will be `null`.
+ */
 export interface CalculatedPriceSetDTO {
   id: string
   amount: number | null
@@ -28,31 +69,90 @@ export interface CalculatedPriceSetDTO {
   max_quantity: number | null
 }
 
+/**
+ * @interface
+ * 
+ * An object used to specify the rules to add to a price set.
+ * 
+ * @prop priceSetId - A string indicating the ID of the price set to add the rules to.
+ * @prop rules - An array of objects, each object holds a property `attribute`, with its value being the `rule_attribute` of the rule to add to the price set.
+ */
 export interface AddRulesDTO {
   priceSetId: string
   rules: { attribute: string }[]
 }
 
+/**
+ * @interface
+ * 
+ * An object used to pass prices data when creating a price set.
+ * 
+ * @prop rules - An object whose keys are rule types' `rule_attribute` attribute, and values are the value of that rule associated with this price.
+ */
+export interface CreatePricesDTO extends CreateMoneyAmountDTO {
+  rules: Record<string, string>
+}
+
+/**
+ * @interface
+ * 
+ * An object used to specify prices to add to a price set.
+ * 
+ * @prop priceSetId - A string indicating the ID of the price set to add prices to.
+ * @prop prices - An array of objects of type {@link CreatePricesDTO}, each being a price to add to the price set.
+ */
 export interface AddPricesDTO {
   priceSetId: string
-  prices: (CreateMoneyAmountDTO & {
-    rules?: Record<string, string>
-  })[]
+  prices: CreatePricesDTO[]
 }
+
+/**
+ * @interface
+ * 
+ * An object of expected properties when removing a price set's rules.
+ * 
+ * @prop id - A string indicating the ID of the price set.
+ * @prop rules - An array of strings, each string is the `rule_attribute` of a rule you want to remove.
+ */
 export interface RemovePriceSetRulesDTO {
   id: string
   rules: string[]
 }
 
+/**
+ * @interface
+ * 
+ * An object of expected properties when creating a price set.
+ * 
+ * @prop rules - 
+ * An array of objects, each object accepts a property `rule_attribute`, whose value is a string indicating the `rule_attribute` value of a rule type. 
+ * This property is used to specify the rule types associated with the price set.
+ * @prop prices - An array of objects of type {@link CreatePricesDTO}, each being a price to associate with the price set.
+ */
 export interface CreatePriceSetDTO {
   rules?: { rule_attribute: string }[]
-  prices?: (CreateMoneyAmountDTO & { rules: Record<string, string> })[]
+  prices?: CreatePricesDTO[]
 }
 
+/**
+ * @interface
+ * 
+ * An object of expected properties when updating a price set.
+ * 
+ * @prop id - A string indicating the ID of the price set to update.
+ */
 export interface UpdatePriceSetDTO {
   id: string
 }
 
+/**
+ * @interface
+ * 
+ * An object that can be used to specify filters on price sets.
+ * 
+ * @prop id - An array of strings, each being an ID to filter price sets.
+ * @prop money_amounts - An object of type {@link FilterableMoneyAmountProps} that is used to filter the price sets by their associated money amounts.
+ */
 export interface FilterablePriceSetProps
   extends BaseFilterable<FilterablePriceSetProps> {
   id?: string[]

packages/types/src/pricing/common/rule-type.ts

@@ -1,5 +1,15 @@
 import { BaseFilterable } from "../../dal"
 
+/**
+ * @interface
+ * 
+ * An object that holds the details of a rule type.
+ * 
+ * @prop id - A string indicating the ID of the rule type.
+ * @prop name - A string indicating the display name of the rule type.
+ * @prop rule_attribute - A string indicating a unique name used to later identify the rule_attribute. For example, it can be used in the `context` parameter of the `calculatePrices` method to specify a rule for calculating the price.
+ * @prop default_priority - A number indicating the priority of the rule type. This is useful when calculating the price of a price set, and multiple rules satisfy the provided context. The higher the value, the higher the priority of the rule type.
+ */
 export interface RuleTypeDTO {
   id: string
   name: string
@@ -7,6 +17,16 @@ export interface RuleTypeDTO {
   default_priority: number
 }
 
+/**
+ * @interface
+ * 
+ * An object used when creating a rule type to specify its data.
+ * 
+ * @prop id - A string indicating the ID of the rule type.
+ * @prop name - A string indicating the display name of the rule type.
+ * @prop rule_attribute - A string indicating a unique name used to later identify the rule_attribute. For example, it can be used in the `context` parameter of the `calculatePrices` method to specify a rule for calculating the price.
+ * @prop default_priority - A number indicating the priority of the rule type. This is useful when calculating the price of a price set, and multiple rules satisfy the provided context. The higher the value, the higher the priority of the rule type.
+ */
 export interface CreateRuleTypeDTO {
   id?: string
   name: string
@@ -14,6 +34,16 @@ export interface CreateRuleTypeDTO {
   default_priority?: number
 }
 
+/**
+ * @interface
+ * 
+ * An object used when updating a rule type to specify the data to update.
+ * 
+ * @prop id - A string indicating the ID of the rule type to update.
+ * @prop name - A string indicating the display name of the rule type.
+ * @prop rule_attribute - A string indicating a unique name used to later identify the rule_attribute. For example, it can be used in the `context` parameter of the `calculatePrices` method to specify a rule for calculating the price.
+ * @prop default_priority - A number indicating the priority of the rule type. This is useful when calculating the price of a price set, and multiple rules satisfy the provided context. The higher the value, the higher the priority of the rule type.
+ */
 export interface UpdateRuleTypeDTO {
   id: string
   name?: string
@@ -21,6 +51,15 @@ export interface UpdateRuleTypeDTO {
   default_priority?: number
 }
 
+/**
+ * @interface
+ * 
+ * An object used to filter retrieved rule types.
+ * 
+ * @prop id - an array of strings, each being an ID to filter rule types.
+ * @prop name - an array of strings, each being a name to filter rule types.
+ * @prop rule_attribute - an array of strings, each being a rule attribute to filter rule types.
+ */
 export interface FilterableRuleTypeProps
   extends BaseFilterable<FilterableRuleTypeProps> {
   id?: string[]

packages/types/src/shared-context.ts

@@ -5,6 +5,18 @@ export type SharedContext = {
   manager?: EntityManager
 }
 
+/**
+ * @internal The interface tag is used to ensure that the type is documented similar to interfaces.
+ * @interface
+ * 
+ * A shared context object that is used to share resources between the application and the module.
+ * 
+ * @prop transactionManager - An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.
+ * @prop manager - An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.
+ * @prop isolationLevel - A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.
+ * @prop enableNestedTransactions - a boolean value indicating whether nested transactions are enabled.
+ * @prop transactionId - a string indicating the ID of the current transaction.
+ */
 export type Context<TManager = unknown> = {
   transactionManager?: TManager
   manager?: TManager