feat(core): Add `precision` property to MoneyStrategy

This allows us to easily support use-cases where more than 2 decimal places on the
major currency unit are needed (e.g. some B2B stores).

docs/docs/guides/core-concepts/money/index.mdx

@@ -171,6 +171,7 @@ The `MoneyStrategy` allows you to define:
 
 - How the value is stored and retrieved from the database
 - How rounding is applied internally
+- The precision represented by the monetary value (since v2.2.0)
 
 For example, in addition to the [`DefaultMoneyStrategy`](/reference/typescript-api/money/default-money-strategy), Vendure
 also provides the [`BigIntMoneyStrategy`](/reference/typescript-api/money/big-int-money-strategy) which stores monetary values
@@ -188,3 +189,49 @@ export const config: VendureConfig = {
     }
 }
 ```
+
+### Example: supporting three decimal places
+
+Let's say you have a B2B store which sells products in bulk, and you want to support prices with three decimal places.
+For example, you want to be able to sell a product for `$1.234` per unit. To do this, you would need to:
+
+1. Configure the `MoneyStrategy` to use three decimal places
+
+```ts
+import { DefaultMoneyStrategy, VendureConfig } from '@vendure/core';
+
+export class ThreeDecimalPlacesMoneyStrategy extends DefaultMoneyStrategy {
+    // highlight-next-line
+    readonly precision = 3;
+}
+
+export const config: VendureConfig = {
+    // ...
+    entityOptions: {
+        moneyStrategy: new ThreeDecimalPlacesMoneyStrategy(),
+    }
+};
+```
+
+2. Set up your storefront to correctly convert the integer value to a decimal value with three decimal places. Using the
+`formatCurrency` example above, we can modify it to divide by 1000 instead of 100:
+
+```ts title="src/utils/format-currency.ts"
+export function formatCurrency(value: number, currencyCode: string, locale?: string) {
+    // highlight-next-line
+    const majorUnits = value / 1000;
+    try {
+        return new Intl.NumberFormat(locale, {
+            style: 'currency',
+            currency: currencyCode,
+            // highlight-start
+            minimumFractionDigits: 3,
+            maximumFractionDigits: 3,
+            // highlight-end
+        }).format(majorUnits);
+    } catch (e: any) {
+         // highlight-next-line
+        return majorUnits.toFixed(3);
+    }
+}
+```

packages/admin-ui/src/lib/catalog/src/components/variant-price-detail/variant-price-detail.component.ts

@@ -1,7 +1,7 @@
 import { ChangeDetectionStrategy, Component, Input, OnChanges, OnInit, SimpleChanges } from '@angular/core';
 import { DataService } from '@vendure/admin-ui/core';
 import { BehaviorSubject, combineLatest, Observable, Subject } from 'rxjs';
-import { map } from 'rxjs/operators';
+import { map, tap } from 'rxjs/operators';
 
 @Component({
     selector: 'vdr-variant-price-detail',

packages/admin-ui/src/lib/core/src/common/utilities/interpolate-description.ts

@@ -6,6 +6,7 @@ import { ConfigurableOperationDefinition } from '../generated-types';
 export function interpolateDescription(
     operation: ConfigurableOperationDefinition,
     values: { [name: string]: any },
+    precisionFactor = 100,
 ): string {
     if (!operation) {
         return '';
@@ -20,7 +21,7 @@ export function interpolateDescription(
         let formatted = value;
         const argDef = operation.args.find(arg => arg.name === normalizedArgName);
         if (argDef && argDef.type === 'int' && argDef.ui && argDef.ui.component === 'currency-form-input') {
-            formatted = value / 100;
+            formatted = value / precisionFactor;
         }
         if (argDef && argDef.type === 'datetime' && value instanceof Date) {
             formatted = value.toLocaleDateString();

packages/admin-ui/src/lib/core/src/data/definitions/settings-definitions.ts

@@ -685,6 +685,7 @@ export const GET_SERVER_CONFIG = gql`
         globalSettings {
             id
             serverConfig {
+                moneyStrategyPrecision
                 orderProcess {
                     name
                     to

packages/admin-ui/src/lib/core/src/providers/currency/currency.service.ts

@@ -0,0 +1,18 @@
+import { Injectable } from '@angular/core';
+import { ServerConfigService } from '../../data/server-config';
+
+@Injectable({
+    providedIn: 'root',
+})
+export class CurrencyService {
+    readonly precision: number;
+    readonly precisionFactor: number;
+    constructor(serverConfigService: ServerConfigService) {
+        this.precision = serverConfigService.serverConfig.moneyStrategyPrecision;
+        this.precisionFactor = Math.pow(10, this.precision);
+    }
+
+    toMajorUnits(value: number): number {
+        return value / this.precisionFactor;
+    }
+}

packages/admin-ui/src/lib/core/src/shared/components/chart/chart.component.ts

@@ -10,6 +10,7 @@ import {
     ViewChild,
 } from '@angular/core';
 import { easings, LineChart, LineChartData, LineChartOptions } from 'chartist';
+import { CurrencyService } from '../../../providers/currency/currency.service';
 import { tooltipPlugin } from './tooltip-plugin';
 
 export interface ChartFormatOptions {
@@ -36,6 +37,8 @@ export class ChartComponent implements OnInit, OnChanges, OnDestroy {
     @ViewChild('chartDiv', { static: true }) private chartDivRef: ElementRef<HTMLDivElement>;
     private chart: LineChart;
 
+    constructor(private currencyService: CurrencyService) {}
+
     ngOnInit() {
         this.chart = new LineChart(
             this.chartDivRef.nativeElement,
@@ -55,7 +58,12 @@ export class ChartComponent implements OnInit, OnChanges, OnDestroy {
                     showLabel: false,
                     offset: 1,
                 },
-                plugins: [tooltipPlugin()],
+                plugins: [
+                    tooltipPlugin({
+                        currencyPrecision: this.currencyService.precision,
+                        currencyPrecisionFactor: this.currencyService.precisionFactor,
+                    }),
+                ],
                 ...this.options,
             },
         );

packages/admin-ui/src/lib/core/src/shared/components/chart/tooltip-plugin.ts

@@ -4,11 +4,13 @@
  */
 /* global Chartist */
 
-import { LineChart, PieChart, DrawEvent } from 'chartist';
+import { DrawEvent, LineChart } from 'chartist';
 import { ChartFormatOptions } from './chart.component';
 
 const defaultOptions = {
     currency: undefined,
+    currencyPrecision: 2,
+    currencyPrecisionFactor: 100,
     currencyFormatCallback: undefined,
     tooltipOffset: {
         x: 0,
@@ -20,13 +22,12 @@ const defaultOptions = {
     pointClass: 'ct-point',
 };
 
-export function tooltipPlugin(userOptions?: any) {
+export function tooltipPlugin(userOptions?: Partial<typeof defaultOptions>) {
     return function tooltip(chart: LineChart) {
         const options = {
             ...defaultOptions,
             ...userOptions,
         };
-        const tooltipSelector = options.pointClass;
 
         const $chart = (chart as any).container as HTMLDivElement;
         let $toolTip = $chart.querySelector('.chartist-tooltip') as HTMLDivElement;
@@ -97,8 +98,6 @@ export function tooltipPlugin(userOptions?: any) {
             closestPoint.element.addClass('ct-tooltip-hover');
 
             const $point = closestPoint.element.getNode() as HTMLElement;
-
-            const seriesName = 'ct:series-name';
             const meta: {
                 label: string;
                 formatOptions: ChartFormatOptions;
@@ -111,8 +110,9 @@ export function tooltipPlugin(userOptions?: any) {
                     ? new Intl.NumberFormat(meta.formatOptions.locale, {
                           style: 'currency',
                           currency: meta.formatOptions.currencyCode,
-                          minimumFractionDigits: 2,
-                      }).format(+(value ?? 0) / 100)
+                          minimumFractionDigits: options.currencyPrecision,
+                          maximumFractionDigits: options.currencyPrecision,
+                      }).format(+(value ?? 0) / options.currencyPrecisionFactor)
                     : new Intl.NumberFormat(meta.formatOptions.locale).format(+(value ?? 0));
 
             const tooltipText = `
@@ -172,16 +172,6 @@ function hasClass(element, className) {
     return (' ' + element.getAttribute('class') + ' ').indexOf(' ' + className + ' ') > -1;
 }
 
-function next(element, className) {
-    do {
-        element = element.nextSibling;
-    } while (element && !hasClass(element, className));
-    return element;
-}
-
-function text(element) {
-    return element.innerText || element.textContent;
-}
 function calculateDistance(x1, x2) {
     return Math.abs(x2 - x1);
 }

packages/admin-ui/src/lib/core/src/shared/components/configurable-input/configurable-input.component.ts

@@ -30,6 +30,7 @@ import {
 } from '../../../common/generated-types';
 import { getDefaultConfigArgValue } from '../../../common/utilities/configurable-operation-utils';
 import { interpolateDescription } from '../../../common/utilities/interpolate-description';
+import { CurrencyService } from '../../../providers/currency/currency.service';
 
 /**
  * A form input which renders a card with the internal form fields of the given ConfigurableOperation.
@@ -69,9 +70,15 @@ export class ConfigurableInputComponent
     private positionChangeSubject = new BehaviorSubject<number>(0);
     private subscription: Subscription;
 
+    constructor(private currencyService: CurrencyService) {}
+
     interpolateDescription(): string {
         if (this.operationDefinition) {
-            return interpolateDescription(this.operationDefinition, this.form.value);
+            return interpolateDescription(
+                this.operationDefinition,
+                this.form.value,
+                this.currencyService.precisionFactor,
+            );
         } else {
             return '';
         }

packages/admin-ui/src/lib/core/src/shared/components/currency-input/currency-input.component.html

@@ -4,7 +4,7 @@
 >
     <input
         type="number"
-        [step]="hasFractionPart ? 0.01 : 1"
+        [step]="hasFractionPart ? 1 / precisionFactor : 1"
         [value]="_inputValue"
         [disabled]="disabled"
         [readonly]="readonly"

packages/admin-ui/src/lib/core/src/shared/components/currency-input/currency-input.component.ts

@@ -1,5 +1,4 @@
 import {
-    ChangeDetectorRef,
     Component,
     EventEmitter,
     Input,
@@ -14,6 +13,7 @@ import { BehaviorSubject, combineLatest, Observable, Subscription } from 'rxjs';
 import { map } from 'rxjs/operators';
 
 import { DataService } from '../../../data/providers/data.service';
+import { CurrencyService } from '../../../providers/currency/currency.service';
 
 /**
  * @description
@@ -56,8 +56,13 @@ export class CurrencyInputComponent implements ControlValueAccessor, OnInit, OnC
     _inputValue: string;
     private currencyCode$ = new BehaviorSubject<string>('');
     private subscription: Subscription;
+    readonly precision: number;
+    readonly precisionFactor: number;
 
-    constructor(private dataService: DataService, private changeDetectorRef: ChangeDetectorRef) {}
+    constructor(private dataService: DataService, private currencyService: CurrencyService) {
+        this.precision = currencyService.precision;
+        this.precisionFactor = currencyService.precisionFactor;
+    }
 
     ngOnInit() {
         const languageCode$ = this.dataService.client.uiState().mapStream(data => data.uiState.language);
@@ -133,7 +138,7 @@ export class CurrencyInputComponent implements ControlValueAccessor, OnInit, OnC
     }
 
     onInput(value: string) {
-        const integerValue = Math.round(+value * 100);
+        const integerValue = Math.round(+value * this.currencyService.precisionFactor);
         if (typeof this.onChange === 'function') {
             this.onChange(integerValue);
         }
@@ -155,11 +160,11 @@ export class CurrencyInputComponent implements ControlValueAccessor, OnInit, OnC
     writeValue(value: any): void {
         const numericValue = +value;
         if (!Number.isNaN(numericValue)) {
-            this._inputValue = this.toNumericString(Math.floor(value) / 100);
+            this._inputValue = this.toNumericString(this.currencyService.toMajorUnits(Math.floor(value)));
         }
     }
 
     private toNumericString(value: number | string): string {
-        return this.hasFractionPart ? Number(value).toFixed(2) : Number(value).toFixed(0);
+        return this.hasFractionPart ? Number(value).toFixed(this.precision) : Number(value).toFixed(0);
     }
 }

packages/admin-ui/src/lib/core/src/shared/pipes/locale-currency.pipe.ts

@@ -1,6 +1,7 @@
 import { ChangeDetectorRef, Optional, Pipe, PipeTransform } from '@angular/core';
 
 import { DataService } from '../../data/providers/data.service';
+import { CurrencyService } from '../../providers/currency/currency.service';
 
 import { LocaleBasePipe } from './locale-base.pipe';
 
@@ -21,7 +22,12 @@ import { LocaleBasePipe } from './locale-base.pipe';
     pure: false,
 })
 export class LocaleCurrencyPipe extends LocaleBasePipe implements PipeTransform {
-    constructor(@Optional() dataService?: DataService, @Optional() changeDetectorRef?: ChangeDetectorRef) {
+    readonly precisionFactor: number;
+    constructor(
+        private currencyService: CurrencyService,
+        @Optional() dataService?: DataService,
+        @Optional() changeDetectorRef?: ChangeDetectorRef,
+    ) {
         super(dataService, changeDetectorRef);
     }
 
@@ -29,14 +35,16 @@ export class LocaleCurrencyPipe extends LocaleBasePipe implements PipeTransform
         const [currencyCode, locale] = args;
         if (typeof value === 'number') {
             const activeLocale = this.getActiveLocale(locale);
-            const majorUnits = value / 100;
+            const majorUnits = this.currencyService.toMajorUnits(value);
             try {
                 return new Intl.NumberFormat(activeLocale, {
                     style: 'currency',
                     currency: currencyCode as any,
+                    minimumFractionDigits: this.currencyService.precision,
+                    maximumFractionDigits: this.currencyService.precision,
                 }).format(majorUnits);
             } catch (e: any) {
-                return majorUnits.toFixed(2);
+                return majorUnits.toFixed(this.currencyService.precision);
             }
         }
         return value;

packages/admin-ui/src/lib/dashboard/src/widgets/order-summary-widget/order-summary-widget.component.html

@@ -5,7 +5,7 @@
     </div>
     <div class="stat">
         <div class="stat-figure">
-            {{ totalOrderValue$ | async | currency: (currencyCode$ | async) || undefined }}
+            {{ totalOrderValue$ | async | localeCurrency: (currencyCode$ | async) || undefined }}
         </div>
         <div class="stat-label">{{ 'dashboard.total-order-value' | translate }}</div>
     </div>

packages/admin-ui/src/lib/dashboard/src/widgets/order-summary-widget/order-summary-widget.component.ts

@@ -60,7 +60,7 @@ export class OrderSummaryWidgetComponent implements OnInit {
         );
         this.totalOrderCount$ = orderSummary$.pipe(map(res => res.totalItems));
         this.totalOrderValue$ = orderSummary$.pipe(
-            map(res => res.items.reduce((total, order) => total + order.totalWithTax, 0) / 100),
+            map(res => res.items.reduce((total, order) => total + order.totalWithTax, 0)),
         );
         this.currencyCode$ = this.dataService.settings
             .getActiveChannel()

packages/asset-server-plugin/e2e/graphql/generated-e2e-asset-server-plugin-types.ts

@@ -5421,6 +5421,7 @@ export type SellerSortParameter = {
 
 export type ServerConfig = {
   customFieldConfig: CustomFields;
+  moneyStrategyPrecision: Scalars['Int']['output'];
   orderProcess: Array<OrderProcessState>;
   permissions: Array<PermissionDefinition>;
   permittedAssetTypes: Array<Scalars['String']['output']>;

packages/common/src/generated-types.ts

@@ -5568,6 +5568,7 @@ export type SellerSortParameter = {
 export type ServerConfig = {
   __typename?: 'ServerConfig';
   customFieldConfig: CustomFields;
+  moneyStrategyPrecision: Scalars['Int']['output'];
   orderProcess: Array<OrderProcessState>;
   permissions: Array<PermissionDefinition>;
   permittedAssetTypes: Array<Scalars['String']['output']>;

packages/core/e2e/graphql/generated-e2e-admin-types.ts

@@ -5421,6 +5421,7 @@ export type SellerSortParameter = {
 
 export type ServerConfig = {
   customFieldConfig: CustomFields;
+  moneyStrategyPrecision: Scalars['Int']['output'];
   orderProcess: Array<OrderProcessState>;
   permissions: Array<PermissionDefinition>;
   permittedAssetTypes: Array<Scalars['String']['output']>;

packages/core/src/api/resolvers/admin/global-settings.resolver.ts

@@ -2,7 +2,6 @@ import { Args, Info, Mutation, Query, ResolveField, Resolver } from '@nestjs/gra
 import {
     CustomFields as GraphQLCustomFields,
     MutationUpdateGlobalSettingsArgs,
-    OrderProcessState,
     Permission,
     ServerConfig,
     UpdateGlobalSettingsResult,
@@ -16,20 +15,13 @@ import {
     isNonNullType,
     isObjectType,
     isScalarType,
-    NamedTypeNode,
-    TypeNode,
 } from 'graphql';
 
 import { getAllPermissionsMetadata } from '../../../common/constants';
 import { ErrorResultUnion } from '../../../common/error/error-result';
-import { UserInputError } from '../../../common/error/errors';
 import { ChannelDefaultLanguageError } from '../../../common/error/generated-graphql-admin-errors';
 import { ConfigService } from '../../../config/config.service';
-import {
-    CustomFieldConfig,
-    CustomFields,
-    RelationCustomFieldConfig,
-} from '../../../config/custom-field/custom-field-types';
+import { CustomFields } from '../../../config/custom-field/custom-field-types';
 import { GlobalSettings } from '../../../entity/global-settings/global-settings.entity';
 import { ChannelService } from '../../../service/services/channel.service';
 import { GlobalSettingsService } from '../../../service/services/global-settings.service';
@@ -67,6 +59,7 @@ export class GlobalSettingsResolver {
             orderProcess: this.orderService.getOrderProcessStates(),
             permittedAssetTypes: this.configService.assetOptions.permittedFileTypes,
             permissions,
+            moneyStrategyPrecision: this.configService.entityOptions.moneyStrategy.precision ?? 2,
         };
     }
 

packages/core/src/api/schema/admin-api/global-settings.type.graphql

@@ -24,4 +24,5 @@ type ServerConfig {
     orderProcess: [OrderProcessState!]!
     permittedAssetTypes: [String!]!
     permissions: [PermissionDefinition!]!
+    moneyStrategyPrecision: Int!
 }

packages/core/src/config/entity/bigint-money-strategy.ts

@@ -37,6 +37,7 @@ export class BigIntMoneyStrategy implements MoneyStrategy {
             },
         },
     };
+    precision = 2;
 
     round(value: number, quantity = 1): number {
         return Math.round(value * quantity);

packages/core/src/config/entity/default-money-strategy.ts

@@ -16,6 +16,7 @@ export class DefaultMoneyStrategy implements MoneyStrategy {
     readonly moneyColumnOptions: ColumnOptions = {
         type: 'int',
     };
+    readonly precision: number = 2;
 
     round(value: number, quantity = 1): number {
         return Math.round(value) * quantity;

packages/core/src/config/entity/money-strategy.ts

@@ -25,14 +25,30 @@ import { InjectableStrategy } from '../../common/types/injectable-strategy';
  * {@link BigIntMoneyStrategy} which will use the `bigint` type to store monetary values,
  * giving an effective upper limit of over 9 quadrillion.
  *
- * ## Precision & rounding
+ * ## Precision
  *
  * Both the `DefaultMoneyStrategy` and `BigIntMoneyStrategy` store monetary values as integers, representing
  * the price in the minor units of the currency (i.e. _cents_ in USD or _pennies_ in GBP).
  *
- * In certain use-cases, it may be required that fractions of a cent or penny be supported. In this case,
- * the solution would be to define a custom MoneyStrategy which uses a non-integer data type for storing
- * the value in the database, and defines a `round()` implementation which allows decimal places to be kept.
+ * Since v2.2.0, you can configure the precision of the stored values via the `precision` property of the
+ * strategy. Changing the precision has **no effect** on the stored value. It is merely a hint to the
+ * UI as to how many decimal places to display.
+ *
+ * @example
+ * ```ts
+ * import { DefaultMoneyStrategy, VendureConfig } from '\@vendure/core';
+ *
+ * export class ThreeDecimalPlacesMoneyStrategy extends DefaultMoneyStrategy {
+ *   readonly precision = 3;
+ * }
+ *
+ * export const config: VendureConfig = {
+ *   // ...
+ *   entityOptions: {
+ *     moneyStrategy: new ThreeDecimalPlacesMoneyStrategy(),
+ *   }
+ * };
+ * ```
  *
  * :::info
  *
@@ -50,6 +66,21 @@ export interface MoneyStrategy extends InjectableStrategy {
      * Defines the TypeORM column used to store monetary values.
      */
     readonly moneyColumnOptions: ColumnOptions;
+    /**
+     * @description
+     * Defines the precision (i.e. number of decimal places) represented by the monetary values.
+     * For example, consider a product variant with a price value of `12345`.
+     *
+     * - If the precision is `2`, then the price is `123.45`.
+     * - If the precision is `3`, then the price is `12.345`.
+     *
+     * Changing the precision has **no effect** on the stored value. It is merely a hint to the
+     * UI as to how many decimal places to display.
+     *
+     * @default 2
+     * @since 2.2.0
+     */
+    readonly precision?: number;
 
     /**
      * @description

packages/elasticsearch-plugin/e2e/graphql/generated-e2e-elasticsearch-plugin-types.ts

@@ -5421,6 +5421,7 @@ export type SellerSortParameter = {
 
 export type ServerConfig = {
   customFieldConfig: CustomFields;
+  moneyStrategyPrecision: Scalars['Int']['output'];
   orderProcess: Array<OrderProcessState>;
   permissions: Array<PermissionDefinition>;
   permittedAssetTypes: Array<Scalars['String']['output']>;

packages/payments-plugin/e2e/graphql/generated-admin-types.ts

@@ -5421,6 +5421,7 @@ export type SellerSortParameter = {
 
 export type ServerConfig = {
   customFieldConfig: CustomFields;
+  moneyStrategyPrecision: Scalars['Int']['output'];
   orderProcess: Array<OrderProcessState>;
   permissions: Array<PermissionDefinition>;
   permittedAssetTypes: Array<Scalars['String']['output']>;