Add priority-queue example for TS

Author: jackkleeman

patterns-use-cases/priority-queue/priority-queue-typescript/README.md

@@ -0,0 +1,18 @@
+# Priority queue
+
+An example of implementing your own priority queue using Restate state and
+awakeables.
+
+Run the example with `npm run app-dev`.
+
+You can simulate adding work to the queue like this:
+```shell
+# add a single entry
+curl localhost:8080/myService/expensiveMethod/send --json '{"left": 1, "right": 2}'
+# add lots
+for i in $(seq 1 30); do curl localhost:8080/myService/expensiveMethod/send --json '{"left": 1, "right": 2}'; done
+```
+
+As you do so, you can observe the logs; in flight requests will increase up to 10, beyond which items will be enqueued.
+
+You can write your own queue item selection logic in `selectAndPopItem`; doing so is outside the scope of this example.

patterns-use-cases/priority-queue/priority-queue-typescript/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@restatedev/example-pattern-priority-queue",
+  "version": "0.1.0",
+  "description": "A Restate example showing the implementation of a distributed priority queue",
+  "type": "commonjs",
+  "scripts": {
+    "build": "tsc --noEmitOnError",
+    "app-dev": "tsx --watch ./src/app.ts",
+    "app": "tsx ./src/app.ts"
+  },
+  "dependencies": {
+    "@restatedev/restate-sdk": "^1.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "tsx": "^4.17.0",
+    "typescript": "^5.0.2"
+  }
+}

patterns-use-cases/priority-queue/priority-queue-typescript/src/app.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2024 - Restate Software, Inc., Restate GmbH
+ *
+ * This file is part of the Restate Examples for the Node.js/TypeScript SDK,
+ * which is released under the MIT license.
+ *
+ * You can find a copy of the license in the file LICENSE
+ * in the root directory of this repository or package or at
+ * https://github.com/restatedev/examples/blob/main/LICENSE
+ */
+
+import { endpoint } from "@restatedev/restate-sdk";
+
+import { queue } from "./queue";
+import { myService } from "./service";
+
+endpoint().bind(queue).bind(myService).listen();

patterns-use-cases/priority-queue/priority-queue-typescript/src/queue.ts

@@ -0,0 +1,73 @@
+/*
+ * Copyright (c) 2024 - Restate Software, Inc., Restate GmbH
+ *
+ * This file is part of the Restate Examples for the Node.js/TypeScript SDK,
+ * which is released under the MIT license.
+ *
+ * You can find a copy of the license in the file LICENSE
+ * in the root directory of this repository or package or at
+ * https://github.com/restatedev/examples/blob/main/LICENSE
+ */
+
+import { object, ObjectContext, TerminalError } from "@restatedev/restate-sdk";
+
+type QueueState = {
+  items: QueueItem[];
+  inFlight: number;
+};
+
+type QueueItem = {
+  awakeable: string;
+  priority: number;
+};
+
+type TickCause =
+  | {
+      type: "done";
+    }
+  | { type: "push"; item: QueueItem };
+
+// Put your super clever queue fairness algorithm here
+function selectAndPopItem<T>(items: QueueItem[]): QueueItem {
+  return items.pop()!;
+}
+
+const MAX_IN_FLIGHT = 10;
+
+export const queue = object({
+  name: "queue",
+  handlers: {
+    tick: async (
+      ctx: ObjectContext<QueueState>,
+      cause: TickCause,
+    ): Promise<void> => {
+      let items = (await ctx.get("items")) ?? [];
+      let inFlight = (await ctx.get("inFlight")) ?? 0;
+      switch (cause?.type) {
+        case "done":
+          inFlight--;
+          break;
+        case "push":
+          items.push(cause.item);
+          break;
+        default:
+          throw new TerminalError(`unexpected queue tick cause ${cause}`);
+      }
+
+      while (inFlight < MAX_IN_FLIGHT && items.length > 0) {
+        let item = selectAndPopItem(items);
+        inFlight++;
+        ctx.resolveAwakeable(item.awakeable);
+      }
+
+      ctx.console.log(
+        `Tick end. Queue length: ${items.length}, In Flight: ${inFlight}`,
+      );
+
+      ctx.set("items", items);
+      ctx.set("inFlight", inFlight);
+    },
+  },
+});
+
+export type Queue = typeof queue;

patterns-use-cases/priority-queue/priority-queue-typescript/src/queue_client.ts

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2024 - Restate Software, Inc., Restate GmbH
+ *
+ * This file is part of the Restate Examples for the Node.js/TypeScript SDK,
+ * which is released under the MIT license.
+ *
+ * You can find a copy of the license in the file LICENSE
+ * in the root directory of this repository or package or at
+ * https://github.com/restatedev/examples/blob/main/LICENSE
+ */
+
+import { Context, TerminalError } from "@restatedev/restate-sdk";
+import type { Queue } from "./queue";
+
+export async function doWithQueue<T>(
+  ctx: Context,
+  priority: number,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const awakeable = ctx.awakeable();
+  ctx.objectSendClient<Queue>({ name: "queue" }, "").tick({
+    type: "push",
+    item: {
+      awakeable: awakeable.id,
+      priority,
+    },
+  });
+
+  await awakeable.promise;
+
+  try {
+    const result = await operation();
+
+    ctx.objectSendClient<Queue>({ name: "queue" }, "").tick({
+      type: "done",
+    });
+
+    return result;
+  } catch (e) {
+    if (e instanceof TerminalError) {
+      ctx.objectSendClient<Queue>({ name: "queue" }, "").tick({
+        type: "done",
+      });
+    }
+    throw e;
+  }
+}

patterns-use-cases/priority-queue/priority-queue-typescript/src/service.ts

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2024 - Restate Software, Inc., Restate GmbH
+ *
+ * This file is part of the Restate Examples for the Node.js/TypeScript SDK,
+ * which is released under the MIT license.
+ *
+ * You can find a copy of the license in the file LICENSE
+ * in the root directory of this repository or package or at
+ * https://github.com/restatedev/examples/blob/main/LICENSE
+ */
+
+import { Context, service } from "@restatedev/restate-sdk";
+import { doWithQueue } from "./queue_client";
+
+export const myService = service({
+  name: "myService",
+  handlers: {
+    expensiveMethod: async (
+      ctx: Context,
+      params: { left: number; right: number },
+    ): Promise<number> => {
+      return doWithQueue(ctx, 1, () =>
+        ctx.run(() => expensiveOperation(params.left, params.right)),
+      );
+    },
+  },
+});
+
+async function expensiveOperation(
+  left: number,
+  right: number,
+): Promise<number> {
+  await new Promise((resolve) => setTimeout(resolve, 5_000));
+
+  // very cpu heavy - important that the queue protects this
+  return left + right;
+}
+
+export type MyService = typeof myService;

patterns-use-cases/priority-queue/priority-queue-typescript/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "lib": ["esnext"],
+    "module": "nodenext",
+    "allowJs": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipDefaultLibCheck": true,
+    "skipLibCheck": true
+  }
+}