index.d.ts

/* tslint:disable */
/* eslint-disable */

/* auto-generated by NAPI-RS */

/** Runtime options configurable from JavaScript. */
export interface JsRuntimeOptions {
  /** Orchestration concurrency (default: 4) */
  orchestrationConcurrency?: number
  /** Worker/activity concurrency (default: 8) */
  workerConcurrency?: number
  /** Dispatcher poll interval in ms (default: 100) */
  dispatcherPollIntervalMs?: number
  /**
   * Worker lock timeout in ms (default: 30000). Controls how often the activity
   * manager renews locks, which affects cancellation detection speed.
   */
  workerLockTimeoutMs?: number
  /** Log format: "json", "pretty", or "compact" (default) */
  logFormat?: string
  /** Log level filter: "info", "debug", "warn", "error", etc. */
  logLevel?: string
  /** Service name for identification in logs/metrics */
  serviceName?: string
  /** Optional service version */
  serviceVersion?: string
  /** Maximum concurrent sessions per runtime (default: 10) */
  maxSessionsPerRuntime?: number
  /** Session idle timeout in ms (default: 300000 = 5 minutes) */
  sessionIdleTimeoutMs?: number
  /** Stable worker identity for session ownership (e.g., K8s pod name) */
  workerNodeId?: string
  /**
   * Worker tag filter mode: "defaultOnly" (default), "any", "none", "tags", or "defaultAnd".
   * When "tags" or "defaultAnd", provide the tag list in `worker_tag_filter_tags`.
   */
  workerTagFilter?: string
  /** Tag list for "tags" or "defaultAnd" filter modes. */
  workerTagFilterTags?: Array<string>
}
/** Orchestration status returned to JS. */
export interface JsOrchestrationStatus {
  status: string
  output?: string
  error?: string
  customStatus?: string
  customStatusVersion: number
}
/** System metrics returned to JS. */
export interface JsSystemMetrics {
  totalInstances: number
  totalExecutions: number
  runningInstances: number
  completedInstances: number
  failedInstances: number
  totalEvents: number
}
/** Queue depths returned to JS. */
export interface JsQueueDepths {
  orchestratorQueue: number
  workerQueue: number
  timerQueue: number
}
/** Instance info returned to JS. */
export interface JsInstanceInfo {
  instanceId: string
  orchestrationName: string
  orchestrationVersion: string
  currentExecutionId: number
  status: string
  output?: string
  createdAt: number
  updatedAt: number
  parentInstanceId?: string
}
/** Execution info returned to JS. */
export interface JsExecutionInfo {
  executionId: number
  status: string
  output?: string
  startedAt: number
  completedAt?: number
  eventCount: number
}
/** Instance tree returned to JS. */
export interface JsInstanceTree {
  rootId: string
  allIds: Array<string>
  size: number
}
/** Delete result returned to JS. */
export interface JsDeleteInstanceResult {
  instancesDeleted: number
  executionsDeleted: number
  eventsDeleted: number
  queueMessagesDeleted: number
}
/** Prune options from JS. */
export interface JsPruneOptions {
  keepLast?: number
  completedBefore?: number
}
/** Prune result returned to JS. */
export interface JsPruneResult {
  instancesProcessed: number
  executionsDeleted: number
  eventsDeleted: number
}
/** Instance filter from JS. */
export interface JsInstanceFilter {
  instanceIds?: Array<string>
  completedBefore?: number
  limit?: number
}
/** Runtime metrics snapshot returned to JS. */
export interface JsMetricsSnapshot {
  orchStarts: number
  orchCompletions: number
  orchFailures: number
  orchApplicationErrors: number
  orchInfrastructureErrors: number
  orchConfigurationErrors: number
  orchPoison: number
  activitySuccess: number
  activityAppErrors: number
  activityInfraErrors: number
  activityConfigErrors: number
  activityPoison: number
  orchDispatcherItemsFetched: number
  workerDispatcherItemsFetched: number
  orchContinueAsNew: number
  suborchestrationCalls: number
  providerErrors: number
}
/** A single history event returned to JS. */
export interface JsEvent {
  eventId: number
  kind: string
  sourceEventId?: number
  timestampMs: number
  /** Event-specific data (activity result, input, error, timer fire_at, etc.) */
  data?: string
}
/**
 * Emit an activity trace through the current Rust ActivityContext.
 * Delegates to ActivityContext.trace_info/warn/error/debug which includes
 * all structured fields (instance_id, activity_name, activity_id, worker_id, etc.)
 */
export declare function activityTraceLog(token: string, level: string, message: string): void
/**
 * Emit an orchestration trace through the Rust OrchestrationContext.
 * Delegates to OrchestrationContext.trace() which checks is_replaying
 * and includes all structured fields (instance_id, orchestration_name, etc.)
 */
export declare function orchestrationTraceLog(instanceId: string, level: string, message: string): void
/**
 * Check if an activity's cancellation token has been triggered.
 * Returns true if the activity has been cancelled (e.g., due to losing a race/select).
 */
export declare function activityIsCancelled(token: string): boolean
/** Get a Client from an activity context, allowing activities to start new orchestrations. */
export declare function activityGetClient(token: string): JsClient | null
/**
 * Get the routing tag from an activity context.
 * Returns null if the activity was scheduled without a tag.
 */
export declare function activityTag(token: string): string | null
/** Set custom status on an orchestration context (fire-and-forget, no yield needed). */
export declare function orchestrationSetCustomStatus(instanceId: string, status: string): void
/** Reset (clear) custom status on an orchestration context (fire-and-forget, no yield needed). */
export declare function orchestrationResetCustomStatus(instanceId: string): void
/**
 * Read the current custom status value from an orchestration context.
 * Returns null if no custom status has been set.
 */
export declare function orchestrationGetCustomStatus(instanceId: string): string | null
/**
 * Options for `initTracing`. Call before `runtime.start()` to direct
 * Rust tracing output to a file instead of stdout.
 */
export interface JsTracingOptions {
  /** Path to the log file. Traces are appended. */
  logFile: string
  /**
   * Log level filter (default: "info"). Respects the same syntax as
   * `ObservabilityConfig.log_level` — the default filter expression is
   * `warn,duroxide::orchestration={level},duroxide::activity={level}`.
   */
  logLevel?: string
  /** Log format: "json", "pretty", or "compact" (default: "compact") */
  logFormat?: string
}
/**
 * Install a tracing subscriber that writes to a file.
 *
 * Must be called **before** `runtime.start()`. Since duroxide uses
 * `try_init()` (first-writer-wins), the runtime's built-in subscriber
 * will silently no-op if one is already installed.
 */
export declare function initTracing(options: JsTracingOptions): void
/** Wraps duroxide's Client for use from JavaScript. */
export declare class JsClient {
  constructor(provider: JsSqliteProvider)
  /** Create a client backed by PostgreSQL. */
  static fromPostgres(provider: JsPostgresProvider): JsClient
  /** Start a new orchestration instance. */
  startOrchestration(instanceId: string, orchestrationName: string, input: string): Promise<void>
  /** Start a new orchestration instance with a specific version. */
  startOrchestrationVersioned(instanceId: string, orchestrationName: string, input: string, version: string): Promise<void>
  /** Get the current status of an orchestration instance. */
  getStatus(instanceId: string): Promise<JsOrchestrationStatus>
  /** Wait for an orchestration to complete (with timeout in milliseconds). */
  waitForOrchestration(instanceId: string, timeoutMs: number): Promise<JsOrchestrationStatus>
  /** Cancel a running orchestration instance. */
  cancelInstance(instanceId: string, reason?: string | undefined | null): Promise<void>
  /** Raise an external event to an orchestration instance. */
  raiseEvent(instanceId: string, eventName: string, data: string): Promise<void>
  /** Get system metrics (if provider supports management). */
  getSystemMetrics(): Promise<JsSystemMetrics>
  /** Get queue depths (if provider supports management). */
  getQueueDepths(): Promise<JsQueueDepths>
  /** List all orchestration instance IDs. */
  listAllInstances(): Promise<Array<string>>
  /** List orchestration instance IDs by status. */
  listInstancesByStatus(status: string): Promise<Array<string>>
  /** Get detailed info about a specific instance. */
  getInstanceInfo(instanceId: string): Promise<JsInstanceInfo>
  /** Get detailed info about a specific execution within an instance. */
  getExecutionInfo(instanceId: string, executionId: number): Promise<JsExecutionInfo>
  /** List execution IDs for an instance. */
  listExecutions(instanceId: string): Promise<Array<number>>
  /** Read the event history for a specific execution. */
  readExecutionHistory(instanceId: string, executionId: number): Promise<Array<JsEvent>>
  /** Get the full instance tree (root + all descendants). */
  getInstanceTree(instanceId: string): Promise<JsInstanceTree>
  /** Delete an orchestration instance and all its data. */
  deleteInstance(instanceId: string, force: boolean): Promise<JsDeleteInstanceResult>
  /** Delete multiple instances matching a filter. */
  deleteInstanceBulk(filter: JsInstanceFilter): Promise<JsDeleteInstanceResult>
  /** Prune old executions from a single instance. */
  pruneExecutions(instanceId: string, options: JsPruneOptions): Promise<JsPruneResult>
  /** Prune old executions from multiple instances matching a filter. */
  pruneExecutionsBulk(filter: JsInstanceFilter, options: JsPruneOptions): Promise<JsPruneResult>
  /** Enqueue an event to a named queue on an orchestration instance. */
  enqueueEvent(instanceId: string, queueName: string, data: string): Promise<void>
  /** Wait for the custom status version to change on an orchestration instance. */
  waitForStatusChange(instanceId: string, lastSeenVersion: number, pollIntervalMs: number, timeoutMs: number): Promise<JsOrchestrationStatus>
}
/** Wraps duroxide-pg's PostgresProvider for use from JavaScript. */
export declare class JsPostgresProvider {
  /**
   * Connect to a PostgreSQL database.
   * Uses the default "public" schema.
   */
  static connect(databaseUrl: string): Promise<JsPostgresProvider>
  /**
   * Connect to a PostgreSQL database with a custom schema.
   * The schema will be created if it does not exist.
   */
  static connectWithSchema(databaseUrl: string, schema: string): Promise<JsPostgresProvider>
}
/** Wraps duroxide's SqliteProvider for use from JavaScript. */
export declare class JsSqliteProvider {
  /**
   * Open a SQLite database at the given file path.
   * Path should be a sqlite: URL, e.g. "sqlite:./data.db" or "sqlite:/tmp/test.db".
   * The file will be created if it does not exist.
   */
  static open(path: string): Promise<JsSqliteProvider>
  /** Create an in-memory SQLite database (useful for testing). */
  static inMemory(): Promise<JsSqliteProvider>
}
/** Builder for the duroxide runtime, wrapping registration and startup. */
export declare class JsRuntime {
  constructor(provider: JsSqliteProvider, options?: JsRuntimeOptions | undefined | null)
  /** Create a runtime backed by PostgreSQL. */
  static fromPostgres(provider: JsPostgresProvider, options?: JsRuntimeOptions | undefined | null): JsRuntime
  /**
   * Set the generator driver functions (called once from JS before registering orchestrations).
   * These three functions handle: creating generators, driving next steps, and disposing.
   */
  setGeneratorDriver(createFn: (arg: string) => any, nextFn: (arg: string) => any, disposeFn: (arg: string) => any): void
  /**
   * Register a JavaScript activity function.
   * The JS function receives (contextInfoJson, input) and returns a Promise<string>.
   */
  registerActivity(name: string, callback: (arg: string) => any): void
  /**
   * Register a JavaScript orchestration (generator function).
   * The orchestration name is used for both registration and the generator function lookup.
   */
  registerOrchestration(name: string): void
  /** Register a versioned JavaScript orchestration. */
  registerOrchestrationVersioned(name: string, version: string): void
  /**
   * Start the runtime. This processes orchestrations and activities until shutdown.
   *
   * # Safety
   * This is async and takes &mut self. napi-rs requires async &mut methods to be marked unsafe.
   */
  start(): Promise<void>
  /** Get a snapshot of runtime metrics. */
  metricsSnapshot(): JsMetricsSnapshot | null
  /**
   * Shutdown the runtime gracefully.
   *
   * # Safety
   * Must not be called concurrently from multiple threads.
   */
  shutdown(timeoutMs?: number | undefined | null): Promise<void>
}