convex-batch-processor 1.0.2

package/dist/component/schema.d.ts

@@ -0,0 +1,100 @@
+declare const _default: import("convex/server").SchemaDefinition<{
+    batches: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        scheduledFlushId?: import("convex/values").GenericId<"_scheduled_functions"> | undefined;
+        items: any[];
+        batchId: string;
+        config: {
+            maxBatchSize: number;
+            flushIntervalMs: number;
+            processBatchHandle: string;
+        };
+        status: "accumulating" | "flushing" | "completed";
+        itemCount: number;
+        createdAt: number;
+        lastUpdatedAt: number;
+    }, {
+        batchId: import("convex/values").VString<string, "required">;
+        items: import("convex/values").VArray<any[], import("convex/values").VAny<any, "required", string>, "required">;
+        itemCount: import("convex/values").VFloat64<number, "required">;
+        createdAt: import("convex/values").VFloat64<number, "required">;
+        lastUpdatedAt: import("convex/values").VFloat64<number, "required">;
+        status: import("convex/values").VUnion<"accumulating" | "flushing" | "completed", [import("convex/values").VLiteral<"accumulating", "required">, import("convex/values").VLiteral<"flushing", "required">, import("convex/values").VLiteral<"completed", "required">], "required", never>;
+        config: import("convex/values").VObject<{
+            maxBatchSize: number;
+            flushIntervalMs: number;
+            processBatchHandle: string;
+        }, {
+            maxBatchSize: import("convex/values").VFloat64<number, "required">;
+            flushIntervalMs: import("convex/values").VFloat64<number, "required">;
+            processBatchHandle: import("convex/values").VString<string, "required">;
+        }, "required", "maxBatchSize" | "flushIntervalMs" | "processBatchHandle">;
+        scheduledFlushId: import("convex/values").VId<import("convex/values").GenericId<"_scheduled_functions"> | undefined, "optional">;
+    }, "required", "items" | "batchId" | "config" | "status" | "itemCount" | "createdAt" | "lastUpdatedAt" | "scheduledFlushId" | "config.maxBatchSize" | "config.flushIntervalMs" | "config.processBatchHandle">, {
+        by_batchId: ["batchId", "_creationTime"];
+        by_status: ["status", "_creationTime"];
+    }, {}, {}>;
+    iteratorJobs: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        cursor?: string | undefined;
+        errorMessage?: string | undefined;
+        lastRunAt?: number | undefined;
+        jobId: string;
+        processedCount: number;
+        config: {
+            onCompleteHandle?: string | undefined;
+            maxRetries?: number | undefined;
+            batchSize: number;
+            processBatchHandle: string;
+            delayBetweenBatchesMs: number;
+            getNextBatchHandle: string;
+        };
+        status: "completed" | "pending" | "running" | "paused" | "failed";
+        createdAt: number;
+        retryCount: number;
+    }, {
+        jobId: import("convex/values").VString<string, "required">;
+        cursor: import("convex/values").VString<string | undefined, "optional">;
+        processedCount: import("convex/values").VFloat64<number, "required">;
+        status: import("convex/values").VUnion<"completed" | "pending" | "running" | "paused" | "failed", [import("convex/values").VLiteral<"pending", "required">, import("convex/values").VLiteral<"running", "required">, import("convex/values").VLiteral<"paused", "required">, import("convex/values").VLiteral<"completed", "required">, import("convex/values").VLiteral<"failed", "required">], "required", never>;
+        config: import("convex/values").VObject<{
+            onCompleteHandle?: string | undefined;
+            maxRetries?: number | undefined;
+            batchSize: number;
+            processBatchHandle: string;
+            delayBetweenBatchesMs: number;
+            getNextBatchHandle: string;
+        }, {
+            batchSize: import("convex/values").VFloat64<number, "required">;
+            delayBetweenBatchesMs: import("convex/values").VFloat64<number, "required">;
+            getNextBatchHandle: import("convex/values").VString<string, "required">;
+            processBatchHandle: import("convex/values").VString<string, "required">;
+            onCompleteHandle: import("convex/values").VString<string | undefined, "optional">;
+            maxRetries: import("convex/values").VFloat64<number | undefined, "optional">;
+        }, "required", "batchSize" | "processBatchHandle" | "delayBetweenBatchesMs" | "getNextBatchHandle" | "onCompleteHandle" | "maxRetries">;
+        retryCount: import("convex/values").VFloat64<number, "required">;
+        errorMessage: import("convex/values").VString<string | undefined, "optional">;
+        createdAt: import("convex/values").VFloat64<number, "required">;
+        lastRunAt: import("convex/values").VFloat64<number | undefined, "optional">;
+    }, "required", "cursor" | "jobId" | "processedCount" | "config" | "status" | "createdAt" | "config.processBatchHandle" | "retryCount" | "errorMessage" | "lastRunAt" | "config.batchSize" | "config.delayBetweenBatchesMs" | "config.getNextBatchHandle" | "config.onCompleteHandle" | "config.maxRetries">, {
+        by_jobId: ["jobId", "_creationTime"];
+        by_status: ["status", "_creationTime"];
+    }, {}, {}>;
+    flushHistory: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        errorMessage?: string | undefined;
+        batchId: string;
+        itemCount: number;
+        flushedAt: number;
+        durationMs: number;
+        success: boolean;
+    }, {
+        batchId: import("convex/values").VString<string, "required">;
+        itemCount: import("convex/values").VFloat64<number, "required">;
+        flushedAt: import("convex/values").VFloat64<number, "required">;
+        durationMs: import("convex/values").VFloat64<number, "required">;
+        success: import("convex/values").VBoolean<boolean, "required">;
+        errorMessage: import("convex/values").VString<string | undefined, "optional">;
+    }, "required", "batchId" | "itemCount" | "errorMessage" | "flushedAt" | "durationMs" | "success">, {
+        by_batchId: ["batchId", "_creationTime"];
+    }, {}, {}>;
+}, true>;
+export default _default;
+//# sourceMappingURL=schema.d.ts.map

package/dist/component/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGA,wBAqDG"}

package/dist/component/schema.js

@@ -0,0 +1,49 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+export default defineSchema({
+    batches: defineTable({
+        batchId: v.string(),
+        items: v.array(v.any()),
+        itemCount: v.number(),
+        createdAt: v.number(),
+        lastUpdatedAt: v.number(),
+        status: v.union(v.literal("accumulating"), v.literal("flushing"), v.literal("completed")),
+        config: v.object({
+            maxBatchSize: v.number(),
+            flushIntervalMs: v.number(),
+            processBatchHandle: v.string(),
+        }),
+        scheduledFlushId: v.optional(v.id("_scheduled_functions")),
+    })
+        .index("by_batchId", ["batchId"])
+        .index("by_status", ["status"]),
+    iteratorJobs: defineTable({
+        jobId: v.string(),
+        cursor: v.optional(v.string()),
+        processedCount: v.number(),
+        status: v.union(v.literal("pending"), v.literal("running"), v.literal("paused"), v.literal("completed"), v.literal("failed")),
+        config: v.object({
+            batchSize: v.number(),
+            delayBetweenBatchesMs: v.number(),
+            getNextBatchHandle: v.string(),
+            processBatchHandle: v.string(),
+            onCompleteHandle: v.optional(v.string()),
+            maxRetries: v.optional(v.number()),
+        }),
+        retryCount: v.number(),
+        errorMessage: v.optional(v.string()),
+        createdAt: v.number(),
+        lastRunAt: v.optional(v.number()),
+    })
+        .index("by_jobId", ["jobId"])
+        .index("by_status", ["status"]),
+    flushHistory: defineTable({
+        batchId: v.string(),
+        itemCount: v.number(),
+        flushedAt: v.number(),
+        durationMs: v.number(),
+        success: v.boolean(),
+        errorMessage: v.optional(v.string()),
+    }).index("by_batchId", ["batchId"]),
+});
+//# sourceMappingURL=schema.js.map

package/dist/component/schema.js.map

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

package/package.json

@@ -0,0 +1,63 @@
+{
+	"name": "convex-batch-processor",
+	"version": "1.0.2",
+	"description": "Batch processing component for Convex - batch accumulator and table iterator",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/blocknavi/convex-batch-processor"
+	},
+	"homepage": "https://github.com/blocknavi/convex-batch-processor#readme",
+	"bugs": {
+		"url": "https://github.com/blocknavi/convex-batch-processor/issues"
+	},
+	"license": "MIT",
+	"keywords": ["convex", "component", "batch", "processing", "iterator", "accumulator"],
+	"type": "module",
+	"scripts": {
+		"codegen": "npx convex codegen --component-dir src/component",
+		"build": "tsc --project ./tsconfig.build.json",
+		"build:clean": "rm -rf dist *.tsbuildinfo && pnpm run build",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write .",
+		"format": "biome format --write .",
+		"prepublishOnly": "pnpm run build && pnpm run lint",
+		"preversion": "pnpm install && pnpm run build:clean && pnpm run test && pnpm run lint",
+		"alpha": "npm version prerelease --preid alpha && npm publish --tag alpha && git push --follow-tags",
+		"release": "npm version patch && npm publish && git push --follow-tags"
+	},
+	"files": ["dist", "src"],
+	"exports": {
+		"./package.json": "./package.json",
+		".": {
+			"types": "./dist/client/index.d.ts",
+			"default": "./dist/client/index.js"
+		},
+		"./convex.config.js": {
+			"types": "./dist/component/convex.config.d.ts",
+			"default": "./dist/component/convex.config.js"
+		},
+		"./convex.config": {
+			"types": "./dist/component/convex.config.d.ts",
+			"default": "./dist/component/convex.config.js"
+		},
+		"./_generated/component.js": {
+			"types": "./dist/component/_generated/component.d.ts"
+		},
+		"./_generated/component": {
+			"types": "./dist/component/_generated/component.d.ts"
+		}
+	},
+	"dependencies": {
+		"convex": "^1.31.6"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.0",
+		"typescript": "^5.6.0",
+		"vitest": "^2.0.0"
+	},
+	"peerDependencies": {
+		"convex": "^1.31.6"
+	}
+}

package/src/client/index.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from "vitest";
+import {
+	type BatchConfig,
+	BatchProcessor,
+	type GetNextBatchArgs,
+	type GetNextBatchResult,
+	type IteratorConfig,
+	type OnCompleteArgs,
+	type ProcessBatchArgs,
+} from "./index";
+
+describe("BatchProcessor client", () => {
+	test("exports BatchProcessor class", () => {
+		expect(BatchProcessor).toBeDefined();
+		expect(typeof BatchProcessor).toBe("function");
+	});
+
+	test("BatchProcessor constructor accepts component API without config", () => {
+		// Create a mock component API
+		const mockComponent = {
+			lib: {
+				addItems: {} as any,
+				flushBatch: {} as any,
+				getBatchStatus: {} as any,
+				getFlushHistory: {} as any,
+				deleteBatch: {} as any,
+				startIteratorJob: {} as any,
+				pauseIteratorJob: {} as any,
+				resumeIteratorJob: {} as any,
+				cancelIteratorJob: {} as any,
+				getIteratorJobStatus: {} as any,
+				listIteratorJobs: {} as any,
+				deleteIteratorJob: {} as any,
+			},
+		};
+
+		const processor = new BatchProcessor(mockComponent);
+		expect(processor).toBeInstanceOf(BatchProcessor);
+	});
+
+	test("BatchProcessor constructor accepts component API with config", () => {
+		const mockComponent = {
+			lib: {
+				addItems: {} as any,
+				flushBatch: {} as any,
+				getBatchStatus: {} as any,
+				getFlushHistory: {} as any,
+				deleteBatch: {} as any,
+				startIteratorJob: {} as any,
+				pauseIteratorJob: {} as any,
+				resumeIteratorJob: {} as any,
+				cancelIteratorJob: {} as any,
+				getIteratorJobStatus: {} as any,
+				listIteratorJobs: {} as any,
+				deleteIteratorJob: {} as any,
+			},
+		};
+
+		const processor = new BatchProcessor(mockComponent, {
+			maxBatchSize: 100,
+			flushIntervalMs: 30000,
+			processBatch: {} as any, // Mock FunctionReference
+		});
+		expect(processor).toBeInstanceOf(BatchProcessor);
+	});
+});
+
+describe("type exports", () => {
+	test("BatchConfig type is usable", () => {
+		const config: BatchConfig = {
+			maxBatchSize: 100,
+			flushIntervalMs: 30000,
+			processBatch: {} as any, // FunctionReference is opaque, use mock
+		};
+		expect(config.maxBatchSize).toBe(100);
+	});
+
+	test("IteratorConfig type is usable", () => {
+		const config: IteratorConfig = {
+			batchSize: 50,
+			delayBetweenBatchesMs: 100,
+			getNextBatch: {} as any, // FunctionReference mock
+			processBatch: {} as any, // FunctionReference mock
+			onComplete: {} as any, // FunctionReference mock
+			maxRetries: 3,
+		};
+		expect(config.batchSize).toBe(50);
+	});
+
+	test("GetNextBatchResult type is usable", () => {
+		const result: GetNextBatchResult<{ id: number }> = {
+			items: [{ id: 1 }, { id: 2 }],
+			cursor: "cursor-123",
+			done: false,
+		};
+		expect(result.items.length).toBe(2);
+	});
+
+	test("GetNextBatchArgs type is usable", () => {
+		const args: GetNextBatchArgs = {
+			cursor: "cursor-123",
+			batchSize: 100,
+		};
+		expect(args.batchSize).toBe(100);
+	});
+
+	test("ProcessBatchArgs type is usable", () => {
+		const args: ProcessBatchArgs<{ id: number }> = {
+			items: [{ id: 1 }],
+		};
+		expect(args.items.length).toBe(1);
+	});
+
+	test("OnCompleteArgs type is usable", () => {
+		const args: OnCompleteArgs = {
+			jobId: "job-123",
+			processedCount: 1000,
+		};
+		expect(args.processedCount).toBe(1000);
+	});
+});

package/src/client/index.ts

@@ -0,0 +1,308 @@
+import {
+	type FunctionReference,
+	type GenericMutationCtx,
+	type GenericQueryCtx,
+	createFunctionHandle,
+} from "convex/server";
+
+export type BatchStatus = "accumulating" | "flushing" | "completed";
+export type JobStatus = "pending" | "running" | "paused" | "completed" | "failed";
+
+// User-facing config interfaces (accept FunctionReference)
+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;
+}
+
+// Internal config interfaces (use string handles for component API)
+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 class BatchProcessor<T = unknown> {
+	private component: BatchProcessorAPI;
+	private config?: BatchConfig<T>;
+	private processBatchHandle: string | null = null;
+
+	constructor(component: BatchProcessorAPI, config?: BatchConfig<T>) {
+		this.component = component;
+		this.config = config;
+	}
+
+	async addItems(ctx: GenericMutationCtx<any>, batchId: string, items: T[]): Promise<BatchResult> {
+		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: InternalBatchConfig = {
+			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: GenericMutationCtx<any>, batchId: string): Promise<FlushResult> {
+		return await ctx.runMutation(this.component.lib.flushBatch, { batchId });
+	}
+
+	async getBatchStatus(
+		ctx: GenericQueryCtx<any>,
+		batchId: string,
+	): Promise<BatchStatusResult | null> {
+		return await ctx.runQuery(this.component.lib.getBatchStatus, { batchId });
+	}
+
+	async getFlushHistory(
+		ctx: GenericQueryCtx<any>,
+		batchId: string,
+		limit?: number,
+	): Promise<FlushHistoryItem[]> {
+		return await ctx.runQuery(this.component.lib.getFlushHistory, { batchId, limit });
+	}
+
+	async deleteBatch(
+		ctx: GenericMutationCtx<any>,
+		batchId: string,
+	): Promise<{ deleted: boolean; reason?: string }> {
+		return await ctx.runMutation(this.component.lib.deleteBatch, { batchId });
+	}
+
+	async startIterator<T>(
+		ctx: GenericMutationCtx<any>,
+		jobId: string,
+		config: IteratorConfig<T>,
+	): Promise<JobResult> {
+		const internalConfig: InternalIteratorConfig = {
+			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: GenericMutationCtx<any>, jobId: string): Promise<JobResult> {
+		return await ctx.runMutation(this.component.lib.pauseIteratorJob, { jobId });
+	}
+
+	async resumeIterator(ctx: GenericMutationCtx<any>, jobId: string): Promise<JobResult> {
+		return await ctx.runMutation(this.component.lib.resumeIteratorJob, { jobId });
+	}
+
+	async cancelIterator(
+		ctx: GenericMutationCtx<any>,
+		jobId: string,
+	): Promise<JobResult & { reason?: string }> {
+		return await ctx.runMutation(this.component.lib.cancelIteratorJob, { jobId });
+	}
+
+	async getIteratorStatus(
+		ctx: GenericQueryCtx<any>,
+		jobId: string,
+	): Promise<JobStatusResult | null> {
+		return await ctx.runQuery(this.component.lib.getIteratorJobStatus, { jobId });
+	}
+
+	async listIteratorJobs(
+		ctx: GenericQueryCtx<any>,
+		options?: { status?: JobStatus; limit?: number },
+	): Promise<JobListItem[]> {
+		return await ctx.runQuery(this.component.lib.listIteratorJobs, options ?? {});
+	}
+
+	async deleteIteratorJob(
+		ctx: GenericMutationCtx<any>,
+		jobId: string,
+	): Promise<{ deleted: boolean; reason?: string }> {
+		return await ctx.runMutation(this.component.lib.deleteIteratorJob, { jobId });
+	}
+}
+
+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;
+}