painless-airtable
v0.3.0
Published
Easily interact with the Airtable API
Downloads
13
Maintainers
Readme
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?)