docs: migrate guides to TSDoc references (#6100)
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
85dad169bb
commit
4792c55226
980 files changed
+195537
-160619
No files matched your search
+209
@@ -0,0 +1,209 @@
|
||||
---
|
||||
displayed_sidebar: modules
|
||||
---
|
||||
|
||||
import ParameterTypes from "@site/src/components/ParameterTypes"
|
||||
|
||||
# IPriceSelectionStrategy
|
||||
|
||||
## Overview
|
||||
|
||||
The price selection strategy retrieves the best price for a product variant for a specific context such as selected region, taxes applied,
|
||||
the quantity in cart, and more.
|
||||
|
||||
Medusa provides a default price selection strategy, but you can override it. A price selecion strategy is a TypeScript or JavaScript file in the `src/strategies` directory of your Medusa backend project. It exports a class that extends the `AbstractPriceSelectionStrategy` class.
|
||||
|
||||
For example:
|
||||
|
||||
```ts title="src/strategies/price.ts"
|
||||
import {
|
||||
AbstractPriceSelectionStrategy,
|
||||
PriceSelectionContext,
|
||||
PriceSelectionResult,
|
||||
} from "@medusajs/medusa"
|
||||
|
||||
export default class MyStrategy extends
|
||||
AbstractPriceSelectionStrategy {
|
||||
|
||||
async calculateVariantPrice(
|
||||
data: {
|
||||
variantId: string;
|
||||
quantity?: number
|
||||
}[],
|
||||
context: PriceSelectionContext
|
||||
): Promise<Map<string, PriceSelectionResult>> {
|
||||
throw new Error("Method not implemented.")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Methods
|
||||
|
||||
### calculateVariantPrice
|
||||
|
||||
This method retrieves one or more product variants' prices. It's used when retrieving product variants or their associated line items.
|
||||
It's also used when retrieving other entities that product variants and line items belong to, such as products and carts respectively.
|
||||
|
||||
#### Example
|
||||
|
||||
For example, here's a snippet of how the price selection strategy is implemented in the Medusa backend:
|
||||
|
||||
```ts
|
||||
import {
|
||||
AbstractPriceSelectionStrategy,
|
||||
CustomerService,
|
||||
PriceSelectionContext,
|
||||
PriceSelectionResult,
|
||||
} from "@medusajs/medusa"
|
||||
|
||||
type InjectedDependencies = {
|
||||
customerService: CustomerService
|
||||
}
|
||||
|
||||
export default class MyStrategy extends
|
||||
AbstractPriceSelectionStrategy {
|
||||
|
||||
async calculateVariantPrice(
|
||||
data: {
|
||||
variantId: string
|
||||
quantity?: number
|
||||
}[],
|
||||
context: PriceSelectionContext
|
||||
): Promise<Map<string, PriceSelectionResult>> {
|
||||
const dataMap = new Map(data.map((d) => [d.variantId, d]))
|
||||
|
||||
const cacheKeysMap = new Map(
|
||||
data.map(({ variantId, quantity }) => [
|
||||
variantId,
|
||||
this.getCacheKey(variantId, { ...context, quantity }),
|
||||
])
|
||||
)
|
||||
|
||||
const nonCachedData: {
|
||||
variantId: string
|
||||
quantity?: number
|
||||
}[] = []
|
||||
|
||||
const variantPricesMap = new Map<string, PriceSelectionResult>()
|
||||
|
||||
if (!context.ignore_cache) {
|
||||
const cacheHits = await promiseAll(
|
||||
[...cacheKeysMap].map(async ([, cacheKey]) => {
|
||||
return await this.cacheService_.get<PriceSelectionResult>(cacheKey)
|
||||
})
|
||||
)
|
||||
|
||||
if (!cacheHits.length) {
|
||||
nonCachedData.push(...dataMap.values())
|
||||
}
|
||||
|
||||
for (const [index, cacheHit] of cacheHits.entries()) {
|
||||
const variantId = data[index].variantId
|
||||
if (cacheHit) {
|
||||
variantPricesMap.set(variantId, cacheHit)
|
||||
continue
|
||||
}
|
||||
|
||||
nonCachedData.push(dataMap.get(variantId)!)
|
||||
}
|
||||
} else {
|
||||
nonCachedData.push(...dataMap.values())
|
||||
}
|
||||
|
||||
let results: Map<string, PriceSelectionResult> = new Map()
|
||||
|
||||
if (
|
||||
this.featureFlagRouter_.isFeatureEnabled(
|
||||
TaxInclusivePricingFeatureFlag.key
|
||||
)
|
||||
) {
|
||||
results = await this.calculateVariantPrice_new(nonCachedData, context)
|
||||
} else {
|
||||
results = await this.calculateVariantPrice_old(nonCachedData, context)
|
||||
}
|
||||
|
||||
await promiseAll(
|
||||
[...results].map(async ([variantId, prices]) => {
|
||||
variantPricesMap.set(variantId, prices)
|
||||
if (!context.ignore_cache) {
|
||||
await this.cacheService_.set(cacheKeysMap.get(variantId)!, prices)
|
||||
}
|
||||
})
|
||||
)
|
||||
|
||||
return variantPricesMap
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"data","type":"`object`[]","description":"The necessary data to perform the price selection for each variant ID.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"variantId","type":"`string`","description":"The ID of the variant to retrieve its prices.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"quantity","type":"`number`","description":"The variant's quantity in the cart, if available.","optional":true,"defaultValue":"","expandable":false,"children":[]}]},{"name":"context","type":"[PriceSelectionContext](price_selection.PriceSelectionContext.mdx)","description":"The context of the price selection.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"cart_id","type":"`string`","description":"The cart's ID. This is used when the prices are being retrieved for the variant of a line item,\nas it is used to determine the current region and currency code of the context.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"currency_code","type":"`string`","description":"The currency code the customer is using.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"customer_id","type":"`string`","description":"The ID of the customer viewing the variant.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"ignore_cache","type":"`boolean`","description":"Whether to calculate the prices even if the value of an earlier price calculation\nis available in the cache.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"include_discount_prices","type":"`boolean`","description":"Whether the price list's prices should be retrieved or not.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"quantity","type":"`number`","description":"The quantity of the item in the cart. This is used to filter out price lists that have\n`min_quantity` or `max_quantity` conditions set.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"region_id","type":"`string`","description":"The region's ID.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"tax_rates","type":"[TaxServiceRate](../../medusa/types/medusa.TaxServiceRate.mdx)[]","description":"The tax rates to be applied. This is only used for\n[Tax-Inclusive Pricing](https://docs.medusajs.com/modules/taxes/inclusive-pricing).","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"name","type":"`string`","description":"The tax rate's name.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"code","type":"`string` \\| `null`","description":"The tax rate's code.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"rate","type":"`number` \\| `null`","description":"The tax rate.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]}]} />
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<Map<string, [PriceSelectionResult](price_selection.PriceSelectionResult.mdx)>>","optional":false,"defaultValue":"","description":"A map, each key is an ID of a variant, and its value is an object holding the price selection result.","expandable":false,"children":[{"name":"Map","type":"Map<string, [PriceSelectionResult](price_selection.PriceSelectionResult.mdx)>","optional":false,"defaultValue":"","description":"","expandable":false,"children":[{"name":"string","type":"`string`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]},{"name":"PriceSelectionResult","type":"`object`","description":"The price selection result of a variant.","optional":false,"defaultValue":"","expandable":false,"children":[]}]}]}]} />
|
||||
|
||||
### onVariantsPricesUpdate
|
||||
|
||||
This method is called when prices of product variants have changed.
|
||||
You can use it to invalidate prices stored in the cache.
|
||||
|
||||
#### Example
|
||||
|
||||
For example, this is how this method is implemented in the Medusa backend's default
|
||||
price selection strategy:
|
||||
|
||||
```ts
|
||||
import {
|
||||
AbstractPriceSelectionStrategy,
|
||||
CustomerService,
|
||||
} from "@medusajs/medusa"
|
||||
import { promiseAll } from "@medusajs/utils"
|
||||
|
||||
type InjectedDependencies = {
|
||||
customerService: CustomerService
|
||||
}
|
||||
|
||||
export default class MyStrategy extends
|
||||
AbstractPriceSelectionStrategy {
|
||||
|
||||
public async onVariantsPricesUpdate(variantIds: string[]): Promise<void> {
|
||||
await promiseAll(
|
||||
variantIds.map(
|
||||
async (id: string) => await this.cacheService_.invalidate(`ps:${id}:*`)
|
||||
)
|
||||
)
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
Learn more about the cache service in [this documentation](https://docs.medusajs.com/development/cache/overview).
|
||||
|
||||
:::
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"variantIds","type":"`string`[]","description":"The IDs of the updated variants.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} />
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"Promise","type":"Promise<void>","optional":false,"defaultValue":"","description":"Resolves after any necessary actions are performed.","expandable":false,"children":[]}]} />
|
||||
|
||||
### withTransaction
|
||||
|
||||
#### Parameters
|
||||
|
||||
<ParameterTypes parameters={[{"name":"transactionManager","type":"`EntityManager`","description":"","optional":true,"defaultValue":"","expandable":false,"children":[]}]} />
|
||||
|
||||
#### Returns
|
||||
|
||||
<ParameterTypes parameters={[{"name":"this","type":"`this`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} />
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
---
|
||||
displayed_sidebar: modules
|
||||
---
|
||||
|
||||
import ParameterTypes from "@site/src/components/ParameterTypes"
|
||||
|
||||
# PriceSelectionContext
|
||||
|
||||
The context of the price selection.
|
||||
|
||||
## Properties
|
||||
|
||||
<ParameterTypes parameters={[{"name":"cart_id","type":"`string`","description":"The cart's ID. This is used when the prices are being retrieved for the variant of a line item,\nas it is used to determine the current region and currency code of the context.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"currency_code","type":"`string`","description":"The currency code the customer is using.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"customer_id","type":"`string`","description":"The ID of the customer viewing the variant.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"ignore_cache","type":"`boolean`","description":"Whether to calculate the prices even if the value of an earlier price calculation\nis available in the cache.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"include_discount_prices","type":"`boolean`","description":"Whether the price list's prices should be retrieved or not.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"quantity","type":"`number`","description":"The quantity of the item in the cart. This is used to filter out price lists that have\n`min_quantity` or `max_quantity` conditions set.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"region_id","type":"`string`","description":"The region's ID.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"tax_rates","type":"[TaxServiceRate](../../medusa/types/medusa.TaxServiceRate.mdx)[]","description":"The tax rates to be applied. This is only used for\n[Tax-Inclusive Pricing](https://docs.medusajs.com/modules/taxes/inclusive-pricing).","optional":true,"defaultValue":"","expandable":false,"children":[{"name":"name","type":"`string`","description":"The tax rate's name.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"code","type":"`string` \\| `null`","description":"The tax rate's code.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"rate","type":"`number` \\| `null`","description":"The tax rate.","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} />
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
---
|
||||
displayed_sidebar: modules
|
||||
---
|
||||
|
||||
import ParameterTypes from "@site/src/components/ParameterTypes"
|
||||
|
||||
# PriceSelectionResult
|
||||
|
||||
The price selection result of a variant.
|
||||
|
||||
## Properties
|
||||
|
||||
<ParameterTypes parameters={[{"name":"calculatedPrice","type":"`null` \\| `number`","description":"The lowest price among the prices of the product variant retrieved using the context object.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"originalPrice","type":"`null` \\| `number`","description":"The original price of the variant which depends on the selected region or currency code in the context object.\nIf both region ID and currency code are available in the context object, the region has higher precedence.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"prices","type":"[MoneyAmount](../../entities/classes/entities.MoneyAmount.mdx)[]","description":"All possible prices of the variant that are retrieved using the `context` object.\nIt can include its original price and its price lists if there are any.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"amount","type":"`number`","description":"The amount in the smallest currecny unit (e.g. cents 100 cents to charge $1) that the Product Variant will cost.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"created_at","type":"`Date`","description":"The date with timezone at which the resource was created.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"currency_code","type":"`string`","description":"The 3 character currency code that the money amount may belong to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"deleted_at","type":"`null` \\| `Date`","description":"The date with timezone at which the resource was deleted.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"id","type":"`string`","description":"The money amount's ID","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"max_quantity","type":"`null` \\| `number`","description":"The maximum quantity that the Money Amount applies to. If this value is not set, the Money Amount applies to all quantities.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"min_quantity","type":"`null` \\| `number`","description":"The minimum quantity that the Money Amount applies to. If this value is not set, the Money Amount applies to all quantities.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"price_list","type":"`null` \\| [PriceList](../../entities/classes/entities.PriceList.mdx)","description":"The details of the price list that the money amount may belong to.","optional":false,"defaultValue":"","expandable":true,"children":[]},{"name":"price_list_id","type":"`null` \\| `string`","description":"The ID of the price list that the money amount may belong to.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"region_id","type":"`null` \\| `string`","description":"The region's ID","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"updated_at","type":"`Date`","description":"The date with timezone at which the resource was updated.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"variant","type":"[ProductVariant](../../entities/classes/entities.ProductVariant.mdx)","description":"The details of the product variant that the money amount may belong to.","optional":false,"defaultValue":"","expandable":true,"children":[{"name":"allow_backorder","type":"`boolean`","description":"Whether the Product Variant should be purchasable when `inventory\\_quantity` is 0.","optional":false,"defaultValue":"false","expandable":false,"children":[]},{"name":"barcode","type":"`null` \\| `string`","description":"A generic field for a GTIN number that can be used to identify the Product Variant.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"created_at","type":"`Date`","description":"The date with timezone at which the resource was created.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"deleted_at","type":"`null` \\| `Date`","description":"The date with timezone at which the resource was deleted.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"ean","type":"`null` \\| `string`","description":"An EAN barcode number that can be used to identify the Product Variant.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"height","type":"`null` \\| `number`","description":"The height of the Product Variant. May be used in shipping rate calculations.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"hs_code","type":"`null` \\| `string`","description":"The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"id","type":"`string`","description":"The product variant's ID","optiLine truncated
|
||||
Reference in new issue
Block a user