flowli 0.3.0 → 0.4.0

package/README.md

@@ -20,6 +20,7 @@ Define jobs once. Run them anywhere.
 - [Context vs Meta](#context-vs-meta)
 - [Async Execution](#async-execution)
 - [Runner](#runner)
+- [Inspection And Observability](#inspection-and-observability)
 - [Async Semantics](#async-semantics)
 - [Reusable Predeclared Jobs](#reusable-predeclared-jobs)
 - [Hono](#hono)
@@ -460,6 +461,53 @@ await runner.stop();
 
 `createRunner()` consumes an existing runtime. It does not recreate jobs or rebuild context.
 
+## Inspection And Observability
+
+Flowli now exposes a read-side inspection surface on the runtime:
+
+```ts
+const job = await flowli.inspect.getJob("job_123");
+const schedule = await flowli.inspect.getSchedule("daily-report");
+const counts = await flowli.inspect.getQueueCounts();
+const queuedJobs = await flowli.inspect.getJobsByState("queued", {
+  limit: 25,
+});
+const schedules = await flowli.inspect.getSchedules({
+  limit: 25,
+});
+```
+
+This gives you enough visibility to:
+
+- inspect retry metadata like `failureCount`, `lastFailedAt`, and `nextRetryAt`
+- power operational logs and lightweight admin pages
+- debug delayed, failed, and completed work without reaching into Redis directly
+
+The runner also supports lifecycle hooks for observability:
+
+```ts
+const runner = createRunner({
+  flowli,
+  hooks: {
+    onJobStarted(jobId, jobName) {
+      logger.info({ event: "job.started", jobId, jobName });
+    },
+    onJobRetryScheduled(jobId, jobName, retryAt, error) {
+      logger.warn({
+        event: "job.retry_scheduled",
+        jobId,
+        jobName,
+        retryAt,
+        error,
+      });
+    },
+    onLeaseRecovered(jobId, jobName) {
+      logger.warn({ event: "job.lease_recovered", jobId, jobName });
+    },
+  },
+});
+```
+
 ## Async Semantics
 
 Persisted execution in Flowli is:

package/dist/bun-redis.d.ts

@@ -1 +1,4 @@
+/**
+ * The `flowli/bun-redis` entrypoint provides the Bun Redis-backed driver adapter.
+ */
 export { type BunRedisDriverOptions, type BunRedisLikeClient, bunRedisDriver, } from "./drivers/bun-redis.js";

package/dist/core/define-jobs.d.ts

@@ -3,6 +3,11 @@ type DefineJobsFunction = {
     <const TJobs extends JobsRecord, TContext extends FlowliContextRecord>(options: DefineJobsFactoryOptions<TJobs, TContext>): FlowliRuntime<TJobs, TContext>;
     withContext<TContext extends FlowliContextRecord>(): <const TJobs extends JobsRecord>(options: DefineJobsOptions<EnsureJobContexts<TJobs, TContext>, TContext>) => FlowliRuntime<EnsureJobContexts<TJobs, TContext>, TContext>;
 };
+/**
+ * Creates a Flowli runtime from a runtime-scoped context, a jobs registry, and
+ * an optional async driver.
+ */
 export declare const defineJobs: DefineJobsFunction;
+/** Returns the non-public runtime internals used by integrations and tests. */
 export declare function getFlowliRuntimeInternals<TJobs extends JobsRecord, TContext extends FlowliContextRecord>(runtime: FlowliRuntime<TJobs, TContext>): FlowliRuntimeInternals<TJobs, TContext>;
 export {};

package/dist/core/errors.d.ts

@@ -1,21 +1,27 @@
 import type { StandardSchemaIssue } from "./types.js";
+/** Base error type for all Flowli-specific failures. */
 export declare class FlowliError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
+/** Raised when Flowli definitions or registry shape are invalid. */
 export declare class FlowliDefinitionError extends FlowliError {
     constructor(message: string);
 }
+/** Raised when input or meta validation fails against the configured schema. */
 export declare class FlowliValidationError extends FlowliError {
     readonly issues: ReadonlyArray<StandardSchemaIssue>;
     constructor(message: string, issues: ReadonlyArray<StandardSchemaIssue>);
 }
+/** Raised when a strategy is used in an invalid way for the current runtime. */
 export declare class FlowliStrategyError extends FlowliError {
     constructor(message: string);
 }
+/** Raised when a driver is missing or behaves incompatibly. */
 export declare class FlowliDriverError extends FlowliError {
     constructor(message: string);
 }
+/** Raised when schedule registration or cron handling fails. */
 export declare class FlowliSchedulingError extends FlowliError {
     constructor(message: string);
 }

package/dist/core/job.d.ts

@@ -1,9 +1,13 @@
 import type { FlowliContextRecord, JobDefinition, JobOptions, StandardSchemaV1 } from "./types.js";
+/** A job factory already bound to a specific Flowli context type. */
 type JobFactory = {
     <TInputSchema extends StandardSchemaV1<any, any>, TMetaSchema extends StandardSchemaV1<any, any> | undefined, TResult>(name: string, options: JobOptions<TInputSchema, TMetaSchema, FlowliContextRecord, TResult>): JobDefinition<TInputSchema, TMetaSchema, FlowliContextRecord, TResult>;
     withContext<TContext extends FlowliContextRecord>(): <TInputSchema extends StandardSchemaV1<any, any>, TMetaSchema extends StandardSchemaV1<any, any> | undefined, TResult>(name: string, options: JobOptions<TInputSchema, TMetaSchema, TContext, TResult>) => JobDefinition<TInputSchema, TMetaSchema, TContext, TResult>;
 };
+/** The typed factory signature returned when a runtime binds `ctx` shape. */
 export type ContextualJobFactory<TContext extends FlowliContextRecord> = <TInputSchema extends StandardSchemaV1<any, any>, TMetaSchema extends StandardSchemaV1<any, any> | undefined, TResult>(name: string, options: JobOptions<TInputSchema, TMetaSchema, TContext, TResult>) => JobDefinition<TInputSchema, TMetaSchema, TContext, TResult>;
+/** Defines a Flowli job with typed input, optional meta, and a handler. */
 export declare const job: JobFactory;
+/** Creates a contextual `job()` factory for runtime-first authoring flows. */
 export declare function createContextualJobFactory<TContext extends FlowliContextRecord>(): ContextualJobFactory<TContext>;
 export {};

package/dist/core/types.d.ts

@@ -1,3 +1,4 @@
+/** A normalized validation issue reported by a Standard Schema-compatible validator. */
 export interface StandardSchemaIssue {
     message: string;
     path?: ReadonlyArray<unknown>;
@@ -9,6 +10,7 @@ export interface StandardSchemaFailure {
     readonly issues: ReadonlyArray<StandardSchemaIssue>;
 }
 export type StandardSchemaResult<TValue> = StandardSchemaSuccess<TValue> | StandardSchemaFailure;
+/** The minimal Standard Schema v1 contract Flowli consumes for validation and inference. */
 export interface StandardSchemaV1<Input = unknown, Output = Input> {
     readonly "~standard": {
         readonly version: number;
@@ -22,37 +24,46 @@ export interface StandardSchemaV1<Input = unknown, Output = Input> {
 }
 export type InferInput<TSchema extends StandardSchemaV1<any, any>> = TSchema extends StandardSchemaV1<infer TInput, any> ? TInput : never;
 export type InferOutput<TSchema extends StandardSchemaV1<any, any>> = TSchema extends StandardSchemaV1<any, infer TOutput> ? TOutput : never;
+/** The shared runtime-scoped dependency object passed to Flowli job handlers as `ctx`. */
 export interface FlowliContextRecord {
     readonly [key: PropertyKey]: unknown;
 }
+/** A static context object or lazy resolver used when constructing a Flowli runtime. */
 export type FlowliContextResolver<TContext extends FlowliContextRecord> = TContext | (() => TContext | Promise<TContext>);
 export type ResolveContext<TResolver> = TResolver extends () => infer TResult ? Awaited<TResult> : TResolver extends FlowliContextRecord ? TResolver : never;
+/** Shared retry and persistence defaults that can be applied globally or per job. */
 export interface JobDefaults {
     readonly maxAttempts?: number;
     readonly backoff?: BackoffOptions;
 }
+/** Configures a randomized multiplier for retry backoff delay. */
 export interface BackoffJitterOptions {
     readonly minRatio: number;
     readonly maxRatio: number;
 }
+/** Defines how retries are delayed for persisted async execution. */
 export interface BackoffOptions {
     readonly type: "fixed" | "exponential";
     readonly delayMs: number;
     readonly maxDelayMs?: number;
     readonly jitter?: boolean | BackoffJitterOptions;
 }
+/** Per-invocation options shared by all execution strategies. */
 export interface FlowliInvocationOptions<TMeta> {
     readonly meta?: TMeta;
 }
 export interface PersistedInvocationOptions<TMeta> extends FlowliInvocationOptions<TMeta>, JobDefaults {
 }
+/** The payload required to register a recurring schedule for a job. */
 export interface ScheduleInvocation<TInput, TMeta> {
     readonly key?: string;
     readonly cron: string;
     readonly input: TInput;
     readonly meta?: TMeta;
 }
+/** A supported delay literal or numeric millisecond delay. */
 export type DelayValue = number | `${number}${"ms" | "s" | "m" | "h" | "d"}`;
+/** The receipt returned when a job is persisted for async execution. */
 export interface JobReceipt {
     readonly id: string;
     readonly name: string;
@@ -60,18 +71,24 @@ export interface JobReceipt {
     readonly scheduledFor: number;
     readonly attemptsMade: number;
 }
+/** The receipt returned when a recurring schedule is registered. */
 export interface ScheduleReceipt {
     readonly key: string;
     readonly name: string;
     readonly cron: string;
     readonly nextRunAt: number;
 }
+/** The persisted lifecycle states a job can move through in Flowli. */
 export type JobState = "queued" | "active" | "completed" | "failed" | "scheduled";
+/** The inspectable persisted job states exposed by `flowli.inspect`. */
+export type InspectableJobState = Exclude<JobState, "scheduled">;
+/** The typed arguments delivered to a Flowli job handler. */
 export interface JobHandlerArgs<TInput, TContext, TMeta> {
     readonly input: TInput;
     readonly ctx: TContext;
     readonly meta: TMeta | undefined;
 }
+/** A fully-defined Flowli job produced by `job()` or a contextual job factory. */
 export interface JobDefinition<TInputSchema extends StandardSchemaV1<any, any>, TMetaSchema extends StandardSchemaV1<any, any> | undefined, TContext extends FlowliContextRecord, TResult> {
     readonly __flowli: "job";
     readonly name: string;
@@ -82,6 +99,7 @@ export interface JobDefinition<TInputSchema extends StandardSchemaV1<any, any>,
     readonly description?: string;
     readonly tags?: ReadonlyArray<string>;
 }
+/** Options accepted by `job()` when defining a job. */
 export interface JobOptions<TInputSchema extends StandardSchemaV1<any, any>, TMetaSchema extends StandardSchemaV1<any, any> | undefined, TContext extends FlowliContextRecord, TResult> {
     readonly input: TInputSchema;
     readonly meta?: TMetaSchema;
@@ -97,46 +115,80 @@ export type JobsRecord = {
 export type JobInput<TJob extends AnyJobDefinition> = InferOutput<TJob["input"]>;
 export type JobMeta<TJob extends AnyJobDefinition> = NonNullable<TJob["meta"]> extends StandardSchemaV1<any, any> ? InferOutput<NonNullable<TJob["meta"]>> : undefined;
 export type JobResult<TJob extends AnyJobDefinition> = Awaited<ReturnType<TJob["handler"]>>;
+/** The internal driver contract implemented by Redis-backed adapters. */
 export interface FlowliDriver {
     readonly kind: string;
     enqueue(record: PersistedJobRecord): Promise<JobReceipt>;
     registerSchedule(record: ScheduleRecord): Promise<ScheduleReceipt>;
-    recoverExpiredLeases(now: number): Promise<number>;
+    recoverExpiredLeases(now: number): Promise<ReadonlyArray<PersistedJobRecord>>;
     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<MarkFailedResult>;
     materializeDueSchedules(now: number, leaseMs: number): Promise<number>;
+    getJob(id: string): Promise<PersistedJobRecord | null>;
+    getSchedule(key: string): Promise<ScheduleRecord | null>;
+    getQueueCounts(): Promise<FlowliQueueCounts>;
+    getJobsByState(state: InspectableJobState, options?: FlowliInspectListOptions): Promise<ReadonlyArray<PersistedJobRecord>>;
+    getSchedules(options?: FlowliInspectListOptions): Promise<ReadonlyArray<ScheduleRecord>>;
 }
+/** Options for defining a runtime from an already-declared jobs object. */
 export interface DefineJobsOptions<TJobs extends JobsRecord, TContext extends FlowliContextRecord> {
     readonly jobs: TJobs;
     readonly context: FlowliContextResolver<TContext>;
     readonly driver?: FlowliDriver;
     readonly defaults?: JobDefaults;
 }
+/** The builder object supplied to runtime-first `defineJobs({ jobs })`. */
 export interface DefineJobsBuilder<TContext extends FlowliContextRecord> {
     readonly job: <TInputSchema extends StandardSchemaV1<any, any>, TMetaSchema extends StandardSchemaV1<any, any> | undefined, TResult>(name: string, options: JobOptions<TInputSchema, TMetaSchema, TContext, TResult>) => JobDefinition<TInputSchema, TMetaSchema, TContext, TResult>;
 }
+/** Options for the runtime-first `defineJobs({ jobs: ({ job }) => ... })` API. */
 export interface DefineJobsFactoryOptions<TJobs extends JobsRecord, TContext extends FlowliContextRecord> {
     readonly jobs: (builder: DefineJobsBuilder<TContext>) => TJobs;
     readonly context: FlowliContextResolver<TContext>;
     readonly driver?: FlowliDriver;
     readonly defaults?: JobDefaults;
 }
+/** Ensures reusable predeclared jobs are compatible with runtime context. */
 export type EnsureJobContexts<TJobs extends JobsRecord, TContext extends FlowliContextRecord> = {
     readonly [TKey in keyof TJobs]: TJobs[TKey] extends JobDefinition<StandardSchemaV1<any, any>, StandardSchemaV1<any, any> | undefined, infer TJobContext, unknown> ? TContext extends TJobContext ? TJobs[TKey] : never : never;
 };
+/** The public surface exposed for each Flowli job on the runtime. */
 export interface FlowliJobSurface<TJob extends AnyJobDefinition> {
     run(input: JobInput<TJob>, options?: FlowliInvocationOptions<JobMeta<TJob>>): Promise<JobResult<TJob>>;
     enqueue(input: JobInput<TJob>, options?: PersistedInvocationOptions<JobMeta<TJob>>): Promise<JobReceipt>;
     delay(delay: DelayValue, input: JobInput<TJob>, options?: PersistedInvocationOptions<JobMeta<TJob>>): Promise<JobReceipt>;
     schedule(invocation: ScheduleInvocation<JobInput<TJob>, JobMeta<TJob>>): Promise<ScheduleReceipt>;
 }
+/** List options for read-side inspection queries. */
+export interface FlowliInspectListOptions {
+    readonly limit?: number;
+}
+/** Aggregate queue counts returned by the inspect surface. */
+export interface FlowliQueueCounts {
+    readonly queued: number;
+    readonly active: number;
+    readonly completed: number;
+    readonly failed: number;
+    readonly schedules: number;
+}
+/** Read-side inspection helpers for persisted jobs and schedules. */
+export interface FlowliInspectSurface {
+    getJob(id: string): Promise<PersistedJobRecord | null>;
+    getSchedule(key: string): Promise<ScheduleRecord | null>;
+    getQueueCounts(): Promise<FlowliQueueCounts>;
+    getJobsByState(state: InspectableJobState, options?: FlowliInspectListOptions): Promise<ReadonlyArray<PersistedJobRecord>>;
+    getSchedules(options?: FlowliInspectListOptions): Promise<ReadonlyArray<ScheduleRecord>>;
+}
+/** The Flowli runtime returned by `defineJobs()`. */
 export type FlowliRuntime<TJobs extends JobsRecord, TContext extends FlowliContextRecord> = {
     readonly [TKey in keyof TJobs]: FlowliJobSurface<TJobs[TKey]>;
 } & {
+    readonly inspect: FlowliInspectSurface;
     readonly [FLOWLI_RUNTIME_SYMBOL]: FlowliRuntimeInternals<TJobs, TContext>;
 };
+/** The hidden runtime internals attached to a Flowli runtime instance. */
 export interface FlowliRuntimeInternals<TJobs extends JobsRecord, TContext extends FlowliContextRecord> {
     readonly jobs: TJobs;
     readonly jobsByName: Map<string, AnyJobDefinition>;
@@ -144,6 +196,7 @@ export interface FlowliRuntimeInternals<TJobs extends JobsRecord, TContext exten
     readonly driver?: FlowliDriver;
     readonly defaults: JobDefaults;
 }
+/** The internal symbol used to attach Flowli runtime internals to an instance. */
 export declare const FLOWLI_RUNTIME_SYMBOL: unique symbol;
 export interface PersistedJobError {
     readonly code: string;

package/dist/drivers/bun-redis.d.ts

@@ -1,5 +1,6 @@
 import type { FlowliDriver } from "../core/types.js";
 import { type RedisCommandAdapter } from "./shared.js";
+/** The subset of a Bun Redis client Flowli requires. */
 export interface BunRedisLikeClient {
     get(key: string): Promise<string | null>;
     set(key: string, value: string, options?: {
@@ -16,9 +17,12 @@ export interface BunRedisLikeClient {
         };
     }): Promise<string[]>;
 }
+/** Options for creating the `flowli/bun-redis` driver. */
 export interface BunRedisDriverOptions {
     readonly client: BunRedisLikeClient;
     readonly prefix?: string;
 }
+/** Creates a Flowli driver backed by a Bun Redis-compatible client. */
 export declare function bunRedisDriver(options: BunRedisDriverOptions): FlowliDriver;
+/** Adapts Bun Redis commands to Flowli's shared Redis driver contract. */
 export declare function createBunRedisAdapter(client: BunRedisLikeClient): RedisCommandAdapter;

package/dist/drivers/ioredis.d.ts

@@ -1,5 +1,6 @@
 import type { FlowliDriver } from "../core/types.js";
 import { type RedisCommandAdapter } from "./shared.js";
+/** The subset of an ioredis client Flowli requires. */
 export interface IoredisLikeClient {
     get(key: string): Promise<string | null>;
     set(key: string, value: string, modeOrOptions?: "PX" | "NX" | undefined, ttlOrMode?: number | "NX" | "PX", maybeMode?: "NX" | "PX"): Promise<"OK" | null>;
@@ -8,9 +9,12 @@ export interface IoredisLikeClient {
     zrem(key: string, member: string): Promise<number>;
     zrangebyscore(key: string, min: number | string, max: number | string, limitToken?: "LIMIT", offset?: number, count?: number): Promise<string[]>;
 }
+/** Options for creating the `flowli/ioredis` driver. */
 export interface IoredisDriverOptions {
     readonly client: IoredisLikeClient;
     readonly prefix?: string;
 }
+/** Creates a Flowli driver backed by an ioredis-compatible client. */
 export declare function ioredisDriver(options: IoredisDriverOptions): FlowliDriver;
+/** Adapts ioredis commands to Flowli's shared Redis driver contract. */
 export declare function createIoredisAdapter(client: IoredisLikeClient): RedisCommandAdapter;

package/dist/drivers/redis.d.ts

@@ -1,5 +1,6 @@
 import type { FlowliDriver } from "../core/types.js";
 import { type RedisCommandAdapter } from "./shared.js";
+/** The subset of a node-redis client Flowli requires. */
 export interface NodeRedisLikeClient {
     get(key: string): Promise<string | null>;
     set(key: string, value: string, options?: {
@@ -19,9 +20,12 @@ export interface NodeRedisLikeClient {
         };
     }): Promise<string[]>;
 }
+/** Options for creating the `flowli/redis` driver. */
 export interface RedisDriverOptions {
     readonly client: NodeRedisLikeClient;
     readonly prefix?: string;
 }
+/** Creates a Flowli driver backed by a node-redis-compatible client. */
 export declare function redisDriver(options: RedisDriverOptions): FlowliDriver;
+/** Adapts node-redis commands to Flowli's shared Redis driver contract. */
 export declare function createNodeRedisAdapter(client: NodeRedisLikeClient): RedisCommandAdapter;

package/dist/hono.d.ts

@@ -1 +1,5 @@
+/**
+ * The `flowli/hono` entrypoint provides middleware helpers for attaching an
+ * existing Flowli runtime to Hono context.
+ */
 export { type HonoFlowliVariables, type HonoJobsOptions, type HonoLikeContext, type HonoLikeNext, honoJobs, } from "./integrations/hono.js";

package/dist/index.d.ts

@@ -1,4 +1,8 @@
+/**
+ * Flowli's root entrypoint exports the typed jobs runtime, core errors, and
+ * essential public types without pulling in driver or framework code.
+ */
 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 { BackoffJitterOptions, 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, FlowliInspectListOptions, FlowliInspectSurface, FlowliInvocationOptions, FlowliJobSurface, FlowliQueueCounts, FlowliRuntime, InspectableJobState, JobDefaults, JobDefinition, JobHandlerArgs, JobReceipt, ScheduleInvocation, ScheduleReceipt, StandardSchemaIssue, StandardSchemaV1, } from "./core/types.js";

package/dist/integrations/hono.d.ts

@@ -1,10 +1,15 @@
 import type { FlowliContextRecord, FlowliRuntime, JobsRecord } from "../core/types.js";
+/** The minimal Hono context contract required by `honoJobs()`. */
 export interface HonoLikeContext {
     set(key: string, value: unknown): void;
 }
+/** The continuation callback shape used by Hono middleware. */
 export type HonoLikeNext = () => Promise<unknown>;
+/** Options for attaching a Flowli runtime to Hono context. */
 export interface HonoJobsOptions<TKey extends string = "flowli"> {
     readonly key?: TKey;
 }
+/** The typed variables shape added to Hono context by `honoJobs()`. */
 export type HonoFlowliVariables<TFlowli, TKey extends string = "flowli"> = Record<TKey, TFlowli>;
+/** Creates Hono middleware that attaches an existing Flowli runtime to `c`. */
 export declare function honoJobs<TJobs extends JobsRecord, TContext extends FlowliContextRecord, TKey extends string = "flowli">(flowli: FlowliRuntime<TJobs, TContext>, options?: HonoJobsOptions<TKey>): (context: HonoLikeContext, next: HonoLikeNext) => Promise<void>;

package/dist/integrations/next.d.ts

@@ -1,18 +1,26 @@
 import type { FlowliContextRecord, FlowliRuntime, JobsRecord } from "../core/types.js";
+/** A minimal route params record compatible with Next.js route handlers. */
 export type NextRouteParams = Record<string, string | ReadonlyArray<string> | undefined>;
+/** The request context object supplied by Next.js route handlers. */
 export interface NextRouteContext<TParams extends NextRouteParams = NextRouteParams> {
     readonly params?: TParams | Promise<TParams>;
 }
+/** Arguments passed to a `nextRoute()` handler. */
 export interface NextRouteHandlerArgs<TFlowli, TParams extends NextRouteParams = NextRouteParams, TRequest extends Request = Request> {
     readonly request: TRequest;
     readonly context: NextRouteContext<TParams>;
     readonly params: TParams | undefined;
     readonly flowli: TFlowli;
 }
+/** A typed handler for the `nextRoute()` integration helper. */
 export type NextRouteHandler<TFlowli, TParams extends NextRouteParams = NextRouteParams, TRequest extends Request = Request, TResult = Response> = (args: NextRouteHandlerArgs<TFlowli, TParams, TRequest>) => TResult | Promise<TResult>;
+/** Tools injected into a `nextAction()` handler. */
 export interface NextActionTools<TFlowli> {
     readonly flowli: TFlowli;
 }
+/** A typed handler for the `nextAction()` integration helper. */
 export type NextActionHandler<TFlowli, TArgs extends ReadonlyArray<unknown>, TResult> = (tools: NextActionTools<TFlowli>, ...args: TArgs) => TResult | Promise<TResult>;
+/** Wraps a Next.js route handler with access to an existing Flowli runtime. */
 export declare function nextRoute<TJobs extends JobsRecord, TContext extends FlowliContextRecord, TParams extends NextRouteParams = NextRouteParams, TRequest extends Request = Request, TResult = Response>(flowli: FlowliRuntime<TJobs, TContext>, handler: NextRouteHandler<FlowliRuntime<TJobs, TContext>, TParams, TRequest, TResult>): (request: TRequest, context?: NextRouteContext<TParams>) => Promise<Awaited<TResult>>;
+/** Wraps a Next.js server action with access to an existing Flowli runtime. */
 export declare function nextAction<TJobs extends JobsRecord, TContext extends FlowliContextRecord, TArgs extends ReadonlyArray<unknown>, TResult>(flowli: FlowliRuntime<TJobs, TContext>, handler: NextActionHandler<FlowliRuntime<TJobs, TContext>, TArgs, TResult>): (...args: TArgs) => Promise<Awaited<TResult>>;

package/dist/integrations/tanstack-start.d.ts

@@ -1,20 +1,28 @@
 import type { FlowliContextRecord, FlowliRuntime, JobsRecord } from "../core/types.js";
+/** A minimal params record compatible with TanStack Start server routes. */
 export type TanStackStartRouteParams = Record<string, string | ReadonlyArray<string> | undefined>;
+/** The generic server route context provided by TanStack Start. */
 export interface TanStackStartRouteContext {
     readonly [key: PropertyKey]: unknown;
 }
+/** Arguments passed to a `tanstackStartRoute()` handler. */
 export interface TanStackStartRouteHandlerArgs<TFlowli, TParams extends TanStackStartRouteParams = TanStackStartRouteParams, TContext extends TanStackStartRouteContext = TanStackStartRouteContext, TRequest extends Request = Request> {
     readonly request: TRequest;
     readonly params: TParams;
     readonly context: TContext;
     readonly flowli: TFlowli;
 }
+/** A typed handler for TanStack Start route integration. */
 export type TanStackStartRouteHandler<TFlowli, TParams extends TanStackStartRouteParams = TanStackStartRouteParams, TContext extends TanStackStartRouteContext = TanStackStartRouteContext, TRequest extends Request = Request, TResult = Response> = (args: TanStackStartRouteHandlerArgs<TFlowli, TParams, TContext, TRequest>) => TResult | Promise<TResult>;
+/** Tools injected into a TanStack Start server function handler. */
 export interface TanStackStartServerFnTools<TFlowli> {
     readonly flowli: TFlowli;
 }
 type StripFlowli<TArgs extends object> = Omit<TArgs, keyof TanStackStartServerFnTools<unknown>>;
+/** A typed handler for TanStack Start server function integration. */
 export type TanStackStartServerFnHandler<TFlowli, TArgs extends TanStackStartServerFnTools<TFlowli>, TResult> = (args: TArgs) => TResult | Promise<TResult>;
+/** Wraps a TanStack Start route with access to an existing Flowli runtime. */
 export declare function tanstackStartRoute<TJobs extends JobsRecord, TContext extends FlowliContextRecord, TParams extends TanStackStartRouteParams = TanStackStartRouteParams, TRouteContext extends TanStackStartRouteContext = TanStackStartRouteContext, TRequest extends Request = Request, TResult = Response>(flowli: FlowliRuntime<TJobs, TContext>, handler: TanStackStartRouteHandler<FlowliRuntime<TJobs, TContext>, TParams, TRouteContext, TRequest, TResult>): (args: Omit<TanStackStartRouteHandlerArgs<FlowliRuntime<TJobs, TContext>, TParams, TRouteContext, TRequest>, "flowli">) => Promise<Awaited<TResult>>;
+/** Wraps a TanStack Start server function with Flowli runtime access. */
 export declare function tanstackStartServerFn<TJobs extends JobsRecord, TContext extends FlowliContextRecord, TArgs extends TanStackStartServerFnTools<FlowliRuntime<TJobs, TContext>>, TResult>(flowli: FlowliRuntime<TJobs, TContext>, handler: TanStackStartServerFnHandler<FlowliRuntime<TJobs, TContext>, TArgs, TResult>): (args: StripFlowli<TArgs>) => Promise<Awaited<TResult>>;
 export {};

package/dist/ioredis.d.ts

@@ -1 +1,4 @@
+/**
+ * The `flowli/ioredis` entrypoint provides the ioredis-backed driver adapter.
+ */
 export { type IoredisDriverOptions, type IoredisLikeClient, ioredisDriver, } from "./drivers/ioredis.js";

package/dist/next.d.ts

@@ -1 +1,5 @@
+/**
+ * The `flowli/next` entrypoint provides lightweight helpers for Next.js route
+ * handlers and server actions.
+ */
 export { type NextActionHandler, type NextActionTools, type NextRouteContext, type NextRouteHandler, type NextRouteHandlerArgs, type NextRouteParams, nextAction, nextRoute, } from "./integrations/next.js";

package/dist/redis.d.ts

@@ -1 +1,4 @@
+/**
+ * The `flowli/redis` entrypoint provides the node-redis-backed driver adapter.
+ */
 export { type NodeRedisLikeClient, type RedisDriverOptions, redisDriver, } from "./drivers/redis.js";

package/dist/runner/create-runner.d.ts

@@ -1,3 +1,4 @@
 import type { FlowliContextRecord, JobsRecord } from "../core/types.js";
 import type { FlowliRunner, RunnerOptions } from "./types.js";
+/** Creates an explicit runner for queued, delayed, and scheduled Flowli jobs. */
 export declare function createRunner<TJobs extends JobsRecord, TContext extends FlowliContextRecord>(options: RunnerOptions<TJobs, TContext>): FlowliRunner;

package/dist/runner/types.d.ts

@@ -1,10 +1,13 @@
-import type { FlowliContextRecord, FlowliRuntime, JobsRecord, PersistedJobError } from "../core/types.js";
+import type { FlowliContextRecord, FlowliRuntime, JobsRecord, PersistedJobError, PersistedJobRecord } from "../core/types.js";
+/** Lifecycle hooks emitted by the Flowli runner during async execution. */
 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>;
+    readonly onLeaseRecovered?: (jobId: string, jobName: string, record: PersistedJobRecord) => void | Promise<void>;
 }
+/** Options for constructing a Flowli runner from an existing runtime. */
 export interface RunnerOptions<TJobs extends JobsRecord, TContext extends FlowliContextRecord> {
     readonly flowli: FlowliRuntime<TJobs, TContext>;
     readonly concurrency?: number;
@@ -13,6 +16,7 @@ export interface RunnerOptions<TJobs extends JobsRecord, TContext extends Flowli
     readonly maxJobsPerTick?: number;
     readonly hooks?: RunnerHooks;
 }
+/** The explicit async processor returned by `createRunner()`. */
 export interface FlowliRunner {
     readonly running: boolean;
     runOnce(): Promise<number>;

package/dist/runner.d.ts

@@ -1,2 +1,6 @@
+/**
+ * The `flowli/runner` entrypoint provides the explicit async processor used to
+ * execute queued, delayed, and scheduled work.
+ */
 export { createRunner } from "./runner/create-runner.js";
 export type { FlowliRunner, RunnerHooks, RunnerOptions, } from "./runner/types.js";

package/dist/runtime/create-inspect-surface.d.ts

@@ -0,0 +1,2 @@
+import type { FlowliContextRecord, FlowliInspectSurface, FlowliRuntimeInternals, JobsRecord } from "../core/types.js";
+export declare function createInspectSurface<TJobs extends JobsRecord, TContext extends FlowliContextRecord>(internals: FlowliRuntimeInternals<TJobs, TContext>): FlowliInspectSurface;

package/dist/tanstack-start.d.ts

@@ -1 +1,5 @@
+/**
+ * The `flowli/tanstack-start` entrypoint provides helpers for TanStack Start
+ * server routes and server functions.
+ */
 export { type TanStackStartRouteContext, type TanStackStartRouteHandler, type TanStackStartRouteHandlerArgs, type TanStackStartRouteParams, type TanStackStartServerFnHandler, type TanStackStartServerFnTools, tanstackStartRoute, tanstackStartServerFn, } from "./integrations/tanstack-start.js";

package/jsr.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jsr.io/schema/config-file.v1.json",
   "name": "@alialnaghmoush/flowli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "exports": {
     ".": "./src/index.ts",
     "./ioredis": "./src/ioredis.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowli",
-  "version": "0.3.0",
+  "version": "0.4.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",