@coji/durably-react 0.10.0 → 0.11.0

package/README.md

@@ -9,19 +9,42 @@ React bindings for [Durably](https://github.com/coji/durably) - step-oriented re
 ## Installation
 
 ```bash
-# Browser mode (with SQLocal)
+# Fullstack mode (connects to Durably server)
+npm install @coji/durably-react
+
+# SPA mode (runs Durably in the browser with SQLocal)
 npm install @coji/durably-react @coji/durably kysely zod sqlocal
+```
 
-# Server-connected mode (client only)
-npm install @coji/durably-react
+## Quick Start (Fullstack Mode)
+
+```tsx
+import { createDurably } from '@coji/durably-react'
+import type { durably } from './durably.server'
+
+// Create type-safe hooks from server's Durably type
+export const durably = createDurably<typeof durably>({
+  api: '/api/durably',
+})
+
+function MyComponent() {
+  const { trigger, isRunning, isCompleted, output } = durably.myJob.useJob()
+
+  return (
+    <button onClick={() => trigger({ id: '123' })} disabled={isRunning}>
+      Run
+    </button>
+  )
+}
 ```
 
-## Quick Start
+## SPA Mode
+
+For browser-only apps, import from `@coji/durably-react/spa`:
 
 ```tsx
-import { Suspense } from 'react'
 import { createDurably, defineJob } from '@coji/durably'
-import { DurablyProvider, useJob } from '@coji/durably-react'
+import { DurablyProvider, useJob } from '@coji/durably-react/spa'
 import { SQLocalKysely } from 'sqlocal/kysely'
 import { z } from 'zod'
 
@@ -38,8 +61,9 @@ const myJob = defineJob({
 // Initialize Durably
 async function initDurably() {
   const sqlocal = new SQLocalKysely('app.sqlite3')
-  const durably = createDurably({ dialect: sqlocal.dialect }).register({
-    myJob,
+  const durably = createDurably({
+    dialect: sqlocal.dialect,
+    jobs: { myJob },
   })
   await durably.init() // migrate + start
   return durably
@@ -48,11 +72,9 @@ const durablyPromise = initDurably()
 
 function App() {
   return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <DurablyProvider durably={durablyPromise}>
-        <MyComponent />
-      </DurablyProvider>
-    </Suspense>
+    <DurablyProvider durably={durablyPromise} fallback={<div>Loading...</div>}>
+      <MyComponent />
+    </DurablyProvider>
   )
 }
 
@@ -66,44 +88,12 @@ function MyComponent() {
 }
 ```
 
-## Server-Connected Mode
-
-For full-stack apps, use hooks from `@coji/durably-react/client`:
-
-```tsx
-import { useJob } from '@coji/durably-react/client'
-
-function MyComponent() {
-  const {
-    trigger,
-    status,
-    output,
-    isRunning,
-    isPending,
-    isCompleted,
-    isFailed,
-    isCancelled,
-  } = useJob<{ id: string }, { result: number }>({
-    api: '/api/durably',
-    jobName: 'my-job',
-    autoResume: true, // Auto-resume running/pending jobs on mount (default)
-    followLatest: true, // Switch to tracking new runs via SSE (default)
-  })
-
-  return (
-    <button onClick={() => trigger({ id: '123' })} disabled={isRunning}>
-      Run
-    </button>
-  )
-}
-```
-
 ## Documentation
 
 For full documentation, visit [coji.github.io/durably](https://coji.github.io/durably/).
 
-- [React Guide](https://coji.github.io/durably/guide/react) - Browser mode with hooks
-- [Full-Stack Guide](https://coji.github.io/durably/guide/full-stack) - Server-connected mode
+- [SPA Hooks](https://coji.github.io/durably/api/durably-react/spa) - SPA mode with OPFS
+- [Fullstack Hooks](https://coji.github.io/durably/api/durably-react/fullstack) - Server-connected mode
 
 ## License
 

package/dist/index.d.ts

@@ -1,64 +1,37 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Durably, JobDefinition } from '@coji/durably';
-import { ReactNode } from 'react';
-import { R as RunStatus, L as LogEntry, P as Progress, T as TypedRun } from './types-xrRs7jov.js';
-export { D as DurablyEvent } from './types-xrRs7jov.js';
+import { R as RunStatus, L as LogEntry, P as Progress, I as InferInput, a as InferOutput, T as TypedClientRun } from './types-JIBwGTm6.js';
+export { D as DurablyEvent } from './types-JIBwGTm6.js';
+import { JobDefinition, ClientRun } from '@coji/durably';
+export { ClientRun } from '@coji/durably';
 
-interface DurablyContextValue {
-    durably: Durably;
-}
-interface DurablyProviderProps {
-    /**
-     * Durably instance or Promise that resolves to one.
-     * The instance should already be initialized via `await durably.init()`.
-     *
-     * When passing a Promise, wrap the provider with Suspense or use the fallback prop.
-     *
-     * @example
-     * // With Suspense (recommended)
-     * <Suspense fallback={<Loading />}>
-     *   <DurablyProvider durably={durablyPromise}>
-     *     <App />
-     *   </DurablyProvider>
-     * </Suspense>
-     *
-     * @example
-     * // With fallback prop
-     * <DurablyProvider durably={durablyPromise} fallback={<Loading />}>
-     *   <App />
-     * </DurablyProvider>
-     */
-    durably: Durably | Promise<Durably>;
-    /**
-     * Fallback to show while waiting for the Durably Promise to resolve.
-     * This wraps the provider content in a Suspense boundary automatically.
-     */
-    fallback?: ReactNode;
-    children: ReactNode;
-}
-declare function DurablyProvider({ durably, fallback, children, }: DurablyProviderProps): react_jsx_runtime.JSX.Element;
-declare function useDurably(): DurablyContextValue;
-
-interface UseJobOptions {
+interface UseJobClientOptions {
+    /**
+     * API endpoint URL (e.g., '/api/durably')
+     */
+    api: string;
+    /**
+     * Job name to trigger
+     */
+    jobName: string;
     /**
      * Initial Run ID to subscribe to (for reconnection scenarios)
+     * When provided, the hook will immediately start subscribing to this run
      */
     initialRunId?: string;
     /**
-     * Automatically resume tracking any pending or running job on initialization.
-     * If a pending or running run exists for this job, the hook will subscribe to it.
+     * Automatically resume tracking a running/pending job on mount
      * @default true
      */
     autoResume?: boolean;
     /**
-     * Automatically switch to tracking the latest running job when a new run starts.
-     * When true, the hook will update to track any new run for this job as soon as it starts running.
-     * When false, the hook will only track the run that was triggered or explicitly set.
+     * Automatically switch to tracking the latest triggered job
      * @default true
      */
     followLatest?: boolean;
 }
-interface UseJobResult<TInput, TOutput> {
+interface UseJobClientResult<TInput, TOutput> {
+    /**
+     * Whether the hook is ready (always true for client mode)
+     */
     /**
      * Trigger the job with the given input
      */
@@ -121,9 +94,17 @@ interface UseJobResult<TInput, TOutput> {
      */
     reset: () => void;
 }
-declare function useJob<TName extends string, TInput extends Record<string, unknown>, TOutput extends Record<string, unknown> | void>(jobDefinition: JobDefinition<TName, TInput, TOutput>, options?: UseJobOptions): UseJobResult<TInput, TOutput>;
+/**
+ * Hook for triggering and subscribing to jobs via server API.
+ * Uses fetch for triggering and EventSource for SSE subscription.
+ */
+declare function useJob<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = Record<string, unknown>>(options: UseJobClientOptions): UseJobClientResult<TInput, TOutput>;
 
-interface UseJobLogsOptions {
+interface UseJobLogsClientOptions {
+    /**
+     * API endpoint URL (e.g., '/api/durably')
+     */
+    api: string;
     /**
      * The run ID to subscribe to logs for
      */
@@ -133,7 +114,10 @@ interface UseJobLogsOptions {
      */
     maxLogs?: number;
 }
-interface UseJobLogsResult {
+interface UseJobLogsClientResult {
+    /**
+     * Whether the hook is ready (always true for client mode)
+     */
     /**
      * Logs collected during execution
      */
@@ -144,18 +128,37 @@ interface UseJobLogsResult {
     clearLogs: () => void;
 }
 /**
- * Hook for subscribing to logs from a run.
- * Use this when you only need logs, not full run status.
+ * Hook for subscribing to logs from a run via server API.
+ * Uses EventSource for SSE subscription.
  */
-declare function useJobLogs(options: UseJobLogsOptions): UseJobLogsResult;
+declare function useJobLogs(options: UseJobLogsClientOptions): UseJobLogsClientResult;
 
-interface UseJobRunOptions {
+interface UseJobRunClientOptions {
+    /**
+     * API endpoint URL (e.g., '/api/durably')
+     */
+    api: string;
     /**
      * The run ID to subscribe to
      */
     runId: string | null;
+    /**
+     * Callback when run starts (transitions to pending/running)
+     */
+    onStart?: () => void;
+    /**
+     * Callback when run completes successfully
+     */
+    onComplete?: () => void;
+    /**
+     * Callback when run fails
+     */
+    onFail?: () => void;
 }
-interface UseJobRunResult<TOutput = unknown> {
+interface UseJobRunClientResult<TOutput = unknown> {
+    /**
+     * Whether the hook is ready (always true for client mode)
+     */
     /**
      * Current run status
      */
@@ -198,20 +201,158 @@ interface UseJobRunResult<TOutput = unknown> {
     isCancelled: boolean;
 }
 /**
- * Hook for subscribing to an existing run by ID.
- * Use this when you have a runId and want to track its status.
+ * Hook for subscribing to an existing run via server API.
+ * Uses EventSource for SSE subscription.
+ */
+declare function useJobRun<TOutput = unknown>(options: UseJobRunClientOptions): UseJobRunClientResult<TOutput>;
+
+/**
+ * Options for createJobHooks
+ */
+interface CreateJobHooksOptions {
+    /**
+     * API endpoint URL (e.g., '/api/durably')
+     */
+    api: string;
+    /**
+     * Job name (must match the server-side job name)
+     */
+    jobName: string;
+}
+/**
+ * Type-safe hooks for a specific job
+ */
+interface JobHooks<TInput, TOutput> {
+    /**
+     * Hook for triggering and monitoring the job
+     */
+    useJob: () => UseJobClientResult<TInput, TOutput>;
+    /**
+     * Hook for subscribing to an existing run by ID
+     */
+    useRun: (runId: string | null) => UseJobRunClientResult<TOutput>;
+    /**
+     * Hook for subscribing to logs from a run
+     */
+    useLogs: (runId: string | null, options?: {
+        maxLogs?: number;
+    }) => UseJobLogsClientResult;
+}
+/**
+ * Create type-safe hooks for a specific job.
+ *
+ * @example
+ * ```tsx
+ * // Import job type from server (type-only import is safe)
+ * import type { importCsvJob } from '~/lib/durably.server'
+ * import { createJobHooks } from '@coji/durably-react'
+ *
+ * const importCsv = createJobHooks<typeof importCsvJob>({
+ *   api: '/api/durably',
+ *   jobName: 'import-csv',
+ * })
+ *
+ * // In your component - fully type-safe
+ * function CsvImporter() {
+ *   const { trigger, output, progress, isRunning } = importCsv.useJob()
+ *
+ *   return (
+ *     <button onClick={() => trigger({ rows: [...] })}>
+ *       Import
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+declare function createJobHooks<TJob extends JobDefinition<string, any, any>>(options: CreateJobHooksOptions): JobHooks<InferInput<TJob>, InferOutput<TJob>>;
+
+/**
+ * Step record returned from the server API
+ */
+interface StepRecord {
+    name: string;
+    status: 'completed' | 'failed' | 'cancelled';
+    output: unknown;
+}
+interface UseRunActionsClientOptions {
+    /**
+     * API endpoint URL (e.g., '/api/durably')
+     */
+    api: string;
+}
+interface UseRunActionsClientResult {
+    /**
+     * Retry a failed or cancelled run
+     */
+    retry: (runId: string) => Promise<void>;
+    /**
+     * Cancel a pending or running run
+     */
+    cancel: (runId: string) => Promise<void>;
+    /**
+     * Delete a run (only completed, failed, or cancelled runs)
+     */
+    deleteRun: (runId: string) => Promise<void>;
+    /**
+     * Get a single run by ID
+     */
+    getRun: (runId: string) => Promise<ClientRun | null>;
+    /**
+     * Get steps for a run
+     */
+    getSteps: (runId: string) => Promise<StepRecord[]>;
+    /**
+     * Whether an action is in progress
+     */
+    isLoading: boolean;
+    /**
+     * Error message from last action
+     */
+    error: string | null;
+}
+/**
+ * Hook for run actions (retry, cancel) via server API.
+ *
+ * @example
+ * ```tsx
+ * function RunActions({ runId, status }: { runId: string; status: string }) {
+ *   const { retry, cancel, isLoading, error } = useRunActions({
+ *     api: '/api/durably',
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       {status === 'failed' && (
+ *         <button onClick={() => retry(runId)} disabled={isLoading}>
+ *           Retry
+ *         </button>
+ *       )}
+ *       {(status === 'pending' || status === 'running') && (
+ *         <button onClick={() => cancel(runId)} disabled={isLoading}>
+ *           Cancel
+ *         </button>
+ *       )}
+ *       {error && <span className="error">{error}</span>}
+ *     </div>
+ *   )
+ * }
+ * ```
  */
-declare function useJobRun<TOutput = unknown>(options: UseJobRunOptions): UseJobRunResult<TOutput>;
+declare function useRunActions(options: UseRunActionsClientOptions): UseRunActionsClientResult;
 
-interface UseRunsOptions {
+interface UseRunsClientOptions {
+    /**
+     * API endpoint URL (e.g., '/api/durably')
+     */
+    api: string;
     /**
-     * Filter by job name
+     * Filter by job name(s). Pass a string for one, or an array for multiple.
      */
-    jobName?: string;
+    jobName?: string | string[];
     /**
      * Filter by status
      */
-    status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    status?: RunStatus;
     /**
      * Filter by labels (all specified labels must match)
      */
@@ -222,16 +363,16 @@ interface UseRunsOptions {
      */
     pageSize?: number;
     /**
-     * Subscribe to real-time updates
+     * Subscribe to real-time updates via SSE (first page only)
      * @default true
      */
     realtime?: boolean;
 }
-interface UseRunsResult<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> | undefined = Record<string, unknown> | undefined> {
+interface UseRunsClientResult<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> | undefined = Record<string, unknown> | undefined> {
     /**
      * List of runs for the current page
      */
-    runs: TypedRun<TInput, TOutput>[];
+    runs: TypedClientRun<TInput, TOutput>[];
     /**
      * Current page (0-indexed)
      */
@@ -244,6 +385,10 @@ interface UseRunsResult<TInput extends Record<string, unknown> = Record<string,
      * Whether data is being loaded
      */
     isLoading: boolean;
+    /**
+     * Error message if fetch failed
+     */
+    error: string | null;
     /**
      * Go to the next page
      */
@@ -262,14 +407,16 @@ interface UseRunsResult<TInput extends Record<string, unknown> = Record<string,
     refresh: () => Promise<void>;
 }
 /**
- * Hook for listing runs with pagination and real-time updates.
+ * Hook for listing runs via server API with pagination.
+ * First page (page 0) automatically subscribes to SSE for real-time updates.
+ * Other pages are static and require manual refresh.
  *
  * @example With generic type parameter (dashboard with multiple job types)
  * ```tsx
- * type DashboardRun = TypedRun<ImportInput, ImportOutput> | TypedRun<SyncInput, SyncOutput>
+ * type DashboardRun = TypedClientRun<ImportInput, ImportOutput> | TypedClientRun<SyncInput, SyncOutput>
  *
  * function Dashboard() {
- *   const { runs } = useRuns<DashboardRun>({ pageSize: 10 })
+ *   const { runs } = useRuns<DashboardRun>({ api: '/api/durably', pageSize: 10 })
  *   // runs are typed as DashboardRun[]
  * }
  * ```
@@ -278,8 +425,8 @@ interface UseRunsResult<TInput extends Record<string, unknown> = Record<string,
  * ```tsx
  * const myJob = defineJob({ name: 'my-job', ... })
  *
- * function Dashboard() {
- *   const { runs } = useRuns(myJob)
+ * function RunHistory() {
+ *   const { runs } = useRuns(myJob, { api: '/api/durably' })
  *   // runs[0].output is typed!
  *   return <div>{runs[0]?.output?.someField}</div>
  * }
@@ -287,14 +434,87 @@ interface UseRunsResult<TInput extends Record<string, unknown> = Record<string,
  *
  * @example With options only (untyped)
  * ```tsx
- * function Dashboard() {
- *   const { runs } = useRuns({ pageSize: 20 })
+ * function RunHistory() {
+ *   const { runs } = useRuns({ api: '/api/durably', pageSize: 10 })
  *   // runs[0].output is unknown
  * }
  * ```
  */
-declare function useRuns<TRun extends TypedRun<Record<string, unknown>, Record<string, unknown> | undefined>>(options?: UseRunsOptions): UseRunsResult<TRun extends TypedRun<infer I, infer _O> ? I : Record<string, unknown>, TRun extends TypedRun<infer _I, infer O> ? O : Record<string, unknown>>;
-declare function useRuns<TName extends string, TInput extends Record<string, unknown>, TOutput extends Record<string, unknown> | undefined>(jobDefinition: JobDefinition<TName, TInput, TOutput>, options?: Omit<UseRunsOptions, 'jobName'>): UseRunsResult<TInput, TOutput>;
-declare function useRuns(options?: UseRunsOptions): UseRunsResult;
+declare function useRuns<TRun extends TypedClientRun<Record<string, unknown>, Record<string, unknown> | undefined>>(options: UseRunsClientOptions): UseRunsClientResult<TRun extends TypedClientRun<infer I, infer _O> ? I : Record<string, unknown>, TRun extends TypedClientRun<infer _I, infer O> ? O : Record<string, unknown>>;
+declare function useRuns<TName extends string, TInput extends Record<string, unknown>, TOutput extends Record<string, unknown> | undefined>(jobDefinition: JobDefinition<TName, TInput, TOutput>, options: Omit<UseRunsClientOptions, 'jobName'>): UseRunsClientResult<TInput, TOutput>;
+declare function useRuns(options: UseRunsClientOptions): UseRunsClientResult;
+
+/**
+ * Options for createDurably
+ */
+interface CreateDurablyOptions {
+    /**
+     * API endpoint URL (e.g., '/api/durably')
+     */
+    api: string;
+}
+/**
+ * Extract the jobs record from a Durably instance type.
+ * Allows `createDurably<typeof serverDurably>()` to infer job types.
+ */
+type ExtractJobs<T> = T extends {
+    readonly jobs: infer TJobs;
+} ? TJobs : T;
+/**
+ * A type-safe Durably client with per-job hooks and cross-job utilities.
+ */
+type DurablyClient<T> = {
+    [K in keyof ExtractJobs<T>]: JobHooks<InferInput<ExtractJobs<T>[K]>, InferOutput<ExtractJobs<T>[K]>>;
+} & {
+    /**
+     * List runs with pagination and real-time updates (cross-job).
+     * The `api` option is pre-configured.
+     */
+    useRuns: <TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> | undefined = Record<string, unknown> | undefined>(options?: Omit<UseRunsClientOptions, 'api'>) => UseRunsClientResult<TInput, TOutput>;
+    /**
+     * Run actions: retry, cancel, delete, getRun, getSteps (cross-job).
+     * The `api` option is pre-configured.
+     */
+    useRunActions: () => UseRunActionsClientResult;
+};
+/**
+ * Create a type-safe Durably client for React.
+ *
+ * Uses the same name as the server-side `createDurably` — the API endpoint
+ * option distinguishes it from the server constructor.
+ *
+ * @example
+ * ```tsx
+ * // Server: create Durably instance
+ * // app/lib/durably.server.ts
+ * import { createDurably } from '@coji/durably'
+ * export const durably = createDurably({
+ *   dialect,
+ *   jobs: { importCsv: importCsvJob, syncUsers: syncUsersJob },
+ * })
+ *
+ * // Client: create typed hooks
+ * // app/lib/durably.ts
+ * import type { durably as serverDurably } from '~/lib/durably.server'
+ * import { createDurably } from '@coji/durably-react'
+ *
+ * export const durably = createDurably<typeof serverDurably>({
+ *   api: '/api/durably',
+ * })
+ *
+ * // In your component — fully type-safe with autocomplete
+ * function CsvImporter() {
+ *   const { trigger, output, isRunning } = durably.importCsv.useJob()
+ *   return <button onClick={() => trigger({ rows: [...] })}>Import</button>
+ * }
+ *
+ * // Cross-job hooks
+ * function Dashboard() {
+ *   const { runs, nextPage } = durably.useRuns({ pageSize: 10 })
+ *   const { retry, cancel } = durably.useRunActions()
+ * }
+ * ```
+ */
+declare function createDurably<T>(options: CreateDurablyOptions): DurablyClient<T>;
 
-export { DurablyProvider, type DurablyProviderProps, LogEntry, Progress, RunStatus, TypedRun, type UseJobLogsOptions, type UseJobLogsResult, type UseJobOptions, type UseJobResult, type UseJobRunOptions, type UseJobRunResult, type UseRunsOptions, type UseRunsResult, useDurably, useJob, useJobLogs, useJobRun, useRuns };
+export { type CreateDurablyOptions, type CreateJobHooksOptions, type DurablyClient, type JobHooks, LogEntry, Progress, RunStatus, type StepRecord, TypedClientRun, type UseJobClientOptions, type UseJobClientResult, type UseJobLogsClientOptions, type UseJobLogsClientResult, type UseJobRunClientOptions, type UseJobRunClientResult, type UseRunActionsClientOptions, type UseRunActionsClientResult, type UseRunsClientOptions, type UseRunsClientResult, createDurably, createJobHooks, useJob, useJobLogs, useJobRun, useRunActions, useRuns };