airtable-plus v1.0.4

airtable-plus

Airtable Node library designed for async/await with useful helper methods

Install

npm i airtable-plus

Tests

This package's testing suite utilizes:

• Mocha
• Chai
• Leasot
• Istanbul

# Run Mocha tests
npm run test

Usage

const AirtablePlus = require('airtable-plus');

// baseID, apiKey, and tableName can alternatively be set by environment variables
const airtable = new AirtablePlus({
    baseID: 'xxx',
    apiKey: 'xxx',
    tableName: 'Table 1',
});

(async () => {
    try {
        // allows for api params to be passed in from Airtable api
        const readRes = await airtable.read({
            filterByFormula: 'Name = "Foo"',
            maxRecords: 1
        });

        // functions can take optional override configuration object
        const cfg = { tableName: 'Read' };
        const updateRes = await airtable.update('1234', {
            Name: 'foobar'
        }, cfg);

        const updateWhereRes = await airtable.updateWhere('Name = "Foo"', {
            filterByFormula: 'Name = "foobar"'
        });

        const deleteRes = await airtable.delete('1234');

        const truncRes = await airtable.truncate();
    }
    catch(e) {
        console.error(e);
    }
})();

API

AirtablePlus

Creates an Airtable api object. Additional parameters can be set to the global configuration object each method uses on subsequent calls. The instance will default to environment variables for apiKey, baseID, and tableName if not passed into configuration object.

Kind: global class

• AirtablePlus
  • new AirtablePlus(config)
  • .create(data, [config]) ⇒ Promise
  • .read([params], [config]) ⇒ Promise
  • .find(rowID, [config]) ⇒ Promise
  • .update(rowID, data, [config]) ⇒ Promise
  • .updateWhere(where, data, [config]) ⇒ Promise
  • .replace(rowID, data, [config]) ⇒ Promise
  • .replaceWhere(where, data, [config]) ⇒ Promise
  • .delete(rowID, data, [config]) ⇒ Promise
  • .deleteWhere(where, data, [config]) ⇒ Promise
  • .truncate(config) ⇒ Promise
  • .appendTable(source, dest) ⇒ Promise
  • .overwriteTable(source, dest) ⇒ Promise
  • .upsert(key, data, [config]) ⇒ Promise

new AirtablePlus(config)

Example

//common usage
const inst = new AirtablePlus({
 baseID: 'xxx',
 tableName: 'Table 1'
});

// instantiating with all optional parameters set to their defaults
const inst = new AirtablePlus({
 apiKey: process.env.AIRTABLE_API_KEY,
 baseID: process.env.AIRTABLE_BASE_ID,
 tableName: process.env.AIRTABLE_TABLE_NAME,
 camelCase: false,
 complex: false,
 transform: undefined // optional function to modify records on read
});

airtablePlus.create(data, config) ⇒ Promise

Creates a new row using the supplied data object as row values. The object must contain valid keys that correspond to the name and data type of the Airtable table schema being written into, else it will throw an error.

Kind: instance method of AirtablePlus
Returns: Promise - Created Record Object

Example

const res = await inst.create({ firstName: 'foo' });

airtablePlus.read(params, config) ⇒ Promise

Read all data from a table. Can be passed api options for filtering and sorting (see Airtable API docs). An optional transform function can be passed in to manipulate the rows as they are being read in.

Kind: instance method of AirtablePlus
Returns: Promise - Array of record objects

Example

// standard usage
const res = await inst.read();

// takes airtable api options
const res = await inst.read({ maxRecords: 1 });

airtablePlus.find(rowID, config) ⇒ Promise

Get data for a specific row on Airtable

Kind: instance method of AirtablePlus
Returns: Promise - Record object

Example

const res = await inst.find('1234');

airtablePlus.update(rowID, data, config) ⇒ Promise

Updates a row in Airtable. Unlike the replace method anything not passed into the update data object still will be retained. You must send in an object with the keys in the same casing as the Airtable table columns (even when using camelCase=true in config)

Kind: instance method of AirtablePlus
Returns: Promise - Array of record objects

Example

const res = await inst.update('1234', { firstName: 'foobar' });

airtablePlus.updateWhere(where, data, config) ⇒ Promise

Performs a bulk update based on a search criteria. The criteria must be formatted in the valid Airtable formula syntax (see Airtable API docs)

Kind: instance method of AirtablePlus
Returns: Promise - Array of record objects

Example

const res = await inst.updateWhere('firstName = "foo"', { firstName: 'fooBar' });

airtablePlus.replace(rowID, data, config) ⇒ Promise

Replaces a given row in airtable. Similar to the update function, the only difference is this will completely overwrite the row. Any cells not passed in will be deleted from source row.

Kind: instance method of AirtablePlus
Returns: Promise - Record object

Example

const res = await inst.replace('1234', { firstName: 'foobar' });

airtablePlus.replaceWhere(where, data, config) ⇒ Promise

Performs a bulk replace based on a given search criteria. The criteria must be formatted in the valid Airtable formula syntax (see Airtable API docs)

Kind: instance method of AirtablePlus
Returns: Promise - Array of record objects

Example

const res = await inst.replaceWhere('firstName = "foo"', { firstName: 'fooBar' });

airtablePlus.delete(rowID, data, config) ⇒ Promise

Deletes a row in the provided table

Kind: instance method of AirtablePlus
Returns: Promise - Record object

Example

const res = await inst.delete('1234');

airtablePlus.deleteWhere(where, data, config) ⇒ Promise

Performs a bulk delete based on a search criteria. The criteria must be formatted in the valid Airtable formula syntax (see Airtable API docs)

Kind: instance method of AirtablePlus
Returns: Promise - Array of record objects

Example

const res = await inst.deleteWhere('firstName = "foo"');

airtablePlus.truncate(config) ⇒ Promise

Truncates a table specified in the configuration object

Kind: instance method of AirtablePlus
Returns: Promise - Array of record objects

Example

const res = await inst.truncate();

airtablePlus.appendTable(source, dest) ⇒ Promise

Reads all the values from one table and appends to another table. Allows for selective appending by sending optional fields and filters.

Kind: instance method of AirtablePlus
Returns: Promise - Array of record objects

Example

// complex usage in the same base
const res = await inst.appendTable('Read', 'Write');

// allows for configuration of both source and dest
const res = await inst.appendTable({ tableName: 'Read', baseID: 'xxx' },  { tableName: 'Write' })

airtablePlus.overwriteTable(source, dest) ⇒ Promise

Copies/Overwrites one table into another. The source table will have all rows deleted prior to having the source rows inserted.

Kind: instance method of AirtablePlus
Returns: Promise - Array of record objects

Example

// complex usage in the same base
const res = await inst.overwriteTable('Read', 'Write');

// allows for configuration of both source and dest
const res = await inst.overwriteTable({ tableName: 'Read', baseID: 'xxx' },  { tableName: 'Write' })

airtablePlus.upsert(key, data, config) ⇒ Promise

Attempts to upsert based on passed in primary key. Inserts if a new entry or updates if entry is already found

Kind: instance method of AirtablePlus
Returns: Promise - Array of record objects

Example

const res = await inst.upsert('primarKeyID', data);

MIT © Victor Hahn