@uploadista/server 0.2.0 → 1.0.0-beta.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uploadista/server",
   "type": "module",
-  "version": "0.2.0",
+  "version": "1.0.0-beta.3",
   "description": "Core Server package for Uploadista",
   "license": "MIT",
   "author": "Uploadista",
@@ -20,23 +20,23 @@
     }
   },
   "dependencies": {
-    "@uploadista/core": "0.2.0",
-    "@uploadista/event-broadcaster-memory": "0.2.0",
-    "@uploadista/observability": "0.2.0",
-    "@uploadista/event-emitter-websocket": "0.2.0"
+    "@uploadista/core": "1.0.0-beta.3",
+    "@uploadista/observability": "1.0.0-beta.3",
+    "@uploadista/event-broadcaster-memory": "1.0.0-beta.3",
+    "@uploadista/event-emitter-websocket": "1.0.0-beta.3"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "4.20260213.0",
+    "@cloudflare/workers-types": "4.20260301.1",
     "@effect/vitest": "0.27.0",
     "@types/express": "^5.0.0",
     "@types/node": "24.10.9",
-    "effect": "3.19.17",
+    "effect": "3.19.19",
     "tsd": "0.33.0",
     "tsdown": "0.20.3",
     "typescript": "5.9.3",
     "vitest": "4.0.18",
     "zod": "4.3.6",
-    "@uploadista/typescript-config": "0.2.0"
+    "@uploadista/typescript-config": "1.0.0-beta.3"
   },
   "peerDependencies": {
     "effect": "^3.0.0",

package/src/core/server.ts

@@ -4,6 +4,7 @@ import {
   type Flow,
   FlowLifecycleHook,
   FlowProvider,
+  FlowQueueService,
   FlowWaitUntil,
   kvCircuitBreakerStoreLayer,
 } from "@uploadista/core/flow";
@@ -203,6 +204,7 @@ export const createUploadistaServer = async <
   authCacheConfig,
   circuitBreaker = true,
   deadLetterQueue = false,
+  flowQueue,
   healthCheck,
   usageHooks,
 }: UploadistaServerConfig<
@@ -289,6 +291,30 @@ export const createUploadistaServer = async <
       )
     : null;
 
+  // Create flow queue layer if enabled.
+  // FlowQueueService requires FlowEngine (to dispatch jobs) and optionally
+  // DeadLetterQueueService (for the DLQ retry loop — resolved via optional).
+  const flowQueueLayer = flowQueue
+    ? (() => {
+        const queueConfig =
+          flowQueue === true ? {} : (flowQueue.config ?? {});
+        const queueStore =
+          flowQueue === true ? undefined : flowQueue.store;
+        // When a custom store is provided (e.g. RedisFlowQueueStore), use it directly.
+        // Otherwise back the queue with the application's kvStore — same backend already
+        // used by uploads, flows, and the DLQ, no extra Redis client needed.
+        const base = queueStore
+          ? FlowQueueService.make(queueConfig, queueStore).pipe(
+              Layer.provide(flowEngineLayer),
+            )
+          : FlowQueueService.fromBaseKvStore(queueConfig).pipe(
+              Layer.provide(flowEngineLayer),
+              Layer.provide(kvStore),
+            );
+        return base;
+      })()
+    : null;
+
   // Create usage hook layer (defaults to no-op if not configured)
   const usageHookLayer = UsageHookServiceLive(usageHooks);
 
@@ -330,6 +356,7 @@ export const createUploadistaServer = async <
     ...plugins,
     ...(circuitBreakerStoreLayer ? [circuitBreakerStoreLayer] : []),
     ...(dlqLayer ? [dlqLayer] : []),
+    ...(flowQueueLayer ? [flowQueueLayer] : []),
   );
 
   /**
@@ -564,9 +591,12 @@ export const createUploadistaServer = async <
       const withCircuitBreakerContext = circuitBreakerStoreLayer
         ? Layer.merge(baseRequestContextLayer, circuitBreakerStoreLayer)
         : baseRequestContextLayer;
-      const requestContextLayer = dlqLayer
+      const withDlqContext = dlqLayer
         ? Layer.merge(withCircuitBreakerContext, dlqLayer)
         : withCircuitBreakerContext;
+      const requestContextLayer = flowQueueLayer
+        ? Layer.merge(withDlqContext, flowQueueLayer)
+        : withDlqContext;
 
       // Check for baseUrl/api/ prefix
       if (uploadistaRequest.type === "not-found") {

package/src/core/types.ts

@@ -1,5 +1,6 @@
 import type { PluginLayer, UploadistaError } from "@uploadista/core";
 import type { Flow } from "@uploadista/core/flow";
+import type { FlowQueueConfig, FlowQueueStore } from "@uploadista/core/flow";
 import type {
   BaseEventEmitterService,
   BaseKvStoreService,
@@ -412,6 +413,37 @@ export interface UploadistaServerConfig<
    */
   healthCheck?: HealthCheckConfig;
 
+  /**
+   * Optional: Flow queue for bounded concurrent flow execution.
+   *
+   * When enabled, `FlowEngine.runFlow()` delegates to the queue instead of
+   * forking immediately. The queue dispatches flows up to `maxConcurrency`
+   * simultaneously, buffering the rest as `"pending"`.
+   *
+   * Set to `true` to use the default in-memory store (state lost on restart).
+   * Provide a `store` to use a persistent backend such as `RedisFlowQueueStore`.
+   *
+   * When both `flowQueue` and `deadLetterQueue` are enabled, the queue
+   * automatically retries DLQ items on a configurable interval.
+   *
+   * @default undefined (disabled — fire-and-forget behavior preserved)
+   *
+   * @example
+   * ```typescript
+   * // Simple in-memory queue
+   * flowQueue: true
+   *
+   * // Persistent Redis-backed queue with custom concurrency
+   * import { RedisFlowQueueStore } from "@uploadista/queue-store-redis";
+   *
+   * flowQueue: {
+   *   store: new RedisFlowQueueStore({ redis }),
+   *   config: { maxConcurrency: 8, dlqRetryIntervalMs: 60_000 },
+   * }
+   * ```
+   */
+  flowQueue?: boolean | { config?: FlowQueueConfig; store?: FlowQueueStore };
+
   /**
    * Optional: Usage hooks for tracking and billing integration.
    *