@vendure/docs 0.0.0-202601161541

package/docs/guides/developer-guide/the-service-layer/index.mdx

@@ -0,0 +1,311 @@
+---
+title: 'The Service Layer'
+sidebar_position: 2
+---
+
+The service layer is the core of the application. This is where the business logic is implemented, and where
+the application interacts with the database. When a request comes in to the API, it gets routed to a resolver
+which then calls a service method to perform the required operation.
+
+![../the-api-layer/Vendure_docs-api_request.webp](../the-api-layer/Vendure_docs-api_request.webp)
+
+:::info
+Services are classes which, in NestJS terms, are [providers](https://docs.nestjs.com/providers#services). They
+follow all the rules of NestJS providers, including dependency injection, scoping, etc.
+:::
+
+Services are generally scoped to a specific domain or entity. For instance, in the Vendure core, there is a [`Product` entity](/reference/typescript-api/entities/product),
+and a corresponding [`ProductService`](/reference/typescript-api/services/product-service) which contains all the methods for interacting with products.
+
+Here's a simplified example of a `ProductService`, including an implementation of the `findOne()` method that was
+used in the example in the [previous section](/guides/developer-guide/the-api-layer/#resolvers):
+
+```ts title="src/services/product.service.ts"
+import { Injectable } from '@nestjs/common';
+import { IsNull } from 'typeorm';
+import { ID, Product, RequestContext, TransactionalConnection, TranslatorService } from '@vendure/core';
+
+@Injectable()
+export class ProductService {
+
+    constructor(private connection: TransactionalConnection,
+                private translator: TranslatorService){}
+
+    /**
+     * @description
+     * Returns a Product with the given id, or undefined if not found.
+     */
+    async findOne(ctx: RequestContext, productId: ID): Promise<Product | undefined> {
+        const product = await this.connection.findOneInChannel(ctx, Product, productId, ctx.channelId, {
+            where: {
+                deletedAt: IsNull(),
+            },
+        });
+        if (!product) {
+            return;
+        }
+        return this.translator.translate(product, ctx);
+    }
+
+    // ... other methods
+    findMany() {}
+    create() {}
+    update() {}
+}
+```
+
+- The `@Injectable()` decorator is a [NestJS](https://docs.nestjs.com/providers#services) decorator which allows the service
+    to be injected into other services or resolvers.
+- The `constructor()` method is where the dependencies of the service are injected. In this case, the `TransactionalConnection`
+    is used to access the database, and the `TranslatorService` is used to translate the Product entity into the current
+    language.
+
+## Using core services
+
+All the internal Vendure services can be used in your own plugins and scripts. They are listed in the [Services API reference](/reference/typescript-api/services/) and
+can be imported from the `@vendure/core` package.
+
+To make use of a core service in your own plugin, you need to ensure your plugin is importing the `PluginCommonModule` and
+then inject the desired service into your own service's constructor:
+
+```ts title="src/my-plugin/my.plugin.ts"
+import { PluginCommonModule, VendurePlugin } from '@vendure/core';
+import { MyService } from './services/my.service';
+
+@VendurePlugin({
+    // highlight-start
+    imports: [PluginCommonModule],
+    providers: [MyService],
+    // highlight-end
+})
+export class MyPlugin {}
+```
+
+```ts title="src/my-plugin/services/my.service.ts"
+import { Injectable } from '@nestjs/common';
+import { ProductService } from '@vendure/core';
+
+@Injectable()
+export class MyService {
+
+    // highlight-next-line
+    constructor(private productService: ProductService) {}
+
+    // you can now use the productService methods
+}
+```
+
+## Accessing the database
+
+One of the main responsibilities of the service layer is to interact with the database. For this, you will be using
+the [`TransactionalConnection` class](/reference/typescript-api/data-access/transactional-connection/), which is a wrapper
+around the [TypeORM `DataSource` object](https://typeorm.io/data-source-api). The primary purpose of the `TransactionalConnection`
+is to ensure that database operations can be performed within a transaction (which is essential for ensuring data integrity), even
+across multiple services. Furthermore, it exposes some helper methods which make it easier to perform common operations.
+
+:::info
+
+Always pass the `RequestContext` (`ctx`) to the `TransactionalConnection` methods. This ensures the operation occurs within
+any active transaction.
+
+:::
+
+There are two primary APIs for accessing data provided by TypeORM: the **Find API** and the **QueryBuilder API**.
+
+### The Find API
+
+This API is the most convenient and type-safe way to query the database. It provides a powerful type-safe way to query
+including support for eager relations, pagination, sorting, filtering and more.
+
+Here are some examples of using the Find API:
+
+```ts title="src/services/item.service.ts"
+import { Injectable } from '@nestjs/common';
+import { ID, RequestContext, TransactionalConnection } from '@vendure/core';
+import { IsNull } from 'typeorm';
+import { Item } from '../entities/item.entity';
+
+@Injectable()
+export class ItemService {
+
+    constructor(private connection: TransactionalConnection) {}
+
+    findById(ctx: RequestContext, itemId: ID): Promise<Item | null> {
+        return this.connection.getRepository(ctx, Item).findOne({
+            where: { id: itemId },
+        });
+    }
+
+    findByName(ctx: RequestContext, name: string): Promise<Item | null> {
+        return this.connection.getRepository(ctx, Item).findOne({
+            where: {
+                // Multiple where clauses can be specified,
+                // which are joined with AND
+                name,
+                deletedAt: IsNull(),
+            },
+        });
+    }
+
+    findWithRelations() {
+        return this.connection.getRepository(ctx, Item).findOne({
+            where: { name },
+            relations: {
+                // Join the `item.customer` relation
+                customer: true,
+                product: {
+                    // Here we are joining a nested relation `item.product.featuredAsset`
+                    featuredAsset: true,
+                },
+            },
+        });
+    }
+
+    findMany(ctx: RequestContext): Promise<Item[]> {
+        return this.connection.getRepository(ctx, Item).find({
+            // Pagination
+            skip: 0,
+            take: 10,
+            // Sorting
+            order: {
+                name: 'ASC',
+            },
+        });
+    }
+}
+```
+
+:::info
+
+Further examples can be found in the [TypeORM Find Options documentation](https://typeorm.io/find-options).
+
+:::
+
+### The QueryBuilder API
+
+When the Find API is not sufficient, the QueryBuilder API can be used to construct more complex queries. For instance,
+if you want to have a more complex `WHERE` clause than what can be achieved with the Find API, or if you want to perform
+sub-queries, then the QueryBuilder API is the way to go.
+
+Here are some examples of using the QueryBuilder API:
+
+```ts title="src/services/item.service.ts"
+import { Injectable } from '@nestjs/common';
+import { ID, RequestContext, TransactionalConnection } from '@vendure/core';
+import { Brackets, IsNull } from 'typeorm';
+import { Item } from '../entities/item.entity';
+
+@Injectable()
+export class ItemService {
+
+    constructor(private connection: TransactionalConnection) {}
+
+    findById(ctx: RequestContext, itemId: ID): Promise<Item | null> {
+        // This is simple enough that you should prefer the Find API,
+        // but here is how it would be done with the QueryBuilder API:
+        return this.connection.getRepository(ctx, Item).createQueryBuilder('item')
+            .where('item.id = :id', { id: itemId })
+            .getOne();
+    }
+
+    findManyWithSubquery(ctx: RequestContext, name: string) {
+        // Here's a more complex query that would not be possible using the Find API:
+        return this.connection.getRepository(ctx, Item).createQueryBuilder('item')
+            .where('item.name = :name', { name })
+            .andWhere(
+                new Brackets(qb1 => {
+                    qb1.where('item.state = :state1', { state1: 'PENDING' })
+                       .orWhere('item.state = :state2', { state2: 'RETRYING' });
+                }),
+            )
+            .orderBy('item.createdAt', 'ASC')
+            .getMany();
+    }
+}
+```
+
+:::info
+
+Further examples can be found in the [TypeORM QueryBuilder documentation](https://typeorm.io/select-query-builder).
+
+:::
+
+### Working with relations
+
+One limitation of TypeORM's typings is that we have no way of knowing at build-time whether a particular relation will be
+joined at runtime. For instance, the following code will build without issues, but will result in a runtime error:
+
+```ts
+const product = await this.connection.getRepository(ctx, Product).findOne({
+    where: { id: productId },
+});
+if (product) {
+    // highlight-start
+    console.log(product.featuredAsset.preview);
+    // ^ Error: Cannot read property 'preview' of undefined
+    // highlight-end
+}
+```
+
+This is because the `featuredAsset` relation is not joined by default. The simple fix for the above example is to use
+the `relations` option:
+
+```ts
+const product = await this.connection.getRepository(ctx, Product).findOne({
+    where: { id: productId },
+    // highlight-next-line
+    relations: { featuredAsset: true },
+});
+```
+or in the case of the QueryBuilder API, we can use the `leftJoinAndSelect()` method:
+
+```ts
+const product = await this.connection.getRepository(ctx, Product).createQueryBuilder('product')
+    // highlight-next-line
+    .leftJoinAndSelect('product.featuredAsset', 'featuredAsset')
+    .where('product.id = :id', { id: productId })
+    .getOne();
+```
+
+### Using the EntityHydrator
+
+But what about when we do not control the code which fetches the entity from the database? For instance, we might be implementing
+a function which gets an entity passed to it by Vendure. In this case, we can use the [`EntityHydrator`](/reference/typescript-api/data-access/entity-hydrator/)
+to ensure that a given relation is "hydrated" (i.e. joined) before we use it:
+
+```ts
+import { EntityHydrator, ShippingCalculator } from '@vendure/core';
+
+let entityHydrator: EntityHydrator;
+
+const myShippingCalculator = new ShippingCalculator({
+    // ... rest of config omitted for brevity
+    init(injector) {
+        entityHydrator = injector.get(EntityHydrator);
+    },
+    calculate: (ctx, order, args) => {
+      // highlight-start
+      // ensure that the customer and customer.groups relations are joined
+      await entityHydrator.hydrate(ctx, order, { relations: ['customer.groups' ]});
+      // highlight-end
+
+      if (order.customer?.groups?.some(g => g.name === 'VIP')) {
+        // ... do something special for VIP customers
+      } else {
+        // ... do something else
+      }
+    },
+});
+```
+
+### Joining relations in built-in service methods
+
+Many of the core services allow an optional `relations` argument in their `findOne()` and `findMany()` and related methods.
+This allows you to specify which relations should be joined when the query is executed. For instance, in the [`ProductService`](/reference/typescript-api/services/product-service)
+there is a `findOne()` method which allows you to specify which relations should be joined:
+
+```ts
+const productWithAssets = await this.productService
+    .findOne(ctx, productId, ['featuredAsset', 'assets']);
+```
+

package/docs/guides/developer-guide/translatable/index.md

@@ -0,0 +1,224 @@
+---
+title: "Implementing Translatable"
+showtoc: true
+---
+
+## Defining translatable entities
+
+Making an entity translatable means that string properties of the entity can have a different values for multiple languages.
+To make an entity translatable, you need to implement the [`Translatable`](/reference/typescript-api/entities/interfaces/#translatable) interface and add a `translations` property to the entity.
+
+```ts title="src/plugins/requests/entities/product-request.entity.ts"
+import { DeepPartial } from '@vendure/common/lib/shared-types';
+import { VendureEntity, Product, EntityId, ID, Translatable } from '@vendure/core';
+import { Column, Entity, ManyToOne } from 'typeorm';
+
+import { ProductRequestTranslation } from './product-request-translation.entity';
+
+@Entity()
+class ProductRequest extends VendureEntity implements Translatable {
+    constructor(input?: DeepPartial<ProductRequest>) {
+        super(input);
+    }
+// highlight-start
+    text: LocaleString;
+// highlight-end
+    
+    @ManyToOne(type => Product)
+    product: Product;
+
+    @EntityId()
+    productId: ID;
+
+
+// highlight-start
+    @OneToMany(() => ProductRequestTranslation, translation => translation.base, { eager: true })
+    translations: Array<Translation<ProductRequest>>;
+// highlight-end
+}
+```
+
+The `translations` property is a `OneToMany` relation to the translations. Any fields that are to be translated are of type `LocaleString`, and **do not have a `@Column()` decorator**.
+This is because the `text` field here does not in fact exist in the database in the `product_request` table. Instead, it belongs to the `product_request_translations` table of the `ProductRequestTranslation` entity:
+
+```ts title="src/plugins/requests/entities/product-request-translation.entity.ts"
+import { DeepPartial } from '@vendure/common/lib/shared-types';
+import { HasCustomFields, Translation, VendureEntity, LanguageCode } from '@vendure/core';
+import { Column, Entity, Index, ManyToOne } from 'typeorm';
+
+import { ProductRequest } from './release-note.entity';
+
+@Entity()
+export class ProductRequestTranslation
+    extends VendureEntity
+    implements Translation<ProductRequest>, HasCustomFields
+{
+    constructor(input?: DeepPartial<Translation<ProductRequestTranslation>>) {
+        super(input);
+    }
+
+    @Column('varchar')
+    languageCode: LanguageCode;
+
+    @Column('varchar')
+// highlight-start
+    text: string; // same name as the translatable field in the base entity
+// highlight-end
+    @Index()
+    @ManyToOne(() => ProductRequest, base => base.translations, { onDelete: 'CASCADE' })
+    base: ProductRequest;
+}
+```
+
+Thus there is a one-to-many relation between `ProductRequest` and `ProductRequestTranslation`, which allows Vendure to handle multiple translations of the same entity. The `ProductRequestTranslation` entity also implements the `Translation` interface, which requires the `languageCode` field and a reference to the base entity.
+
+### Translations in the GraphQL schema
+Since the `text` field is getting hydrated with the translation it should be exposed in the GraphQL Schema. Additionally, the `ProductRequestTranslation` type should
+be defined as well, to access other translations as well:
+```graphql title="src/plugins/requests/api/types.ts"
+type ProductRequestTranslation {
+    id: ID!
+    createdAt: DateTime!
+    updatedAt: DateTime!
+// highlight-start
+    languageCode: LanguageCode!
+    text: String!
+// highlight-end
+}
+
+type ProductRequest implements Node {
+    id: ID!
+    createdAt: DateTime!
+    updatedAt: DateTime!
+    # Will be filled with the translation for the current language
+    text: String!
+// highlight-next-line
+    translations: [ProductRequestTranslation!]!
+}
+
+```
+
+## Creating translatable entities
+
+Creating a translatable entity is usually done by using the [`TranslatableSaver`](/reference/typescript-api/service-helpers/translatable-saver/). This injectable service provides a `create` and `update` method which can be used to save or update a translatable entity.
+
+```ts title="src/plugins/requests/service/product-request.service.ts"
+export class RequestService {
+
+    constructor(private translatableSaver: TranslatableSaver) {}
+
+    async create(ctx: RequestContext, input: CreateProductRequestInput): Promise<ProductRequest> {
+        const request = await this.translatableSaver.create({
+            ctx,
+            input,
+            entityType: ProductRequest,
+            translationType: ProductRequestTranslation,
+            beforeSave: async f => {
+                // Assign relations here
+            },
+        });
+        return request;
+    }
+}
+```
+
+Important for the creation of translatable entities is the input object. The input object should contain a `translations` array with the translations for the entity. This can be done
+by defining the types like `CreateRequestInput` inside the GraphQL schema:
+
+```graphql title="src/plugins/requests/api/types.ts"
+input ProductRequestTranslationInput {
+    # Only defined for update mutations
+    id: ID
+// highlight-start
+    languageCode: LanguageCode!
+    text: String!
+// highlight-end
+}
+
+input CreateProductRequestInput {
+    text: String!
+// highlight-next-line
+    translations: [ProductRequestTranslationInput!]!
+}
+```
+
+## Updating translatable entities
+
+Updating a translatable entity is done in a similar way as creating one. The [`TranslatableSaver`](/reference/typescript-api/service-helpers/translatable-saver/) provides an `update` method which can be used to update a translatable entity.
+
+```ts title="src/plugins/requests/service/product-request.service.ts"
+export class RequestService {
+
+    constructor(private translatableSaver: TranslatableSaver) {}
+
+    async update(ctx: RequestContext, input: UpdateProductRequestInput): Promise<ProductRequest> {
+        const updatedEntity = await this.translatableSaver.update({
+            ctx,
+            input,
+            entityType: ProductRequest,
+            translationType: ProductRequestTranslation,
+            beforeSave: async f => {
+                // Assign relations here
+            },
+        });
+        return updatedEntity;
+    }
+}
+```
+
+Once again it's important to provide the `translations` array in the input object. This array should contain the translations for the entity.
+
+```graphql title="src/plugins/requests/api/types.ts"
+
+input UpdateProductRequestInput {
+    text: String
+// highlight-next-line
+    translations: [ProductRequestTranslationInput!]
+}
+```
+
+## Loading translatable entities
+
+If your plugin needs to load a translatable entity, you will need to use the [`TranslatorService`](/reference/typescript-api/service-helpers/translator-service/) to hydrate all the `LocaleString` fields will the actual translated values from the correct translation.
+
+```ts title="src/plugins/requests/service/product-request.service.ts"
+export class RequestService {
+
+    constructor(private translator: TranslatorService) {}
+
+    findAll(
+        ctx: RequestContext,
+        options?: ListQueryOptions<ProductRequest>,
+        relations?: RelationPaths<ProductRequest>,
+    ): Promise<PaginatedList<Translated<ProductRequest>>> {
+        return this.listQueryBuilder
+            .build(ProductRequest, options, {
+                relations,
+                ctx,
+            })
+            .getManyAndCount()
+            .then(([items, totalItems]) => {
+                return {
+// highlight-next-line
+                    items: items.map(item => this.translator.translate(item, ctx)),
+                    totalItems,
+                };
+            });
+    }
+    
+    findOne(
+        ctx: RequestContext,
+        id: ID,
+        relations?: RelationPaths<ProductRequest>,
+    ): Promise<Translated<ProductRequest> | null> {
+        return this.connection
+            .getRepository(ctx, ProductRequest)
+            .findOne({
+                where: { id },
+                relations,
+            })
+// highlight-next-line
+            .then(entity => entity && this.translator.translate(entity, ctx));
+    }
+}
+```

package/docs/guides/developer-guide/translations/index.md

@@ -0,0 +1,165 @@
+---
+title: "Translations"
+showtoc: true
+---
+
+The following items in Vendure can be translated:
+
+- Entities which implement the [`Translatable`](/reference/typescript-api/entities/interfaces/#translatable) interface.
+- Admin UI text labels and messages
+- Server error message
+
+## Translatable entities
+
+The following entities implement the `Translatable` interface:
+
+- [Collection](/reference/typescript-api/entities/collection/)
+- [Country](/reference/typescript-api/entities/country/)
+- [Facet](/reference/typescript-api/entities/facet/)
+- [FacetValue](/reference/typescript-api/entities/facet-value/)
+- [PaymentMethod](/reference/typescript-api/entities/payment-method/)
+- [Product](/reference/typescript-api/entities/product/)
+- [ProductOption](/reference/typescript-api/entities/product-option/)
+- [ProductOptionGroup](/reference/typescript-api/entities/product-option-group/)
+- [ProductVariant](/reference/typescript-api/entities/product-variant/)
+- [Promotion](/reference/typescript-api/entities/promotion/)
+- [Province](/reference/typescript-api/entities/province/)
+- [Region](/reference/typescript-api/entities/region/)
+- [ShippingMethod](/reference/typescript-api/entities/shipping-method/)
+
+To understand how translatable entities are implemented, let's take a look at a simplified version of the `Facet` entity:
+
+```ts
+@Entity()
+export class Facet extends VendureEntity implements Translatable {
+    
+    // highlight-next-line
+    name: LocaleString;
+
+    @Column({ unique: true })
+    code: string;
+
+    // highlight-next-line
+    @OneToMany(type => FacetTranslation, translation => translation.base, { eager: true })
+    // highlight-next-line
+    translations: Array<Translation<Facet>>;
+}
+```
+
+All translatable entities have a `translations` field which is a relation to the translations. Any fields that are to be translated are of type `LocaleString`, and **do note have a `@Column()` decorator**. This is because the `name` field here does not in fact exist in the database in the `facet` table. Instead, it belongs to the `facet_translations` table, which brings us to the `FacetTranslation` entity (again simplified for clarity):
+
+```ts
+@Entity()
+export class FacetTranslation extends VendureEntity implements Translation<Facet> {
+
+    @Column('varchar') languageCode: LanguageCode;
+
+    // highlight-next-line
+    @Column() name: string;
+
+    @Index()
+    @ManyToOne(type => Facet, base => base.translations, { onDelete: 'CASCADE' })
+    base: Facet;
+}
+```
+
+Thus there is a one-to-many relation between `Facet` and `FacetTranslation`, which allows Vendure to handle multiple translations of the same entity. The `FacetTranslation` entity also implements the `Translation` interface, which requires the `languageCode` field and a reference to the base entity.
+
+### Loading translatable entities
+
+If your plugin needs to load a translatable entity, you will need to use the [`TranslatorService`](/reference/typescript-api/service-helpers/translator-service/) to hydrate all the `LocaleString` fields will the actual translated values from the correct translation.
+
+For example, if you are loading a `Facet` entity, you would do the following:
+
+```ts
+import { Facet } from '@vendure/core';
+import { LanguageCode, RequestContext, TranslatorService, TransactionalConnection } from '@vendure/core';
+
+@Injectable()
+export class MyService {
+    
+    constructor(private connection: TransactionalConnection, private translator: TranslatorService) {}
+
+    async getFacet(ctx: RequestContext, id: ID): Promise<Facet | undefined> {
+        const facet = await this.connection.getRepository(ctx, Facet).findOne(id);
+        if (facet) {
+            // highlight-next-line
+            return this.translatorService.translate(facet, ctx);
+        }
+    }
+    
+    async getFacets(ctx: RequestContext): Promise<Facet[]> {
+        // highlight-next-line
+        const facets = await this.connection.getRepository(ctx, Facet).find();
+        // highlight-next-line
+        return Promise.all(facets.map(facet => this.translatorService.translate(facet, ctx)));
+    }
+}
+```
+## Admin UI translations
+
+See the [Adding Admin UI Translations guide](/guides/extending-the-admin-ui/adding-ui-translations/).
+
+## Server message translations
+
+Let's say you've implemented some custom server-side functionality as part of a plugin. You may be returning custom errors or other messages. Here's how you can
+provide these messages in multiple languages.
+
+Using [`addTranslation`](/reference/typescript-api/common/i18n-service/#addtranslation) inside the `onApplicationBootstrap` ([Nestjs lifecycle hooks](https://docs.nestjs.com/fundamentals/lifecycle-events)) of a Plugin is the easiest way to add new translations.
+While Vendure is only using `error`, `errorResult` and `message` resource keys you are free to use your own.
+
+### Translatable Error
+This example shows how to create a custom translatable error
+```ts
+/**
+ * Custom error class
+ */
+class CustomError extends ErrorResult {
+    readonly __typename = 'CustomError';
+    readonly errorCode = 'CUSTOM_ERROR';
+    readonly message = 'CUSTOM_ERROR'; //< looks up errorResult.CUSTOM_ERROR
+}
+
+@VendurePlugin({
+    imports: [PluginCommonModule],
+    providers: [I18nService],
+    // ...
+})
+export class TranslationTestPlugin implements OnApplicationBootstrap {
+
+    constructor(private i18nService: I18nService) {
+
+    }
+
+    onApplicationBootstrap(): any {
+        this.i18nService.addTranslation('en', {
+            errorResult: {
+                CUSTOM_ERROR: 'A custom error message',
+            },
+            anything: {
+                foo: 'bar'
+            }
+        });
+
+        this.i18nService.addTranslation('de', {
+            errorResult: {
+                CUSTOM_ERROR: 'Eine eigene Fehlermeldung',
+            },
+            anything: {
+                foo: 'bar'
+            }
+        });
+
+    }
+}
+```
+
+To receive an error in a specific language you need to use the `languageCode` query parameter
+`query(QUERY_WITH_ERROR_RESULT, { variables }, { languageCode: LanguageCode.de });`
+
+### Use translations
+
+Vendure uses the internationalization-framework [i18next](https://www.i18next.com/).
+
+Therefore you are free to use the i18next translate function to [access keys](https://www.i18next.com/translation-function/essentials#accessing-keys) \
+`i18next.t('error.any-message');`