Painless Airtable

Easily interact with the Airtable API.

Usage

npm install painless-airtable

import { useAirtable } from 'painless-airtable';

const { AIRTABLE_TOKEN } = import.meta.env;

const airtable = useAirtable({
  base: '<< Airtable base ID >>',
  token: AIRTABLE_TOKEN,
});

// Queries return a promise and must be inside an async function
const results = await airtable.select('users', {
  fields: ['name', 'phone', 'email'],
  sort: { name: 'asc' },
  max: 20,
});

If you are not working with a bundler, you can also load the module from a CDN such as unpkg and initialize it with the convenient init method.

const airtable = painlessairtable.init({
  base: '<< Airtable base ID >>',
  token: '<< Airtable API token >>',
});

Options

select and find methods accept some options to tailor the response from Airtable. If not provided the results will be as is with Airtable's default options.

option	type	default	description
base	string	undefined	Override the global base
view	string	undefined	Get results from a specific view
fields	array	undefined	Fields to retrieve
max	int	undefined	Max number of results
sort	object	undefined	Fields and order to sort the results
persist	boolean	false	Automatically query for more results when max-results-per-query limit is reached. Be aware it may trigger the max-query-per-second limit error
index	boolean	false	Return an an object of indexed records by RECORD_ID()
where	object, string	undefined	Options to filter results
expand	object	undefined	Options to expand linked records
flatten	boolean	true	Flatten records, assigning metadata to underscore fields

where

Results may be filtered using an object parameter, with some mongodb-like operands.

where: {
  age: 35, // Field is equal to the value
  age: [20, 25, 30], // Field is ANY of the values
  age: { $lt: 35 },  // Apply an operand to the value
  age: [20, { $gte: 50 }], // Combine options
  is_valid: { checked: true },
  tags: { has: 'development' },
  type: { not: ['post', 'page'] },
}

operand	equivalent	meaning
is	=	Equal to
has	⊃	Contains
not	!	Negate
checked		Is checked
$eq	=	Equal to
$neq	!=	Not equal to
$lt	<	Lower than
$gt	>	Greater than
$lte	<=	Lower than or equal
$gte	>=	Greater than or equal

For more complex filtering you may have to write your own filterByFormula string and pass it directly.

expand

Automatically query and populate fields with linked records information.

[!] Be aware it may trigger the max-query-per-second limit error.

expand: {
  // Field with linked records to expand
  company: {
    // Linked table
    table: 'companies',
    // Accepts the same options object as the select method
    options: { 
      fields: ['name', 'address', 'phone'],
    },
  },
}

To Do

• [ ] Add methods for a complete CRUD
• [ ] Throttle queries (with retry option?)