TypeScript icon, indicating that this package has built-in type declarations

    1.6.8 • Public • Published


    NPM Version NPM Downloads NPM Dependents Build Coverage NPM Downloads

    API Docs


    npm i node-beanstalk
    # or
    yarn add node-beanstalk


    node-beanstalk fully supports beanstalk protocol v1.12


    node-beanstalk is built with use of promises.
    Each client gives you full access to functionality of beanstalk queue manager, without strict separation to emitter and worker.

    import { Client, BeanstalkJobState } from 'node-beanstalk';
    const c = new Client();
    // connect to beasntalkd server
    await c.connect();
    // use our own tube
    await c.use('my-own-tube');
    // put our very important job
    const putJob = await c.put({ foo: "My awsome payload", bar: ["baz", "qux"] }, 40);
    if (putJob.state !== BeanstalkJobState.ready) {
      // as a result of put command job can done in `buried` state,
      // or `delayed` in case delay or client's default delay been specified
      throw new Error('job is not in ready state');
    // watch our tube to be able to reserve from it
    // acquire new job (ideally the one we've just put)
    const job = await c.reserveWithTimeout(10);
    /* some important job

    As beanstalk is pretty fast but still synchronous on a single connection - all consecutive calls will wait for the end of previous one. So below code will be executed consecutively, despite the fact of being asyncronous.

    import { Client, BeanstalkJobState } from 'node-beanstalk';
    const c = new Client();
    await c.connect();

    Above code will reserve 5 jobs one by one, in asyncronous way (each next promise will be resolved one by one).
    To see all the Client methods and properties see Client API docs


    To disconnect the client from remote - call client.disconnect(), it will wait for all the pending requests to be performed and then disconnect the client from server. All requests queued after disconnection will be rejected.

    To disconnect client immediately - call client.disconnect(true), it will perform disconnect right after currently running request.

    Payload serialization

    As in most cases our job payloads are complex objets - they somehow must be serialized to Buffer. In general, serialized payload can be any bytes sequence, but by default, payload is serialized via JSON and casted to buffer, but you can specify your own serializer by passing corresponding parameter to client constructor options. Required serializer interface can be found in API docs.


    For the cases of being used within webservers when waiting for all previous requests is not an option - node-beasntalk Pool exists.


    • Connecting new client requires a handshake, which takes some time (around 10-20ms), so creating new client on each incoming request would substantially slow down our application.
    • As already being said - each connection can handle only one request at a time. So in case you application use a single client - all your simultaneous requests will be pipelined into serial execution queue, one after another, that is really no good (despite of node-beanstalk queue being very fast and low-cost).

    Client pool allows you to have a pool af reusable clients you can check out, use, and return back to the pool.

    Checkout, use, and return

    import { Pool } from 'node-beanstalk';
    const p = new Pool({ capacity: 5 });
    // acquire our very own client
    const client = await p.connect();
    try {
      // do some work
      await client.statsTube('my-own-tube')
    } finally {
      // return client back to the pool

    You must always release client back to the pool, otherwise, at some point, your pool will be empty forever, and your subsequent requests will wait forever.


    To disconnect all clients in the pool you have to call pool.disconnect().
    This will wait for all pending client reserves and returns to be done. After disconnect executed all returned clients will be disconnected and not returned to the idle queue. All reserves queued after disconnection will be rejected.

    Force disconnect pool.disconnect(true) will not wait for pending reserve and start disconnection immediately (it will still be waiting clients return to the pool) by calling force disconnect on each client.


    node-beanstalk is built to be as much tests-covered as it is possible, but not to go nuts with LOC coverage. It is important to have comprehensive unit-testing to make sure that everything is working fine, and it is my goal for this package.

    It is pretty hard to make real tests for the sockets witch is used in this package, so Connection class is still at 80% covered with tests, maybe I'll finish it later.


    npm i node-beanstalk

    DownloadsWeekly Downloads






    Unpacked Size

    202 kB

    Total Files


    Last publish


    • xobotyi