$ man asyncops
run your own workers, let asyncops orchestrate.
the asyncops sdk is node.js only (node 18+). workers must run in a node process. more language sdks are on the roadmap — in the meantime, apps in any language can create and inspect jobs via the rest api.
# overview
asyncops is a hosted job orchestration service. your app creates jobs via the api, and a worker process you run (anywhere — laptop, vm, kubernetes) pulls jobs, executes your handler, and reports back. asyncops stores state, retries on failure, and gives you a live dashboard of every job.
the sdk has two entry points: createWorker for the process that executes handlers, and client for creating and inspecting jobs from your application code. call asyncops.init() once at startup and both reuse the same api key.
# install sdk
the sdk is a single npm package. node.js 18+ required — no other runtimes are supported yet.
npm install asyncops-sdk
# run a worker
a worker is a long-running process. it polls asyncops for jobs whose type matches one of its registered handlers, executes the handler in-process, and reports the result. run as many workers as you like — they coordinate automatically.
const { init, createWorker } = require('asyncops-sdk');
init({ apiKey: process.env.ASYNCOPS_API_KEY });
createWorker({
handlers: {
'send-email': async (job, ctx) => {
await ctx.log(`sending to ${job.data.to}`);
// ... your logic
return { messageId: 'm_abc123' };
},
'process-data': async (job, ctx) => {
await ctx.log(`processing ${job.data.items.length} items`);
// ... your logic
return { processed: job.data.items.length };
},
},
}).start();inside a handler, job.data is whatever you passed to createJob. the return value becomes the job's result. throw an error to fail the job — asyncops will automatically retry up to 3 times with exponential backoff.
# create a job
the sdk tab below is node.js only. if your app is in another language, use the curl or http tabs — the endpoint is plain rest and works from anywhere. the job type must match a handler registered on one of your (node.js) workers.
const { init, client } = require('asyncops-sdk');
init({ apiKey: process.env.ASYNCOPS_API_KEY });
const { id } = await client.createJob({
type: 'send-email',
data: { to: 'you@example.com' },
});# inspect a job
get the full state of a job plus every log your worker emitted. works from node.js via the sdk, or from any language via rest.
const { job, logs } = await client.getJob(id);
console.log(job.status); // 'pending' | 'processing' | 'completed' | 'failed'
console.log(job.result); // return value of your handler
console.log(job.error); // error message if failed
console.log(logs); // [{ message, timestamp }, ...]# retry a job
replay any job — failed or successful. clears the previous result / error, re-queues it, and the next idle worker picks it up.
await client.retryJob(id);
# errors
every sdk method throws on non-2xx responses. the error carries err.message (human-readable, includes path + method) and err.status (http status code).