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:

``ts
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:

$3

`ts
new AirtableTs(options: AirtableTsOptions)
`

Creates a new instance of the AirtableTs client.

Parameters:
- options: Configuration options
- apiKey: Your Airtable API key (required)
- Create one at https://airtable.com/create/tokens
- Recommended scopes: schema.bases:read, data.records:read, data.records:write
- baseSchemaCacheDurationMs: Duration in milliseconds to cache base schema (default: 120,000ms = 2 minutes)
- readValidation: How to handle validation failures when reading from Airtable (default: 'error')
- 'error': Throws an error on validation failure
- 'warning': Sets failing fields to type-appropriate default values and optionally calls onWarning. Default values: nullable types return null; non-nullable types return '' (string), 0 (number), false (boolean), or [] (arrays)
- onWarning: Callback function called with validation errors when readValidation is 'warning'
- Other options from Airtable.js are supported, including: apiVersion, customHeaders, endpointUrl, noRetryIfRateLimited, requestTimeout

Example:
`ts
const db = new AirtableTs({
apiKey: 'pat1234.abcdef',
baseSchemaCacheDurationMs: 300000, // 5 minutes
});
`

$3

`ts
async get(table: Table, id: string): Promise
`

Retrieves a single record from a table by its ID.

Parameters:
- table: Table definition object
- id: The ID of the record to retrieve

Example:
`ts
const student = await db.get(studentTable, 'rec1234');
console.log(student.firstName); // Access fields with type safety
`

$3

`ts
async scan(table: Table, params?: ScanParams): Promise
`

Retrieves all records from a table, with optional filtering parameters.

Parameters:
- table: Table definition object
- params (optional): Parameters for filtering, sorting, and limiting results
- filterByFormula: 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 return
- view: Name of a view to use for record selection
- timeZone: Timezone for interpreting date values
- userLocale: Locale for formatting date values

Example:
`ts
// 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
});
`

$3

`ts
async insert(table: Table, data: Partial>): Promise
`

Creates a new record in a table. Returns the new record.

Parameters:
- table: Table definition object
- data: The data for the new record (without an ID, as Airtable will generate one)

Example:
`ts
const newStudent = await db.insert(studentTable, {
firstName: 'Jane',
classes: ['rec5678', 'rec9012']
});
console.log(newStudent.id); // The new record ID generated by Airtable
`

$3

`ts
async update(table: Table, data: Partial & { id: string }): Promise
`

Updates an existing record in a table. Returns the updated record.

Parameters:
- table: Table definition object
- data: The data to update, must include the record ID

Example:
`ts
const updatedStudent = await db.update(studentTable, {
id: 'rec1234',
firstName: 'John',
// Only include fields you want to update
});
`

$3

`ts
async remove(table: Table, id: string): Promise<{ id: string }>
`

Deletes a record from a table.

Parameters:
- table: Table definition object
- id: The ID of the record to delete

Example:
`ts
await db.remove(studentTable, 'rec1234');
`

$3

`ts
async table(table: Table): Promise>
`

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:
`ts
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
`

$3

The underlying Airtable.js SDK is exposed in the airtable property.

`ts
const rawSdk: Airtable = db.airtable;
`

Contributing

Pull requests are welcomed on GitHub! To get started:

1. Install Git and Node.js
2. Clone the repository
3. Install dependencies with npm install
4. Run npm run test to run tests
5. Build with npm run build

Releases

Versions follow the semantic versioning spec.

To release:

1. Use npm version to bump the version
2. Run git push --follow-tags` to push with tags
3. Wait for GitHub Actions to publish to the NPM registry.