@vendure/docs 0.0.0-202601161541

package/docs/guides/developer-guide/database-entity/index.md

@@ -0,0 +1,136 @@
+---
+title: "Define a database entity"
+showtoc: true
+---
+
+:::cli
+Use `npx vendure add` to easily add a new entity to a plugin.
+:::
+
+Your plugin can define new database entities to model the data it needs to store. For instance, a product
+review plugin would need a way to store reviews. This would be done by defining a new database entity.
+
+This example shows how new [TypeORM database entities](https://typeorm.io/entities) can be defined by plugins.
+
+## Create the entity class
+
+```ts title="src/plugins/reviews/entities/product-review.entity.ts"
+import { DeepPartial } from '@vendure/common/lib/shared-types';
+import { VendureEntity, Product, EntityId, ID } from '@vendure/core';
+import { Column, Entity, ManyToOne } from 'typeorm';
+
+@Entity()
+class ProductReview extends VendureEntity {
+    constructor(input?: DeepPartial<ProductReview>) {
+        super(input);
+    }
+
+    @ManyToOne(type => Product)
+    product: Product;
+    
+    @EntityId()
+    productId: ID;
+
+    @Column()
+    text: string;
+
+    @Column()
+    rating: number;
+}
+```
+
+:::note
+Any custom entities *must* extend the [`VendureEntity`](/reference/typescript-api/entities/vendure-entity/) class.
+:::
+
+In this example, we are making use of the following TypeORM decorators:
+
+* [`@Entity()`](https://typeorm.io/decorator-reference#entity) - defines the entity as a TypeORM entity. This is **required** for all entities. It tells TypeORM to create a new table in the database for this entity.
+* [`@Column()`](https://typeorm.io/decorator-reference#column) - defines a column in the database table. The data type of the column is inferred from the TypeScript type of the property, but can be overridden by passing an options object to the decorator. The `@Column()` also supports many other options for defining the column, such as `nullable`, `default`, `unique`, `primary`, `enum` etc.
+* [`@ManyToOne()`](https://typeorm.io/decorator-reference#manytoone) - defines a many-to-one relationship between this entity and another entity. In this case, many  `ProductReview` entities can be associated with a given `Product`. There are other types of relations that can be defined - see the [TypeORM relations docs](https://typeorm.io/relations).
+
+There is an additional Vendure-specific decorator:
+
+* [`@EntityId()`](/reference/typescript-api/configuration/entity-id-decorator) marks a property as the ID of another entity. In this case, the `productId` property is the ID of the `Product` entity. The reason that we have a special decorator for this is that Vendure supports both numeric and string IDs, and the `@EntityId()` decorator will automatically set the database column to be the correct type. This `productId` is not _necessary_, but it is a useful convention to allow access to the ID of the associated entity without having to perform a database join.
+
+## Register the entity
+
+The new entity is then passed to the `entities` array of the VendurePlugin metadata:
+
+```ts title="src/plugins/reviews/reviews-plugin.ts"
+import { VendurePlugin } from '@vendure/core';
+import { ProductReview } from './entities/product-review.entity';
+
+@VendurePlugin({
+    // highlight-next-line
+    entities: [ProductReview],
+})
+export class ReviewsPlugin {}
+```
+
+:::note
+Once you have added a new entity to your plugin, and the plugin has been added to your VendureConfig plugins array, you must create a [database migration](/guides/developer-guide/migrations/) to create the new table in the database.
+:::
+
+## Using the entity
+
+The new entity can now be used in your plugin code. For example, you might want to create a new product review when a customer submits a review via the storefront:
+
+```ts title="src/plugins/reviews/services/review.service.ts"
+import { Injectable } from '@nestjs/common';
+import { RequestContext, Product, TransactionalConnection } from '@vendure/core';
+
+import { ProductReview } from '../entities/product-review.entity';
+
+@Injectable()
+export class ReviewService {
+    constructor(private connection: TransactionalConnection) {}
+
+    async createReview(ctx: RequestContext, productId: string, rating: number, text: string) {
+        const product = await this.connection.getEntityOrThrow(ctx, Product, productId);
+        // highlight-start
+        const review = new ProductReview({
+            product,
+            rating,
+            text,
+        });
+        return this.connection.getRepository(ctx, ProductReview).save(review);
+        // highlight-end
+    }
+}
+```
+
+## Available entity decorators
+
+In addition to the decorators described above, there are many other decorators provided by TypeORM. Some commonly used ones are:
+
+- [`@OneToOne()`](https://typeorm.io/decorator-reference#onetoone)
+- [`@OneToMany()`](https://typeorm.io/decorator-reference#onetomany)
+- [`@ManyToMany()`](https://typeorm.io/decorator-reference#manytomany)
+- [`@Index()`](https://typeorm.io/decorator-reference#index)
+- [`@Unique()`](https://typeorm.io/decorator-reference#unique)
+
+There is also another Vendure-specific decorator for representing monetary values specifically:
+
+- [`@Money()`](/reference/typescript-api/money/money-decorator): This works together with the [`MoneyStrategy`](/reference/typescript-api/money/money-strategy) to allow configurable control over how monetary values are stored in the database. For more information see the [Money & Currency guide](/guides/core-concepts/money/#the-money-decorator).
+
+:::info
+The full list of TypeORM decorators can be found in the [TypeORM decorator reference](https://typeorm.io/decorator-reference)
+:::
+
+
+## Corresponding GraphQL type
+
+Once you have defined a new DB entity, it is likely that you want to expose it in your GraphQL API. Here's how to [define a new type in your GraphQL API](/guides/developer-guide/extend-graphql-api/#defining-a-new-type).
+
+## Supporting translations
+
+In case you'd like to make the `ProductReview` entity support content in multiple languages, here's how to [implement the `Translatable` Interface](/guides/developer-guide/translatable).
+
+## Supporting channels
+
+In case you'd like to support separate `ProductReview` entities per Channel, here's how to [implement the `ChannelAware` Interface](/guides/developer-guide/channel-aware).
+
+## Supporting custom fields
+
+Just like you can extend Vendures native entities like `Product` to support your custom needs, you may enable other developers to extend your custom entities too! Here's how to [implement the `HasCustomFields` Interface](/guides/developer-guide/has-custom-fields).

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

@@ -0,0 +1,137 @@
+---
+title: "GraphQL Dataloaders"
+showtoc: true
+---
+
+[Dataloaders](https://github.com/graphql/dataloader) are used in GraphQL to solve the so called N+1 problem. This is an advanced performance optimization technique you may
+want to use in your application if you find certain custom queries are slow or inefficient.
+
+## N+1 problem
+
+Imagine a cart with 20 items. Your implementation requires you to perform an `async` calculation `isSubscription` for each cart item which executes one or more queries each time it is called, and it takes pretty long on each execution. It works fine for a cart with 1 or 2 items. But with more than 15 items, suddenly the cart takes a **lot** longer to load. Especially when the site is busy.
+
+The reason: the N+1 problem. Your cart is firing of 20 or more queries almost at the same time, adding **significantly** to the GraphQL request. It's like going to the McDonald's drive-in to get 10 hamburgers and getting in line 10 times to get 1 hamburger at a time. It's not efficient.
+
+## The solution: dataloaders
+
+Dataloaders allow you to say: instead of loading each field in the `grapqhl` tree one at a time, aggregate all the `ids` you want to execute the `async` calculation for, and then execute this for all the `ids` in one efficient `request`.
+
+Dataloaders are generally used on `fieldResolver`s. Often, you will need a specific dataloader for each field resolver.
+
+A Dataloader can return anything: `boolean`, `ProductVariant`, `string`, etc.
+
+## Performance implications
+
+Dataloaders can have a huge impact on performance. If your `fieldResolver` executes queries, and you log these queries, you should see a cascade of queries before the implementation of the dataloader, change to a single query using multiple `ids` after you implement it.
+
+## Do I need this for `CustomField` relations? 
+
+No, not normally. `CustomField` relations are automatically added to the root query for the `entity` that they are part of. So, they are loaded as part of the query that loads that entity.
+
+## Example
+
+We will provide a complete example here for you to use as a starting point. The skeleton created can handle multiple dataloaders across multiple channels. We will implement a `fieldResolver` called `isSubscription` for an `OrderLine` that will return a `true/false` for each incoming `orderLine`, to indicate whether the `orderLine` represents a subscription.
+
+
+```ts title="src/plugins/my-plugin/api/api-extensions.ts"
+import gql from 'graphql-tag';
+
+export const shopApiExtensions = gql`
+    extend type OrderLine {
+        isSubscription: Boolean!
+    }
+`
+```
+
+This next part import the `dataloader` package, which you can install with
+
+```sh
+npm install dataloader
+```
+
+**Dataloader skeleton**
+
+```ts title="src/plugins/my-plugin/api/dataloader.ts"
+import DataLoader from 'dataloader'
+
+const LoggerCtx = 'SubscriptionDataloaderService'
+
+@Injectable({ scope: Scope.REQUEST }) // Important! Dataloaders live at the request level
+export class DataloaderService {
+
+  /**
+   * first level is channel identifier, second level is dataloader key
+   */
+  private loaders = new Map<string, Map<string, DataLoader<ID, any>>>()
+
+  constructor(private service: SubscriptionExtensionService) {}
+
+  getLoader(ctx: RequestContext, dataloaderKey: string) {
+    const token = ctx.channel?.code ?? `${ctx.channelId}`
+    
+    Logger.debug(`Dataloader retrieval: ${token}, ${dataloaderKey}`, LoggerCtx)
+
+    if (!this.loaders.has(token)) {
+      this.loaders.set(token, new Map<string, DataLoader<ID, any>>())
+    }
+
+    const channelLoaders = this.loaders.get(token)!
+    if (!channelLoaders.get(dataloaderKey)) {
+      let loader: DataLoader<ID, any>
+
+      switch (dataloaderKey) {
+        case 'is-subscription':
+          loader = new DataLoader<ID, any>((ids) =>
+            this.batchLoadIsSubscription(ctx, ids as ID[]),
+          )
+          break
+        // Implement cases for your other dataloaders here
+        default:
+          throw new Error(`Unknown dataloader key ${dataloaderKey}`)
+      }
+
+      channelLoaders.set(dataloaderKey, loader)
+    }
+    return channelLoaders.get(dataloaderKey)!
+  }
+
+  private async batchLoadIsSubscription(
+    ctx: RequestContext,
+    ids: ID[],
+  ): Promise<Boolean[]> {
+    // Returns an array of ids that represent those input ids that are subscriptions
+    // Remember: this array can be smaller than the input array
+    const subscriptionIds = await this.service.whichSubscriptions(ctx, ids)
+
+    Logger.debug(`Dataloader is-subscription: ${ids}: ${subscriptionIds}`, LoggerCtx)
+
+    return ids.map((id) => subscriptionIds.includes(id)) // Important! preserve order and size of input ids array
+  }
+}
+```
+
+
+```ts title="src/plugins/my-plugin/api/entity-resolver.ts"
+@Resolver(() => OrderLine)
+export class MyPluginOrderLineEntityResolver {
+  constructor(
+    private dataloaderService: DataloaderService,
+  ) {}
+
+  @ResolveField()
+  isSubscription(@Ctx() ctx: RequestContext, @Parent() parent: OrderLine) {
+    const loader = this.dataloaderService.getLoader(ctx, 'is-subscription')
+    return loader.load(parent.id)
+  }
+}
+```
+
+To make it all work, ensure that the `DataLoaderService` is loaded in your `plugin` as a provider.
+
+:::tip
+Dataloaders map the result in the same order as the `ids` you send to the dataloader. 
+Dataloaders expect the same order and array size in the return result. 
+
+In other words: ensure that the order of your returned result is the same as the incoming `ids` and don't omit values!
+:::
+

package/docs/guides/developer-guide/db-subscribers/index.md

@@ -0,0 +1,115 @@
+---
+title: "Database subscribers"
+---
+
+# Defining database subscribers
+
+TypeORM allows us to define [subscribers](https://typeorm.io/listeners-and-subscribers#what-is-a-subscriber). With a subscriber, we can listen to specific entity events and take actions based on inserts, updates, deletions and more.
+
+If you need lower-level access to database changes that you get with the [Vendure EventBus system](/reference/typescript-api/events/event-bus/), TypeORM subscribers can be useful.
+
+## Simple subscribers
+
+The simplest way to register a subscriber is to pass it to the `dbConnectionOptions.subscribers` array:
+
+```ts title="src/plugins/my-plugin/product-subscriber.ts"
+import { Product, VendureConfig } from '@vendure/core';
+import { EntitySubscriberInterface, EventSubscriber, UpdateEvent } from 'typeorm';
+
+@EventSubscriber()
+export class ProductSubscriber implements EntitySubscriberInterface<Product> {
+  listenTo() {
+    return Product;
+  }
+  
+  beforeUpdate(event: UpdateEvent<Product>) {
+    console.log(`BEFORE PRODUCT UPDATED: `, event.entity);
+  }
+}
+```
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+import { ProductSubscriber } from './plugins/my-plugin/product-subscriber';
+
+// ...
+export const config: VendureConfig = {
+  dbConnectionOptions: {
+    // ...
+    subscribers: [ProductSubscriber],
+  }
+}
+```
+
+The limitation of this method is that the `ProductSubscriber` class cannot make use of dependency injection, since it is not known to the underlying NestJS application and is instead instantiated by TypeORM directly.
+
+If you need to make use of providers in your subscriber class, you'll need to use the following pattern.
+
+## Injectable subscribers
+
+By defining the subscriber as an injectable provider, and passing it to a Vendure plugin, you can take advantage of Nest's dependency injection inside the subscriber methods.
+
+```ts title="src/plugins/my-plugin/product-subscriber.ts"
+import {
+  PluginCommonModule,
+  Product,
+  TransactionalConnection,
+  VendureConfig,
+  VendurePlugin,
+} from '@vendure/core';
+import { Injectable } from '@nestjs/common';
+import { EntitySubscriberInterface, EventSubscriber, UpdateEvent } from 'typeorm';
+import { MyService } from './services/my.service';
+
+@Injectable()
+@EventSubscriber()
+export class ProductSubscriber implements EntitySubscriberInterface<Product> {
+    constructor(private connection: TransactionalConnection,
+                private myService: MyService) {
+        // This is how we can dynamically register the subscriber
+        // with TypeORM
+        connection.rawConnection.subscribers.push(this);
+    }
+
+    listenTo() {
+        return Product;
+    }
+
+    async beforeUpdate(event: UpdateEvent<Product>) {
+        console.log(`BEFORE PRODUCT UPDATED: `, event.entity);
+        // Now we can make use of our injected provider
+        await this.myService.handleProductUpdate(event);
+    }
+}
+```
+
+```ts title="src/plugins/my-plugin/my.plugin.ts"
+@VendurePlugin({
+    imports: [PluginCommonModule],
+    providers: [ProductSubscriber, MyService],
+})
+class MyPlugin {
+}
+```
+
+```ts title="src/vendure-config.ts"
+// ...
+export const config: VendureConfig = {
+    dbConnectionOptions: {
+        // We no longer need to pass the subscriber here
+        // subscribers: [ProductSubscriber],
+    },
+    plugins: [
+        MyPlugin,
+    ],
+}
+```
+
+## Troubleshooting subscribers
+
+An important factor when working with TypeORM subscribers is that they are very low-level and require some understanding of the Vendure schema.
+
+For example consider the `ProductSubscriber` above. If an admin changes a product's name in the Dashboard, this subscriber **will not fire**. The reason is that the `name` property is actually stored on the `ProductTranslation` entity, rather than on the `Product` entity.
+
+So if your subscribers do not seem to work as expected, check your database schema and make sure you are really targeting the correct entity which has the property that you are interested in.
+