@coji/durably-react 0.6.0 → 0.7.0

package/dist/chunk-42AVE35N.js

@@ -0,0 +1,142 @@
+// src/types.ts
+function isJobDefinition(obj) {
+  return typeof obj === "object" && obj !== null && "name" in obj && "run" in obj && typeof obj.run === "function";
+}
+
+// src/shared/create-log-entry.ts
+function createLogEntry(params) {
+  return {
+    id: crypto.randomUUID(),
+    runId: params.runId,
+    stepName: params.stepName,
+    level: params.level,
+    message: params.message,
+    data: params.data,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function appendLog(logs, newLog, maxLogs) {
+  const newLogs = [...logs, newLog];
+  if (maxLogs > 0 && newLogs.length > maxLogs) {
+    return newLogs.slice(-maxLogs);
+  }
+  return newLogs;
+}
+
+// src/shared/subscription-reducer.ts
+var initialSubscriptionState = {
+  status: null,
+  output: null,
+  error: null,
+  logs: [],
+  progress: null
+};
+function subscriptionReducer(state, action) {
+  switch (action.type) {
+    case "run:start":
+      return { ...state, status: "running" };
+    case "run:complete":
+      return { ...state, status: "completed", output: action.output };
+    case "run:fail":
+      return { ...state, status: "failed", error: action.error };
+    case "run:cancel":
+      return { ...state, status: "cancelled" };
+    case "run:retry":
+      return { ...state, status: "pending", error: null };
+    case "run:progress":
+      return { ...state, progress: action.progress };
+    case "log:write": {
+      const newLog = createLogEntry({
+        runId: action.runId,
+        stepName: action.stepName,
+        level: action.level,
+        message: action.message,
+        data: action.data
+      });
+      return { ...state, logs: appendLog(state.logs, newLog, action.maxLogs) };
+    }
+    case "reset":
+      return initialSubscriptionState;
+    case "clear_logs":
+      return { ...state, logs: [] };
+    case "connection_error":
+      return { ...state, error: action.error };
+    default:
+      return state;
+  }
+}
+
+// src/shared/use-subscription.ts
+import { useCallback, useEffect, useReducer, useRef } from "react";
+function useSubscription(subscriber, runId, options) {
+  const [state, dispatch] = useReducer(
+    subscriptionReducer,
+    initialSubscriptionState
+  );
+  const runIdRef = useRef(runId);
+  const prevRunIdRef = useRef(null);
+  const maxLogs = options?.maxLogs ?? 0;
+  if (prevRunIdRef.current !== runId) {
+    prevRunIdRef.current = runId;
+    if (runIdRef.current !== runId) {
+      dispatch({ type: "reset" });
+    }
+  }
+  runIdRef.current = runId;
+  useEffect(() => {
+    if (!subscriber || !runId) return;
+    const unsubscribe = subscriber.subscribe(runId, (event) => {
+      if (runIdRef.current !== runId) return;
+      switch (event.type) {
+        case "run:start":
+        case "run:cancel":
+        case "run:retry":
+          dispatch({ type: event.type });
+          break;
+        case "run:complete":
+          dispatch({ type: "run:complete", output: event.output });
+          break;
+        case "run:fail":
+          dispatch({ type: "run:fail", error: event.error });
+          break;
+        case "run:progress":
+          dispatch({ type: "run:progress", progress: event.progress });
+          break;
+        case "log:write":
+          dispatch({
+            type: "log:write",
+            runId: event.runId,
+            stepName: event.stepName,
+            level: event.level,
+            message: event.message,
+            data: event.data,
+            maxLogs
+          });
+          break;
+        case "connection_error":
+          dispatch({ type: "connection_error", error: event.error });
+          break;
+      }
+    });
+    return unsubscribe;
+  }, [subscriber, runId, maxLogs]);
+  const clearLogs = useCallback(() => {
+    dispatch({ type: "clear_logs" });
+  }, []);
+  const reset = useCallback(() => {
+    dispatch({ type: "reset" });
+  }, []);
+  return {
+    ...state,
+    clearLogs,
+    reset
+  };
+}
+
+export {
+  initialSubscriptionState,
+  subscriptionReducer,
+  useSubscription,
+  isJobDefinition
+};
+//# sourceMappingURL=chunk-42AVE35N.js.map

package/dist/chunk-42AVE35N.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/shared/create-log-entry.ts","../src/shared/subscription-reducer.ts","../src/shared/use-subscription.ts"],"sourcesContent":["// Shared type definitions for @coji/durably-react\n\nimport type { JobDefinition, Run } from '@coji/durably'\n\n// Type inference utilities for extracting Input/Output types from JobDefinition\nexport type InferInput<T> =\n  T extends JobDefinition<string, infer TInput, unknown>\n    ? TInput extends Record<string, unknown>\n      ? TInput\n      : Record<string, unknown>\n    : T extends { trigger: (input: infer TInput) => unknown }\n      ? TInput extends Record<string, unknown>\n        ? TInput\n        : Record<string, unknown>\n      : Record<string, unknown>\n\nexport type InferOutput<T> =\n  T extends JobDefinition<string, unknown, infer TOutput>\n    ? TOutput extends Record<string, unknown>\n      ? TOutput\n      : Record<string, unknown>\n    : T extends {\n          trigger: (input: unknown) => Promise<{ output?: infer TOutput }>\n        }\n      ? TOutput extends Record<string, unknown>\n        ? TOutput\n        : Record<string, unknown>\n      : Record<string, unknown>\n\nexport type RunStatus =\n  | 'pending'\n  | 'running'\n  | 'completed'\n  | 'failed'\n  | 'cancelled'\n\nexport interface Progress {\n  current: number\n  total?: number\n  message?: string\n}\n\nexport interface LogEntry {\n  id: string\n  runId: string\n  stepName: string | null\n  level: 'info' | 'warn' | 'error'\n  message: string\n  data: unknown\n  timestamp: string\n}\n\n// Shared subscription state (used by both direct and SSE subscriptions)\nexport interface SubscriptionState<TOutput = unknown> {\n  status: RunStatus | null\n  output: TOutput | null\n  error: string | null\n  logs: LogEntry[]\n  progress: Progress | null\n}\n\n// SSE event types (sent from server)\nexport type DurablyEvent =\n  | { type: 'run:start'; runId: string; jobName: string; payload: unknown }\n  | {\n      type: 'run:complete'\n      runId: string\n      jobName: string\n      output: unknown\n      duration: number\n    }\n  | { type: 'run:fail'; runId: string; jobName: string; error: string }\n  | { type: 'run:cancel'; runId: string; jobName: string }\n  | { type: 'run:retry'; runId: string; jobName: string }\n  | {\n      type: 'run:progress'\n      runId: string\n      jobName: string\n      progress: Progress\n    }\n  | {\n      type: 'step:start'\n      runId: string\n      jobName: string\n      stepName: string\n      stepIndex: number\n    }\n  | {\n      type: 'step:complete'\n      runId: string\n      jobName: string\n      stepName: string\n      stepIndex: number\n      output: unknown\n    }\n  | {\n      type: 'log:write'\n      runId: string\n      jobName: string\n      level: 'info' | 'warn' | 'error'\n      message: string\n      data: unknown\n    }\n\n// =============================================================================\n// Typed Run types for useRuns hooks\n// =============================================================================\n\n/**\n * A typed version of Run with generic payload/output types.\n * Used by browser hooks (direct durably access).\n */\nexport type TypedRun<\n  TInput extends Record<string, unknown> = Record<string, unknown>,\n  TOutput extends Record<string, unknown> | undefined =\n    | Record<string, unknown>\n    | undefined,\n> = Omit<Run, 'payload' | 'output'> & {\n  payload: TInput\n  output: TOutput | null\n}\n\n/**\n * Run type for client mode (matches server response).\n * Used by client hooks (HTTP/SSE connection).\n */\nexport interface ClientRun {\n  id: string\n  jobName: string\n  status: RunStatus\n  input: unknown\n  output: unknown | null\n  error: string | null\n  currentStepIndex: number\n  stepCount: number\n  progress: Progress | null\n  createdAt: string\n  startedAt: string | null\n  completedAt: string | null\n}\n\n/**\n * A typed version of ClientRun with generic input/output types.\n * Used by client hooks (HTTP/SSE connection).\n */\nexport type TypedClientRun<\n  TInput extends Record<string, unknown> = Record<string, unknown>,\n  TOutput extends Record<string, unknown> | undefined =\n    | Record<string, unknown>\n    | undefined,\n> = Omit<ClientRun, 'input' | 'output'> & {\n  input: TInput\n  output: TOutput | null\n}\n\n/**\n * Type guard to check if an object is a JobDefinition.\n * Used to distinguish between JobDefinition and options objects in overloaded functions.\n */\nexport function isJobDefinition<\n  TName extends string = string,\n  TInput extends Record<string, unknown> = Record<string, unknown>,\n  TOutput extends Record<string, unknown> | undefined = undefined,\n>(obj: unknown): obj is JobDefinition<TName, TInput, TOutput> {\n  return (\n    typeof obj === 'object' &&\n    obj !== null &&\n    'name' in obj &&\n    'run' in obj &&\n    typeof (obj as { run: unknown }).run === 'function'\n  )\n}\n","import type { LogEntry } from '../types'\n\nexport interface CreateLogEntryParams {\n  runId: string\n  stepName: string | null\n  level: 'info' | 'warn' | 'error'\n  message: string\n  data: unknown\n}\n\n/**\n * Creates a LogEntry with auto-generated id and timestamp.\n * Extracted to eliminate duplication between subscription hooks.\n */\nexport function createLogEntry(params: CreateLogEntryParams): LogEntry {\n  return {\n    id: crypto.randomUUID(),\n    runId: params.runId,\n    stepName: params.stepName,\n    level: params.level,\n    message: params.message,\n    data: params.data,\n    timestamp: new Date().toISOString(),\n  }\n}\n\n/**\n * Appends a log entry to the array, respecting maxLogs limit.\n */\nexport function appendLog(\n  logs: LogEntry[],\n  newLog: LogEntry,\n  maxLogs: number,\n): LogEntry[] {\n  const newLogs = [...logs, newLog]\n  if (maxLogs > 0 && newLogs.length > maxLogs) {\n    return newLogs.slice(-maxLogs)\n  }\n  return newLogs\n}\n","import type { Progress, SubscriptionState } from '../types'\nimport { appendLog, createLogEntry } from './create-log-entry'\n\n// Action types for subscription state transitions\nexport type SubscriptionAction<TOutput = unknown> =\n  | { type: 'run:start' }\n  | { type: 'run:complete'; output: TOutput }\n  | { type: 'run:fail'; error: string }\n  | { type: 'run:cancel' }\n  | { type: 'run:retry' }\n  | { type: 'run:progress'; progress: Progress }\n  | {\n      type: 'log:write'\n      runId: string\n      stepName: string | null\n      level: 'info' | 'warn' | 'error'\n      message: string\n      data: unknown\n      maxLogs: number\n    }\n  | { type: 'reset' }\n  | { type: 'clear_logs' }\n  | { type: 'connection_error'; error: string }\n\nexport const initialSubscriptionState: SubscriptionState<unknown> = {\n  status: null,\n  output: null,\n  error: null,\n  logs: [],\n  progress: null,\n}\n\n/**\n * Pure reducer for subscription state transitions.\n * Extracted to eliminate duplication between useRunSubscription and useSSESubscription.\n */\nexport function subscriptionReducer<TOutput = unknown>(\n  state: SubscriptionState<TOutput>,\n  action: SubscriptionAction<TOutput>,\n): SubscriptionState<TOutput> {\n  switch (action.type) {\n    case 'run:start':\n      return { ...state, status: 'running' }\n\n    case 'run:complete':\n      return { ...state, status: 'completed', output: action.output }\n\n    case 'run:fail':\n      return { ...state, status: 'failed', error: action.error }\n\n    case 'run:cancel':\n      return { ...state, status: 'cancelled' }\n\n    case 'run:retry':\n      return { ...state, status: 'pending', error: null }\n\n    case 'run:progress':\n      return { ...state, progress: action.progress }\n\n    case 'log:write': {\n      const newLog = createLogEntry({\n        runId: action.runId,\n        stepName: action.stepName,\n        level: action.level,\n        message: action.message,\n        data: action.data,\n      })\n      return { ...state, logs: appendLog(state.logs, newLog, action.maxLogs) }\n    }\n\n    case 'reset':\n      return initialSubscriptionState as SubscriptionState<TOutput>\n\n    case 'clear_logs':\n      return { ...state, logs: [] }\n\n    case 'connection_error':\n      return { ...state, error: action.error }\n\n    default:\n      return state\n  }\n}\n","import { useCallback, useEffect, useReducer, useRef } from 'react'\nimport type { SubscriptionState } from '../types'\nimport type { EventSubscriber } from './event-subscriber'\nimport {\n  initialSubscriptionState,\n  subscriptionReducer,\n} from './subscription-reducer'\n\nexport interface UseSubscriptionOptions {\n  /**\n   * Maximum number of logs to keep (0 = unlimited)\n   */\n  maxLogs?: number\n}\n\nexport interface UseSubscriptionResult<\n  TOutput = unknown,\n> extends SubscriptionState<TOutput> {\n  /**\n   * Clear all logs\n   */\n  clearLogs: () => void\n  /**\n   * Reset all state\n   */\n  reset: () => void\n}\n\n/**\n * Core subscription hook that works with any EventSubscriber implementation.\n * This unifies the subscription logic between Durably.on and SSE.\n */\nexport function useSubscription<TOutput = unknown>(\n  subscriber: EventSubscriber | null,\n  runId: string | null,\n  options?: UseSubscriptionOptions,\n): UseSubscriptionResult<TOutput> {\n  const [state, dispatch] = useReducer(\n    subscriptionReducer<TOutput>,\n    initialSubscriptionState as SubscriptionState<TOutput>,\n  )\n\n  const runIdRef = useRef<string | null>(runId)\n  const prevRunIdRef = useRef<string | null>(null)\n\n  const maxLogs = options?.maxLogs ?? 0\n\n  // Reset state when runId changes\n  if (prevRunIdRef.current !== runId) {\n    prevRunIdRef.current = runId\n    if (runIdRef.current !== runId) {\n      dispatch({ type: 'reset' })\n    }\n  }\n  runIdRef.current = runId\n\n  useEffect(() => {\n    if (!subscriber || !runId) return\n\n    const unsubscribe = subscriber.subscribe<TOutput>(runId, (event) => {\n      // Verify runId hasn't changed during async operation\n      if (runIdRef.current !== runId) return\n\n      switch (event.type) {\n        case 'run:start':\n        case 'run:cancel':\n        case 'run:retry':\n          dispatch({ type: event.type })\n          break\n        case 'run:complete':\n          dispatch({ type: 'run:complete', output: event.output })\n          break\n        case 'run:fail':\n          dispatch({ type: 'run:fail', error: event.error })\n          break\n        case 'run:progress':\n          dispatch({ type: 'run:progress', progress: event.progress })\n          break\n        case 'log:write':\n          dispatch({\n            type: 'log:write',\n            runId: event.runId,\n            stepName: event.stepName,\n            level: event.level,\n            message: event.message,\n            data: event.data,\n            maxLogs,\n          })\n          break\n        case 'connection_error':\n          dispatch({ type: 'connection_error', error: event.error })\n          break\n      }\n    })\n\n    return unsubscribe\n  }, [subscriber, runId, maxLogs])\n\n  const clearLogs = useCallback(() => {\n    dispatch({ type: 'clear_logs' })\n  }, [])\n\n  const reset = useCallback(() => {\n    dispatch({ type: 'reset' })\n  }, [])\n\n  return {\n    ...state,\n    clearLogs,\n    reset,\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/client.d.ts

@@ -1,5 +1,6 @@
+import { R as RunStatus, L as LogEntry, P as Progress, I as InferInput, a as InferOutput, b as TypedClientRun } from './types-DY4Y6ggJ.js';
+export { C as ClientRun } from './types-DY4Y6ggJ.js';
 import { JobDefinition } from '@coji/durably';
-import { R as RunStatus, L as LogEntry, P as Progress } from './types-BDUvsa8u.js';
 
 interface UseJobClientOptions {
     /**
@@ -190,20 +191,6 @@ interface UseJobRunClientResult<TOutput = unknown> {
  */
 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
  */
@@ -236,7 +223,7 @@ interface CreateDurablyClientOptions {
  * 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]>>;
+    [K in keyof TJobs]: JobClient<InferInput<TJobs[K]>, InferOutput<TJobs[K]>>;
 };
 /**
  * Create a type-safe Durably client with hooks for all registered jobs.
@@ -273,14 +260,6 @@ type DurablyClient<TJobs extends Record<string, unknown>> = {
  */
 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
  */
@@ -341,23 +320,6 @@ interface JobHooks<TInput, TOutput> {
  */
 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')
@@ -377,11 +339,11 @@ interface UseRunsClientOptions {
      */
     pageSize?: number;
 }
-interface UseRunsClientResult {
+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: ClientRun[];
+    runs: TypedClientRun<TInput, TOutput>[];
     /**
      * Current page (0-indexed)
      */
@@ -420,28 +382,37 @@ interface UseRunsClientResult {
  * First page (page 0) automatically subscribes to SSE for real-time updates.
  * Other pages are static and require manual refresh.
  *
- * @example
+ * @example With generic type parameter (dashboard with multiple job types)
+ * ```tsx
+ * type DashboardRun = TypedClientRun<ImportInput, ImportOutput> | TypedClientRun<SyncInput, SyncOutput>
+ *
+ * function Dashboard() {
+ *   const { runs } = useRuns<DashboardRun>({ api: '/api/durably', pageSize: 10 })
+ *   // runs are typed as DashboardRun[]
+ * }
+ * ```
+ *
+ * @example With JobDefinition (single job, auto-filters by jobName)
  * ```tsx
+ * const myJob = defineJob({ name: 'my-job', ... })
+ *
  * function RunHistory() {
- *   const { runs, page, hasMore, nextPage, prevPage, refresh } = useRuns({
- *     api: '/api/durably',
- *     jobName: 'import-csv',
- *     pageSize: 10,
- *   })
+ *   const { runs } = useRuns(myJob, { api: '/api/durably' })
+ *   // runs[0].output is typed!
+ *   return <div>{runs[0]?.output?.someField}</div>
+ * }
+ * ```
  *
- *   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>
- *   )
+ * @example With options only (untyped)
+ * ```tsx
+ * function RunHistory() {
+ *   const { runs } = useRuns({ api: '/api/durably', pageSize: 10 })
+ *   // runs[0].output is unknown
  * }
  * ```
  */
+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;
 
 /**
@@ -539,4 +510,4 @@ interface UseRunActionsClientResult {
  */
 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 };
+export { type CreateDurablyClientOptions, type CreateJobHooksOptions, type DurablyClient, type JobClient, type JobHooks, LogEntry, Progress, type RunRecord, RunStatus, type StepRecord, TypedClientRun, 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 };