Type safe async jobs (#1400)

Author: infomiho

waspc/ChangeLog.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.11.4
+
+### 🎉 [New Feature] Added Typescript support for Jobs
+
+Now you can type your async jobs better and receive all the benefits of Typescript. When you define a job, Wasp will generate a generic type which you can use to type your job function:
+
+```wasp
+job simplePrintJob {
+  executor: PgBoss,
+  perform: {
+    fn: import { simplePrint } from "@server/jobs.js",
+  },
+  entities: [Task]
+}
+```
+
+```typescript
+import { SimplePrintJob } from "@wasp/jobs/simplePrintJob";
+import { Task } from "@wasp/entities";
+
+export const simplePrint: SimplePrintJob<
+  { name: string },
+  { tasks: Task[] }
+> = async (args, context) => {
+  //        👆 args are typed e.g. { name: string }
+  //                👆 context is typed e.g. { entitites: { Task: ... } }
+  const tasks = await context.entities.Task.findMany({});
+  return {
+    tasks,
+  };
+};
+```
+
+When you use the job, you can pass the arguments and receive the result with the correct types:
+
+```typescript
+import { simplePrintJob } from "@wasp/jobs/simplePrintJob.js";
+
+...
+const job = await simplePrintJob.submit({ name: "John" })
+...
+const result = await result.pgBoss.details()
+//      👆 result is typed e.g. { tasks: Task[] }
+```
+
 ## 0.11.3
 
 ### 🎉 [New Feature] Type-safe links

waspc/data/Generator/templates/server/prettier.config.js

@@ -0,0 +1,7 @@
+// Used for internal Wasp development only, not copied to generated app.
+module.exports = {
+  trailingComma: 'es5',
+  tabWidth: 2,
+  semi: false,
+  singleQuote: true,
+}

waspc/data/Generator/templates/server/src/_types/index.ts

@@ -66,7 +66,7 @@ type EntityMap<Entities extends _Entity[]> = {
   [EntityName in Entities[number]["_entityName"]]: PrismaDelegate[EntityName]
 }
 
-type PrismaDelegate = {
+export type PrismaDelegate = {
   {=# entities =}
   "{= name =}": typeof prisma.{= prismaIdentifier =},
   {=/ entities =}

waspc/data/Generator/templates/server/src/_types/serialization.ts

@@ -1,35 +1,43 @@
-export type Payload = void | SuperJSONValue;
+export type Payload = void | SuperJSONValue
 
 // The part below was copied from SuperJSON and slightly modified:
 // https://github.com/blitz-js/superjson/blob/ae7dbcefe5d3ece5b04be0c6afe6b40f3a44a22a/src/types.ts
 //
 // We couldn't use SuperJSON's types directly because:
 //   1. They aren't exported publicly.
-//   2. They have a werid quirk that turns `SuperJSONValue` into `any`. 
-//      See why here: 
+//   2. They have a werid quirk that turns `SuperJSONValue` into `any`.
+//      See why here:
 //      https://github.com/blitz-js/superjson/pull/36#issuecomment-669239876
 //
 // We changed the code as little as possible to make future comparisons easier.
+export type JSONValue = PrimitiveJSONValue | JSONArray | JSONObject
 
-type PrimitiveJSONValue = string | number | boolean | undefined | null;
-
-type JSONValue = PrimitiveJSONValue | JSONArray | JSONObject;
-
-interface JSONArray extends Array<JSONValue> {
+export interface JSONObject {
+  [key: string]: JSONValue
 }
 
-interface JSONObject {
-    [key: string]: JSONValue;
-}
+type PrimitiveJSONValue = string | number | boolean | undefined | null
 
-type SerializableJSONValue = Symbol | Set<SuperJSONValue> | Map<SuperJSONValue, SuperJSONValue> | undefined | bigint | Date | RegExp;
+interface JSONArray extends Array<JSONValue> {}
 
-// Here's where we excluded `ClassInstance` (which was `any`) from the union. 
-type SuperJSONValue = JSONValue | SerializableJSONValue | SuperJSONArray | SuperJSONObject;
+type SerializableJSONValue =
+  | Symbol
+  | Set<SuperJSONValue>
+  | Map<SuperJSONValue, SuperJSONValue>
+  | undefined
+  | bigint
+  | Date
+  | RegExp
 
-interface SuperJSONArray extends Array<SuperJSONValue> {
-}
+// Here's where we excluded `ClassInstance` (which was `any`) from the union.
+type SuperJSONValue =
+  | JSONValue
+  | SerializableJSONValue
+  | SuperJSONArray
+  | SuperJSONObject
+
+interface SuperJSONArray extends Array<SuperJSONValue> {}
 
 interface SuperJSONObject {
-    [key: string]: SuperJSONValue;
+  [key: string]: SuperJSONValue
 }

waspc/data/Generator/templates/server/src/jobs/_job.js

@@ -0,0 +1,21 @@
+{{={= =}=}}
+import prisma from '../dbClient.js'
+import type { JSONValue, JSONObject } from '../_types/serialization.js'
+import { createJob, type JobFn } from './{= jobExecutorRelativePath =}'
+{=& jobPerformFnImportStatement =}
+
+const entities = {
+  {=# entities =}
+  {= name =}: prisma.{= prismaIdentifier =},
+  {=/ entities =}
+};
+
+export type {= typeName =}<Input extends JSONObject, Output extends JSONValue | void> = JobFn<Input, Output, typeof entities>
+
+export const {= jobName =} = createJob({
+  jobName: "{= jobName =}",
+  jobFn: {= jobPerformFnName =},
+  defaultJobOptions: {=& jobPerformOptions =},
+  jobSchedule: {=& jobSchedule =},
+  entities,
+})

waspc/data/Generator/templates/server/src/jobs/_job.ts

@@ -0,0 +1,28 @@
+/**
+ * This is a definition of a job (think draft or invocable computation), not the running instance itself.
+ * This can be submitted one or more times to be executed by some job executor via the same instance.
+ * Once submitted, you get a SubmittedJob to track it later.
+ */
+export class Job {
+  public readonly jobName: string
+  public readonly executorName: string | symbol
+
+  constructor(jobName: string, executorName: string | symbol) {
+    this.jobName = jobName
+    this.executorName = executorName
+  }
+}
+
+/**
+ * This is the result of submitting a Job to some executor.
+ * It can be used by callers to track things, or call executor-specific subclass functionality.
+ */
+export class SubmittedJob {
+  public readonly job: Job
+  public readonly jobId: string
+
+  constructor(job: Job, jobId: string) {
+    this.job = job
+    this.jobId = jobId
+  }
+}