airtable-ts 1.4.0 → 1.5.0

package/README.md

@@ -15,7 +15,12 @@ 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.
 
-## Usage
+## Related libraries
+
+- [airtable-ts-codegen](https://github.com/domdomegg/airtable-ts-codegen): Autogenerate TypeScript definitions for your Airtable base, with perfect compatibility with airtable-ts
+- [airtable-ts-formula](https://github.com/domdomegg/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:
 
@@ -24,6 +29,7 @@ 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',
 });
 
@@ -68,6 +74,171 @@ async function prefixTitleOfFirstClassOfFirstStudent(prefix: string) {
 const rawSdk: Airtable = db.airtable;
 ```
 
+## AirtableTs Class Reference
+
+The `AirtableTs` class provides several methods to interact with your Airtable base:
+
+### Constructor
+
+```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)
+  - 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
+});
+```
+
+### get
+
+```ts
+async get<T extends Item>(table: Table<T>, id: string): Promise<T>
+```
+
+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
+```
+
+### scan
+
+```ts
+async scan<T extends Item>(table: Table<T>, params?: ScanParams): Promise<T[]>
+```
+
+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](https://github.com/domdomegg/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
+});
+```
+
+### insert
+
+```ts
+async insert<T extends Item>(table: Table<T>, data: Partial<Omit<T, 'id'>>): Promise<T>
+```
+
+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
+```
+
+### update
+
+```ts
+async update<T extends Item>(table: Table<T>, data: Partial<T> & { id: string }): Promise<T>
+```
+
+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
+});
+```
+
+### remove
+
+```ts
+async remove<T extends Item>(table: Table<T>, 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');
+```
+
+### table
+
+```ts
+async table<T extends Item>(table: Table<T>): Promise<AirtableTsTable<T>>
+```
+
+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
+```
+
+### airtable
+
+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:

package/dist/AirtableTs.d.ts

@@ -0,0 +1,18 @@
+import Airtable from 'airtable';
+import { Item, Table } from './mapping/typeUtils';
+import { AirtableTsTable, AirtableTsOptions, ScanParams } from './types';
+export declare class AirtableTs {
+    airtable: Airtable;
+    private options;
+    constructor(options: AirtableTsOptions);
+    get<T extends Item>(table: Table<T>, id: string): Promise<T>;
+    scan<T extends Item>(table: Table<T>, params?: ScanParams): Promise<T[]>;
+    insert<T extends Item>(table: Table<T>, data: Partial<Omit<T, 'id'>>): Promise<T>;
+    update<T extends Item>(table: Table<T>, data: Partial<T> & {
+        id: string;
+    }): Promise<T>;
+    remove<T extends Item>(table: Table<T>, id: string): Promise<{
+        id: string;
+    }>;
+    table<T extends Item>(table: Table<T>): Promise<AirtableTsTable<T>>;
+}

package/dist/AirtableTs.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AirtableTs = void 0;
+const airtable_1 = __importDefault(require("airtable"));
+const getAirtableTsTable_1 = require("./getAirtableTsTable");
+const assertMatchesSchema_1 = require("./assertMatchesSchema");
+const recordMapper_1 = require("./mapping/recordMapper");
+const getFields_1 = require("./getFields");
+const wrapToCatchAirtableErrors_1 = require("./wrapToCatchAirtableErrors");
+const AirtableTsError_1 = require("./AirtableTsError");
+class AirtableTs {
+    airtable;
+    options;
+    constructor(options) {
+        this.airtable = new airtable_1.default(options);
+        this.options = {
+            ...airtable_1.default.default_config(),
+            ...options,
+            baseSchemaCacheDurationMs: options.baseSchemaCacheDurationMs ?? 120000,
+        };
+    }
+    async get(table, id) {
+        if (!id) {
+            throw new AirtableTsError_1.AirtableTsError({
+                message: `The record ID must be supplied when getting a record. This was thrown when trying to get a '${table.name}' (${table.tableId}) record.`,
+                type: AirtableTsError_1.ErrorType.INVALID_PARAMETER,
+                suggestion: 'Provide a valid record ID when calling the get method.',
+            });
+        }
+        const airtableTsTable = await (0, getAirtableTsTable_1.getAirtableTsTable)(this.airtable, table, this.options);
+        const record = await airtableTsTable.find(id);
+        if (!record) {
+            throw new AirtableTsError_1.AirtableTsError({
+                message: `No record with ID '${id}' exists in table '${table.name}'.`,
+                type: AirtableTsError_1.ErrorType.RESOURCE_NOT_FOUND,
+                suggestion: 'Verify that the record ID is correct and that the record exists in the table.',
+            });
+        }
+        return (0, recordMapper_1.mapRecordFromAirtable)(table, record);
+    }
+    async scan(table, params) {
+        const airtableTsTable = await (0, getAirtableTsTable_1.getAirtableTsTable)(this.airtable, table, this.options);
+        const records = await airtableTsTable.select({
+            fields: (0, getFields_1.getFields)(table),
+            ...params,
+        }).all();
+        return records.map((record) => (0, recordMapper_1.mapRecordFromAirtable)(table, record));
+    }
+    async insert(table, data) {
+        (0, assertMatchesSchema_1.assertMatchesSchema)(table, { ...data, id: 'placeholder' });
+        const airtableTsTable = await (0, getAirtableTsTable_1.getAirtableTsTable)(this.airtable, table, this.options);
+        const record = await airtableTsTable.create((0, recordMapper_1.mapRecordToAirtable)(table, data, airtableTsTable));
+        return (0, recordMapper_1.mapRecordFromAirtable)(table, record);
+    }
+    async update(table, data) {
+        (0, assertMatchesSchema_1.assertMatchesSchema)(table, { ...data });
+        const { id, ...withoutId } = data;
+        const airtableTsTable = await (0, getAirtableTsTable_1.getAirtableTsTable)(this.airtable, table, this.options);
+        const record = await airtableTsTable.update(data.id, (0, recordMapper_1.mapRecordToAirtable)(table, withoutId, airtableTsTable));
+        return (0, recordMapper_1.mapRecordFromAirtable)(table, record);
+    }
+    async remove(table, id) {
+        if (!id) {
+            throw new AirtableTsError_1.AirtableTsError({
+                message: `The record ID must be supplied when removing a record. This was thrown when trying to get a '${table.name}' (${table.tableId}) record.`,
+                type: AirtableTsError_1.ErrorType.INVALID_PARAMETER,
+                suggestion: 'Provide a valid record ID when calling the remove method.',
+            });
+        }
+        const airtableTsTable = await (0, getAirtableTsTable_1.getAirtableTsTable)(this.airtable, table, this.options);
+        const record = await airtableTsTable.destroy(id);
+        return { id: record.id };
+    }
+    async table(table) {
+        return (0, getAirtableTsTable_1.getAirtableTsTable)(this.airtable, table, this.options);
+    }
+}
+exports.AirtableTs = AirtableTs;
+// Wrap all methods of AirtableTs with error handling
+// See https://github.com/Airtable/airtable.js/issues/294
+(0, wrapToCatchAirtableErrors_1.wrapToCatchAirtableErrors)(AirtableTs);

package/dist/AirtableTsError.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Error types for categorizing different kinds of errors
+ */
+export declare enum ErrorType {
+    SCHEMA_VALIDATION = "SCHEMA_VALIDATION",
+    RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND",
+    INVALID_PARAMETER = "INVALID_PARAMETER",
+    API_ERROR = "API_ERROR"
+}
+/**
+ * Base error class for all airtable-ts errors
+ */
+export declare class AirtableTsError extends Error {
+    /** Error type for categorization */
+    type: ErrorType;
+    constructor(options: {
+        message: string;
+        type: ErrorType;
+        suggestion?: string;
+    });
+}
+export declare const prependError: (error: unknown, prefix: string) => unknown;

package/dist/AirtableTsError.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prependError = exports.AirtableTsError = exports.ErrorType = void 0;
+/**
+ * Error types for categorizing different kinds of errors
+ */
+var ErrorType;
+(function (ErrorType) {
+    ErrorType["SCHEMA_VALIDATION"] = "SCHEMA_VALIDATION";
+    ErrorType["RESOURCE_NOT_FOUND"] = "RESOURCE_NOT_FOUND";
+    ErrorType["INVALID_PARAMETER"] = "INVALID_PARAMETER";
+    ErrorType["API_ERROR"] = "API_ERROR";
+})(ErrorType || (exports.ErrorType = ErrorType = {}));
+/**
+ * Base error class for all airtable-ts errors
+ */
+class AirtableTsError extends Error {
+    /** Error type for categorization */
+    type;
+    constructor(options) {
+        const { message, suggestion, type } = options;
+        super(suggestion ? `${message} Suggestion: ${suggestion}` : message);
+        this.type = type;
+        this.name = 'AirtableTsError';
+    }
+}
+exports.AirtableTsError = AirtableTsError;
+const prependError = (error, prefix) => {
+    if (error instanceof AirtableTsError) {
+        // eslint-disable-next-line no-param-reassign
+        error.message = `${prefix}: ${error.message}`;
+        // eslint-disable-next-line no-param-reassign
+        error.stack = `Error: ${prefix}: ${error.stack?.startsWith('Error: ') ? error.stack.slice('Error: '.length) : error.stack}`;
+    }
+    return error;
+};
+exports.prependError = prependError;

package/dist/assertMatchesSchema.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assertMatchesSchema = void 0;
 const typeUtils_1 = require("./mapping/typeUtils");
+const AirtableTsError_1 = require("./AirtableTsError");
 /**
  * In theory, this should never catch stuff because our type mapping logic should
  * verify the types are compatible.
@@ -14,7 +15,10 @@ const typeUtils_1 = require("./mapping/typeUtils");
  */
 function assertMatchesSchema(table, data, mode = 'partial') {
     if (typeof data !== 'object' || data === null) {
-        throw new Error(`[airtable-ts] Item for ${table.name} is not an object`);
+        throw new AirtableTsError_1.AirtableTsError({
+            message: `Data passed in to airtable-ts should be an object but received ${data === null ? 'null' : typeof data}.`,
+            type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+        });
     }
     Object.entries(table.schema).forEach(([fieldName, type]) => {
         const value = data[fieldName];
@@ -22,10 +26,16 @@ function assertMatchesSchema(table, data, mode = 'partial') {
             if (mode === 'partial') {
                 return;
             }
-            throw new Error(`[airtable-ts] Item for ${table.name} table is missing field '${fieldName}' (expected ${type})`);
+            throw new AirtableTsError_1.AirtableTsError({
+                message: `Data passed in to airtable-ts is missing required field '${fieldName}' in table '${table.name}' (expected type: ${type}).`,
+                type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+            });
         }
         if (!(0, typeUtils_1.matchesType)(value, type)) {
-            throw new Error(`[airtable-ts] Item for ${table.name} table has invalid value for field '${fieldName}' (actual type ${typeof value}, but expected ${type})`);
+            throw new AirtableTsError_1.AirtableTsError({
+                message: `Invalid value passed in to airtable-ts for field '${fieldName}' in table '${table.name}' (received type: ${typeof value}, expected type: ${type}).`,
+                type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+            });
         }
     });
 }

package/dist/getAirtableTsTable.d.ts

@@ -0,0 +1,4 @@
+import Airtable from 'airtable';
+import { Item, Table } from './mapping/typeUtils';
+import { AirtableTsTable, CompleteAirtableTsOptions } from './types';
+export declare const getAirtableTsTable: <T extends Item>(airtable: Airtable, table: Table<T>, options: CompleteAirtableTsOptions) => Promise<AirtableTsTable<T>>;

package/dist/getAirtableTsTable.js

@@ -0,0 +1,100 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAirtableTsTable = void 0;
+const axios_1 = __importStar(require("axios"));
+const AirtableTsError_1 = require("./AirtableTsError");
+const getAirtableTsTable = async (airtable, table, options) => {
+    const airtableTable = airtable.base(table.baseId).table(table.tableId);
+    // We need the schema so we know which type mapper to use.
+    // Even if we were inferring a type mapper from the schema, we'd still have to
+    // do this as otherwise we can't distinguish a column with all null values from
+    // a column that is missing entirely. We'd like to do that as for safety, we'd
+    // rather throw an error if the column is missing entirely; this suggests a
+    // misconfiguration. But an all-null column is okay. The particular case that
+    // this is likely for is checkbox columns.
+    const baseSchema = await getAirtableBaseSchema(table.baseId, options);
+    const tableDefinition = baseSchema.find((t) => t.id === table.tableId);
+    if (!tableDefinition) {
+        throw new AirtableTsError_1.AirtableTsError({
+            message: `Table '${table.name}' (${table.tableId}) does not exist in base ${table.baseId}.`,
+            type: AirtableTsError_1.ErrorType.RESOURCE_NOT_FOUND,
+            suggestion: 'Verify that the base ID and table ID are correct.',
+        });
+    }
+    return Object.assign(airtableTable, {
+        fields: tableDefinition.fields,
+        tsDefinition: table,
+    });
+};
+exports.getAirtableTsTable = getAirtableTsTable;
+const baseSchemaCache = new Map();
+/**
+ * Get the schemas from the cache or Airtable API for the tables in the given base.
+ * @see https://airtable.com/developers/web/api/get-base-schema
+ * @param baseId The base id to get the schemas for
+ */
+const getAirtableBaseSchema = async (baseId, options) => {
+    const fromCache = baseSchemaCache.get(baseId);
+    if (fromCache && Date.now() - fromCache.at < options.baseSchemaCacheDurationMs) {
+        return fromCache.data;
+    }
+    if (!options.apiKey) {
+        throw new AirtableTsError_1.AirtableTsError({
+            message: 'API key is required but was not provided.',
+            type: AirtableTsError_1.ErrorType.INVALID_PARAMETER,
+            suggestion: 'Provide a valid Airtable API key when initializing AirtableTs.',
+        });
+    }
+    const res = await (0, axios_1.default)({
+        baseURL: options.endpointUrl ?? 'https://api.airtable.com',
+        url: `/v0/meta/bases/${baseId}/tables`,
+        ...(options.requestTimeout ? { timeout: options.requestTimeout } : {}),
+        headers: {
+            // eslint-disable-next-line no-underscore-dangle
+            Authorization: `Bearer ${options.apiKey}`,
+            ...options.customHeaders,
+        },
+    }).catch((err) => {
+        const normalizedErrorMessage = err instanceof axios_1.AxiosError
+            ? `${err.message}. Status: ${err.status}. Data: ${JSON.stringify(err.response?.data)}`
+            : err;
+        throw new AirtableTsError_1.AirtableTsError({
+            message: `Failed to get base schema: ${normalizedErrorMessage}`,
+            type: AirtableTsError_1.ErrorType.API_ERROR,
+            suggestion: 'Ensure the API token is correct, and has `schema.bases:read` permission to the target base.',
+        });
+    });
+    const baseSchema = res.data.tables;
+    if (baseSchemaCache.size > 100) {
+        baseSchemaCache.clear();
+        // If you're seeing this warning, then we probably either need to:
+        // - Update the maximum limit before clearing the cache, provided we have memory headroom; or
+        // - Use a last recently used cache or similar
+        console.warn('[airtable-ts] baseSchemaCache cleared to avoid a memory leak: this code is not currently optimized for accessing over 100 different bases from a single instance');
+    }
+    baseSchemaCache.set(baseId, { at: Date.now(), data: baseSchema });
+    return baseSchema;
+};

package/dist/index.d.ts

@@ -1,21 +1,5 @@
-import Airtable from 'airtable';
-import type { QueryParams } from 'airtable/lib/query_params';
-import { Item, Table } from './mapping/typeUtils';
-import { AirtableTsOptions } from './types';
-export declare class AirtableTs {
-    airtable: Airtable;
-    private options;
-    constructor(options: AirtableTsOptions);
-    get<T extends Item>(table: Table<T>, id: string): Promise<T>;
-    scan<T extends Item>(table: Table<T>, params?: ScanParams): Promise<T[]>;
-    insert<T extends Item>(table: Table<T>, data: Partial<Omit<T, 'id'>>): Promise<T>;
-    update<T extends Item>(table: Table<T>, data: Partial<T> & {
-        id: string;
-    }): Promise<T>;
-    remove<T extends Item>(table: Table<T>, id: string): Promise<{
-        id: string;
-    }>;
-}
-export type ScanParams = Omit<QueryParams<unknown>, 'fields' | 'cellFormat' | 'method' | 'returnFieldsByFieldId' | 'pageSize' | 'offset'>;
-export type { AirtableTsOptions } from './types';
+export { AirtableTs } from './AirtableTs';
+export { AirtableTsError } from './AirtableTsError';
+export type { AirtableTsOptions, ScanParams, AirtableTsTable } from './types';
 export type { Item, Table } from './mapping/typeUtils';
+export type { WrappedAirtableError } from './wrapToCatchAirtableErrors';

package/dist/index.js

@@ -1,64 +1,7 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AirtableTs = void 0;
-const airtable_1 = __importDefault(require("airtable"));
-const getAirtableTable_1 = require("./getAirtableTable");
-const assertMatchesSchema_1 = require("./assertMatchesSchema");
-const recordMapper_1 = require("./mapping/recordMapper");
-const getFields_1 = require("./getFields");
-class AirtableTs {
-    airtable;
-    options;
-    constructor(options) {
-        this.airtable = new airtable_1.default(options);
-        this.options = {
-            ...airtable_1.default.default_config(),
-            ...options,
-            baseSchemaCacheDurationMs: options.baseSchemaCacheDurationMs ?? 120000,
-        };
-    }
-    async get(table, id) {
-        if (!id) {
-            throw new Error(`[airtable-ts] Tried to get record in ${table.name} with no id`);
-        }
-        const airtableTable = await (0, getAirtableTable_1.getAirtableTable)(this.airtable, table, this.options);
-        const record = await airtableTable.find(id);
-        if (!record) {
-            throw new Error(`[airtable-ts] Failed to find record in ${table.name} with key ${id}`);
-        }
-        return (0, recordMapper_1.mapRecordFromAirtable)(table, record);
-    }
-    async scan(table, params) {
-        const airtableTable = await (0, getAirtableTable_1.getAirtableTable)(this.airtable, table, this.options);
-        const records = await airtableTable.select({
-            fields: (0, getFields_1.getFields)(table),
-            ...params,
-        }).all();
-        return records.map((record) => (0, recordMapper_1.mapRecordFromAirtable)(table, record));
-    }
-    async insert(table, data) {
-        (0, assertMatchesSchema_1.assertMatchesSchema)(table, { ...data, id: 'placeholder' });
-        const airtableTable = await (0, getAirtableTable_1.getAirtableTable)(this.airtable, table, this.options);
-        const record = await airtableTable.create((0, recordMapper_1.mapRecordToAirtable)(table, data, airtableTable));
-        return (0, recordMapper_1.mapRecordFromAirtable)(table, record);
-    }
-    async update(table, data) {
-        (0, assertMatchesSchema_1.assertMatchesSchema)(table, { ...data });
-        const { id, ...withoutId } = data;
-        const airtableTable = await (0, getAirtableTable_1.getAirtableTable)(this.airtable, table, this.options);
-        const record = await airtableTable.update(data.id, (0, recordMapper_1.mapRecordToAirtable)(table, withoutId, airtableTable));
-        return (0, recordMapper_1.mapRecordFromAirtable)(table, record);
-    }
-    async remove(table, id) {
-        if (!id) {
-            throw new Error(`[airtable-ts] Tried to remove record in ${table.name} with no id`);
-        }
-        const airtableTable = await (0, getAirtableTable_1.getAirtableTable)(this.airtable, table, this.options);
-        const record = await airtableTable.destroy(id);
-        return { id: record.id };
-    }
-}
-exports.AirtableTs = AirtableTs;
+exports.AirtableTsError = exports.AirtableTs = void 0;
+var AirtableTs_1 = require("./AirtableTs");
+Object.defineProperty(exports, "AirtableTs", { enumerable: true, get: function () { return AirtableTs_1.AirtableTs; } });
+var AirtableTsError_1 = require("./AirtableTsError");
+Object.defineProperty(exports, "AirtableTsError", { enumerable: true, get: function () { return AirtableTsError_1.AirtableTsError; } });

package/dist/mapping/fieldMappers.js

@@ -2,11 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fieldMappers = void 0;
 const typeUtils_1 = require("./typeUtils");
+const AirtableTsError_1 = require("../AirtableTsError");
 const fallbackMapperPair = (toFallback, fromFallback) => ({
     toAirtable: (value) => value ?? toFallback,
     fromAirtable: (value) => value ?? fromFallback,
 });
-const readonly = (airtableType) => () => { throw new Error(`[airtable-ts] ${airtableType} type field is readonly`); };
+const readonly = (airtableType) => () => {
+    throw new AirtableTsError_1.AirtableTsError({
+        message: `Cannot modify a field of type '${airtableType}' as it is read-only.`,
+        type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+    });
+};
 const coerce = (airtableType, tsType) => (value) => {
     const parsedType = (0, typeUtils_1.parseType)(tsType);
     if (!parsedType.array && typeof value === parsedType.single) {
@@ -25,9 +31,17 @@ const coerce = (airtableType, tsType) => (value) => {
         return value[0];
     }
     if (!parsedType.array && Array.isArray(value) && value.length !== 1) {
-        throw new Error(`[airtable-ts] Can't coerce ${airtableType} to a ${tsType}, as there were ${value.length} array entries`);
+        throw new AirtableTsError_1.AirtableTsError({
+            message: `Cannot convert array with ${value.length} entries from airtable type '${airtableType} to TypeScript type '${tsType}'.`,
+            type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+            suggestion: `Change the type from '${tsType}' to '${tsType}[]' in your table definition.`,
+        });
     }
-    throw new Error(`[airtable-ts] Can't coerce ${airtableType} to a ${tsType}, as it was of type ${typeof value}`);
+    throw new AirtableTsError_1.AirtableTsError({
+        message: `Cannot convert value from airtable type '${airtableType}' to '${tsType}', as the Airtable API provided a '${typeof value}'.`,
+        type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+        suggestion: 'Update the types in your table definition to compatible types for your Airtable base.',
+    });
 };
 const dateTimeMapperPair = {
     // Number assumed to be unix time in seconds
@@ -36,7 +50,10 @@ const dateTimeMapperPair = {
             return null;
         const date = new Date(typeof value === 'number' ? value * 1000 : value);
         if (Number.isNaN(date.getTime())) {
-            throw new Error('[airtable-ts] Invalid dateTime');
+            throw new AirtableTsError_1.AirtableTsError({
+                message: 'Invalid date/time value provided.',
+                type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+            });
         }
         return date.toJSON();
     },
@@ -45,7 +62,10 @@ const dateTimeMapperPair = {
             return null;
         const date = new Date(value);
         if (Number.isNaN(date.getTime())) {
-            throw new Error('[airtable-ts] Invalid dateTime');
+            throw new AirtableTsError_1.AirtableTsError({
+                message: 'Invalid date/time value received from Airtable.',
+                type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+            });
         }
         return date.toJSON();
     },
@@ -196,7 +216,10 @@ const numberOrNull = {
                     return null;
                 const date = new Date(nullableValue);
                 if (Number.isNaN(date.getTime())) {
-                    throw new Error('[airtable-ts] Invalid date');
+                    throw new AirtableTsError_1.AirtableTsError({
+                        message: 'Invalid date/time value received from Airtable.',
+                        type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+                    });
                 }
                 return Math.floor(date.getTime() / 1000);
             },
@@ -209,7 +232,10 @@ const numberOrNull = {
                     return null;
                 const date = new Date(nullableValue);
                 if (Number.isNaN(date.getTime())) {
-                    throw new Error('[airtable-ts] Invalid date');
+                    throw new AirtableTsError_1.AirtableTsError({
+                        message: 'Invalid date/time value received from Airtable.',
+                        type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+                    });
                 }
                 return Math.floor(date.getTime() / 1000);
             },
@@ -222,7 +248,10 @@ const numberOrNull = {
                     return null;
                 const date = new Date(nullableValue);
                 if (Number.isNaN(date.getTime())) {
-                    throw new Error('[airtable-ts] Invalid date');
+                    throw new AirtableTsError_1.AirtableTsError({
+                        message: 'Invalid date/time value received from Airtable.',
+                        type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+                    });
                 }
                 return Math.floor(date.getTime() / 1000);
             },
@@ -235,7 +264,10 @@ const numberOrNull = {
                     return null;
                 const date = new Date(nullableValue);
                 if (Number.isNaN(date.getTime())) {
-                    throw new Error('[airtable-ts] Invalid date');
+                    throw new AirtableTsError_1.AirtableTsError({
+                        message: 'Invalid date/time value received from Airtable.',
+                        type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+                    });
                 }
                 return Math.floor(date.getTime() / 1000);
             },
@@ -265,11 +297,21 @@ const stringArrayOrNull = {
         multipleCollaborators: multipleCollaboratorsMapperPair,
         multipleAttachments: multipleAttachmentsMapperPair,
         multipleLookupValues: {
-            toAirtable: () => { throw new Error('[airtable-ts] lookup type field is readonly'); },
+            toAirtable: () => {
+                throw new AirtableTsError_1.AirtableTsError({
+                    message: 'Lookup fields are read-only and cannot be modified.',
+                    type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+                });
+            },
             fromAirtable: coerce('multipleLookupValues', 'string[] | null'),
         },
         formula: {
-            toAirtable: () => { throw new Error('[airtable-ts] formula type field is readonly'); },
+            toAirtable: () => {
+                throw new AirtableTsError_1.AirtableTsError({
+                    message: 'Formula fields are read-only and cannot be modified.',
+                    type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+                });
+            },
             fromAirtable: coerce('multipleLookupValues', 'string[] | null'),
         },
         unknown: {
@@ -287,7 +329,11 @@ exports.fieldMappers = {
                     fromAirtable: (value) => {
                         const nullableValue = nullablePair.fromAirtable(value);
                         if (nullableValue === null && ['multipleRecordLinks', 'dateTime', 'createdTime', 'lastModifiedTime'].includes(airtableType)) {
-                            throw new Error(`[airtable-ts] Expected non-null or non-empty value to map to string for field type ${airtableType}`);
+                            throw new AirtableTsError_1.AirtableTsError({
+                                message: `Cannot convert null value to string for field type '${airtableType}'.`,
+                                type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+                                suggestion: 'Provide a non-null value for this field or update your schema to allow null values.',
+                            });
                         }
                         return nullableValue ?? '';
                     },
@@ -311,7 +357,11 @@ exports.fieldMappers = {
                     fromAirtable: (value) => {
                         const nullableValue = nullablePair.fromAirtable(value);
                         if (nullableValue === null) {
-                            throw new Error(`[airtable-ts] Expected non-null or non-empty value to map to number for field type ${airtableType}`);
+                            throw new AirtableTsError_1.AirtableTsError({
+                                message: `Cannot convert null value to number for field type '${airtableType}'.`,
+                                type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+                                suggestion: 'Provide a non-null value for this field or update your schema to allow null values.',
+                            });
                         }
                         return nullableValue;
                     },

package/dist/mapping/nameMapper.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mapRecordFieldNamesTsToAirtable = exports.mapRecordFieldNamesAirtableToTs = void 0;
+const AirtableTsError_1 = require("../AirtableTsError");
 /**
  * Maps a TS object (matching table.mappings) to another TS object (matching table.schema),
  * mapping columns based on the table definition.
@@ -86,13 +87,23 @@ const mapRecordFieldNamesTsToAirtable = (table, item) => {
                     return mappingToAirtable.map((airtableFieldName) => [airtableFieldName, null]);
                 }
                 // This should be unreachable because of our types
-                throw new Error(`[airtable-ts] Expected field ${table.name}.${outputFieldName} to match type \`${tsType}\` but got null. This should never happen in normal operation as it should be caught before this point.`);
+                throw new AirtableTsError_1.AirtableTsError({
+                    message: `Received null for non-nullable field '${outputFieldName}' (${mappingToAirtable}) with type '${tsType}' in table '${table.name}' (${table.tableId}). This should never happen in normal operation as it should be caught before this point.`,
+                    type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+                });
             }
             if (!Array.isArray(value)) {
-                throw new Error(`[airtable-ts] Got non-array type ${typeof value} for ${table.name}.${outputFieldName}, but expected ${table.schema[outputFieldName]}.`);
+                throw new AirtableTsError_1.AirtableTsError({
+                    message: `Expected an array for field '${outputFieldName}' (${mappingToAirtable}) in table '${table.name}' (${table.tableId}), but received ${typeof value}.`,
+                    type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+                });
             }
             if (value.length !== mappingToAirtable.length) {
-                throw new Error(`[airtable-ts] Got ${value.length} values for ${table.name}.${outputFieldName}, but ${mappingToAirtable.length} mappings. Expected these to be the same.`);
+                throw new AirtableTsError_1.AirtableTsError({
+                    message: `Array length mismatch for field '${outputFieldName}' (${JSON.stringify(mappingToAirtable)}) in table '${table.name}' (${table.tableId}): received ${value.length} values but had mappings for ${mappingToAirtable.length}.`,
+                    type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+                    suggestion: 'Ensure the array length matches the number of mapped fields in your table definition.',
+                });
             }
             return mappingToAirtable.map((airtableFieldName, index) => [airtableFieldName, value[index]]);
         }

package/dist/mapping/recordMapper.d.ts

@@ -1,17 +1,17 @@
 import { FieldSet } from 'airtable';
-import { AirtableRecord, AirtableTable } from '../types';
+import { AirtableRecord, AirtableTsTable } from '../types';
 import { FromTsTypeString, Item, Table, TsTypeString } from './typeUtils';
 export declare const mapRecordFromAirtable: <T extends Item>(table: Table<T>, record: AirtableRecord) => T;
-export declare const mapRecordToAirtable: <T extends Item>(table: Table<T>, item: Partial<T>, airtableTable: AirtableTable) => FieldSet;
+export declare const mapRecordToAirtable: <T extends Item>(table: Table<T>, item: Partial<T>, airtableTsTable: AirtableTsTable) => FieldSet;
 export declare const visibleForTesting: {
     mapRecordTypeAirtableToTs: <T extends {
         [fieldNameOrId: string]: TsTypeString;
-    }>(tsTypes: T, record: AirtableRecord) => { [F in keyof T]: FromTsTypeString<T[F]>; } & {
+    }>(table: Table<Item>, tsTypes: T, record: AirtableRecord) => { [F in keyof T]: FromTsTypeString<T[F]>; } & {
         id: string;
     };
     mapRecordTypeTsToAirtable: <T_1 extends {
         [fieldNameOrId: string]: TsTypeString;
     }, R extends { [K in keyof T_1]?: FromTsTypeString<T_1[K]>; } & {
         id?: string;
-    }>(tsTypes: T_1, tsRecord: R, airtableTable: AirtableTable) => FieldSet;
+    }>(table: Table<Item>, tsTypes: T_1, tsRecord: R, airtableTsTable: AirtableTsTable) => FieldSet;
 };

package/dist/mapping/recordMapper.js

@@ -4,19 +4,28 @@ exports.visibleForTesting = exports.mapRecordToAirtable = exports.mapRecordFromA
 const fieldMappers_1 = require("./fieldMappers");
 const nameMapper_1 = require("./nameMapper");
 const typeUtils_1 = require("./typeUtils");
+const AirtableTsError_1 = require("../AirtableTsError");
 const getMapper = (tsType, airtableType) => {
     const tsMapper = fieldMappers_1.fieldMappers[tsType];
     if (!tsMapper) {
-        throw new Error(`[airtable-ts] No mappers for ts type ${tsType}`);
+        throw new AirtableTsError_1.AirtableTsError({
+            message: `No mapper exists for TypeScript type '${tsType}'.`,
+            type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+            suggestion: 'Check that you are using a supported TypeScript type in your schema definition.',
+        });
     }
     if (tsMapper[airtableType]) {
         return tsMapper[airtableType];
     }
     if (tsMapper.unknown) {
-        console.warn(`[airtable-ts] Unknown airtable type ${airtableType}. This is not fully supported and exact mapping behaviour may change in a future release.`);
+        console.warn(`[airtable-ts] Unknown airtable type ${airtableType} for tsType ${tsType}. This is not fully supported and exact mapping behaviour may change in a future release.`);
         return tsMapper.unknown;
     }
-    throw new Error(`[airtable-ts] Expected to be able to map to ts type ${tsType}, but got airtable type ${airtableType} which can't.`);
+    throw new AirtableTsError_1.AirtableTsError({
+        message: `Cannot map Airtable type '${airtableType}' to TypeScript type '${tsType}'.`,
+        type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+        suggestion: 'Check that your schema definition uses TypeScript types that are compatible with the Airtable field types.',
+    });
 };
 /**
  * This function coerces an Airtable record to a TypeScript object, given an
@@ -33,13 +42,17 @@ const getMapper = (tsType, airtableType) => {
  * @returns An object matching the TypeScript type passed in, based on the Airtable record. Throws if cannot coerce to requested type.
  * @example { id: 'rec012', a: 'Some text', b: 123, c: false, d: 'rec345' }
  */
-const mapRecordTypeAirtableToTs = (tsTypes, record) => {
+const mapRecordTypeAirtableToTs = (table, tsTypes, record) => {
     const item = {};
     Object.entries(tsTypes).forEach(([fieldNameOrId, tsType]) => {
         // eslint-disable-next-line no-underscore-dangle
         const fieldDefinition = record._table.fields.find((f) => f.id === fieldNameOrId || f.name === fieldNameOrId);
         if (!fieldDefinition) {
-            throw new Error(`[airtable-ts] Failed to get Airtable field ${fieldNameOrId}`);
+            // This should not happen normally, as we should only be trying to map fields that are in the table definition
+            throw new AirtableTsError_1.AirtableTsError({
+                message: `Field '${fieldNameOrId}' does not exist in the table definition. This error should not happen in normal operation.`,
+                type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+            });
         }
         const value = record.fields[fieldDefinition.name];
         try {
@@ -48,13 +61,8 @@ const mapRecordTypeAirtableToTs = (tsTypes, record) => {
             item[fieldNameOrId] = fromAirtable(value);
         }
         catch (error) {
-            if (error instanceof Error) {
-                // eslint-disable-next-line no-underscore-dangle
-                error.message = `Failed to map field ${record._table.name}.${fieldNameOrId}: ${error.message}`;
-                // eslint-disable-next-line no-underscore-dangle
-                error.stack = `Error: Failed to map field ${record._table.name}.${fieldNameOrId}: ${error.stack?.startsWith('Error: ') ? error.stack.slice('Error: '.length) : error.stack}`;
-            }
-            throw error;
+            const tsName = table.mappings ? Object.entries(table.mappings).find((e) => e[1] === fieldNameOrId)?.[0] : undefined;
+            throw (0, AirtableTsError_1.prependError)(error, `Failed to map field ${tsName ? `${tsName} (${fieldNameOrId})` : fieldNameOrId} from Airtable`);
         }
     });
     return Object.assign(item, { id: record.id });
@@ -71,13 +79,13 @@ const mapRecordTypeAirtableToTs = (tsTypes, record) => {
  * @param tsRecord TypeScript object to convert.
  * @example { a: 'Some text', b: 123, c: false, d: 'rec123' }
  *
- * @param airtableTable An Airtable table.
+ * @param airtableTsTable An Airtable table.
  * @example { fields: { a: 'singleLineText', b: 'number', c: 'checkbox', d: 'multipleRecordLinks' }, ... }
  *
  * @returns An Airtable FieldSet. Throws if cannot coerce to requested type.
  * @example { a: 'Some text', b: 123, d: ['rec123'] } // (c is an un-ticked checkbox, d is a multipleRecordLinks)
  */
-const mapRecordTypeTsToAirtable = (tsTypes, tsRecord, airtableTable) => {
+const mapRecordTypeTsToAirtable = (table, tsTypes, tsRecord, airtableTsTable) => {
     const item = {};
     Object.entries(tsTypes).forEach(([fieldNameOrId, tsType]) => {
         const value = tsRecord[fieldNameOrId];
@@ -87,12 +95,21 @@ const mapRecordTypeTsToAirtable = (tsTypes, tsRecord, airtableTable) => {
         }
         if (!(0, typeUtils_1.matchesType)(value, tsType)) {
             // This should be unreachable because of our types
-            throw new Error(`[airtable-ts] Expected field ${airtableTable.name}.${fieldNameOrId} to match type \`${tsType}\` but got value \`${JSON.stringify(value)}\`. This should never happen in normal operation as it should be caught before this point.`);
+            throw new AirtableTsError_1.AirtableTsError({
+                message: `Type mismatch for field '${fieldNameOrId}': expected ${tsType} but got a ${typeof value}.`,
+                type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+                suggestion: 'Ensure the value matches the expected type in your schema definition.',
+            });
         }
         // eslint-disable-next-line no-underscore-dangle
-        const fieldDefinition = airtableTable.fields.find((f) => f.id === fieldNameOrId || f.name === fieldNameOrId);
+        const fieldDefinition = airtableTsTable.fields.find((f) => f.id === fieldNameOrId || f.name === fieldNameOrId);
         if (!fieldDefinition) {
-            throw new Error(`[airtable-ts] Failed to get Airtable field ${fieldNameOrId}`);
+            const tsName = table.mappings ? Object.entries(table.mappings).find((e) => e[1] === fieldNameOrId)?.[0] : undefined;
+            throw new AirtableTsError_1.AirtableTsError({
+                message: `Field ${tsName ? `${tsName} (${fieldNameOrId})` : fieldNameOrId} does not exist in the Airtable table.`,
+                type: AirtableTsError_1.ErrorType.RESOURCE_NOT_FOUND,
+                suggestion: 'Verify that the field exists in your Airtable base and that you are using the correct field name or ID.',
+            });
         }
         try {
             const { toAirtable } = getMapper(tsType, fieldDefinition.type);
@@ -100,29 +117,34 @@ const mapRecordTypeTsToAirtable = (tsTypes, tsRecord, airtableTable) => {
             item[fieldNameOrId] = toAirtable(value);
         }
         catch (error) {
-            if (error instanceof Error) {
-                // eslint-disable-next-line no-underscore-dangle
-                error.message = `Failed to map field ${airtableTable.name}.${fieldNameOrId}: ${error.message}`;
-                // eslint-disable-next-line no-underscore-dangle
-                error.stack = `Error: Failed to map field ${airtableTable.name}.${fieldNameOrId}: ${error.stack?.startsWith('Error: ') ? error.stack.slice('Error: '.length) : error.stack}`;
-            }
-            throw error;
+            const tsName = table.mappings ? Object.entries(table.mappings).find((e) => e[1] === fieldNameOrId)?.[0] : undefined;
+            throw (0, AirtableTsError_1.prependError)(error, `Failed to map field ${tsName ? `${tsName} (${fieldNameOrId})` : fieldNameOrId} to Airtable`);
         }
     });
     return Object.assign(item, { id: tsRecord.id });
 };
 const mapRecordFromAirtable = (table, record) => {
-    const tsTypes = (0, typeUtils_1.airtableFieldNameTsTypes)(table);
-    const tsRecord = mapRecordTypeAirtableToTs(tsTypes, record);
-    const mappedRecord = (0, nameMapper_1.mapRecordFieldNamesAirtableToTs)(table, tsRecord);
-    return mappedRecord;
+    try {
+        const tsTypes = (0, typeUtils_1.airtableFieldNameTsTypes)(table);
+        const tsRecord = mapRecordTypeAirtableToTs(table, tsTypes, record);
+        const mappedRecord = (0, nameMapper_1.mapRecordFieldNamesAirtableToTs)(table, tsRecord);
+        return mappedRecord;
+    }
+    catch (error) {
+        throw (0, AirtableTsError_1.prependError)(error, `Failed to map record from Airtable format for table '${table.name}' (${table.tableId}) and record ${record.id}`);
+    }
 };
 exports.mapRecordFromAirtable = mapRecordFromAirtable;
-const mapRecordToAirtable = (table, item, airtableTable) => {
-    const mappedItem = (0, nameMapper_1.mapRecordFieldNamesTsToAirtable)(table, item);
-    const tsTypes = (0, typeUtils_1.airtableFieldNameTsTypes)(table);
-    const fieldSet = mapRecordTypeTsToAirtable(tsTypes, mappedItem, airtableTable);
-    return fieldSet;
+const mapRecordToAirtable = (table, item, airtableTsTable) => {
+    try {
+        const mappedItem = (0, nameMapper_1.mapRecordFieldNamesTsToAirtable)(table, item);
+        const tsTypes = (0, typeUtils_1.airtableFieldNameTsTypes)(table);
+        const fieldSet = mapRecordTypeTsToAirtable(table, tsTypes, mappedItem, airtableTsTable);
+        return fieldSet;
+    }
+    catch (error) {
+        throw (0, AirtableTsError_1.prependError)(error, `Failed to map record to Airtable format for table '${table.name}' (${table.tableId})`);
+    }
 };
 exports.mapRecordToAirtable = mapRecordToAirtable;
 exports.visibleForTesting = {

package/dist/mapping/typeUtils.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.airtableFieldNameTsTypes = exports.matchesType = exports.parseType = void 0;
+const AirtableTsError_1 = require("../AirtableTsError");
 const parseType = (t) => {
     if (t.endsWith('[] | null')) {
         return {
@@ -74,7 +75,10 @@ const arrayToSingleType = (tsType) => {
     if (tsType.endsWith('[]')) {
         return tsType.slice(0, -'[]'.length);
     }
-    throw new Error(`[airtable-ts] Not an array type: ${tsType}`);
+    throw new AirtableTsError_1.AirtableTsError({
+        message: `The type '${tsType}' is not an array type.`,
+        type: AirtableTsError_1.ErrorType.SCHEMA_VALIDATION,
+    });
 };
 /**
  * Constructs a TypeScript object type definition given a table definition
@@ -98,13 +102,18 @@ const airtableFieldNameTsTypes = (table) => {
     const schemaEntries = Object.entries(table.schema);
     return Object.fromEntries(schemaEntries.map(([outputFieldName, tsType]) => {
         const mappingToAirtable = table.mappings?.[outputFieldName];
-        if (!mappingToAirtable) {
-            return [[outputFieldName, tsType]];
+        try {
+            if (!mappingToAirtable) {
+                return [[outputFieldName, tsType]];
+            }
+            if (Array.isArray(mappingToAirtable)) {
+                return mappingToAirtable.map((airtableFieldName) => [airtableFieldName, arrayToSingleType(tsType)]);
+            }
+            return [[mappingToAirtable, tsType]];
         }
-        if (Array.isArray(mappingToAirtable)) {
-            return mappingToAirtable.map((airtableFieldName) => [airtableFieldName, arrayToSingleType(tsType)]);
+        catch (error) {
+            throw (0, AirtableTsError_1.prependError)(error, `Error with field ${JSON.stringify(outputFieldName)} (${mappingToAirtable})`);
         }
-        return [[mappingToAirtable, tsType]];
     }).flat(1));
 };
 exports.airtableFieldNameTsTypes = airtableFieldNameTsTypes;

package/dist/types.d.ts

@@ -1,13 +1,17 @@
 import type { FieldSet, Table as AirtableSdkTable, Record as AirtableSdkRecord, AirtableOptions } from 'airtable';
+import { QueryParams } from 'airtable/lib/query_params';
+import { Item, Table } from './mapping/typeUtils';
 export type AirtableRecord = Omit<AirtableSdkRecord<FieldSet>, '_table'> & {
-    _table: AirtableTable;
+    _table: AirtableTsTable;
 };
-export type AirtableTable = AirtableSdkTable<FieldSet> & {
+export type AirtableTsTable<T extends Item = Item> = AirtableSdkTable<FieldSet> & {
     fields: {
         id: string;
         name: string;
         type: string;
     }[];
+    tsDefinition: Table<T>;
+    __brand?: T;
 };
 interface AirtableTsSpecificOptions {
     /** The Airtable base schema is used to determine the appropriate type mapper for the field type (for example converting a number to a string representing a date is different to converting a number to a singleLineText). For performance reasons, airtable-ts caches base schemas so we don't refetch it for every request. Note that we always still do validation against the expected type at runtime so the library is always type-safe. @default 120_000 */
@@ -15,4 +19,5 @@ interface AirtableTsSpecificOptions {
 }
 export type AirtableTsOptions = AirtableOptions & AirtableTsSpecificOptions;
 export type CompleteAirtableTsOptions = AirtableTsOptions & Required<AirtableTsSpecificOptions>;
+export type ScanParams = Omit<QueryParams<unknown>, 'fields' | 'cellFormat' | 'method' | 'returnFieldsByFieldId' | 'pageSize' | 'offset'>;
 export {};

package/dist/wrapToCatchAirtableErrors.d.ts

@@ -0,0 +1,13 @@
+import AirtableError from 'airtable/lib/airtable_error';
+export declare class WrappedAirtableError extends Error {
+    /** The original error thrown by Airtable.js */
+    originalError: AirtableError;
+    /** The error type from Airtable.js */
+    error?: string;
+    /** The HTTP status code if applicable */
+    statusCode?: number;
+    constructor(originalError: AirtableError);
+}
+export declare const wrapToCatchAirtableErrors: <T extends {
+    prototype: object;
+}>(c: T) => void;

package/dist/wrapToCatchAirtableErrors.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapToCatchAirtableErrors = exports.WrappedAirtableError = void 0;
+const airtable_error_1 = __importDefault(require("airtable/lib/airtable_error"));
+class WrappedAirtableError extends Error {
+    /** The original error thrown by Airtable.js */
+    originalError;
+    /** The error type from Airtable.js */
+    error;
+    /** The HTTP status code if applicable */
+    statusCode;
+    constructor(originalError) {
+        super(originalError.message);
+        this.name = 'WrappedAirtableError';
+        this.originalError = originalError;
+        this.error = originalError.error;
+        this.statusCode = originalError.statusCode;
+    }
+}
+exports.WrappedAirtableError = WrappedAirtableError;
+/**
+ * Wraps any error thrown that isn't a proper Error object to ensure it has a stack trace for debugging.
+ * @see https://github.com/Airtable/airtable.js/issues/294
+ */
+function wrapAirtableError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    if (error instanceof airtable_error_1.default) {
+        return new WrappedAirtableError(error);
+    }
+    return new Error(String(error));
+}
+const wrapToCatchAirtableErrors = (c) => {
+    // Cast to any to bypass TypeScript's type checking, as unfortunately this is too funky for TypeScript
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const prototype = c.prototype;
+    const methods = Object.getOwnPropertyNames(prototype).filter((prop) => {
+        return prop !== 'constructor' && typeof prototype[prop] === 'function';
+    });
+    methods.forEach((method) => {
+        const original = prototype[method];
+        if (typeof original === 'function') {
+            // eslint-disable-next-line func-names
+            prototype[method] = function (...args) {
+                try {
+                    const result = original.apply(this, args);
+                    if (result instanceof Promise) {
+                        return result.catch((error) => {
+                            throw wrapAirtableError(error);
+                        });
+                    }
+                    return result;
+                }
+                catch (error) {
+                    throw wrapAirtableError(error);
+                }
+            };
+        }
+    });
+};
+exports.wrapToCatchAirtableErrors = wrapToCatchAirtableErrors;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "airtable-ts",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A type-safe Airtable SDK",
   "license": "MIT",
   "author": "Adam Jones (domdomegg)",

package/dist/getAirtableTable.d.ts

@@ -1,4 +0,0 @@
-import Airtable from 'airtable';
-import { Item, Table } from './mapping/typeUtils';
-import { AirtableTable, CompleteAirtableTsOptions } from './types';
-export declare const getAirtableTable: <T extends Item>(airtable: Airtable, table: Table<T>, options: CompleteAirtableTsOptions) => Promise<AirtableTable>;

package/dist/getAirtableTable.js

@@ -1,60 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getAirtableTable = void 0;
-const axios_1 = __importDefault(require("axios"));
-const getAirtableTable = async (airtable, table, options) => {
-    const airtableTable = airtable.base(table.baseId).table(table.tableId);
-    // We need the schema so we know which type mapper to use.
-    // Even if we were inferring a type mapper from the schema, we'd still have to
-    // do this as otherwise we can't distinguish a column with all null values from
-    // a column that is missing entirely. We'd like to do that as for safety, we'd
-    // rather throw an error if the column is missing entirely; this suggests a
-    // misconfiguration. But an all-null column is okay. The particular case that
-    // this is likely for is checkbox columns.
-    const baseSchema = await getAirtableBaseSchema(table.baseId, options);
-    const tableDefinition = baseSchema.find((t) => t.id === table.tableId);
-    if (!tableDefinition) {
-        throw new Error(`[airtable-ts] Failed to find table ${table.tableId} in base ${table.baseId}`);
-    }
-    return Object.assign(airtableTable, { fields: tableDefinition.fields });
-};
-exports.getAirtableTable = getAirtableTable;
-const baseSchemaCache = new Map();
-/**
- * Get the schemas from the cache or Airtable API for the tables in the given base.
- * @see https://airtable.com/developers/web/api/get-base-schema
- * @param baseId The base id to get the schemas for
- */
-const getAirtableBaseSchema = async (baseId, options) => {
-    const fromCache = baseSchemaCache.get(baseId);
-    if (fromCache && Date.now() - fromCache.at < options.baseSchemaCacheDurationMs) {
-        return fromCache.data;
-    }
-    // eslint-disable-next-line no-underscore-dangle
-    if (!options.apiKey) {
-        throw new Error('[airtable-ts] Missing API key');
-    }
-    const res = await (0, axios_1.default)({
-        baseURL: options.endpointUrl ?? 'https://api.airtable.com',
-        url: `/v0/meta/bases/${baseId}/tables`,
-        ...(options.requestTimeout ? { timeout: options.requestTimeout } : {}),
-        headers: {
-            // eslint-disable-next-line no-underscore-dangle
-            Authorization: `Bearer ${options.apiKey}`,
-            ...options.customHeaders,
-        },
-    });
-    const baseSchema = res.data.tables;
-    if (baseSchemaCache.size > 100) {
-        baseSchemaCache.clear();
-        // If you're seeing this warning, then we probably either need to:
-        // - Update the maximum limit before clearing the cache, provided we have memory headroom; or
-        // - Use a last recently used cache or similar
-        console.warn('[airtable-ts] baseSchemaCache cleared to avoid a memory leak: this code is not currently optimized for accessing over 100 different bases from a single instance');
-    }
-    baseSchemaCache.set(baseId, { at: Date.now(), data: baseSchema });
-    return baseSchema;
-};