flowli 0.2.1 → 0.3.0

package/README.md

@@ -2,6 +2,8 @@
 
 **Typed jobs for modern TypeScript backends.**
 
+[npm](https://www.npmjs.com/package/flowli) · [JSR](https://jsr.io/@alialnaghmoush/flowli) · [GitHub](https://github.com/alialnaghmoush/flowli)
+
 Flowli is a jobs runtime with a code-first API, first-class execution strategies, runtime-scoped context injection, and pluggable Redis drivers.
 
 Define jobs once. Run them anywhere.
@@ -9,6 +11,7 @@ Define jobs once. Run them anywhere.
 ## Navigate
 
 - [Why Flowli](#why-flowli)
+- [Compare](#compare)
 - [What It Feels Like](#what-it-feels-like)
 - [The Core Idea](#the-core-idea)
 - [Primary Authoring Path](#primary-authoring-path)
@@ -46,6 +49,30 @@ Flowli is built around a different model:
 
 It is a typed runtime for background and deferred execution with a code-first, framework-agnostic design.
 
+## Compare
+
+Choose Flowli when you want:
+
+- application-first jobs authored in code, not in a dashboard
+- a single runtime that supports both direct execution and persisted async work
+- typed `context` injection without framework lock-in
+- pluggable Redis clients behind a small API surface
+
+Flowli vs BullMQ:
+
+- Flowli centers the typed job-definition experience; BullMQ centers queue primitives and worker infrastructure
+- Flowli makes `run()` a first-class in-process path; BullMQ is primarily queue-first
+
+Flowli vs Trigger.dev:
+
+- Flowli stays library-first and infrastructure-light
+- Trigger.dev is stronger when you want a hosted platform, dashboard, and workflow operations out of the box
+
+Flowli vs Inngest:
+
+- Flowli is better suited when you want application-local jobs and direct runtime wiring
+- Inngest is stronger when you want event-first workflows across services
+
 ```mermaid
 flowchart LR
   App["App Code<br/>Routes, Services, Scripts, Tests"] --> Runtime["defineJobs()<br/>Flowli Runtime"]
@@ -66,93 +93,9 @@ flowchart LR
 ## What It Feels Like
 
 ```ts
-// src/flowli/jobs/create-audit-log.ts
-import * as v from "valibot";
-import { job } from "flowli";
-import type { AppContext } from "..";
-
-export const auditLogSchema = v.object({
-  entityType: v.string(),
-  entityId: v.string(),
-  action: v.string(),
-  message: v.string(),
-});
-
-export const auditLogMeta = v.object({
-  requestId: v.string(),
-  actorId: v.optional(v.string()),
-});
-
-export const createAuditLog = job.withContext<AppContext>()(
-  "create_audit_log",
-  {
-    input: auditLogSchema,
-    meta: auditLogMeta,
-    handler: async ({ input, ctx, meta }) => {
-      await ctx.db.insert(ctx.schema.auditLogs).values({
-        entityType: input.entityType,
-        entityId: input.entityId,
-        action: input.action,
-        message: input.message,
-        requestId: meta?.requestId,
-        actorId: meta?.actorId ?? null,
-      });
-
-      ctx.logger.info({
-        job: "create_audit_log",
-        requestId: meta?.requestId,
-        entityId: input.entityId,
-      });
-    },
-  },
-);
-```
-
-```ts
-// src/flowli/jobs/send-notification-email.ts
 import * as v from "valibot";
-import { job } from "flowli";
-import type { AppContext } from "..";
-
-export const notificationEmailSchema = v.object({
-  email: v.string(),
-  subject: v.string(),
-  message: v.string(),
-});
-
-export const sendNotificationEmail = job.withContext<AppContext>()(
-  "send_notification_email",
-  {
-    input: notificationEmailSchema,
-    handler: async ({ input, ctx }) => {
-      await ctx.mailer.send({
-        to: input.email,
-        subject: input.subject,
-        text: input.message,
-      });
-    },
-  },
-);
-```
-
-```ts
-// src/flowli/jobs/index.ts
-export * from "./create-audit-log";
-export * from "./send-notification-email";
-```
-
-```ts
-// src/flowli/index.ts
 import { defineJobs } from "flowli";
 import { ioredisDriver } from "flowli/ioredis";
-import * as jobs from "./jobs";
-
-export type AppContext = {
-  db: typeof db;
-  schema: typeof schema;
-  logger: typeof logger;
-  mailer: typeof mailer;
-};
 
 export const flowli = defineJobs({
   driver: ioredisDriver({
@@ -165,7 +108,59 @@ export const flowli = defineJobs({
     logger,
     mailer,
   }),
-  jobs,
+  jobs: ({ job }) => {
+    const auditLogSchema = v.object({
+      entityType: v.string(),
+      entityId: v.string(),
+      action: v.string(),
+      message: v.string(),
+    });
+
+    const auditLogMetaSchema = v.object({
+      requestId: v.string(),
+      actorId: v.optional(v.string()),
+    });
+
+    const notificationEmailSchema = v.object({
+      email: v.string(),
+      subject: v.string(),
+      message: v.string(),
+    });
+
+    return {
+      createAuditLog: job("create_audit_log", {
+        input: auditLogSchema,
+        meta: auditLogMetaSchema,
+        handler: async ({ input, ctx, meta }) => {
+          await ctx.db.insert(ctx.schema.auditLogs).values({
+            entityType: input.entityType,
+            entityId: input.entityId,
+            action: input.action,
+            message: input.message,
+            requestId: meta?.requestId,
+            actorId: meta?.actorId ?? null,
+          });
+
+          ctx.logger.info({
+            job: "create_audit_log",
+            requestId: meta?.requestId,
+            entityId: input.entityId,
+          });
+        },
+      }),
+
+      sendNotificationEmail: job("send_notification_email", {
+        input: notificationEmailSchema,
+        handler: async ({ input, ctx }) => {
+          await ctx.mailer.send({
+            to: input.email,
+            subject: input.subject,
+            text: input.message,
+          });
+        },
+      }),
+    };
+  },
 });
 ```
 
@@ -236,63 +231,45 @@ flowchart TD
 
 The canonical Flowli path is runtime-first:
 
-```ts
-// src/flowli/jobs/create-audit-log.ts
-import * as v from "valibot";
-import { job } from "flowli";
-import type { AppContext } from "..";
-
-export const auditLogSchema = v.object({
-  entityId: v.string(),
-  action: v.string(),
-});
-
-export const auditLogMeta = v.object({
-  requestId: v.string(),
-});
-
-export const createAuditLog = job.withContext<AppContext>()(
-  "create_audit_log",
-  {
-    input: auditLogSchema,
-    meta: auditLogMeta,
-    handler: async ({ input, ctx, meta }) => {
-      await ctx.db.insert("audit_logs").values({
-        entityId: input.entityId,
-        action: input.action,
-        requestId: meta?.requestId,
-      });
-
-      ctx.logger.info({
-        entityId: input.entityId,
-        action: input.action,
-      });
-    },
-  },
-);
-```
-
-```ts
-// src/flowli/jobs/index.ts
-export * from "./create-audit-log";
-```
-
 ```ts
 // src/flowli/index.ts
+import * as v from "valibot";
 import { defineJobs } from "flowli";
-import * as jobs from "./jobs";
-
-export type AppContext = {
-  logger: typeof logger;
-  db: typeof db;
-};
 
 export const flowli = defineJobs({
   context: {
     logger,
     db,
   },
-  jobs,
+  jobs: ({ job }) => {
+    const auditLogSchema = v.object({
+      entityId: v.string(),
+      action: v.string(),
+    });
+
+    const auditLogMetaSchema = v.object({
+      requestId: v.string(),
+    });
+
+    return {
+      createAuditLog: job("create_audit_log", {
+        input: auditLogSchema,
+        meta: auditLogMetaSchema,
+        handler: async ({ input, ctx, meta }) => {
+          await ctx.db.insert("audit_logs").values({
+            entityId: input.entityId,
+            action: input.action,
+            requestId: meta?.requestId,
+          });
+
+          ctx.logger.info({
+            entityId: input.entityId,
+            action: input.action,
+          });
+        },
+      }),
+    };
+  },
 });
 ```
 
@@ -407,43 +384,9 @@ In short:
 To persist jobs, add a driver:
 
 ```ts
-// src/flowli/jobs/send-email.ts
 import * as v from "valibot";
-import { job } from "flowli";
-import type { AppContext } from "..";
-
-export const emailInputSchema = v.object({
-  email: v.string(),
-  subject: v.string(),
-});
-
-export const sendEmail = job.withContext<AppContext>()("send_email", {
-  input: emailInputSchema,
-  handler: async ({ input, ctx }) => {
-    await ctx.mailer.send({
-      to: input.email,
-      subject: input.subject,
-    });
-  },
-});
-```
-
-```ts
-// src/flowli/jobs/index.ts
-export * from "./send-email";
-```
-
-```ts
-// src/flowli/index.ts
 import { defineJobs } from "flowli";
 import { ioredisDriver } from "flowli/ioredis";
-import * as jobs from "./jobs";
-
-export type AppContext = {
-  db: typeof db;
-  logger: typeof logger;
-  mailer: typeof mailer;
-};
 
 export const flowli = defineJobs({
   driver: ioredisDriver({
@@ -455,7 +398,24 @@ export const flowli = defineJobs({
     logger,
     mailer,
   }),
-  jobs,
+  jobs: ({ job }) => {
+    const emailInputSchema = v.object({
+      email: v.string(),
+      subject: v.string(),
+    });
+
+    return {
+      sendEmail: job("send_email", {
+        input: emailInputSchema,
+        handler: async ({ input, ctx }) => {
+          await ctx.mailer.send({
+            to: input.email,
+            subject: input.subject,
+          });
+        },
+      }),
+    };
+  },
 });
 ```
 
@@ -467,6 +427,12 @@ Flowli supports:
 
 The job definitions stay the same. Only the driver changes.
 
+Retry defaults can be attached globally or per job, including:
+
+- `fixed` and `exponential` backoff
+- capped retries with `maxDelayMs`
+- jitter to spread retry bursts
+
 ## Runner
 
 The runner is explicit and secondary by design.

package/dist/core/types.d.ts

@@ -31,9 +31,15 @@ export interface JobDefaults {
     readonly maxAttempts?: number;
     readonly backoff?: BackoffOptions;
 }
+export interface BackoffJitterOptions {
+    readonly minRatio: number;
+    readonly maxRatio: number;
+}
 export interface BackoffOptions {
     readonly type: "fixed" | "exponential";
     readonly delayMs: number;
+    readonly maxDelayMs?: number;
+    readonly jitter?: boolean | BackoffJitterOptions;
 }
 export interface FlowliInvocationOptions<TMeta> {
     readonly meta?: TMeta;
@@ -99,7 +105,7 @@ export interface FlowliDriver {
     acquireNextReady(now: number, leaseMs: number): Promise<AcquiredJobRecord | null>;
     renewLease(jobId: string, token: string, leaseMs: number): Promise<boolean>;
     markCompleted(acquired: AcquiredJobRecord, finishedAt: number): Promise<void>;
-    markFailed(acquired: AcquiredJobRecord, finishedAt: number, error: PersistedJobError): Promise<"failed" | "retrying">;
+    markFailed(acquired: AcquiredJobRecord, finishedAt: number, error: PersistedJobError): Promise<MarkFailedResult>;
     materializeDueSchedules(now: number, leaseMs: number): Promise<number>;
 }
 export interface DefineJobsOptions<TJobs extends JobsRecord, TContext extends FlowliContextRecord> {
@@ -153,9 +159,16 @@ export interface PersistedJobRecord {
     readonly updatedAt: number;
     readonly scheduledFor: number;
     readonly attemptsMade: number;
+    readonly failureCount: number;
     readonly maxAttempts: number;
     readonly backoff?: BackoffOptions;
     readonly lastError?: PersistedJobError;
+    readonly lastFailedAt?: number;
+    readonly nextRetryAt?: number;
+}
+export interface MarkFailedResult {
+    readonly state: "failed" | "retrying";
+    readonly retryAt?: number;
 }
 export interface AcquiredJobRecord {
     readonly token: string;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { defineJobs } from "./core/define-jobs.js";
 export { FlowliDefinitionError, FlowliDriverError, FlowliError, FlowliSchedulingError, FlowliStrategyError, FlowliValidationError, } from "./core/errors.js";
 export { createContextualJobFactory, job } from "./core/job.js";
-export type { BackoffOptions, DefineJobsBuilder, DelayValue, FlowliContextRecord, FlowliContextResolver, FlowliDriver, FlowliInvocationOptions, FlowliJobSurface, FlowliRuntime, JobDefaults, JobDefinition, JobHandlerArgs, JobReceipt, ScheduleInvocation, ScheduleReceipt, StandardSchemaIssue, StandardSchemaV1, } from "./core/types.js";
+export type { BackoffJitterOptions, BackoffOptions, DefineJobsBuilder, DelayValue, FlowliContextRecord, FlowliContextResolver, FlowliDriver, FlowliInvocationOptions, FlowliJobSurface, FlowliRuntime, JobDefaults, JobDefinition, JobHandlerArgs, JobReceipt, ScheduleInvocation, ScheduleReceipt, StandardSchemaIssue, StandardSchemaV1, } from "./core/types.js";

package/dist/runner/types.d.ts

@@ -3,6 +3,7 @@ export interface RunnerHooks {
     readonly onJobStarted?: (jobId: string, jobName: string) => void | Promise<void>;
     readonly onJobCompleted?: (jobId: string, jobName: string) => void | Promise<void>;
     readonly onJobFailed?: (jobId: string, jobName: string, error: PersistedJobError) => void | Promise<void>;
+    readonly onJobRetryScheduled?: (jobId: string, jobName: string, retryAt: number, error: PersistedJobError) => void | Promise<void>;
 }
 export interface RunnerOptions<TJobs extends JobsRecord, TContext extends FlowliContextRecord> {
     readonly flowli: FlowliRuntime<TJobs, TContext>;

package/jsr.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jsr.io/schema/config-file.v1.json",
   "name": "@alialnaghmoush/flowli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "exports": {
     ".": "./src/index.ts",
     "./ioredis": "./src/ioredis.ts",
@@ -18,9 +18,19 @@
     "package.json"
   ],
   "exclude": [
+    ".cursor/",
+    ".git/",
+    ".gitignore",
+    ".npm-cache/",
+    "biome.json",
+    "bun.lock",
+    "docker-compose.yml",
     "dist/",
     "node_modules/",
     "test/",
+    "tsconfig.build.json",
+    "tsconfig.json",
+    "tsconfig.type-tests.json",
     "type-tests/"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Flowli is a jobs runtime with a code-first API, first-class execution strategies, runtime-scoped context injection, and pluggable Redis drivers.",
   "keywords": [
     "jobs",
@@ -20,6 +20,7 @@
     "type": "git",
     "url": "git+https://github.com/alialnaghmoush/flowli.git"
   },
+  "license": "MIT",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "type": "module",
@@ -68,9 +69,9 @@
   },
   "peerDependencies": {
     "@tanstack/react-start": "^1.0.0-rc || ^1",
-    "ioredis": "",
+    "ioredis": "^5",
     "next": "^15 || ^16",
-    "redis": "",
+    "redis": "^5",
     "typescript": "^5",
     "valibot": "^1.3.0",
     "zod": "^4.3.6"