effect-mq 0.1.0

package/src/drizzle/schema.ts

@@ -0,0 +1,116 @@
+/**
+ * Drizzle schema factories for effect-mq's Postgres tables.
+ *
+ * Re-export these from your own drizzle schema so drizzle-kit owns the
+ * migrations and your queries are fully typed — including the job `name`
+ * column typed to the union of your job tags:
+ *
+ * ```ts
+ * // schema.ts
+ * import { mqJobAttempts, mqJobs } from "effect-mq/drizzle"
+ *
+ * type DurableJobs = typeof SyncBenefits._tag | typeof GenerateReport._tag
+ * export const jobs = mqJobs<DurableJobs>()
+ * export const jobAttempts = mqJobAttempts(jobs)
+ * ```
+ *
+ * Then `drizzle-kit generate` emits the CREATE TABLE migrations into your
+ * pipeline like any other table. Reads through drizzle are encouraged;
+ * writes must go through the `JobStore` (e.g. `store.retry`) so locking and
+ * wake-up invariants hold.
+ *
+ * @since 0.1.0
+ */
+import type * as JobStore from "../JobStore.ts"
+import { sql } from "drizzle-orm"
+import { bigint, index, integer, jsonb, pgTable, primaryKey, text, timestamp } from "drizzle-orm/pg-core"
+
+type JobId = JobStore.JobId
+type QueueName = JobStore.QueueName
+type JobState = JobStore.JobState
+type BackoffPolicy = JobStore.BackoffPolicy
+type KeepPolicy = JobStore.KeepPolicy
+type AttemptOutcome = JobStore.AttemptRecord["outcome"]
+/**
+ * The jobs table factory. `JobName` types the `name` column — derive it from
+ * your job definitions: `mqJobs<typeof SyncBenefits._tag | typeof Report._tag>()`.
+ *
+ * @since 0.1.0
+ */
+export const mqJobs = <JobName extends string = string>(
+  tableName = "effect_mq_jobs"
+) =>
+  pgTable(tableName, {
+    id: text("id").primaryKey().$type<JobId>(),
+    name: text("name").notNull().$type<JobName>(),
+    queue: text("queue").notNull().$type<QueueName>(),
+    state: text("state").notNull().$type<JobState>(),
+    priority: integer("priority").notNull().default(0),
+    /** FIFO order within a priority; bumped on retry so retries go to the tail. */
+    seq: bigint("seq", { mode: "number" }).notNull().generatedByDefaultAsIdentity(),
+    payload: jsonb("payload"),
+    metadata: jsonb("metadata").notNull().default({}).$type<Record<string, string>>(),
+    attemptsMax: integer("attempts_max").notNull(),
+    attemptsMade: integer("attempts_made").notNull().default(0),
+    stalledCount: integer("stalled_count").notNull().default(0),
+    backoff: jsonb("backoff").$type<BackoffPolicy>(),
+    keep: jsonb("keep").$type<KeepPolicy>(),
+    runAt: timestamp("run_at", { withTimezone: true, mode: "date" }).notNull(),
+    enqueuedAt: timestamp("enqueued_at", { withTimezone: true, mode: "date" }).notNull(),
+    processedAt: timestamp("processed_at", { withTimezone: true, mode: "date" }),
+    finishedAt: timestamp("finished_at", { withTimezone: true, mode: "date" }),
+    exit: jsonb("exit"),
+    failedReason: text("failed_reason"),
+    lockToken: text("lock_token"),
+    lockExpiresAt: timestamp("lock_expires_at", { withTimezone: true, mode: "date" })
+  }, (table) => [
+    // Claim path: pop highest priority, FIFO within it.
+    index(`${tableName}_ready_idx`)
+      .on(table.queue, table.priority.desc(), table.seq.asc())
+      .where(sql`${table.state} = 'waiting'`),
+    // Delayed promotion + nextRunAt.
+    index(`${tableName}_delayed_idx`)
+      .on(table.queue, table.runAt)
+      .where(sql`${table.state} = 'delayed'`),
+    // Stalled sweep.
+    index(`${tableName}_active_idx`)
+      .on(table.lockExpiresAt)
+      .where(sql`${table.state} = 'active'`),
+    // History/retention queries.
+    index(`${tableName}_history_idx`).on(table.name, table.state, table.finishedAt),
+    // Listing (newest first, keyset pagination).
+    index(`${tableName}_listing_idx`).on(table.enqueuedAt.desc(), table.id.desc()),
+    // Metadata containment queries.
+    index(`${tableName}_metadata_idx`).using("gin", table.metadata.op("jsonb_path_ops"))
+  ])
+
+/**
+ * The job run-ledger table factory (one row per attempt, including
+ * successes and stall recoveries).
+ *
+ * @since 0.1.0
+ */
+export const mqJobAttempts = (
+  jobs: ReturnType<typeof mqJobs<any>>,
+  tableName = "effect_mq_job_attempts"
+) =>
+  pgTable(tableName, {
+    jobId: text("job_id").notNull().references(() => jobs.id, { onDelete: "cascade" }).$type<JobId>(),
+    attempt: integer("attempt").notNull(),
+    outcome: text("outcome").notNull().$type<AttemptOutcome>(),
+    startedAt: timestamp("started_at", { withTimezone: true, mode: "date" }),
+    finishedAt: timestamp("finished_at", { withTimezone: true, mode: "date" }).notNull(),
+    exit: jsonb("exit")
+  }, (table) => [
+    primaryKey({ columns: [table.jobId, table.attempt] })
+  ])
+
+/**
+ * @since 0.1.0
+ */
+export type MqJobsTable = ReturnType<typeof mqJobs<any>>
+
+/**
+ * @since 0.1.0
+ */
+export type MqJobAttemptsTable = ReturnType<typeof mqJobAttempts>

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Effect-native, storage-agnostic background jobs.
+ *
+ * @since 0.1.0
+ */
+
+/**
+ * Schema-first job definitions: `Job.make`, `enqueue`, `toLayer`.
+ *
+ * @since 0.1.0
+ */
+export * as Job from "./Job.ts"
+
+/**
+ * The storage seam: the `JobStore` service, job records and typed errors.
+ *
+ * @since 0.1.0
+ */
+export * as JobStore from "./JobStore.ts"
+
+/**
+ * The reference in-memory `JobStore` driver (Effect primitives only).
+ *
+ * @since 0.1.0
+ */
+export * as MemoryJobStore from "./MemoryJobStore.ts"
+
+/**
+ * The worker runtime: `Worker.layer` and handler registration.
+ *
+ * @since 0.1.0
+ */
+export * as Worker from "./Worker.ts"