AWS.Batch reference

CancelJob

Source: src/AWS/Batch/CancelJob.ts

Cancel a queued AWS Batch job from runtime code. Jobs in SUBMITTED, PENDING, or RUNNABLE state are cancelled; jobs that already progressed to STARTING/RUNNING are NOT cancelled (use TerminateJob for those) — the request still succeeds.

CancelJob: Cancelling Jobs

const cancelJob = yield* Batch.CancelJob(queue);
yield* cancelJob({ jobId, reason: "superseded" });

ComputeEnvironment

Source: src/AWS/Batch/ComputeEnvironment.ts

An AWS Batch managed compute environment backed by Fargate (or Fargate Spot) capacity. Fargate compute environments provision in seconds and require no instance management.

ComputeEnvironment: Creating Compute Environments

Default Fargate Compute Environment

// Uses the default VPC's subnets and default security group.
const ce = yield* Batch.ComputeEnvironment("JobsCE", {});

Unmanaged Compute Environment

const ce = yield* Batch.ComputeEnvironment("ExternalCapacity", {
  managementType: "UNMANAGED",
  unmanagedvCpus: 8,
});

Fargate Spot with explicit networking

const ce = yield* Batch.ComputeEnvironment("SpotCE", {
  type: "FARGATE_SPOT",
  maxvCpus: 16,
  subnets: [subnetA.subnetId, subnetB.subnetId],
  securityGroupIds: [sg.groupId],
});

ComputeEnvironment: Composing the Batch chain

const ce = yield* Batch.ComputeEnvironment("JobsCE", {});
const queue = yield* Batch.JobQueue("JobsQueue", {
  computeEnvironments: [ce.computeEnvironmentArn],
});

DescribeJobs

Source: src/AWS/Batch/DescribeJobs.ts

Describe submitted AWS Batch jobs (status polling from runtime code). batch:DescribeJobs has no resource-level IAM, so the policy is service-scoped; the queue anchors the binding’s identity.

DescribeJobs: Describing Jobs

const describeJobs = yield* Batch.DescribeJobs(queue);
const { jobs } = yield* describeJobs({ jobs: [jobId] });
const status = jobs?.[0]?.status;

GetJobQueueSnapshot

Source: src/AWS/Batch/GetJobQueueSnapshot.ts

Snapshot the head of the bound AWS Batch job queue (the next ~100 RUNNABLE jobs the scheduler will run, in dispatch order) — queue introspection for dashboards and backpressure decisions from runtime code.

GetJobQueueSnapshot: Inspecting the Queue

const getJobQueueSnapshot = yield* Batch.GetJobQueueSnapshot(queue);
const { frontOfQueue } = yield* getJobQueueSnapshot();
const next = frontOfQueue?.jobs?.[0]?.jobArn;

JobDefinition

Source: src/AWS/Batch/JobDefinition.ts

An AWS Batch job definition for Fargate container jobs. Job definitions are immutable revisions — changing the container configuration registers a new revision under the same name (like ECS task definitions); destroying the resource deregisters every active revision.

JobDefinition is a Platform: alongside the low-level container form (image + executionRoleArn), it supports Effect-native run-to-completion implementations — an inline Effect program that Alchemy bundles, containerizes as the job container’s command, pushes to a managed ECR repository, and registers, provisioning the job and execution roles automatically. Capability bindings (e.g. S3 GetObject) attach IAM policy statements to the managed job role and inject their environment variables into the container.

JobDefinition: Creating Job Definitions

Busybox echo job (low-level container form)

const jobDef = yield* Batch.JobDefinition("EchoJob", {
  image: "public.ecr.aws/docker/library/busybox:latest",
  command: ["echo", "hello from batch"],
  executionRoleArn: executionRole.roleArn,
});

Sized job with environment

const jobDef = yield* Batch.JobDefinition("EtlJob", {
  image: image.imageUri,
  vcpus: 1,
  memory: 2048,
  environment: { STAGE: "prod" },
  jobRoleArn: jobRole.roleArn,
  executionRoleArn: executionRole.roleArn,
  retryAttempts: 3,
  timeout: "15 minutes",
});

JobDefinition: Effect-Native Jobs

Tagged class with an inline run-to-completion Effect

export default class Nightly extends Batch.JobDefinition<Nightly>()(
  "Nightly",
  { main: import.meta.url, vcpus: 1, memory: 2048 },
  Effect.gen(function* () {
    const getObject = yield* AWS.S3.GetObject(bucket);
    return {
      run: Effect.gen(function* () {
        const data = yield* getObject({ key: "input.csv" });
        yield* Effect.log("processed nightly batch");
      }),
    };
  }),
) {}

Eager inline job

export default Batch.JobDefinition(
  "Reindex",
  { main: import.meta.url },
  Effect.succeed({
    run: Effect.log("reindex complete"),
  }),
);

Plain external script (bundled as-is)

// ./job.ts runs top-level and exits; Alchemy bundles + containerizes it.
const jobDef = yield* Batch.JobDefinition("Script", {
  main: path.join(import.meta.dirname, "job.ts"),
});

JobDefinition: Bundling & Tree-shaking

main is bundled with rolldown at deploy time. Unused code is tree-shaken. effect, alchemy, and @distilled.cloud are marked pure so unused parts prune more aggressively. Your app is not marked pure.

Mark additional packages as pure

Only list packages with no top-level side effects.

{
  main: import.meta.url,
  build: {
    pure: { packages: ["my-lib", "@my-scope/*"] },
  },
}

Turn it off

{
  main: import.meta.url,
  build: { pure: false },
}

JobQueue

Source: src/AWS/Batch/JobQueue.ts

An AWS Batch job queue. Jobs submitted to the queue are scheduled onto its associated compute environments in preference order.

JobQueue: Creating Job Queues

Queue on a Fargate Compute Environment

const ce = yield* Batch.ComputeEnvironment("JobsCE", {});
const queue = yield* Batch.JobQueue("JobsQueue", {
  computeEnvironments: [ce.computeEnvironmentArn],
});

Prioritized queue

const critical = yield* Batch.JobQueue("CriticalQueue", {
  priority: 10,
  computeEnvironments: [ce.computeEnvironmentArn],
});

ListJobs

Source: src/AWS/Batch/ListJobs.ts

List AWS Batch jobs in the bound job queue from runtime code. batch:ListJobs has no resource-level IAM, so the policy is service-scoped; the queue anchors the binding and is injected as the jobQueue selector.

ListJobs: Listing Jobs

const listJobs = yield* Batch.ListJobs(queue);
const { jobSummaryList } = yield* listJobs({ jobStatus: "RUNNABLE" });

SubmitJob

Source: src/AWS/Batch/SubmitJob.ts

Submit a job to an AWS Batch job queue against a bound job definition — fire-and-forget heavy work from a Lambda or Task.

SubmitJob: Submitting Jobs

const submitJob = yield* Batch.SubmitJob(queue, jobDef);
const { jobId } = yield* submitJob({
  jobName: "nightly-export",
  containerOverrides: { command: ["echo", "hello"] },
});

TerminateJob

Source: src/AWS/Batch/TerminateJob.ts

Terminate a running (or cancel a queued) AWS Batch job from runtime code.

TerminateJob: Terminating Jobs

const terminateJob = yield* Batch.TerminateJob(queue);
yield* terminateJob({ jobId, reason: "superseded" });