Overhaul examples for testing and demonstrating patterns

jest.config.js

@@ -2,5 +2,5 @@
 module.exports = {
   preset: "ts-jest",
   testEnvironment: "node",
-  testMatch: ["<rootDir>/src/**/*.test.ts", "!**/examples/test/**/*.test.ts"],
+  testMatch: ["<rootDir>/src/**/*.test.ts", "!**/examples/**/*.test.ts"],
 };

package.json

@@ -20,7 +20,7 @@
     "pb:landing": "yarn build:landing && node -e 'const page = JSON.stringify(require(\"fs\").readFileSync(\"./landing/dist/index.html\").toString()); console.log(\"export const landing = \" + page);' > ./src/landing.ts && npx prettier ./src/landing.ts --write",
     "build": "yarn run clean && tsc --project tsconfig.build.json",
     "test": "node --expose-gc --max-old-space-size=4096 ./node_modules/.bin/jest --silent --logHeapUsage --maxWorkers=8 --coverage --ci --verbose",
-    "test:examples": "node --expose-gc --max-old-space-size=4096 ./node_modules/.bin/jest --silent --logHeapUsage --maxWorkers=8 --testMatch \"**/examples/test/*.test.ts\" --ci --verbose",
+    "test:examples": "node --expose-gc --max-old-space-size=4096 ./node_modules/.bin/jest --logHeapUsage --maxWorkers=8 --testMatch \"**/examples/**/*.test.ts\" --ci --verbose",
     "clean": "rm -rf ./dist",
     "lint": "eslint .",
     "postversion": "yarn run build && yarn run build:copy",

src/examples/README.md

@@ -3,3 +3,11 @@
 This directory contains examples of how to use the Inngest SDK.
 
 They are copied to various example repos to test against when building releases.
+
+- [**Hello World**](/src/examples/hello-world) - The simplest function
+- [**Parallel reduce**](/src/examples/parallel-reduce) - Accumulate values using reduce in parallel
+- [**Parallel work**](/src/examples/parallel-work) - Run concurrent chains of work in the same function
+- [**Polling**](/src/examples/polling) - Poll an external API for a change, timing out after a given period
+- [**Promise.all**](/src/examples/promise-all) - Basic usage of `Promise.all` with step tooling
+- [**Promise.race**](/src/examples/promise-race) - Basic usage of `Promise.race` with step tooling
+- [**Sequential reduce**](/src/examples/sequential-reduce) - Accumulate values using reduce in sequence

src/examples/hello-world/README.md

@@ -0,0 +1,9 @@
+# Hello World Example
+
+This demonstrates the simplest possible function. It's triggered by a `demo/hello.world` event and returns `"Hello, Inngest!"`.
+
+```mermaid
+graph TD
+Inngest -->|demo/hello.world| Function
+Function -->|Returns| Hello[Hello, Inngest!]
+```

src/examples/test/helloWorld.test.ts → src/examples/hello-world/index.test.ts

@@ -21,7 +21,7 @@ describe("introspection", () => {
       expect(data.functions).toContainEqual({
         name: "Hello World",
         id: expect.stringMatching(/^.*-hello-world$/),
-        triggers: [{ event: "demo/event.sent" }],
+        triggers: [{ event: "demo/hello.world" }],
         steps: {
           step: {
             id: "step",
@@ -44,10 +44,10 @@ describe("run", () => {
   let runId: string;
 
   beforeAll(async () => {
-    eventId = await sendEvent("demo/event.sent");
+    eventId = await sendEvent("demo/hello.world");
   });
 
-  test("runs in response to 'demo/event.sent'", async () => {
+  test("runs in response to 'demo/hello.world'", async () => {
     runId = await eventRunWithName(eventId, "Hello World");
     expect(runId).toEqual(expect.any(String));
   });

src/examples/helloWorld.ts → src/examples/hello-world/index.ts

@@ -1,7 +1,7 @@
-import { inngest } from "./client";
+import { inngest } from "../client";
 
 export default inngest.createFunction(
   { name: "Hello World" },
-  { event: "demo/event.sent" },
+  { event: "demo/hello.world" },
   () => "Hello, Inngest!"
 );

src/examples/index.ts

@@ -1,10 +1,10 @@
-import helloWorld from "./helloWorld";
-import parallelReduce from "./parallelReduce";
-import parallelWork from "./parallelWork";
+import helloWorld from "./hello-world";
+import parallelReduce from "./parallel-reduce";
+import parallelWork from "./parallel-work";
 import polling from "./polling";
-import promiseAll from "./Promise.all";
-import promiseRace from "./Promise.race";
-import sequentialReduce from "./sequentialReduce";
+import promiseAll from "./promise-all";
+import promiseRace from "./promise-race";
+import sequentialReduce from "./sequential-reduce";
 
 export default [
   helloWorld,

src/examples/parallel-reduce/README.md

@@ -0,0 +1,17 @@
+# Parallel Reduce Example
+
+This example demonstrates how to run multiple steps in parallel to accumulate a value using `Array.prototype.reduce`.
+
+It is triggered by a `demo/parallel.reduce` event, runs three steps in parallel to fetch scores from a database, and accumulates the total of all of the scores.
+
+To see a sequential version of this pattern, see the [sequential reduce example](/src/examples/sequential-reduce).
+
+```mermaid
+graph TD
+Inngest -->|demo/parallel.reduce| Function
+Function -->|Run step| blue[Get blue team score]
+Function -->|Run step| red[Get red team score]
+Function -->|Run step| green[Get green team score]
+blue & red & green --> total[Accumulate score]
+total -->|Returns| done[150]
+```

src/examples/parallelReduce.ts → src/examples/parallel-reduce/index.ts

@@ -1,4 +1,4 @@
-import { inngest } from "./client";
+import { inngest } from "../client";
 
 const scoresDb: Record<string, number> = {
   blue: 50,

src/examples/parallel-work/README.md

@@ -0,0 +1,34 @@
+# Parallel Work Example
+
+This example demonstrates how to run concurrent chains of work in the same step function, bringing their values together at the end.
+
+It is triggered by a `demo/parallel.work` event, runs 2 separate chains of work in parallel: `getScore()` and `getFruits()`.
+
+`getScore()` will run 3 steps sequentially, returning a `number` score.
+
+`getFruits()` will run 3 steps in parallel, returning an array of fruits.
+
+Finally, we return the result of these two chains of work at the end of the function.
+
+```mermaid
+graph TD
+Inngest -->|demo/parallel.work| Function
+
+subgraph getScore["getScore (sequential)"]
+score1[First score]
+score1 -->|Run step| score2[Second score]
+score2 -->|Run step| score3[Third score]
+end
+
+subgraph getFruits["getFruits (parallel)"]
+apple[Get apple]
+banana[Get banana]
+orange[Get orange]
+end
+
+Function -->|Run steps| getScore & getFruits
+
+getFruits ----> ret[Accumulate results]
+score3 --> ret
+ret -->|Returns| done["[ 5, 'Apple, Banana, Orange' ]"]
+```

src/examples/parallelWork.ts → src/examples/parallel-work/index.ts

@@ -1,4 +1,4 @@
-import { inngest } from "./client";
+import { inngest } from "../client";
 
 export default inngest.createFunction(
   { name: "Parallel Work" },

src/examples/polling.ts → src/examples/polling/index.ts

@@ -1,4 +1,4 @@
-import { inngest } from "./client";
+import { inngest } from "../client";
 
 export default inngest.createFunction(
   { name: "Parallel Reduce" },

src/examples/Promise.all.ts → src/examples/promise-all/index.ts

@@ -1,4 +1,4 @@
-import { inngest } from "./client";
+import { inngest } from "../client";
 
 export default inngest.createFunction(
   { name: "Promise.all" },

src/examples/Promise.race.ts → src/examples/promise-race/index.ts

@@ -1,4 +1,4 @@
-import { inngest } from "./client";
+import { inngest } from "../client";
 
 export default inngest.createFunction(
   { name: "Promise.race" },

src/examples/sequential-reduce/README.md

@@ -0,0 +1,17 @@
+# Sequential Reduce Example
+
+This example demonstrates how to run multiple steps in sequence to accumulate a value using `Array.prototype.reduce`.
+
+It is triggered by a `demo/sequential.reduce` event, runs three steps sequentially to fetch scores from a database, and accumulates the total of all of the scores.
+
+To see a parallel version of this pattern, see the [parallel reduce example](/src/examples/parallel-reduce).
+
+```mermaid
+graph TD
+Inngest -->|demo/sequential.reduce| Function
+Function -->|Run step| blue[Get blue team score]
+blue -->|Run step| red[Get red team score]
+red -->|Run step| green[Get green team score]
+green --> total[Accumulate score]
+total -->|Returns| done[150]
+```

src/examples/sequentialReduce.ts → src/examples/sequential-reduce/index.ts

@@ -1,4 +1,4 @@
-import { inngest } from "./client";
+import { inngest } from "../client";
 
 const scoresDb: Record<string, number> = {
   blue: 50,