IBM Cloudant Node.js SDK Version 0.6.0

• Overview
• Features
• Prerequisites
• Installation
• Using the SDK
  • Authentication
    • Authentication with environment variables
      • IAM API key authentication
      • IAM Trusted profile (container) authentication
      • IAM Trusted profile (VPC) authentication
      • Session cookie authentication
    • Authentication with external configuration
    • Programmatic authentication
  • Request timeout configuration
  • Code examples
    • 1. Create a database and add a document
    • 2. Retrieve information from an existing database
    • 3. Update your previously created document
    • 4. Delete your previously created document
    • Further code examples
  • Error handling
  • Raw IO
  • Further resources
  • Changes feed follower (beta)
    • Introduction
    • Modes of operation
    • Configuring the changes follower
    • Error suppression
    • Follower operation
    • Checkpointing
    • Code examples
      • Initializing a changes follower
      • Starting the changes follower
        • Start mode for continuous listening
        • Start mode for one-off fetching
      • Processing changes
        • Process continuous changes
        • Process one-off changes
      • Stopping the changes follower
• Questions
• Issues
• Open source at IBM
• Contributing
• License

import { CloudantV1 } from "@ibm-cloud/cloudant";
Copy

interface OrderDocument extends CloudantV1.Document {
  name?: string;
  joined?: string;
  _id: string;
  _rev?: string;
}

// 1. Create a client with `CLOUDANT` default service name ======================
const client = CloudantV1.newInstance({});

// 2. Create a database =========================================================
const exampleDbName = 'orders';

// Try to create database if it doesn't exist
const createDb = client
  .putDatabase({ db: exampleDbName })
  .then((putDatabaseResult) => {
    if (putDatabaseResult.result.ok) {
      console.log(`"${exampleDbName}" database created."`);
    }
  })
  .catch((err) => {
    if (err.code === 412) {
      console.log(
        `Cannot create "${exampleDbName}" database, it already exists.`
      );
    }
  });

// 3. Create a document =========================================================
// Create a document object with "example" id
const exampleDocId = 'example';

// Setting `_id` for the document is optional when postDocument function is used for CREATE.
// When `_id` is not provided the server will generate one for your document.
const exampleDocument: OrderDocument = { _id: exampleDocId };

// Add "name" and "joined" fields to the document
exampleDocument.name = 'Bob Smith';
exampleDocument.joined = '2019-01-24T10:42:59.000Z';

// Save the document in the database with "postDocument" function
createDb.then(() => {
  client
    .postDocument({
      db: exampleDbName,
      document: exampleDocument,
    })
    // ==========================================================================
    // Note: saving the document can also be done with the "putDocument"
    // function. In this case `docId` is required for a CREATE operation:
    /*
    .putDocument({
      db: exampleDbName,
      docId: exampleDocId,
      document: exampleDocument,
    })
    */
    // ==========================================================================
    .then((createDocumentResponse) => {
      // Keeping track of the revision number of the document object
      // is necessary for further UPDATE/DELETE operations:
      exampleDocument._rev = createDocumentResponse.result.rev;
      console.log(
        'You have created the document:\n' +
          JSON.stringify(exampleDocument, null, 2)
      );
    });
});
Copy

const { CloudantV1 } = require('@ibm-cloud/cloudant');
Copy

embedmd:# (test/examples/src/js/CreateDbAndDoc.js /const createDbAndDoc/ /createDbAndDoc();\n}/)

const createDbAndDoc = async () => {
  // 1. Create a client with `CLOUDANT` default service name ====================
  const client = CloudantV1.newInstance({});

  // 2. Create a database =======================================================
  const exampleDbName = 'orders';

  // Try to create database if it doesn't exist
  try {
    const putDatabaseResult = (
      await client.putDatabase({
        db: exampleDbName,
      })
    ).result;
    if (putDatabaseResult.ok) {
      console.log(`"${exampleDbName}" database created.`);
    }
  } catch (err) {
    if (err.code === 412) {
      console.log(
        `Cannot create "${exampleDbName}" database, it already exists.`
      );
    }
  }

  // 3. Create a document =======================================================
  // Create a document object with "example" id
  const exampleDocId = 'example';

  // Setting `_id` for the document is optional when "postDocument" function is used for CREATE.
  // When `_id` is not provided the server will generate one for your document.
  const exampleDocument = { _id: exampleDocId };

  // Add "name" and "joined" fields to the document
  exampleDocument['name'] = 'Bob Smith';
  exampleDocument.joined = '2019-01-24T10:42:59.000Z';

  // Save the document in the database with "postDocument" function
  const createDocumentResponse = await client.postDocument({
    db: exampleDbName,
    document: exampleDocument,
  });

  // ==========================================================================
  // Note: saving the document can also be done with the "putDocument"
  // function. In this case `docId` is required for a CREATE operation:
  /* const createDocumentResponse = await client.putDocument({
       db: exampleDbName,
       docId: exampleDocId,
       document: exampleDocument,
  }); */
  // ==========================================================================

  // Keeping track of the revision number of the document object
  // is necessary for further UPDATE/DELETE operations:
  exampleDocument._rev = createDocumentResponse.result.rev;
  console.log(
    'You have created the document:\n' +
      JSON.stringify(exampleDocument, null, 2)
  );
};

if (require.main === module) {
  createDbAndDoc();
}
Copy

import { ChangesFollower, CloudantV1 } from '@ibm-cloud/cloudant';
import { PostChangesParams } from '@ibm-cloud/cloudant/cloudant/v1';
Copy

const client = CloudantV1.newInstance({});
const changesParams: PostChangesParams = {
  db: 'example', // Required: the database name.
  limit: 100, // Optional: return only 100 changes (including duplicates).
  since: '3-g1AG3...' // Optional: start from this sequence ID (e.g. with a value read from persistent storage).
};
const errorTolerance: number = 10000; // 10 second duration to suppress transient errors
const changesFollower: ChangesFollower = new ChangesFollower(
  client, // Required: the Cloudant service client instance.
  changesParams, // Required: changes feed configuration options dict.
  10000 // Optional: suppress transient errors for at least 10 seconds before terminating.
);
Copy

const { ChangesFollower, CloudantV1 } = require('@ibm-cloud/cloudant');
Copy

const client = CloudantV1.newInstance();
const changesParams = {
  db: 'example', // Required: the database name.
  limit: 100, // Optional: return only 100 changes (including duplicates).
  since: '3-g1AG3...' // Optional: start from this sequence ID (e.g. with a value read from persistent storage).
};
const changesFollower = new ChangesFollower(
  client, // Required: the Cloudant service client instance.
  changesParams, // Required: changes feed configuration options dict.
  10000 // Optional: suppress transient errors for at least 10 seconds before terminating.
);
Copy

import { ChangesFollower, CloudantV1, Stream } from '@ibm-cloud/cloudant';
import { ChangesResultItem, PostChangesParams } from '@ibm-cloud/cloudant/cloudant/v1';
Copy

const client = CloudantV1.newInstance({});
const changesParams: PostChangesParams = {
  db: 'example'
};
const changesFollower: ChangesFollower = new ChangesFollower(client, changesParams);
const changesItemsStream: Stream<ChangesResultItem> = changesFollower.start();
// Create for-async-loop or pipeline to begin the flow of changes
// e.g. pipeline(changesItemsStream, destinationStream).then(() => { ... }).catch((err) => { ... });
Copy

const { ChangesFollower, CloudantV1 } = require('@ibm-cloud/cloudant');
Copy

const client = CloudantV1.newInstance();
const changesParams = {
  db: 'example'
};
const changesFollower = new ChangesFollower(client, changesParams);
const changesItemsStream = changesFollower.start();
// Create for-async-loop or pipeline to begin the flow of changes
// e.g. pipeline(changesItemsStream, destinationStream).then(() => { ... }).catch((err) => { ... });
Copy

import { ChangesFollower, CloudantV1, Stream } from '@ibm-cloud/cloudant';
import { ChangesResultItem, PostChangesParams } from '@ibm-cloud/cloudant/cloudant/v1';
Copy

const client = CloudantV1.newInstance({});
const changesParams: PostChangesParams = {
  db: 'example'
};
const changesFollower: ChangesFollower = new ChangesFollower(client, changesParams);
const changesItemsStream: Stream<ChangesResultItem> = changesFollower.startOneOff();
// Create for-async-loop or pipeline to begin the flow of changes
// e.g. pipeline(changesItemsStream, destinationStream).then(() => { ... }).catch((err) => { ... });
Copy

const { ChangesFollower, CloudantV1 } = require('@ibm-cloud/cloudant');
Copy

const client = CloudantV1.newInstance();
const changesParams = {
  db: 'example'
};
const changesFollower = new ChangesFollower(client, changesParams);
const changesItemsStream = changesFollower.startOneOff();
// Create for-async-loop or pipeline to begin the flow of changes
// e.g. pipeline(changesItemsStream, destinationStream).then(() => { ... }).catch((err) => { ... });
Copy

import { ChangesFollower, CloudantV1, Stream } from '@ibm-cloud/cloudant';
import { ChangesResultItem, PostChangesParams } from '@ibm-cloud/cloudant/cloudant/v1';
import { Writable } from 'node:stream';
import { pipeline } from 'node:stream/promises'
Copy

const client = CloudantV1.newInstance({});
// Start from a previously persisted seq
// Normally this would be read by the app from persistent storage
// e.g. previouslyPersistedSeq = yourAppPersistenceReadFunc()
const previouslyPersistedSeq = '3-g1AG3...'
const changesParams: PostChangesParams = {
  db: 'example',
  since: previouslyPersistedSeq
};
const changesFollower = new ChangesFollower(client, changesParams);
const changesItemsStream: Stream<ChangesResultItem> = changesFollower.start();

const destinationStream = new Writable({
  objectMode: true,
  write(changesItem: CloudantV1.ChangesResultItem, _, callback) {
    // do something with change item
    console.log(changesItem.id);
    for (const change of changesItem.changes) {
      console.log(change.rev)
    }
    // when change item processing is complete app can store seq
    const seq = changesItem.seq
    // write seq to persistent storage for use as since if required to resume later
    // e.g. yourAppPersistenceWriteFunc()
    callback();
  }
});

// A pipeline to keep processing changes until the follower is stopped or some other stop condition is reached
pipeline(changesItemsStream, destinationStream)
  .then(() => {
    console.log('Stopped');  
  })
  .catch((err) => {
    console.log(err);
  });
Copy

const { ChangesFollower, CloudantV1 } = require('@ibm-cloud/cloudant');
const { Writable } = require('node:stream');
const { pipeline } = require('node:stream/promises');
Copy

const client = CloudantV1.newInstance();
// Start from a previously persisted seq
// Normally this would be read by the app from persistent storage
// e.g. previouslyPersistedSeq = yourAppPersistenceReadFunc()
const previouslyPersistedSeq = '3-g1AG3...'
const changesParams = {
  db: 'example',
  since: previouslyPersistedSeq
};
const changesFollower = new ChangesFollower(client, changesParams);
const changesItemsStream = changesFollower.start();

const destinationStream = new Writable({
  objectMode: true,
  write(changesItem, _, callback) {
    // do something with change item
    console.log(changesItem.id);
    for (const change of changesItem.changes) {
      console.log(change.rev)
    }
    // when change item processing is complete app can store seq
    const seq = changesItem.seq
    // write seq to persistent storage for use as since if required to resume later
    // e.g. yourAppPersistenceWriteFunc()
    callback();
  }
});

// A pipeline to keep processing changes until the follower is stopped or some other stop condition is reached
pipeline(changesItemsStream, destinationStream)
  .then(() => {
    console.log('Stopped');  
  })
  .catch((err) => {
    console.log(err);
  });
Copy

import { ChangesFollower, CloudantV1, Stream } from '@ibm-cloud/cloudant';
import { ChangesResultItem, PostChangesParams } from '@ibm-cloud/cloudant/cloudant/v1';
import { Writable } from 'node:stream';
import { pipeline } from 'node:stream/promises'
Copy

const client = CloudantV1.newInstance({});
// Start from a previously persisted seq
// Normally this would be read by the app from persistent storage
// e.g. previouslyPersistedSeq = yourAppPersistenceReadFunc()
const previouslyPersistedSeq = '3-g1AG3...'
const changesParams: PostChangesParams = {
  db: 'example',
  since: previouslyPersistedSeq
};
const changesFollower: ChangesFollower = new ChangesFollower(client, changesParams);
const changesItemsStream: Stream<ChangesResultItem> = changesFollower.startOneOff();

const destinationStream = new Writable({
  objectMode: true,
  write(changesItem: CloudantV1.ChangesResultItem, _, callback) {
    // do something with change item
    console.log(changesItem.id);
    for (const change of changesItem.changes) {
      console.log(change.rev)
    }
    // when change item processing is complete app can store seq
    const seq = changesItem.seq
    // write seq to persistent storage for use as since if required to resume later
    // e.g. yourAppPersistenceWriteFunc()
    callback();
  }
});

pipeline(changesItemsStream, destinationStream)
  .then(() => {
    console.log('All changes done');
  })
  .catch((err) => {
    console.log(err);
  });

// use for-async-loop feature for stream
/*
getChangesFromFollower(changesItemsStream);
async function getChangesFromFollower(changesItemsStream: Stream<CloudantV1.ChangesResultItem>) {
  for await (const changesItem of changesItemsStream) {
    // do something with change item
    // write seq to persistent storage for use as since
    console.log(changesItem.id);
    for (const change of changesItem.changes) {
      console.log(change.rev)
    }
    // when change item processing is complete app can store seq
    seq = changesItem.seq
    // write seq to persistent storage for use as since if required to resume later
    // e.g. yourAppPersistenceWriteFunc()
  }
}
*/
Copy

const { ChangesFollower, CloudantV1 } = require('@ibm-cloud/cloudant');
const { Writable } = require('node:stream');
const { pipeline } = require('node:stream/promises');
Copy

const client = CloudantV1.newInstance();
// Start from a previously persisted seq
// Normally this would be read by the app from persistent storage
// e.g. previouslyPersistedSeq = yourAppPersistenceReadFunc()
const previouslyPersistedSeq = '3-g1AG3...'
const changesParams = {
  db: 'example',
  since: previouslyPersistedSeq
};
const changesFollower = new ChangesFollower(client, changesParams);
const changesItemsStream = changesFollower.startOneOff();

const destinationStream = new Writable({
  objectMode: true,
  write(changesItem, _, callback) {
    // do something with change item
    console.log(changesItem.id);
    for (const change of changesItem.changes) {
      console.log(change.rev)
    }
    // when change item processing is complete app can store seq
    const seq = changesItem.seq
    // write seq to persistent storage for use as since if required to resume later
    // e.g. yourAppPersistenceWriteFunc()
    callback();
  }
});

pipeline(changesItemsStream, destinationStream)
  .then(() => {
    console.log('All changes done');
  })
  .catch((err) => {
    console.log(err);
  });

// use for-async-loop feature for stream
/*
getChangesFromFollower(changesItemsStream);
async function getChangesFromFollower(changesItemsStream) {
  for await (const changesItem of changesItemsStream) {
    // do something with change item
    // write seq to persistent storage for use as since
    console.log(changesItem.id);
    for (const change of changesItem.changes) {
      console.log(change.rev)
    }
    // when change item processing is complete app can store seq
    seq = changesItem.seq
    // write seq to persistent storage for use as since if required to resume later
    // e.g. yourAppPersistenceWriteFunc()
  }
}
*/
Copy

import { ChangesFollower, CloudantV1, Stream } from '@ibm-cloud/cloudant';
import { ChangesResultItem, PostChangesParams } from '@ibm-cloud/cloudant/cloudant/v1';
import { Writable } from 'node:stream';
import { pipeline } from 'node:stream/promises'
Copy

const client = CloudantV1.newInstance({});
const changesParams: PostChangesParams = {
  db: 'example'
};
const changesFollower: ChangesFollower = new ChangesFollower(client, changesParams);
const changesItemsStream: Stream<ChangesResultItem> = changesFollower.start();

const destinationStream = new Writable({
  objectMode: true,
  write(changesItem: CloudantV1.ChangesResultItem, _, callback) {
    // Option 1: call stop after some condition
    // Note that at least one item
    // must be returned to reach to this point.
    // Additional changes may be processed before the iterator stops.
    changesFollower.stop();
    callback();
  }
});

pipeline(changesItemsStream, destinationStream)
  .then(() => {
    console.log('Stopped');  
  })
  .catch((err) => {
    console.log(err);
  });

// Option 2: call stop method when you want to end the continuous loop from
// outside the pipeline.
// Normally the call would be made from some other application function
// executing later.
// For example, stop the changesFollower after 1 minute of listening for changes
setTimeout(() => {
  changesFollower.stop();
}, 60000);
Copy

const { ChangesFollower, CloudantV1 } = require('@ibm-cloud/cloudant');
const { Writable } = require('node:stream');
const { pipeline } = require('node:stream/promises');
Copy

const client = CloudantV1.newInstance();
const changesParams = {
  db: 'example'
};
const changesFollower = new ChangesFollower(client, changesParams);
const changesItemsStream = changesFollower.start();

const destinationStream = new Writable({
  objectMode: true,
  write(changesItem, _, callback) {
    // Option 1: call stop after some condition
    // Note that at least one item
    // must be returned to reach to this point.
    // Additional changes may be processed before the iterator stops.
    changesFollower.stop();
    callback();
  }
});

pipeline(changesItemsStream, destinationStream)
  .then(() =>{
    console.log('Stopped');  
  })
  .catch((err) => {
    console.log(err);
  });

// Option 2: call stop method when you want to end the continuous loop from
// outside the pipeline.
// Normally the call would be made from some other application function
// executing later.
// For example, stop the changesFollower after 1 minute of listening for changes
setTimeout(() => {
  changesFollower.stop();
}, 60000);
Copy