Merge pull request #98 from medusajs/chore/update-sub-and-job-example

chore: update examples and bump dotenv to use the same version as Medusa

package.json

@@ -33,10 +33,9 @@
     "@medusajs/file-local": "^1.0.2",
     "@medusajs/medusa": "1.18.0",
     "@tanstack/react-query": "4.22.0",
-    "babel-preset-medusa-package": "^1.1.13",
     "body-parser": "^1.19.0",
     "cors": "^2.8.5",
-    "dotenv": "16.0.3",
+    "dotenv": "16.3.1",
     "express": "^4.17.2",
     "medusa-fulfillment-manual": "^1.1.38",
     "medusa-interfaces": "^1.3.7",

src/jobs/README.md

@@ -0,0 +1,32 @@
+# Custom scheduled jobs
+
+You may define custom scheduled jobs (cron jobs) by creating files in the `/jobs` directory.
+
+```ts
+import {
+  ProductService,
+  ScheduledJobArgs,
+  ScheduledJobConfig,
+} from "@medusajs/medusa";
+
+export default async function myCustomJob({ container }: ScheduledJobArgs) {
+  const productService: ProductService = container.resolve("productService");
+
+  const products = await productService.listAndCount();
+
+  // Do something with the products
+}
+
+export const config: ScheduledJobConfig = {
+  name: "daily-product-report",
+  schedule: "0 0 * * *", // Every day at midnight
+};
+```
+
+A scheduled job is defined in two parts a `handler` and a `config`. The `handler` is a function which is invoked when the job is scheduled. The `config` is an object which defines the name of the job, the schedule, and an optional data object.
+
+The `handler` is a function which takes one parameter, an `object` of type `ScheduledJobArgs` with the following properties:
+
+- `container` - a `MedusaContainer` instance which can be used to resolve services.
+- `data` - an `object` containing data passed to the job when it was scheduled. This object is passed in the `config` object.
+- `pluginOptions` - an `object` containing plugin options, if the job is defined in a plugin.

src/subscribers/README.md

@@ -4,40 +4,41 @@ You may define custom eventhandlers, `subscribers` by creating files in the `/su
 
 ```ts
 import MyCustomService from "../services/my-custom";
-import { EntityManager } from "typeorm";
-import { OrderService } from "@medusajs/medusa";
-import { IEventBusService } from "@medusajs/types";
-
-export default class MySubscriber {
-  protected readonly manager_: EntityManager;
-  protected readonly myCustomService_: MyCustomService
-
-  constructor(
-    {
-      manager,
-      eventBusService,
-      myCustomService,
-    }: {
-      manager: EntityManager;
-      eventBusService: IEventBusService;
-      myCustomService: MyCustomService;
-    }
-  ) {
-    this.manager_ = manager;
-    this.myCustomService_ = myCustomService;
-
-    eventBusService.subscribe(OrderService.Events.PLACED, this.handleOrderPlaced);
-  }
-
-  handleOrderPlaced = async (data): Promise<any> => {
-    return true;
-  }
+import {
+  OrderService,
+  SubscriberArgs,
+  SubscriberConfig,
+} from "@medusajs/medusa";
+
+type OrderPlacedEvent = {
+  id: string;
+  no_notification: boolean;
+};
+
+export default async function orderPlacedHandler({
+  data,
+  eventName,
+  container,
+}: SubscriberArgs<OrderPlacedEvent>) {
+  const orderService: OrderService = container.resolve(OrderService);
+
+  const order = await orderService.retrieve(data.id, {
+    relations: ["items", "items.variant", "items.variant.product"],
+  });
+
+  // Do something with the order
 }
 
+export const config: SubscriberConfig = {
+  event: OrderService.Events.PLACED,
+};
 ```
 
-A subscriber is defined as a `class` which is registered as a subscriber by invoking `eventBusService.subscribe` in the `constructor` of the class.
+A subscriber is defined in two parts a `handler` and a `config`. The `handler` is a function which is invoked when an event is emitted. The `config` is an object which defines which event(s) the subscriber should subscribe to.
 
-The type of event that the subscriber subscribes to is passed as the first parameter to the `eventBusService.subscribe` and the eventhandler is passed as the second parameter. The types of events a service can emmit are described in the individual service.
+The `handler` is a function which takes one parameter, an `object` of type `SubscriberArgs<T>` with the following properties:
 
-An eventhandler has one parameter; a data `object` which contain information relating to the event, including relevant `id's`. The `id` can be used to fetch the appropriate entity in the eventhandler.
+- `data` - an `object` of type `T` containing information about the event.
+- `eventName` - a `string` containing the name of the event.
+- `container` - a `MedusaContainer` instance which can be used to resolve services.
+- `pluginOptions` - an `object` containing plugin options, if the subscriber is defined in a plugin.