convex-batch-processor 0.5.0

package/dist/component/lib.d.ts

@@ -0,0 +1,351 @@
+export declare const addItems: import("convex/server").RegisteredMutation<"public", {
+    items: any[];
+    batchId: string;
+    config: {
+        maxBatchSize: number;
+        flushIntervalMs: number;
+        processBatchHandle: string;
+    };
+}, Promise<{
+    batchId: string;
+    itemCount: number;
+    flushed: boolean;
+    status: string;
+}>>;
+export declare const flushBatch: import("convex/server").RegisteredMutation<"public", {
+    batchId: string;
+}, Promise<{
+    batchId: string;
+    itemCount: number;
+    flushed: boolean;
+    reason: string;
+    status?: undefined;
+} | {
+    batchId: string;
+    itemCount: number;
+    flushed: boolean;
+    status: string;
+    reason?: undefined;
+}>>;
+export declare const getBatchStatus: import("convex/server").RegisteredQuery<"public", {
+    batchId: string;
+}, Promise<{
+    batchId: string;
+    batches: {
+        status: "accumulating" | "flushing";
+        itemCount: number;
+        createdAt: number;
+        lastUpdatedAt: number;
+    }[];
+    config: {
+        maxBatchSize: number;
+        flushIntervalMs: number;
+    };
+} | null>>;
+export declare const getAllBatchesForBaseId: import("convex/server").RegisteredQuery<"public", {
+    baseBatchId: string;
+}, Promise<{
+    batchId: string;
+    baseBatchId: string;
+    sequence: number;
+    itemCount: number;
+    status: "accumulating" | "flushing" | "completed";
+    createdAt: number;
+    lastUpdatedAt: number;
+}[]>>;
+export declare const getFlushHistory: import("convex/server").RegisteredQuery<"public", {
+    limit?: number | undefined;
+    batchId: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"flushHistory">;
+    _creationTime: number;
+    errorMessage?: string | undefined;
+    batchId: string;
+    itemCount: number;
+    flushedAt: number;
+    durationMs: number;
+    success: boolean;
+}[]>>;
+export declare const deleteBatch: import("convex/server").RegisteredMutation<"public", {
+    batchId: string;
+}, Promise<{
+    deleted: boolean;
+    reason: string;
+} | {
+    deleted: boolean;
+    reason?: undefined;
+}>>;
+export declare const getBatch: import("convex/server").RegisteredQuery<"internal", {
+    batchId: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"batches">;
+    _creationTime: number;
+    scheduledFlushId?: import("convex/values").GenericId<"_scheduled_functions"> | undefined;
+    flushStartedAt?: number | undefined;
+    batchId: string;
+    config: {
+        maxBatchSize: number;
+        flushIntervalMs: number;
+        processBatchHandle: string;
+    };
+    baseBatchId: string;
+    status: "accumulating" | "flushing" | "completed";
+    sequence: number;
+    createdAt: number;
+    lastUpdatedAt: number;
+} | null>>;
+export declare const collectBatchItems: import("convex/server").RegisteredQuery<"internal", {
+    batchDocId: import("convex/values").GenericId<"batches">;
+}, Promise<{
+    items: never[];
+    flushStartedAt: undefined;
+} | {
+    items: unknown[];
+    flushStartedAt: number;
+}>>;
+type FlushTransitionResult = {
+    flushed: true;
+    itemCount: number;
+} | {
+    flushed: false;
+    reason: string;
+};
+/**
+ * maybeFlush - Attempts to transition a batch from "accumulating" to "flushing" state.
+ *
+ * This is an internal action scheduled by addItems (when threshold is reached) or
+ * flushBatch (for manual flushes). It serves as a lightweight coordinator that
+ * delegates the actual state transition to doFlushTransition (a mutation).
+ *
+ * ## Why this architecture?
+ *
+ * 1. **OCC is handled automatically by Convex**: When doFlushTransition (a mutation)
+ *    encounters an OCC conflict, Convex automatically retries it. We don't need
+ *    external retry logic like ActionRetrier for database operations.
+ *
+ * 2. **Race conditions are handled gracefully**: Multiple maybeFlush calls can be
+ *    scheduled concurrently (e.g., rapid addItems calls all hitting threshold).
+ *    The first one to execute wins the race and transitions the batch to "flushing".
+ *    Subsequent calls see status !== "accumulating" and return early with
+ *    reason: "not_accumulating". This is expected behavior, not an error.
+ *
+ * 3. **Mutations can't call actions directly**: Convex mutations are deterministic
+ *    and can't have side effects. To execute the user's processBatchHandle (an action),
+ *    we need this action layer. The flow is:
+ *      mutation (addItems) → schedules action (maybeFlush)
+ *      action (maybeFlush) → calls mutation (doFlushTransition)
+ *      mutation (doFlushTransition) → schedules action (executeFlush)
+ *
+ * 4. **Non-blocking for callers**: addItems returns immediately after scheduling
+ *    maybeFlush. Users don't wait for the flush to complete.
+ *
+ * ## Failure scenarios
+ *
+ * - If maybeFlush fails completely (rare), the batch stays in "accumulating" state.
+ *   The next addItems call that hits threshold will schedule another maybeFlush.
+ * - If a scheduled interval flush exists, it will also attempt the transition.
+ *
+ * @param batchDocId - The batch document ID to potentially flush
+ * @param force - If true, flush regardless of threshold (used by manual flush and interval timer)
+ */
+export declare const maybeFlush: import("convex/server").RegisteredAction<"internal", {
+    force?: boolean | undefined;
+    batchDocId: import("convex/values").GenericId<"batches">;
+}, Promise<void>>;
+/**
+ * doFlushTransition - The actual state machine transition from "accumulating" to "flushing".
+ *
+ * This mutation is the source of truth for batch state transitions. It's designed to be
+ * idempotent and race-condition safe:
+ *
+ * - Returns early if batch is already flushing/completed (another caller won the race)
+ * - Returns early if batch is empty or below threshold (unless force=true)
+ * - On success, atomically updates status and schedules executeFlush
+ *
+ * OCC (Optimistic Concurrency Control) note:
+ * If two doFlushTransition calls race, Convex detects the conflict when both try to
+ * patch the same batch document. One succeeds, the other is auto-retried by Convex.
+ * On retry, it sees status="flushing" and returns { flushed: false, reason: "not_accumulating" }.
+ */
+export declare const doFlushTransition: import("convex/server").RegisteredMutation<"internal", {
+    force?: boolean | undefined;
+    batchDocId: import("convex/values").GenericId<"batches">;
+}, Promise<FlushTransitionResult>>;
+export declare const executeFlush: import("convex/server").RegisteredAction<"internal", {
+    processBatchHandle: string;
+    batchDocId: import("convex/values").GenericId<"batches">;
+}, Promise<{
+    success: boolean;
+    durationMs: number;
+    errorMessage?: undefined;
+} | {
+    success: boolean;
+    errorMessage: string | undefined;
+    durationMs: number;
+}>>;
+export declare const recordFlushResult: import("convex/server").RegisteredMutation<"internal", {
+    flushStartedAt?: number | undefined;
+    errorMessage?: string | undefined;
+    batchDocId: import("convex/values").GenericId<"batches">;
+    itemCount: number;
+    durationMs: number;
+    success: boolean;
+}, Promise<void>>;
+/**
+ * scheduledIntervalFlush - Timer-triggered flush that runs after flushIntervalMs.
+ *
+ * Scheduled once when a batch is created (if flushIntervalMs > 0). Uses force=true
+ * to flush regardless of whether the batch has reached maxBatchSize threshold.
+ * This ensures batches don't sit indefinitely waiting for more items.
+ */
+export declare const scheduledIntervalFlush: import("convex/server").RegisteredAction<"internal", {
+    batchDocId: import("convex/values").GenericId<"batches">;
+}, Promise<void>>;
+export declare const startIteratorJob: import("convex/server").RegisteredMutation<"public", {
+    jobId: string;
+    config: {
+        delayBetweenBatchesMs?: number | undefined;
+        onCompleteHandle?: string | undefined;
+        maxRetries?: number | undefined;
+        batchSize: number;
+        processBatchHandle: string;
+        getNextBatchHandle: string;
+    };
+}, Promise<{
+    jobId: string;
+    status: string;
+}>>;
+export declare const pauseIteratorJob: import("convex/server").RegisteredMutation<"public", {
+    jobId: string;
+}, Promise<{
+    jobId: string;
+    status: string;
+}>>;
+export declare const resumeIteratorJob: import("convex/server").RegisteredMutation<"public", {
+    jobId: string;
+}, Promise<{
+    jobId: string;
+    status: string;
+}>>;
+export declare const cancelIteratorJob: import("convex/server").RegisteredMutation<"public", {
+    jobId: string;
+}, Promise<{
+    jobId: string;
+    status: "completed" | "failed";
+    reason: string;
+} | {
+    jobId: string;
+    status: string;
+    reason?: undefined;
+}>>;
+export declare const getIteratorJobStatus: import("convex/server").RegisteredQuery<"public", {
+    jobId: string;
+}, Promise<{
+    jobId: string;
+    status: "completed" | "pending" | "running" | "paused" | "failed";
+    processedCount: number;
+    cursor: string | undefined;
+    retryCount: number;
+    errorMessage: string | undefined;
+    createdAt: number;
+    lastRunAt: number | undefined;
+    config: {
+        batchSize: number;
+        delayBetweenBatchesMs: number;
+    };
+} | null>>;
+export declare const listIteratorJobs: import("convex/server").RegisteredQuery<"public", {
+    limit?: number | undefined;
+    status?: "completed" | "pending" | "running" | "paused" | "failed" | undefined;
+}, Promise<{
+    jobId: string;
+    status: "completed" | "pending" | "running" | "paused" | "failed";
+    processedCount: number;
+    createdAt: number;
+    lastRunAt: number | undefined;
+    errorMessage: string | undefined;
+}[]>>;
+export declare const deleteIteratorJob: import("convex/server").RegisteredMutation<"public", {
+    jobId: string;
+}, Promise<{
+    deleted: boolean;
+    reason: string;
+} | {
+    deleted: boolean;
+    reason?: undefined;
+}>>;
+export declare const getIteratorJob: import("convex/server").RegisteredQuery<"internal", {
+    jobId: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"iteratorJobs">;
+    _creationTime: number;
+    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;
+} | null>>;
+export declare const getIteratorJobById: import("convex/server").RegisteredQuery<"internal", {
+    jobDocId: import("convex/values").GenericId<"iteratorJobs">;
+}, Promise<{
+    _id: import("convex/values").GenericId<"iteratorJobs">;
+    _creationTime: number;
+    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;
+} | null>>;
+export declare const processNextBatch: import("convex/server").RegisteredAction<"internal", {
+    jobDocId: import("convex/values").GenericId<"iteratorJobs">;
+}, Promise<{
+    processed: boolean;
+    done?: boolean;
+    processedCount?: number;
+    reason?: string;
+    error?: string;
+    retryCount?: number;
+}>>;
+export declare const updateJobProgress: import("convex/server").RegisteredMutation<"internal", {
+    cursor?: string | undefined;
+    processedCount: number;
+    jobDocId: import("convex/values").GenericId<"iteratorJobs">;
+}, Promise<void>>;
+export declare const markJobCompleted: import("convex/server").RegisteredMutation<"internal", {
+    processedCount: number;
+    jobDocId: import("convex/values").GenericId<"iteratorJobs">;
+}, Promise<void>>;
+export declare const markJobFailed: import("convex/server").RegisteredMutation<"internal", {
+    retryCount: number;
+    errorMessage: string;
+    jobDocId: import("convex/values").GenericId<"iteratorJobs">;
+}, Promise<void>>;
+export declare const incrementRetryCount: import("convex/server").RegisteredMutation<"internal", {
+    retryCount: number;
+    errorMessage: string;
+    jobDocId: import("convex/values").GenericId<"iteratorJobs">;
+}, Promise<void>>;
+export {};
+//# sourceMappingURL=lib.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../../src/component/lib.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,QAAQ;;;;;;;;;;;;;GA8FnB,CAAC;AAEH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;GAwDrB,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;gBA6CE,cAAc,GAAG,UAAU;;;;;;;;;UAiBtD,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;KAiCjC,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;KAiB1B,CAAC;AAEH,eAAO,MAAM,WAAW;;;;;;;;GAuCtB,CAAC;AAMH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;UAQnB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;GA0B5B,CAAC;AAGH,KAAK,qBAAqB,GACvB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,UAAU;;;iBAcrB,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB;;;kCAqD5B,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;;;;;;;GA+CvB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;iBAgH5B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;;iBASjC,CAAC;AAMH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;GA8C3B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;GAsB3B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;GAyB5B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;GAuB5B,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;UA2B/B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;KAmC3B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;GAmB5B,CAAC;AAMH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;UAQzB,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;UAK7B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;eAGhB,OAAO;WACX,OAAO;qBACG,MAAM;aACd,MAAM;YACP,MAAM;iBACD,MAAM;GA+FnB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;iBAc5B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;iBAY3B,CAAC;AAEH,eAAO,MAAM,aAAa;;;;iBAcxB,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;iBAa9B,CAAC"}