Temporal Developer

// BAD - Brings actual code into workflow sandbox
import * as activities from './activities';

const { greet } = proxyActivities<typeof activities>({
  startToCloseTimeout: '1 minute',
});

// GOOD - Type-only import
import type * as activities from './activities';

const { greet } = proxyActivities<typeof activities>({
  startToCloseTimeout: '1 minute',
});

// BAD - fs is not available in workflow sandbox
import * as fs from 'fs';

export async function myWorkflow(): Promise<void> {
  const data = fs.readFileSync('file.txt'); // Will fail!
}

// GOOD - File I/O belongs in activities
export async function myWorkflow(): Promise<void> {
  const data = await activities.readFile('file.txt');
}

// OK for development/testing, BAD for production - bundles at startup
const worker = await Worker.create({
  workflowsPath: require.resolve('./workflows'),
  // ...
});

// GOOD for production - use pre-bundled code
import { bundleWorkflowCode } from '@temporalio/worker';

// Build step (run once at build time)
const bundle = await bundleWorkflowCode({
  workflowsPath: require.resolve('./workflows'),
});
await fs.promises.writeFile('./workflow-bundle.js', bundle.code);

// Worker startup (fast, no bundling)
const worker = await Worker.create({
  workflowBundle: {
    codePath: require.resolve('./workflow-bundle.js'),
  },
  // ...
});

// If using external packages in workflows, ensure they're bundled

// worker.ts
const worker = await Worker.create({
  workflowsPath: require.resolve('./workflows'),
  bundlerOptions: {
    // Exclude Node.js-only packages that cause bundling errors
    // WARNING: Modules listed here will be completely unavailable
    // at workflow runtime - any imports will fail
    ignoreModules: ['some-node-only-package'],
  },
});

// BAD: Retrying a permanent error
throw ApplicationFailure.create({ message: 'User not found' });
// This will retry indefinitely!

// GOOD: Mark permanent errors as non-retryable
throw ApplicationFailure.nonRetryable('User not found');

// BAD - Cleanup doesn't run on cancellation
export async function workflowWithCleanup(): Promise<void> {
  await activities.acquireResource();
  await activities.doWork();
  await activities.releaseResource(); // Never runs if cancelled!
}

// GOOD - Use CancellationScope for cleanup
import { CancellationScope } from '@temporalio/workflow';

export async function workflowWithCleanup(): Promise<void> {
  await activities.acquireResource();
  try {
    await activities.doWork();
  } finally {
    // Run cleanup even on cancellation
    await CancellationScope.nonCancellable(async () => {
      await activities.releaseResource();
    });
  }
}

// BAD - Activity ignores cancellation
export async function longActivity(): Promise<void> {
  await doExpensiveWork(); // Runs to completion even if cancelled
}

// GOOD - Heartbeat in background and race work against cancellation promise
import { Context, CancelledFailure } from '@temporalio/activity';

export async function longActivity(): Promise<void> {
  // Heartbeat in background so cancellation can be delivered
  let heartbeatEnabled = true;
  (async () => {
    while (heartbeatEnabled) {
      await Context.current().sleep(5000);
      Context.current().heartbeat();
    }
  })().catch(() => {});

  try {
    await Promise.race([
      Context.current().cancelled,  // Rejects with CancelledFailure
      doExpensiveWork(),
    ]);
  } catch (err) {
    if (err instanceof CancelledFailure) {
      await cleanup();
    }
    throw err;
  } finally {
    heartbeatEnabled = false;
  }
}

// GOOD - Use AbortSignal with libraries that support it
import fetch from 'node-fetch';
import { cancellationSignal, heartbeat } from '@temporalio/activity';
import type { AbortSignal as FetchAbortSignal } from 'node-fetch/externals';

export async function cancellableFetch(url: string): Promise<Uint8Array> {
  const response = await fetch(url, { signal: cancellationSignal() as FetchAbortSignal });

  const contentLength = parseInt(response.headers.get('Content-Length')!);
  let bytesRead = 0;
  const chunks: Buffer[] = [];

  for await (const chunk of response.body) {
    if (!(chunk instanceof Buffer)) throw new TypeError('Expected Buffer');
    bytesRead += chunk.length;
    chunks.push(chunk);
    heartbeat(bytesRead / contentLength);  // Heartbeat to keep cancellation delivery alive
  }
  return Buffer.concat(chunks);
}

// BAD - No heartbeat, can't detect stuck activities
export async function processLargeFile(path: string): Promise<void> {
  for await (const chunk of readChunks(path)) {
    await processChunk(chunk); // Takes hours, no heartbeat
  }
}

// GOOD - Regular heartbeats with progress
import { heartbeat } from '@temporalio/activity';

export async function processLargeFile(path: string): Promise<void> {
  let i = 0;
  for await (const chunk of readChunks(path)) {
    heartbeat(`Processing chunk ${i++}`);
    await processChunk(chunk);
  }
}

// BAD - Heartbeat timeout shorter than processing time
const { processChunk } = proxyActivities<typeof activities>({
  startToCloseTimeout: '30 minutes',
  heartbeatTimeout: '10 seconds', // Too short!
});

// GOOD - Heartbeat timeout allows for processing variance
const { processChunk } = proxyActivities<typeof activities>({
  startToCloseTimeout: '30 minutes',
  heartbeatTimeout: '2 minutes',
});

import { TestWorkflowEnvironment } from '@temporalio/testing';
import { Worker } from '@temporalio/worker';

test('handles activity failure', async () => {
  const env = await TestWorkflowEnvironment.createTimeSkipping();

  const worker = await Worker.create({
    connection: env.nativeConnection,
    taskQueue: 'test',
    workflowsPath: require.resolve('./workflows'),
    activities: {
      // Activity that always fails
      riskyOperation: async () => {
        throw ApplicationFailure.nonRetryable('Simulated failure');
      },
    },
  });

  await worker.runUntil(async () => {
    await expect(
      env.client.workflow.execute(riskyWorkflow, {
        workflowId: 'test-failure',
        taskQueue: 'test',
      })
    ).rejects.toThrow('Simulated failure');
  });

  await env.teardown();
});

import { Worker } from '@temporalio/worker';
import * as fs from 'fs';

test('replay compatibility', async () => {
  const history = JSON.parse(await fs.promises.readFile('./fixtures/workflow_history.json', 'utf8'));

  // Fails if current code is incompatible with history
  await Worker.runReplayHistory(
    {
      workflowsPath: require.resolve('./workflows'),
    },
    history,
  );
});