convex-batch-processor 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blocksight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,337 @@
+# convex-batch-processor
+
+A Convex component for batch processing:
+
+1. **Batch Accumulator** - Collect items and flush when reaching size threshold or time interval
+2. **Table Iterator** - Process large tables in controlled batch sizes with pause/resume support
+
+## Installation
+
+```bash
+npm install convex-batch-processor
+```
+
+## Setup
+
+Add the component to your Convex app:
+
+```typescript
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import batchProcessor from "convex-batch-processor/convex.config";
+
+const app = defineApp();
+app.use(batchProcessor);
+
+export default app;
+```
+
+## Usage
+
+### Batch Accumulator
+
+The batch accumulator collects items and flushes them based on:
+- **Size threshold**: Flush when `maxBatchSize` items collected
+- **Time interval**: Flush automatically after `flushIntervalMs` since first item was added
+- **Manual trigger**: Force flush via API call
+
+```typescript
+import { mutation, internalAction } from "./_generated/server";
+import { internal, components } from "./_generated/api";
+import { BatchProcessor } from "convex-batch-processor";
+import { v } from "convex/values";
+
+// Define the event schema
+const analyticsEventValidator = v.object({
+  eventName: v.string(),
+  properties: v.optional(v.record(v.string(), v.string())),
+  timestamp: v.number(),
+});
+
+type AnalyticsEvent = typeof analyticsEventValidator.type;
+
+// Create a batch processor with config
+const batchProcessor = new BatchProcessor<AnalyticsEvent>(components.batchProcessor, {
+  maxBatchSize: 100,
+  flushIntervalMs: 30000,
+  processBatch: internal.analytics.processEventsBatch,
+});
+
+// Define the batch processor (must be an action)
+export const processEventsBatch = internalAction({
+  args: { items: v.array(analyticsEventValidator) },
+  handler: async (ctx, { items }) => {
+    await fetch("https://api.analytics.com/batch", {
+      method: "POST",
+      body: JSON.stringify({ events: items }),
+    });
+  },
+});
+
+// Add items to a batch
+export const trackEvent = mutation({
+  args: {
+    eventName: v.string(),
+    properties: v.optional(v.record(v.string(), v.string())),
+  },
+  handler: async (ctx, { eventName, properties }) => {
+    const event: AnalyticsEvent = { eventName, properties, timestamp: Date.now() };
+
+    return await batchProcessor.addItems(ctx, "analytics-events", [event]);
+  },
+});
+
+// Manual flush
+await batchProcessor.flush(ctx, "analytics-events");
+
+// Get batch status
+await batchProcessor.getBatchStatus(ctx, "analytics-events");
+
+// Get flush history
+await batchProcessor.getFlushHistory(ctx, "analytics-events");
+```
+
+The interval flush is scheduled automatically when the first item is added to a batch. No cron job is required.
+
+### Table Iterator
+
+The table iterator processes large datasets using a callback-based design:
+
+1. **You provide**: `getNextBatch` (query) + `processBatch` (action)
+2. **Component handles**: Scheduling, progress tracking, retries, pause/resume
+
+```typescript
+import { mutation, query, internalQuery, internalAction, internalMutation } from "./_generated/server";
+import { internal, components } from "./_generated/api";
+import { BatchProcessor } from "convex-batch-processor";
+import { v } from "convex/values";
+
+// Define the user schema
+const userValidator = v.object({
+  _id: v.id("users"),
+  _creationTime: v.number(),
+  name: v.string(),
+  email: v.string(),
+});
+
+type User = typeof userValidator.type;
+
+// For iterator-only usage, config is optional
+const batchProcessor = new BatchProcessor(components.batchProcessor);
+
+export const startMigration = mutation({
+  args: {},
+  handler: async (ctx) => {
+    const jobId = `migration-${Date.now()}`;
+
+    await batchProcessor.startIterator<User>(ctx, jobId, {
+      batchSize: 100,
+      delayBetweenBatchesMs: 100,
+      getNextBatch: internal.migrations.getNextBatch,
+      processBatch: internal.migrations.processBatch,
+      onComplete: internal.migrations.onComplete,
+      maxRetries: 5,
+    });
+
+    return { jobId };
+  },
+});
+
+export const getNextBatch = internalQuery({
+  args: {
+    cursor: v.optional(v.string()),
+    batchSize: v.number(),
+  },
+  handler: async (ctx, { cursor, batchSize }) => {
+    const results = await ctx.db
+      .query("users")
+      .paginate({ cursor: cursor ?? null, numItems: batchSize });
+
+    return {
+      items: results.page,
+      cursor: results.continueCursor,
+      done: results.isDone,
+    };
+  },
+});
+
+export const processBatch = internalAction({
+  args: { items: v.array(userValidator) },
+  handler: async (ctx, { items }) => {
+    for (const user of items) {
+      await migrateUser(user);
+    }
+  },
+});
+
+export const onComplete = internalMutation({
+  args: {
+    jobId: v.string(),
+    processedCount: v.number(),
+  },
+  handler: async (ctx, { jobId, processedCount }) => {
+    console.log(`Migration ${jobId} completed: ${processedCount} users`);
+  },
+});
+```
+
+#### Job Control
+
+```typescript
+export const pause = mutation({
+  args: { jobId: v.string() },
+  handler: async (ctx, { jobId }) => {
+    return await batchProcessor.pauseIterator(ctx, jobId);
+  },
+});
+
+export const resume = mutation({
+  args: { jobId: v.string() },
+  handler: async (ctx, { jobId }) => {
+    return await batchProcessor.resumeIterator(ctx, jobId);
+  },
+});
+
+export const cancel = mutation({
+  args: { jobId: v.string() },
+  handler: async (ctx, { jobId }) => {
+    return await batchProcessor.cancelIterator(ctx, jobId);
+  },
+});
+
+export const getStatus = query({
+  args: { jobId: v.string() },
+  handler: async (ctx, { jobId }) => {
+    return await batchProcessor.getIteratorStatus(ctx, jobId);
+  },
+});
+
+export const listJobs = query({
+  args: { status: v.optional(v.string()) },
+  handler: async (ctx, { status }) => {
+    return await batchProcessor.listIteratorJobs(ctx, { status });
+  },
+});
+```
+
+## API Reference
+
+### BatchProcessor Class
+
+#### Batch Accumulator Methods
+
+| Method | Description |
+|--------|-------------|
+| `addItems(ctx, batchId, items)` | Add items to a batch |
+| `flush(ctx, batchId)` | Force flush a batch |
+| `getBatchStatus(ctx, batchId)` | Get batch status |
+| `getFlushHistory(ctx, batchId, limit?)` | Get flush history |
+| `deleteBatch(ctx, batchId)` | Delete a completed batch |
+
+#### Table Iterator Methods
+
+| Method | Description |
+|--------|-------------|
+| `startIterator(ctx, jobId, config)` | Start a new iterator job |
+| `pauseIterator(ctx, jobId)` | Pause a running job |
+| `resumeIterator(ctx, jobId)` | Resume a paused job |
+| `cancelIterator(ctx, jobId)` | Cancel a job |
+| `getIteratorStatus(ctx, jobId)` | Get job status |
+| `listIteratorJobs(ctx, options?)` | List jobs |
+| `deleteIteratorJob(ctx, jobId)` | Delete a completed job |
+
+### Types
+
+#### BatchConfig
+
+```typescript
+interface BatchConfig<T = unknown> {
+  maxBatchSize: number;
+  flushIntervalMs: number;
+  processBatch: FunctionReference<"action", "internal", { items: T[] }>;
+}
+```
+
+**`processBatch` Requirements:**
+
+The `processBatch` **must be a Convex action** (not a mutation or plain JavaScript function). This is because:
+- The batch processor is called via `ctx.runAction()` internally
+- Actions can perform async operations like HTTP requests, which is the typical use case for batch processing (e.g., sending events to an external analytics service)
+
+Pass the function reference directly:
+
+```typescript
+const batchProcessor = new BatchProcessor(components.batchProcessor, {
+  maxBatchSize: 100,
+  flushIntervalMs: 30000,
+  processBatch: internal.myModule.processBatch,
+});
+```
+
+If you only need to write to the database (no external calls), you can still use an action that calls a mutation internally:
+
+```typescript
+export const processBatch = internalAction({
+  args: { items: v.array(myItemValidator) },
+  handler: async (ctx, { items }) => {
+    await ctx.runMutation(internal.myModule.writeBatchToDb, { items });
+  },
+});
+```
+
+#### IteratorConfig
+
+```typescript
+interface IteratorConfig<T = unknown> {
+  batchSize: number;
+  delayBetweenBatchesMs?: number;
+  getNextBatch: FunctionReference<"query", "internal", { cursor: string | undefined; batchSize: number }>;
+  processBatch: FunctionReference<"action", "internal", { items: T[] }>;
+  onComplete?: FunctionReference<"mutation", "internal", { jobId: string; processedCount: number }>;
+  maxRetries?: number;
+}
+```
+
+#### Callback Types
+
+```typescript
+interface GetNextBatchResult<T = unknown> {
+  items: T[];
+  cursor: string | undefined;
+  done: boolean;
+}
+
+interface ProcessBatchArgs<T = unknown> {
+  items: T[];
+}
+
+interface OnCompleteArgs {
+  jobId: string;
+  processedCount: number;
+}
+```
+
+## Error Handling
+
+### Batch Accumulator
+- Failed flushes are recorded in `flushHistory`
+- Items are preserved for retry (batch reverts to "accumulating" state)
+
+### Table Iterator
+- Automatic retry with exponential backoff (1s, 2s, 4s... up to 30s)
+- Job marked as "failed" after `maxRetries` attempts
+- Error messages preserved in job status
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+pnpm test
+pnpm run lint
+pnpm run format
+```
+
+## License
+
+MIT

package/dist/client/index.d.ts

@@ -0,0 +1,194 @@
+import { type FunctionReference, type GenericMutationCtx, type GenericQueryCtx } from "convex/server";
+export type BatchStatus = "accumulating" | "flushing" | "completed";
+export type JobStatus = "pending" | "running" | "paused" | "completed" | "failed";
+export interface BatchConfig<T = unknown> {
+    maxBatchSize: number;
+    flushIntervalMs: number;
+    processBatch: FunctionReference<"action", "internal", {
+        items: T[];
+    }>;
+}
+export interface IteratorConfig<T = unknown> {
+    batchSize: number;
+    delayBetweenBatchesMs?: number;
+    getNextBatch: FunctionReference<"query", "internal", {
+        cursor: string | undefined;
+        batchSize: number;
+    }>;
+    processBatch: FunctionReference<"action", "internal", {
+        items: T[];
+    }>;
+    onComplete?: FunctionReference<"mutation", "internal", {
+        jobId: string;
+        processedCount: number;
+    }>;
+    maxRetries?: number;
+}
+interface InternalBatchConfig {
+    maxBatchSize: number;
+    flushIntervalMs: number;
+    processBatchHandle: string;
+}
+interface InternalIteratorConfig {
+    batchSize: number;
+    delayBetweenBatchesMs?: number;
+    getNextBatchHandle: string;
+    processBatchHandle: string;
+    onCompleteHandle?: string;
+    maxRetries?: number;
+}
+export interface BatchResult {
+    batchId: string;
+    itemCount: number;
+    flushed: boolean;
+    status: BatchStatus;
+}
+export interface FlushResult {
+    batchId: string;
+    itemCount: number;
+    flushed: boolean;
+    status?: BatchStatus;
+    reason?: string;
+}
+export interface BatchStatusResult {
+    batchId: string;
+    itemCount: number;
+    status: BatchStatus;
+    createdAt: number;
+    lastUpdatedAt: number;
+    config: BatchConfig;
+}
+export interface JobResult {
+    jobId: string;
+    status: JobStatus;
+}
+export interface JobStatusResult {
+    jobId: string;
+    status: JobStatus;
+    processedCount: number;
+    cursor?: string;
+    retryCount: number;
+    errorMessage?: string;
+    createdAt: number;
+    lastRunAt?: number;
+    config: {
+        batchSize: number;
+        delayBetweenBatchesMs: number;
+    };
+}
+export interface JobListItem {
+    jobId: string;
+    status: JobStatus;
+    processedCount: number;
+    createdAt: number;
+    lastRunAt?: number;
+    errorMessage?: string;
+}
+export interface FlushHistoryItem {
+    batchId: string;
+    itemCount: number;
+    flushedAt: number;
+    durationMs: number;
+    success: boolean;
+    errorMessage?: string;
+}
+export interface BatchProcessorAPI {
+    lib: {
+        addItems: FunctionReference<"mutation", "internal", {
+            batchId: string;
+            items: unknown[];
+            config: InternalBatchConfig;
+        }, BatchResult>;
+        flushBatch: FunctionReference<"mutation", "internal", {
+            batchId: string;
+        }, FlushResult>;
+        getBatchStatus: FunctionReference<"query", "internal", {
+            batchId: string;
+        }, BatchStatusResult | null>;
+        getFlushHistory: FunctionReference<"query", "internal", {
+            batchId: string;
+            limit?: number;
+        }, FlushHistoryItem[]>;
+        deleteBatch: FunctionReference<"mutation", "internal", {
+            batchId: string;
+        }, {
+            deleted: boolean;
+            reason?: string;
+        }>;
+        startIteratorJob: FunctionReference<"mutation", "internal", {
+            jobId: string;
+            config: InternalIteratorConfig;
+        }, JobResult>;
+        pauseIteratorJob: FunctionReference<"mutation", "internal", {
+            jobId: string;
+        }, JobResult>;
+        resumeIteratorJob: FunctionReference<"mutation", "internal", {
+            jobId: string;
+        }, JobResult>;
+        cancelIteratorJob: FunctionReference<"mutation", "internal", {
+            jobId: string;
+        }, JobResult & {
+            reason?: string;
+        }>;
+        getIteratorJobStatus: FunctionReference<"query", "internal", {
+            jobId: string;
+        }, JobStatusResult | null>;
+        listIteratorJobs: FunctionReference<"query", "internal", {
+            status?: JobStatus;
+            limit?: number;
+        }, JobListItem[]>;
+        deleteIteratorJob: FunctionReference<"mutation", "internal", {
+            jobId: string;
+        }, {
+            deleted: boolean;
+            reason?: string;
+        }>;
+    };
+}
+export declare class BatchProcessor<T = unknown> {
+    private component;
+    private config?;
+    private processBatchHandle;
+    constructor(component: BatchProcessorAPI, config?: BatchConfig<T>);
+    addItems(ctx: GenericMutationCtx<any>, batchId: string, items: T[]): Promise<BatchResult>;
+    flush(ctx: GenericMutationCtx<any>, batchId: string): Promise<FlushResult>;
+    getBatchStatus(ctx: GenericQueryCtx<any>, batchId: string): Promise<BatchStatusResult | null>;
+    getFlushHistory(ctx: GenericQueryCtx<any>, batchId: string, limit?: number): Promise<FlushHistoryItem[]>;
+    deleteBatch(ctx: GenericMutationCtx<any>, batchId: string): Promise<{
+        deleted: boolean;
+        reason?: string;
+    }>;
+    startIterator<T>(ctx: GenericMutationCtx<any>, jobId: string, config: IteratorConfig<T>): Promise<JobResult>;
+    pauseIterator(ctx: GenericMutationCtx<any>, jobId: string): Promise<JobResult>;
+    resumeIterator(ctx: GenericMutationCtx<any>, jobId: string): Promise<JobResult>;
+    cancelIterator(ctx: GenericMutationCtx<any>, jobId: string): Promise<JobResult & {
+        reason?: string;
+    }>;
+    getIteratorStatus(ctx: GenericQueryCtx<any>, jobId: string): Promise<JobStatusResult | null>;
+    listIteratorJobs(ctx: GenericQueryCtx<any>, options?: {
+        status?: JobStatus;
+        limit?: number;
+    }): Promise<JobListItem[]>;
+    deleteIteratorJob(ctx: GenericMutationCtx<any>, jobId: string): Promise<{
+        deleted: boolean;
+        reason?: string;
+    }>;
+}
+export interface GetNextBatchResult<T = unknown> {
+    items: T[];
+    cursor: string | undefined;
+    done: boolean;
+}
+export interface GetNextBatchArgs {
+    cursor: string | undefined;
+    batchSize: number;
+}
+export interface ProcessBatchArgs<T = unknown> {
+    items: T[];
+}
+export interface OnCompleteArgs {
+    jobId: string;
+    processedCount: number;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/client/index.js

@@ -0,0 +1,75 @@
+import { createFunctionHandle, } from "convex/server";
+export class BatchProcessor {
+    component;
+    config;
+    processBatchHandle = null;
+    constructor(component, config) {
+        this.component = component;
+        this.config = config;
+    }
+    async addItems(ctx, batchId, items) {
+        if (!this.config) {
+            throw new Error("BatchProcessor config with processBatch is required to use addItems. Pass config to the constructor.");
+        }
+        if (!this.processBatchHandle) {
+            this.processBatchHandle = await createFunctionHandle(this.config.processBatch);
+        }
+        const internalConfig = {
+            maxBatchSize: this.config.maxBatchSize,
+            flushIntervalMs: this.config.flushIntervalMs,
+            processBatchHandle: this.processBatchHandle,
+        };
+        return await ctx.runMutation(this.component.lib.addItems, {
+            batchId,
+            items,
+            config: internalConfig,
+        });
+    }
+    async flush(ctx, batchId) {
+        return await ctx.runMutation(this.component.lib.flushBatch, { batchId });
+    }
+    async getBatchStatus(ctx, batchId) {
+        return await ctx.runQuery(this.component.lib.getBatchStatus, { batchId });
+    }
+    async getFlushHistory(ctx, batchId, limit) {
+        return await ctx.runQuery(this.component.lib.getFlushHistory, { batchId, limit });
+    }
+    async deleteBatch(ctx, batchId) {
+        return await ctx.runMutation(this.component.lib.deleteBatch, { batchId });
+    }
+    async startIterator(ctx, jobId, config) {
+        const internalConfig = {
+            batchSize: config.batchSize,
+            delayBetweenBatchesMs: config.delayBetweenBatchesMs,
+            getNextBatchHandle: await createFunctionHandle(config.getNextBatch),
+            processBatchHandle: await createFunctionHandle(config.processBatch),
+            onCompleteHandle: config.onComplete
+                ? await createFunctionHandle(config.onComplete)
+                : undefined,
+            maxRetries: config.maxRetries,
+        };
+        return await ctx.runMutation(this.component.lib.startIteratorJob, {
+            jobId,
+            config: internalConfig,
+        });
+    }
+    async pauseIterator(ctx, jobId) {
+        return await ctx.runMutation(this.component.lib.pauseIteratorJob, { jobId });
+    }
+    async resumeIterator(ctx, jobId) {
+        return await ctx.runMutation(this.component.lib.resumeIteratorJob, { jobId });
+    }
+    async cancelIterator(ctx, jobId) {
+        return await ctx.runMutation(this.component.lib.cancelIteratorJob, { jobId });
+    }
+    async getIteratorStatus(ctx, jobId) {
+        return await ctx.runQuery(this.component.lib.getIteratorJobStatus, { jobId });
+    }
+    async listIteratorJobs(ctx, options) {
+        return await ctx.runQuery(this.component.lib.listIteratorJobs, options ?? {});
+    }
+    async deleteIteratorJob(ctx, jobId) {
+        return await ctx.runMutation(this.component.lib.deleteIteratorJob, { jobId });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/component/_generated/api.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+import type * as lib from "../lib.js";
+import type { ApiFromModules, FilterApi, FunctionReference } from "convex/server";
+declare const fullApi: ApiFromModules<{
+    lib: typeof lib;
+}>;
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export declare const api: FilterApi<typeof fullApi, FunctionReference<any, "public">>;
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export declare const internal: FilterApi<typeof fullApi, FunctionReference<any, "internal">>;
+export declare const components: {};
+export {};
+//# sourceMappingURL=api.d.ts.map

package/dist/component/_generated/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/api.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,KAAK,GAAG,MAAM,WAAW,CAAC;AAEtC,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAGvB,QAAA,MAAM,OAAO,EAAE,cAAc,CAAC;IAC5B,GAAG,EAAE,OAAO,GAAG,CAAC;CACjB,CAAiB,CAAC;AAEnB;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG,EAAE,SAAS,CACzB,OAAO,OAAO,EACd,iBAAiB,CAAC,GAAG,EAAE,QAAQ,CAAC,CACjB,CAAC;AAElB;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,CAC9B,OAAO,OAAO,EACd,iBAAiB,CAAC,GAAG,EAAE,UAAU,CAAC,CACnB,CAAC;AAElB,eAAO,MAAM,UAAU,EAAqC,EAAE,CAAC"}