solvent (original) (raw)
airtable-ts
🗄️🧱 A type-safe Airtable SDK that makes developing apps on top of Airtable a breeze. We use it in multiple production applications and have found compared to the original SDK it:
- enables us to develop new applications faster
- significantly reduces mean time to detect and resolve issues
- helps us avoid footguns with the Airtable SDK, as well as eliminates boilerplate code
If you've ever tried to build applications on top of the Airtable API, you know it can be a pain. The default SDK leads to:
- apps silently breaking when colleagues edit field definitions in your base
- an error-prone and difficult coding experience with no type safety or editor hints
- unintuitive API behavior, like not being able to distinguish between a non-existent field and a field with unticked checkboxes
- awkward code as each AirtableRecord is a class with many helper methods, so you can't safely stringify them or use Object.entries() etc.
All of these problems are solved with airtable-ts.
In development, you'll define the expected types for different fields: enabling you to leverage type hints in your code editor. After deployment, if people make breaking changes to your base schema you'll get clear runtime errors that pinpoint the problem (rather than your app silently failing, or worse: doing something dangerous!) We also fix unintuitive API behavior, like not being able to tell whether a checkbox field has been deleted or the values are just unticked.
Related libraries
- airtable-ts-codegen: Autogenerate TypeScript definitions for your Airtable base, with perfect compatibility with airtable-ts
- airtable-ts-formula: Type-safe, securely-escaped and rename-robust formulae for Airtable (e.g. for
filterByFormula
)
Example
Install it with npm install airtable-ts
. Then, use it like:
import { AirtableTs, Table } from 'airtable-ts';
const db = new AirtableTs({ // Create your own at https://airtable.com/create/tokens // Recommended scopes: schema.bases:read, data.records:read, data.records:write apiKey: 'pat1234.abcdef', });
// Tip: use airtable-ts-codegen to autogenerate these from your Airtable base export const studentTable: Table<{ id: string, firstName: string, classes: string[] }> = { name: 'student', baseId: 'app1234', tableId: 'tbl1234', schema: { firstName: 'string', classes: 'string[]' }, // optional: use mappings with field ids to prevent renamings breaking your app, // or with field names to make handling renamings easy mappings: { firstName: 'fld1234', classes: 'Classes student is enrolled in' }, };
export const classTable: Table<{ id: string, title: string }> = { name: 'class', baseId: 'app1234', tableId: 'tbl4567', schema: { title: 'string' }, };
// Now we can get all the records in a table (a scan) const classes = await db.scan(classTable);
// Get, update and delete specific records: const student = await db.get(studentTable, 'rec1234'); await db.update(studentTable, { id: 'rec1234', firstName: 'Adam' }); await db.remove(studentTable, 'rec5678');
// Or for a more involved example: async function prefixTitleOfFirstClassOfFirstStudent(prefix: string) { const students = await db.scan(studentTable); if (!students[0]) throw new Error('There are no students'); if (!students[0].classes[0]) throw new Error('First student does not have a class');
const currentClass = await db.get(classTable, students[0].classes[0]); const newTitle = prefix + currentClass.title; await db.update(classTable, { id: currentClass.id, title: newTitle }); }
// And should you ever need it, access to the raw Airtable JS SDK const rawSdk: Airtable = db.airtable;
AirtableTs Class Reference
The AirtableTs
class provides several methods to interact with your Airtable base:
Constructor
new AirtableTs(options: AirtableTsOptions)
Creates a new instance of the AirtableTs client.
Parameters:
options
: Configuration optionsapiKey
: Your Airtable API key (required)
* Create one at https://airtable.com/create/tokens
* Recommended scopes: schema.bases:read, data.records:read, data.records:writebaseSchemaCacheDurationMs
: Duration in milliseconds to cache base schema (default: 120,000ms = 2 minutes)- Other options from Airtable.js are supported, including:
apiVersion
,customHeaders
,endpointUrl
,noRetryIfRateLimited
,requestTimeout
Example:
const db = new AirtableTs({ apiKey: 'pat1234.abcdef', baseSchemaCacheDurationMs: 300000, // 5 minutes });
get
async get(table: Table, id: string): Promise
Retrieves a single record from a table by its ID.
Parameters:
table
: Table definition objectid
: The ID of the record to retrieve
Example:
const student = await db.get(studentTable, 'rec1234'); console.log(student.firstName); // Access fields with type safety
scan
async scan(table: Table, params?: ScanParams): Promise<T[]>
Retrieves all records from a table, with optional filtering parameters.
Parameters:
table
: Table definition objectparams
(optional): Parameters for filtering, sorting, and limiting resultsfilterByFormula
: An Airtable formula to filter records
* Tip: use airtable-ts-formula for type-safe, securely-escaped and rename-robust formulae!sort
: Array of sort objects (e.g.,[{field: 'firstName', direction: 'asc'}]
)maxRecords
: Maximum number of records to returnview
: Name of a view to use for record selectiontimeZone
: Timezone for interpreting date valuesuserLocale
: Locale for formatting date values
Example:
// Get all records const allStudents = await db.scan(studentTable);
// Get records with filtering and sorting const topStudents = await db.scan(studentTable, { filterByFormula: '{grade} >= 90', sort: [{field: 'grade', direction: 'desc'}], maxRecords: 10 });
insert
async insert(table: Table, data: Partial<Omit<T, 'id'>>): Promise
Creates a new record in a table. Returns the new record.
Parameters:
table
: Table definition objectdata
: The data for the new record (without an ID, as Airtable will generate one)
Example:
const newStudent = await db.insert(studentTable, { firstName: 'Jane', classes: ['rec5678', 'rec9012'] }); console.log(newStudent.id); // The new record ID generated by Airtable
update
async update(table: Table, data: Partial & { id: string }): Promise
Updates an existing record in a table. Returns the updated record.
Parameters:
table
: Table definition objectdata
: The data to update, must include the record ID
Example:
const updatedStudent = await db.update(studentTable, { id: 'rec1234', firstName: 'John', // Only include fields you want to update });
remove
async remove(table: Table, id: string): Promise<{ id: string }>
Deletes a record from a table.
Parameters:
table
: Table definition objectid
: The ID of the record to delete
Example:
await db.remove(studentTable, 'rec1234');
table
async table(table: Table): Promise<AirtableTsTable>
Retrieves the AirtableTsTable object for the given table definition. This is the Airtable.js table, enriched with a fields
key that includes details of the Airtable schema for this table.
This is useful for advanced use cases where you need direct access to the Airtable table object.
Parameters:
table
: Table definition object
Example:
const airtableTsTable = await db.table(studentTable); // Now you can use the raw Airtable table object with field information console.log(airtableTsTable.fields); // Access the table's field definitions
airtable
The underlying Airtable.js SDK is exposed in the airtable
property.
const rawSdk: Airtable = db.airtable;
Contributing
Pull requests are welcomed on GitHub! To get started:
- Install Git and Node.js
- Clone the repository
- Install dependencies with
npm install
- Run
npm run test
to run tests - Build with
npm run build
Releases
Versions follow the semantic versioning spec.
To release:
- Use
npm version <major | minor | patch>
to bump the version - Run
git push --follow-tags
to push with tags - Wait for GitHub Actions to publish to the NPM registry.