@coji/durably-react 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 coji
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @coji/durably-react
+
+React bindings for [Durably](https://github.com/coji/durably) - step-oriented resumable batch execution.
+
+**[Documentation](https://coji.github.io/durably/)** | **[GitHub](https://github.com/coji/durably)**
+
+> **Note:** This package is ESM-only. CommonJS is not supported.
+
+## Installation
+
+```bash
+# Browser mode (with SQLocal)
+npm install @coji/durably-react @coji/durably kysely zod sqlocal
+
+# Server-connected mode (client only)
+npm install @coji/durably-react
+```
+
+## Quick Start
+
+```tsx
+import { Suspense } from 'react'
+import { createDurably, defineJob } from '@coji/durably'
+import { DurablyProvider, useJob } from '@coji/durably-react'
+import { SQLocalKysely } from 'sqlocal/kysely'
+import { z } from 'zod'
+
+const myJob = defineJob({
+  name: 'my-job',
+  input: z.object({ id: z.string() }),
+  run: async (step, payload) => {
+    await step.run('step-1', async () => {
+      /* ... */
+    })
+  },
+})
+
+// Initialize Durably
+async function initDurably() {
+  const sqlocal = new SQLocalKysely('app.sqlite3')
+  const durably = createDurably({ dialect: sqlocal.dialect }).register({
+    myJob,
+  })
+  await durably.init() // migrate + start
+  return durably
+}
+const durablyPromise = initDurably()
+
+function App() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <DurablyProvider durably={durablyPromise}>
+        <MyComponent />
+      </DurablyProvider>
+    </Suspense>
+  )
+}
+
+function MyComponent() {
+  const { trigger, isRunning, isCompleted } = useJob(myJob)
+  return (
+    <button onClick={() => trigger({ id: '123' })} disabled={isRunning}>
+      Run
+    </button>
+  )
+}
+```
+
+## 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 } = useJob<
+    { id: string },
+    { result: number }
+  >({
+    api: '/api/durably',
+    jobName: 'my-job',
+  })
+
+  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
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,542 @@
+import { JobDefinition } from '@coji/durably';
+import { R as RunStatus, L as LogEntry, P as Progress } from './types-BDUvsa8u.js';
+
+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;
+}
+interface UseJobClientResult<TInput, TOutput> {
+    /**
+     * Whether the hook is ready (always true for client mode)
+     */
+    /**
+     * Trigger the job with the given input
+     */
+    trigger: (input: TInput) => Promise<{
+        runId: string;
+    }>;
+    /**
+     * Trigger and wait for completion
+     */
+    triggerAndWait: (input: TInput) => Promise<{
+        runId: string;
+        output: TOutput;
+    }>;
+    /**
+     * Current run status
+     */
+    status: RunStatus | null;
+    /**
+     * Output from completed run
+     */
+    output: TOutput | null;
+    /**
+     * Error message from failed run
+     */
+    error: string | null;
+    /**
+     * Logs collected during execution
+     */
+    logs: LogEntry[];
+    /**
+     * Current progress
+     */
+    progress: Progress | null;
+    /**
+     * Whether a run is currently running
+     */
+    isRunning: boolean;
+    /**
+     * Whether a run is pending
+     */
+    isPending: boolean;
+    /**
+     * Whether the run completed successfully
+     */
+    isCompleted: boolean;
+    /**
+     * Whether the run failed
+     */
+    isFailed: boolean;
+    /**
+     * Current run ID
+     */
+    currentRunId: string | null;
+    /**
+     * Reset all state
+     */
+    reset: () => void;
+}
+/**
+ * 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 UseJobLogsClientOptions {
+    /**
+     * API endpoint URL (e.g., '/api/durably')
+     */
+    api: string;
+    /**
+     * The run ID to subscribe to logs for
+     */
+    runId: string | null;
+    /**
+     * Maximum number of logs to keep (default: unlimited)
+     */
+    maxLogs?: number;
+}
+interface UseJobLogsClientResult {
+    /**
+     * Whether the hook is ready (always true for client mode)
+     */
+    /**
+     * Logs collected during execution
+     */
+    logs: LogEntry[];
+    /**
+     * Clear all logs
+     */
+    clearLogs: () => void;
+}
+/**
+ * Hook for subscribing to logs from a run via server API.
+ * Uses EventSource for SSE subscription.
+ */
+declare function useJobLogs(options: UseJobLogsClientOptions): UseJobLogsClientResult;
+
+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 UseJobRunClientResult<TOutput = unknown> {
+    /**
+     * Whether the hook is ready (always true for client mode)
+     */
+    /**
+     * Current run status
+     */
+    status: RunStatus | null;
+    /**
+     * Output from completed run
+     */
+    output: TOutput | null;
+    /**
+     * Error message from failed run
+     */
+    error: string | null;
+    /**
+     * Logs collected during execution
+     */
+    logs: LogEntry[];
+    /**
+     * Current progress
+     */
+    progress: Progress | null;
+    /**
+     * Whether a run is currently running
+     */
+    isRunning: boolean;
+    /**
+     * Whether a run is pending
+     */
+    isPending: boolean;
+    /**
+     * Whether the run completed successfully
+     */
+    isCompleted: boolean;
+    /**
+     * Whether the run failed
+     */
+    isFailed: boolean;
+    /**
+     * Whether the run was cancelled
+     */
+    isCancelled: boolean;
+}
+/**
+ * Hook for subscribing to an existing run via server API.
+ * Uses EventSource for SSE subscription.
+ */
+declare function useJobRun<TOutput = unknown>(options: UseJobRunClientOptions): UseJobRunClientResult<TOutput>;
+
+/**
+ * Extract input type from a JobDefinition or JobHandle
+ */
+type InferInput$1<T> = T extends JobDefinition<string, infer TInput, unknown> ? TInput extends Record<string, unknown> ? TInput : Record<string, unknown> : T extends {
+    trigger: (input: infer TInput) => unknown;
+} ? TInput extends Record<string, unknown> ? TInput : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Extract output type from a JobDefinition or JobHandle
+ */
+type InferOutput$1<T> = T extends JobDefinition<string, unknown, infer TOutput> ? TOutput extends Record<string, unknown> ? TOutput : Record<string, unknown> : T extends {
+    trigger: (input: unknown) => Promise<{
+        output?: infer TOutput;
+    }>;
+} ? TOutput extends Record<string, unknown> ? TOutput : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Type-safe hooks for a specific job
+ */
+interface JobClient<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;
+}
+/**
+ * Options for createDurablyClient
+ */
+interface CreateDurablyClientOptions {
+    /**
+     * API endpoint URL (e.g., '/api/durably')
+     */
+    api: string;
+}
+/**
+ * A type-safe client with hooks for each registered job
+ */
+type DurablyClient<TJobs extends Record<string, unknown>> = {
+    [K in keyof TJobs]: JobClient<InferInput$1<TJobs[K]>, InferOutput$1<TJobs[K]>>;
+};
+/**
+ * Create a type-safe Durably client with hooks for all registered jobs.
+ *
+ * @example
+ * ```tsx
+ * // Server: register jobs
+ * // app/lib/durably.server.ts
+ * export const jobs = durably.register({
+ *   importCsv: importCsvJob,
+ *   syncUsers: syncUsersJob,
+ * })
+ *
+ * // Client: create typed client
+ * // app/lib/durably.client.ts
+ * import type { jobs } from '~/lib/durably.server'
+ * import { createDurablyClient } from '@coji/durably-react/client'
+ *
+ * export const durably = createDurablyClient<typeof jobs>({
+ *   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>
+ *   )
+ * }
+ * ```
+ */
+declare function createDurablyClient<TJobs extends Record<string, unknown>>(options: CreateDurablyClientOptions): DurablyClient<TJobs>;
+
+/**
+ * Extract input type from a JobDefinition
+ */
+type InferInput<T> = T extends JobDefinition<string, infer TInput, unknown> ? TInput extends Record<string, unknown> ? TInput : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Extract output type from a JobDefinition
+ */
+type InferOutput<T> = T extends JobDefinition<string, unknown, infer TOutput> ? TOutput extends Record<string, unknown> ? TOutput : Record<string, unknown> : Record<string, unknown>;
+/**
+ * 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/client'
+ *
+ * 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>>;
+
+/**
+ * Run type for client mode (matches server response)
+ */
+interface ClientRun {
+    id: string;
+    jobName: string;
+    status: RunStatus;
+    input: unknown;
+    output: unknown | null;
+    error: string | null;
+    currentStepIndex: number;
+    stepCount: number;
+    progress: Progress | null;
+    createdAt: string;
+    startedAt: string | null;
+    completedAt: string | null;
+}
+interface UseRunsClientOptions {
+    /**
+     * API endpoint URL (e.g., '/api/durably')
+     */
+    api: string;
+    /**
+     * Filter by job name
+     */
+    jobName?: string;
+    /**
+     * Filter by status
+     */
+    status?: RunStatus;
+    /**
+     * Number of runs per page
+     * @default 10
+     */
+    pageSize?: number;
+}
+interface UseRunsClientResult {
+    /**
+     * List of runs for the current page
+     */
+    runs: ClientRun[];
+    /**
+     * Current page (0-indexed)
+     */
+    page: number;
+    /**
+     * Whether there are more pages
+     */
+    hasMore: boolean;
+    /**
+     * Whether data is being loaded
+     */
+    isLoading: boolean;
+    /**
+     * Error message if fetch failed
+     */
+    error: string | null;
+    /**
+     * Go to the next page
+     */
+    nextPage: () => void;
+    /**
+     * Go to the previous page
+     */
+    prevPage: () => void;
+    /**
+     * Go to a specific page
+     */
+    goToPage: (page: number) => void;
+    /**
+     * Refresh the current page
+     */
+    refresh: () => Promise<void>;
+}
+/**
+ * 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
+ * ```tsx
+ * function RunHistory() {
+ *   const { runs, page, hasMore, nextPage, prevPage, refresh } = useRuns({
+ *     api: '/api/durably',
+ *     jobName: 'import-csv',
+ *     pageSize: 10,
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       {runs.map(run => (
+ *         <div key={run.id}>{run.jobName}: {run.status}</div>
+ *       ))}
+ *       <button onClick={prevPage} disabled={page === 0}>Prev</button>
+ *       <button onClick={nextPage} disabled={!hasMore}>Next</button>
+ *       <button onClick={refresh}>Refresh</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useRuns(options: UseRunsClientOptions): UseRunsClientResult;
+
+/**
+ * Run record returned from the server API
+ */
+interface RunRecord {
+    id: string;
+    jobName: string;
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    payload: unknown;
+    output: unknown | null;
+    error: string | null;
+    progress: {
+        current: number;
+        total?: number;
+        message?: string;
+    } | null;
+    currentStepIndex: number;
+    stepCount: number;
+    createdAt: string;
+    startedAt: string | null;
+    completedAt: string | null;
+}
+/**
+ * Step record returned from the server API
+ */
+interface StepRecord {
+    name: string;
+    status: 'completed' | 'failed';
+    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<RunRecord | 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 useRunActions(options: UseRunActionsClientOptions): UseRunActionsClientResult;
+
+export { type ClientRun, type CreateDurablyClientOptions, type CreateJobHooksOptions, type DurablyClient, type JobClient, type JobHooks, LogEntry, Progress, type RunRecord, RunStatus, type StepRecord, type UseJobClientOptions, type UseJobClientResult, type UseJobLogsClientOptions, type UseJobLogsClientResult, type UseJobRunClientOptions, type UseJobRunClientResult, type UseRunActionsClientOptions, type UseRunActionsClientResult, type UseRunsClientOptions, type UseRunsClientResult, createDurablyClient, createJobHooks, useJob, useJobLogs, useJobRun, useRunActions, useRuns };