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)

Param	Type	Description
config	Object	Configuration object
[config.apiKey]	string	Airtable API key
[config.baseID]	string	Airtable base ID
[config.tableName]	string	Airtable table name
[config.camelCase]	string	Converts column name object keys to camel case in JSON response
[config.concurrency]	string	Sets concurrency for async iteration functions
[config.complex]	boolean	Flag to return full Airtable record object with helper methods attached
[config.transform]	function	Optional global transform function for reads
[config.typecast]	boolean	Sets typecast on create and update operations for automatic data conversion

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

Param	Type	Description
data	Object	Create data object
[config]	Object	Optional configuration override
[config.tableName]	string	Airtable table name
[config.baseID]	string	Airtable base id
[config.complex]	boolean	Flag to return full Airtable record object with helper methods attached

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

Param	Type	Description
[params]	Object | string	If string: sets Airtable table name, If object: Airtable api parameters
[params.filterByFormula]	string	Airtable API parameter filterByFormula
[params.maxRecords]	number	Airtable API parameter maxRecords
[params.pageSize]	number	Airtable API parameter pageSize
[params.sort]	[ 'Array' ].<Object>	Airtable API parameter sort [{field: 'name, direction: 'asc'}]
[params.view]	string	Airtable API parameter view to set view ID
[params.cellFormat]	string	Airtable API parameter cellFormat
[params.timeZone]	string	Airtable API parameter timeZone
[params.userLocale]	string	Airtable API parameter userLocale
[config]	Object	Optional configuration override
[config.tableName]	string	Airtable table name
[config.camelCase]	string	Converts column name object keys to camel case in JSON response
[config.complex]	boolean	Flag to return full Airtable record object with helper methods attached
[config.transform]	function	Optional global transform function for reads
[config.base]	function	Airtable sdk base instance

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

Param	Type	Description
rowID	string	Airtable Row ID to query data from
[config]	Object	Optional config override
[config.tableName]	string	Airtable table name
[config.complex]	boolean	Flag to return full Airtable record object with helper methods attached
[config.base]	function	Airtable sdk base instance

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

Param	Type	Description
rowID	string	Airtable Row ID to update
data	Object	row data with keys that you'd like to update
[config]	Object	Optional config override
[config.tableName]	string	Airtable table name
[config.complex]	boolean	Flag to return full Airtable record object with helper methods attached
[config.base]	function	Airtable sdk base instance

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

Param	Type	Description
where	string	filterByFormula string to filter table data by
data	Object	Data to update if where condition is met
[config]	Object	Optional configuration override
[config.baseID]	string	Airtable base ID
[config.tableName]	string	Airtable table name
[config.camelCase]	string	Converts column name object keys to camel case in JSON response
[config.concurrency]	string	Sets concurrency for async iteration functions
[config.complex]	boolean	Flag to return full Airtable record object with helper methods attached
[config.transform]	function	Optional global transform function for reads

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

Param	Type	Description
rowID	string	Airtable Row ID to replace
data	Object	row data with keys that you'd like to replace
[config]	Object	Optional config override
[config.tableName]	string	Airtable table name
[config.complex]	boolean	Flag to return full Airtable record object with helper methods attached
[config.base]	function	Airtable sdk base instance

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

Param	Type	Description
where	string	filterByFormula string to filter table data by
data	Object	Data to replace if where condition is met
[config]	Object	Optional configuration override
[config.baseID]	string	Airtable base ID
[config.tableName]	string	Airtable table name
[config.camelCase]	string	Converts column name object keys to camel case in JSON response
[config.concurrency]	string	Sets concurrency for async iteration functions
[config.complex]	boolean	Flag to return full Airtable record object with helper methods attached
[config.transform]	function	Optional global transform function for reads

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

Param	Type	Description
rowID	string	Airtable Row ID to delete
data	Object	row data with keys that you'd like to delete
[config]	Object	Optional config override
[config.tableName]	string	Airtable table name
[config.complex]	boolean	Flag to return full Airtable record object with helper methods attached
[config.base]	function	Airtable sdk base instance

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

Param	Type	Description
where	string	filterByFormula string to filter table data by
data	Object	Data to delete if where condition is met
[config]	Object	Optional configuration override
[config.baseID]	string	Airtable base ID
[config.tableName]	string	Airtable table name
[config.camelCase]	string	Converts column name object keys to camel case in JSON response
[config.concurrency]	string	Sets concurrency for async iteration functions
[config.complex]	boolean	Flag to return full Airtable record object with helper methods attached
[config.transform]	function	Optional global transform function for reads

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

Param	Type	Description
config	Object	override configuration object
[config.tableName]	string	Airtable table name

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

Param	Type	Description
source	Object | string	if string, source represents source table name
source.tableName	string	Source table name
[source.baseID]	string	Source base id
[source.fields]	string	What fields to copy over to destination table
[source.where]	string	Filter passed in to conditionally copy
dest	Object | string	if string, dest represents dest table name
dest.tableName	string	Dest table name
[dest.baseID]	string	Dest base id
[dest.concurrency]	string	Dest concurrency when creating new values

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

Param	Type	Description
source	Object | string	if string, source represents source table name
source.tableName	string	Source table name
[source.baseID]	string	Source base id
[source.fields]	string	What fields to copy over to destination table
[source.where]	string	Filter passed in to conditionally copy
dest	Object | string	if string, dest represents dest table name
dest.tableName	string	Dest table name
[dest.baseID]	string	Dest base id
[dest.concurrency]	string	Dest concurrency when creating new values

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

Param	Type	Description
key	string	Primary key to compare value in passed in data object with dest row
data	Object	Updated data
[config]	Object	Optional config override
[config.tableName]	string	Airtable table name
[config.complex]	boolean	Flag to return full Airtable record object with helper methods attached
[config.baseID]	string	Airtable base id

Example

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

MIT © Victor Hahn