@nicnocquee/dataqueue 1.20.0 → 1.21.0

package/src/queue.test.ts

@@ -748,3 +748,452 @@ describe('tags feature', () => {
     expect(job3?.status).toBe('cancelled');
   });
 });
+
+describe('cancelAllUpcomingJobs with runAt object filter', () => {
+  let pool: Pool;
+  let dbName: string;
+
+  beforeEach(async () => {
+    const setup = await createTestDbAndPool();
+    pool = setup.pool;
+    dbName = setup.dbName;
+  });
+
+  afterEach(async () => {
+    await pool.end();
+    await destroyTestDb(dbName);
+  });
+
+  it('should cancel jobs with runAt > filter (gt)', async () => {
+    const now = new Date();
+    const past = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+    const future = new Date(now.getTime() + 24 * 60 * 60 * 1000);
+    const jobIdPast = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'past@example.com' },
+        runAt: past,
+      },
+    );
+    const jobIdNow = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'now@example.com' },
+        runAt: now,
+      },
+    );
+    const jobIdFuture = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'future@example.com' },
+        runAt: future,
+      },
+    );
+    const cancelled = await queue.cancelAllUpcomingJobs(pool, {
+      runAt: { gt: now },
+    });
+    expect(cancelled).toBe(1);
+    const jobPast = await queue.getJob(pool, jobIdPast);
+    const jobNow = await queue.getJob(pool, jobIdNow);
+    const jobFuture = await queue.getJob(pool, jobIdFuture);
+    expect(jobPast?.status).toBe('pending');
+    expect(jobNow?.status).toBe('pending');
+    expect(jobFuture?.status).toBe('cancelled');
+  });
+
+  it('should cancel jobs with runAt >= filter (gte)', async () => {
+    const now = new Date();
+    const past = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+    const future = new Date(now.getTime() + 24 * 60 * 60 * 1000);
+    const jobIdPast = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'past@example.com' },
+        runAt: past,
+      },
+    );
+    const jobIdNow = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'now@example.com' },
+        runAt: now,
+      },
+    );
+    const jobIdFuture = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'future@example.com' },
+        runAt: future,
+      },
+    );
+    const cancelled = await queue.cancelAllUpcomingJobs(pool, {
+      runAt: { gte: now },
+    });
+    expect(cancelled).toBe(2);
+    const jobPast = await queue.getJob(pool, jobIdPast);
+    const jobNow = await queue.getJob(pool, jobIdNow);
+    const jobFuture = await queue.getJob(pool, jobIdFuture);
+    expect(jobPast?.status).toBe('pending');
+    expect(jobNow?.status).toBe('cancelled');
+    expect(jobFuture?.status).toBe('cancelled');
+  });
+
+  it('should cancel jobs with runAt < filter (lt)', async () => {
+    const now = new Date();
+    const past = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+    const future = new Date(now.getTime() + 24 * 60 * 60 * 1000);
+    const jobIdPast = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'past@example.com' },
+        runAt: past,
+      },
+    );
+    const jobIdNow = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'now@example.com' },
+        runAt: now,
+      },
+    );
+    const jobIdFuture = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'future@example.com' },
+        runAt: future,
+      },
+    );
+    const cancelled = await queue.cancelAllUpcomingJobs(pool, {
+      runAt: { lt: now },
+    });
+    expect(cancelled).toBe(1);
+    const jobPast = await queue.getJob(pool, jobIdPast);
+    const jobNow = await queue.getJob(pool, jobIdNow);
+    const jobFuture = await queue.getJob(pool, jobIdFuture);
+    expect(jobPast?.status).toBe('cancelled');
+    expect(jobNow?.status).toBe('pending');
+    expect(jobFuture?.status).toBe('pending');
+  });
+
+  it('should cancel jobs with runAt <= filter (lte)', async () => {
+    const now = new Date();
+    const past = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+    const future = new Date(now.getTime() + 24 * 60 * 60 * 1000);
+    const jobIdPast = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'past@example.com' },
+        runAt: past,
+      },
+    );
+    const jobIdNow = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'now@example.com' },
+        runAt: now,
+      },
+    );
+    const jobIdFuture = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'future@example.com' },
+        runAt: future,
+      },
+    );
+    const cancelled = await queue.cancelAllUpcomingJobs(pool, {
+      runAt: { lte: now },
+    });
+    expect(cancelled).toBe(2);
+    const jobPast = await queue.getJob(pool, jobIdPast);
+    const jobNow = await queue.getJob(pool, jobIdNow);
+    const jobFuture = await queue.getJob(pool, jobIdFuture);
+    expect(jobPast?.status).toBe('cancelled');
+    expect(jobNow?.status).toBe('cancelled');
+    expect(jobFuture?.status).toBe('pending');
+  });
+
+  it('should cancel jobs with runAt eq filter (eq)', async () => {
+    const now = new Date();
+    const past = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+    const future = new Date(now.getTime() + 24 * 60 * 60 * 1000);
+    const jobIdPast = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'past@example.com' },
+        runAt: past,
+      },
+    );
+    const jobIdNow = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'now@example.com' },
+        runAt: now,
+      },
+    );
+    const jobIdFuture = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'future@example.com' },
+        runAt: future,
+      },
+    );
+    const cancelled = await queue.cancelAllUpcomingJobs(pool, {
+      runAt: { eq: now },
+    });
+    expect(cancelled).toBe(1);
+    const jobPast = await queue.getJob(pool, jobIdPast);
+    const jobNow = await queue.getJob(pool, jobIdNow);
+    const jobFuture = await queue.getJob(pool, jobIdFuture);
+    expect(jobPast?.status).toBe('pending');
+    expect(jobNow?.status).toBe('cancelled');
+    expect(jobFuture?.status).toBe('pending');
+  });
+});
+
+describe('getJobs', () => {
+  let pool: Pool;
+  let dbName: string;
+
+  beforeEach(async () => {
+    const setup = await createTestDbAndPool();
+    pool = setup.pool;
+    dbName = setup.dbName;
+  });
+
+  afterEach(async () => {
+    await pool.end();
+    await destroyTestDb(dbName);
+  });
+
+  it('should filter by jobType', async () => {
+    const id1 = await queue.addJob<{ a: { n: number }; b: { n: number } }, 'a'>(
+      pool,
+      { jobType: 'a', payload: { n: 1 } },
+    );
+    const id2 = await queue.addJob<{ a: { n: number }; b: { n: number } }, 'b'>(
+      pool,
+      { jobType: 'b', payload: { n: 2 } },
+    );
+    const jobs = await queue.getJobs(pool, { jobType: 'a' });
+    expect(jobs.map((j) => j.id)).toContain(id1);
+    expect(jobs.map((j) => j.id)).not.toContain(id2);
+  });
+
+  it('should filter by priority', async () => {
+    const id1 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 1 },
+      priority: 1,
+    });
+    const id2 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 2 },
+      priority: 2,
+    });
+    const jobs = await queue.getJobs(pool, { priority: 2 });
+    expect(jobs.map((j) => j.id)).toContain(id2);
+    expect(jobs.map((j) => j.id)).not.toContain(id1);
+  });
+
+  it('should filter by runAt', async () => {
+    const runAt = new Date(Date.UTC(2030, 0, 1, 12, 0, 0, 0));
+    const id1 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 1 },
+      runAt,
+    });
+    const id2 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 2 },
+    });
+    const jobs = await queue.getJobs(pool, { runAt });
+    expect(jobs.map((j) => j.id)).toContain(id1);
+    expect(jobs.map((j) => j.id)).not.toContain(id2);
+  });
+
+  it('should filter jobs using runAt with gt/gte/lt/lte/eq', async () => {
+    const now = new Date();
+    const past = new Date(now.getTime() - 24 * 60 * 60 * 1000); // 1 day ago
+    const future = new Date(now.getTime() + 24 * 60 * 60 * 1000); // 1 day ahead
+    const jobIdPast = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'past@example.com' },
+        runAt: past,
+      },
+    );
+    const jobIdNow = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'now@example.com' },
+        runAt: now,
+      },
+    );
+    const jobIdFuture = await queue.addJob<{ email: { to: string } }, 'email'>(
+      pool,
+      {
+        jobType: 'email',
+        payload: { to: 'future@example.com' },
+        runAt: future,
+      },
+    );
+    // eq
+    let jobs = await queue.getJobs(pool, { runAt: now });
+    expect(jobs.map((j) => j.id)).toContain(jobIdNow);
+    // gt
+    jobs = await queue.getJobs(pool, { runAt: { gt: now } });
+    expect(jobs.map((j) => j.id)).toContain(jobIdFuture);
+    expect(jobs.map((j) => j.id)).not.toContain(jobIdNow);
+    // gte
+    jobs = await queue.getJobs(pool, { runAt: { gte: now } });
+    expect(jobs.map((j) => j.id)).toContain(jobIdNow);
+    expect(jobs.map((j) => j.id)).toContain(jobIdFuture);
+    // lt
+    jobs = await queue.getJobs(pool, { runAt: { lt: now } });
+    expect(jobs.map((j) => j.id)).toContain(jobIdPast);
+    expect(jobs.map((j) => j.id)).not.toContain(jobIdNow);
+    // lte
+    jobs = await queue.getJobs(pool, { runAt: { lte: now } });
+    expect(jobs.map((j) => j.id)).toContain(jobIdPast);
+    expect(jobs.map((j) => j.id)).toContain(jobIdNow);
+  });
+
+  it('should filter by tags (all mode)', async () => {
+    const id1 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 1 },
+      tags: ['foo', 'bar'],
+    });
+    const id2 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 2 },
+      tags: ['foo'],
+    });
+    const jobs = await queue.getJobs(pool, {
+      tags: { values: ['foo', 'bar'], mode: 'all' },
+    });
+    expect(jobs.map((j) => j.id)).toContain(id1);
+    expect(jobs.map((j) => j.id)).not.toContain(id2);
+  });
+
+  it('should filter by tags (any mode)', async () => {
+    const id1 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 1 },
+      tags: ['foo'],
+    });
+    const id2 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 2 },
+      tags: ['bar'],
+    });
+    const jobs = await queue.getJobs(pool, {
+      tags: { values: ['foo', 'bar'], mode: 'any' },
+    });
+    expect(jobs.map((j) => j.id)).toContain(id1);
+    expect(jobs.map((j) => j.id)).toContain(id2);
+  });
+
+  it('should filter by tags (exact mode)', async () => {
+    const id1 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 1 },
+      tags: ['foo', 'bar'],
+    });
+    const id2 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 2 },
+      tags: ['foo', 'bar', 'baz'],
+    });
+    const jobs = await queue.getJobs(pool, {
+      tags: { values: ['foo', 'bar'], mode: 'exact' },
+    });
+    expect(jobs.map((j) => j.id)).toContain(id1);
+    expect(jobs.map((j) => j.id)).not.toContain(id2);
+  });
+
+  it('should filter by tags (none mode)', async () => {
+    const id1 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 1 },
+      tags: ['foo'],
+    });
+    const id2 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 2 },
+      tags: ['bar'],
+    });
+    const id3 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 3 },
+      tags: ['baz'],
+    });
+    const jobs = await queue.getJobs(pool, {
+      tags: { values: ['foo', 'bar'], mode: 'none' },
+    });
+    expect(jobs.map((j) => j.id)).toContain(id3);
+    expect(jobs.map((j) => j.id)).not.toContain(id1);
+    expect(jobs.map((j) => j.id)).not.toContain(id2);
+  });
+
+  it('should support pagination', async () => {
+    const ids = [];
+    for (let i = 0; i < 5; i++) {
+      ids.push(
+        await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+          jobType: 'a',
+          payload: { n: i },
+        }),
+      );
+    }
+    const firstTwo = await queue.getJobs(pool, {}, 2, 0);
+    const nextTwo = await queue.getJobs(pool, {}, 2, 2);
+    expect(firstTwo.length).toBe(2);
+    expect(nextTwo.length).toBe(2);
+    const firstIds = firstTwo.map((j) => j.id);
+    const nextIds = nextTwo.map((j) => j.id);
+    expect(firstIds.some((id) => nextIds.includes(id))).toBe(false);
+  });
+
+  it('should filter by a combination of filters', async () => {
+    const runAt = new Date(Date.UTC(2030, 0, 1, 12, 0, 0, 0));
+    const id1 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 1 },
+      priority: 1,
+      runAt,
+      tags: ['foo', 'bar'],
+    });
+    const id2 = await queue.addJob<{ a: { n: number } }, 'a'>(pool, {
+      jobType: 'a',
+      payload: { n: 2 },
+      priority: 2,
+      tags: ['foo'],
+    });
+    const jobs = await queue.getJobs(pool, {
+      jobType: 'a',
+      priority: 1,
+      runAt,
+      tags: { values: ['foo', 'bar'], mode: 'all' },
+    });
+    expect(jobs.map((j) => j.id)).toContain(id1);
+    expect(jobs.map((j) => j.id)).not.toContain(id2);
+  });
+});

package/src/queue.ts

@@ -421,7 +421,7 @@ export const cancelAllUpcomingJobs = async (
   filters?: {
     jobType?: string;
     priority?: number;
-    runAt?: Date;
+    runAt?: Date | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
     tags?: { values: string[]; mode?: TagQueryMode };
   },
 ): Promise<number> => {
@@ -443,8 +443,32 @@ export const cancelAllUpcomingJobs = async (
         params.push(filters.priority);
       }
       if (filters.runAt) {
-        query += ` AND run_at = $${paramIdx++}`;
-        params.push(filters.runAt);
+        if (filters.runAt instanceof Date) {
+          query += ` AND run_at = $${paramIdx++}`;
+          params.push(filters.runAt);
+        } else if (typeof filters.runAt === 'object') {
+          const ops = filters.runAt;
+          if (ops.gt) {
+            query += ` AND run_at > $${paramIdx++}`;
+            params.push(ops.gt);
+          }
+          if (ops.gte) {
+            query += ` AND run_at >= $${paramIdx++}`;
+            params.push(ops.gte);
+          }
+          if (ops.lt) {
+            query += ` AND run_at < $${paramIdx++}`;
+            params.push(ops.lt);
+          }
+          if (ops.lte) {
+            query += ` AND run_at <= $${paramIdx++}`;
+            params.push(ops.lte);
+          }
+          if (ops.eq) {
+            query += ` AND run_at = $${paramIdx++}`;
+            params.push(ops.eq);
+          }
+        }
       }
       if (
         filters.tags &&
@@ -661,3 +685,123 @@ export const getJobsByTags = async <
     client.release();
   }
 };
+
+export const getJobs = async <PayloadMap, T extends keyof PayloadMap & string>(
+  pool: Pool,
+  filters?: {
+    jobType?: string;
+    priority?: number;
+    runAt?: Date | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
+    tags?: { values: string[]; mode?: TagQueryMode };
+  },
+  limit = 100,
+  offset = 0,
+): Promise<JobRecord<PayloadMap, T>[]> => {
+  const client = await pool.connect();
+  try {
+    let query = `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", tags FROM job_queue`;
+    const params: any[] = [];
+    let where: string[] = [];
+    let paramIdx = 1;
+    if (filters) {
+      if (filters.jobType) {
+        where.push(`job_type = $${paramIdx++}`);
+        params.push(filters.jobType);
+      }
+      if (filters.priority !== undefined) {
+        where.push(`priority = $${paramIdx++}`);
+        params.push(filters.priority);
+      }
+      if (filters.runAt) {
+        if (filters.runAt instanceof Date) {
+          where.push(`run_at = $${paramIdx++}`);
+          params.push(filters.runAt);
+        } else if (
+          typeof filters.runAt === 'object' &&
+          (filters.runAt.gt !== undefined ||
+            filters.runAt.gte !== undefined ||
+            filters.runAt.lt !== undefined ||
+            filters.runAt.lte !== undefined ||
+            filters.runAt.eq !== undefined)
+        ) {
+          const ops = filters.runAt as {
+            gt?: Date;
+            gte?: Date;
+            lt?: Date;
+            lte?: Date;
+            eq?: Date;
+          };
+          if (ops.gt) {
+            where.push(`run_at > $${paramIdx++}`);
+            params.push(ops.gt);
+          }
+          if (ops.gte) {
+            where.push(`run_at >= $${paramIdx++}`);
+            params.push(ops.gte);
+          }
+          if (ops.lt) {
+            where.push(`run_at < $${paramIdx++}`);
+            params.push(ops.lt);
+          }
+          if (ops.lte) {
+            where.push(`run_at <= $${paramIdx++}`);
+            params.push(ops.lte);
+          }
+          if (ops.eq) {
+            where.push(`run_at = $${paramIdx++}`);
+            params.push(ops.eq);
+          }
+        }
+      }
+      if (
+        filters.tags &&
+        filters.tags.values &&
+        filters.tags.values.length > 0
+      ) {
+        const mode = filters.tags.mode || 'all';
+        const tagValues = filters.tags.values;
+        switch (mode) {
+          case 'exact':
+            where.push(`tags = $${paramIdx++}`);
+            params.push(tagValues);
+            break;
+          case 'all':
+            where.push(`tags @> $${paramIdx++}`);
+            params.push(tagValues);
+            break;
+          case 'any':
+            where.push(`tags && $${paramIdx++}`);
+            params.push(tagValues);
+            break;
+          case 'none':
+            where.push(`NOT (tags && $${paramIdx++})`);
+            params.push(tagValues);
+            break;
+          default:
+            where.push(`tags @> $${paramIdx++}`);
+            params.push(tagValues);
+        }
+      }
+    }
+    if (where.length > 0) {
+      query += ` WHERE ${where.join(' AND ')}`;
+    }
+    // Always add LIMIT and OFFSET as the last parameters
+    paramIdx = params.length + 1;
+    query += ` ORDER BY created_at DESC LIMIT $${paramIdx++} OFFSET $${paramIdx}`;
+    params.push(limit, offset);
+    const result = await client.query(query, params);
+    log(`Found ${result.rows.length} jobs`);
+    return result.rows.map((job) => ({
+      ...job,
+      payload: job.payload,
+      timeoutMs: job.timeoutMs,
+      failureReason: job.failureReason,
+    }));
+  } catch (error) {
+    log(`Error getting jobs: ${error}`);
+    throw error;
+  } finally {
+    client.release();
+  }
+};

package/src/types.ts

@@ -225,6 +225,17 @@ export interface JobQueue<PayloadMap> {
     limit?: number,
     offset?: number,
   ) => Promise<JobRecord<PayloadMap, T>[]>;
+  /**
+   * Get jobs by filters.
+  /**
+   * Get jobs by filters.
+   */
+  getJobs: <T extends JobType<PayloadMap>>(filters?: {
+    jobType?: string;
+    priority?: number;
+    runAt?: Date | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
+    tags?: { values: string[]; mode?: TagQueryMode };
+  }) => Promise<JobRecord<PayloadMap, T>[]>;
   /**
    * Retry a job given its ID.
    * - This will set the job status back to 'pending', clear the locked_at and locked_by, and allow it to be picked up by other workers.
@@ -253,13 +264,13 @@ export interface JobQueue<PayloadMap> {
    * - The filters are:
    *   - jobType: The job type to cancel.
    *   - priority: The priority of the job to cancel.
-   *   - runAt: The time the job is scheduled to run at.
+   *   - runAt: The time the job is scheduled to run at (now supports gt/gte/lt/lte/eq).
    *   - tags: An object with 'values' (string[]) and 'mode' (TagQueryMode) for tag-based cancellation.
    */
   cancelAllUpcomingJobs: (filters?: {
     jobType?: string;
     priority?: number;
-    runAt?: Date;
+    runAt?: Date | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
     tags?: { values: string[]; mode?: TagQueryMode };
   }) => Promise<number>;
   /**