airtable-ts 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Adam Jones (domdomegg)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# 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()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#static_methods) 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.
+
+## Usage
+
+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
+  apiKey: 'pat1234.abcdef',
+});
+
+export const studentTable: Table<{ id: string, name: string, classes: string[] }> = {
+  name: 'student',
+  baseId: 'app1234',
+  tableId: 'tbl1234',
+  schema: { name: 'string', classes: 'string[]' },
+};
+
+export const classTable: Table<{ id: string, name: string }> = {
+  name: 'class',
+  baseId: 'app1234',
+  tableId: 'tbl4567',
+  schema: { name: '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', name: 'Adam' });
+await db.remove(studentTable, 'rec5678');
+
+// Or for a more involved example:
+async function prefixNameOfFirstClassOfFirstStudent(namePrefix: 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 newName = namePrefix + currentClass.name;
+  await db.update(classTable, { id: currentClass.id, name: newName });
+}
+
+// And should you ever need it, access to the raw Airtable JS SDK
+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](https://semver.org/).
+
+To release:
+
+1. Use `npm version <major | minor | patch>` 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.

package/dist/assertMatchesSchema.d.ts

@@ -0,0 +1,12 @@
+import { Item, Table } from './mapping/typeUtils';
+/**
+ * In theory, this should never catch stuff because our type mapping logic should
+ * verify the types are compatible.
+ *
+ * "In theory, there is no difference between theory and practice. But in practice, there is."
+ *   ~ Benjamin Brewster, probably: https://quoteinvestigator.com/2018/04/14/theory/
+ *
+ * @param table
+ * @param data
+ */
+export declare function assertMatchesSchema<T extends Item>(table: Table<T>, data: unknown, mode?: 'full' | 'partial'): asserts data is T;

package/dist/assertMatchesSchema.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertMatchesSchema = void 0;
+const typeUtils_1 = require("./mapping/typeUtils");
+// In theory, this should never catch stuff because our type mapping logic should
+// verify the types are compatible. However, "In theory there is no difference
+// between theory and practice - in practice there is"
+/**
+ * In theory, this should never catch stuff because our type mapping logic should
+ * verify the types are compatible.
+ *
+ * "In theory, there is no difference between theory and practice. But in practice, there is."
+ *   ~ Benjamin Brewster, probably: https://quoteinvestigator.com/2018/04/14/theory/
+ *
+ * @param table
+ * @param data
+ */
+function assertMatchesSchema(table, data, mode = 'full') {
+    if (typeof data !== 'object' || data === null) {
+        throw new Error(`[airtable-ts] Item for ${table.name} is not an object`);
+    }
+    Object.entries(table.schema).forEach(([fieldName, type]) => {
+        const value = data[fieldName];
+        if (value === undefined) {
+            if (mode === 'partial') {
+                return;
+            }
+            throw new Error(`[airtable-ts] Item for ${table.name} table is missing field '${fieldName}' (expected ${type})`);
+        }
+        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})`);
+        }
+    });
+}
+exports.assertMatchesSchema = assertMatchesSchema;

package/dist/getAirtableTable.d.ts

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,60 @@
+"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;
+};

package/dist/getFields.d.ts

@@ -0,0 +1,2 @@
+import { Item, Table } from './mapping/typeUtils';
+export declare const getFields: (table: Table<Item>) => string[];

package/dist/getFields.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFields = void 0;
+const getFields = (table) => {
+    if (table.mappings) {
+        return Object.values(table.mappings).flat();
+    }
+    return Object.keys(table.schema);
+};
+exports.getFields = getFields;

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+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: 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<T>;
+}
+export type ScanParams = Omit<QueryParams<unknown>, 'fields' | 'cellFormat' | 'method' | 'returnFieldsByFieldId' | 'pageSize' | 'offset'>;
+export type { AirtableTsOptions } from './types';
+export type { Item, Table } from './mapping/typeUtils';

package/dist/index.js

@@ -0,0 +1,64 @@
+"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 }, 'partial');
+        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 (0, recordMapper_1.mapRecordFromAirtable)(table, record);
+    }
+}
+exports.AirtableTs = AirtableTs;

package/dist/mapping/fieldMappers.d.ts

@@ -0,0 +1,11 @@
+import { AirtableTypeString, FromAirtableTypeString, FromTsTypeString, TsTypeString } from './typeUtils';
+type Mapper = {
+    [T in TsTypeString]?: {
+        [A in AirtableTypeString]?: {
+            toAirtable: (value: FromTsTypeString<T>) => FromAirtableTypeString<A>;
+            fromAirtable: (value: FromAirtableTypeString<A> | null | undefined) => FromTsTypeString<T>;
+        };
+    };
+};
+export declare const fieldMappers: Mapper;
+export {};

package/dist/mapping/fieldMappers.js

@@ -0,0 +1,296 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fieldMappers = void 0;
+const required = (value) => {
+    if (value === null || value === undefined) {
+        throw new Error('[airtable-ts] Missing required value');
+    }
+    return value;
+};
+const fallbackMapperPair = (toFallback, fromFallback) => ({
+    toAirtable: (value) => value ?? toFallback,
+    fromAirtable: (value) => value ?? fromFallback,
+});
+const requiredMapperPair = {
+    toAirtable: (value) => required(value),
+    fromAirtable: (value) => required(value),
+};
+exports.fieldMappers = {
+    string: {
+        singleLineText: fallbackMapperPair('', ''),
+        email: fallbackMapperPair('', ''),
+        url: fallbackMapperPair('', ''),
+        multilineText: fallbackMapperPair('', ''),
+        richText: fallbackMapperPair('', ''),
+        phoneNumber: fallbackMapperPair('', ''),
+        multipleRecordLinks: {
+            toAirtable: (value) => {
+                return [value];
+            },
+            fromAirtable: (value) => {
+                if (!value) {
+                    throw new Error('[airtable-ts] Failed to coerce multipleRecordLinks type field to a single string, as it was blank');
+                }
+                if (value.length !== 1) {
+                    throw new Error(`[airtable-ts] Can't coerce multipleRecordLinks to a single string, as there were ${value?.length} entries`);
+                }
+                return value[0];
+            },
+        },
+        dateTime: {
+            toAirtable: (value) => {
+                const date = new Date(value);
+                if (Number.isNaN(date.getTime())) {
+                    throw new Error('[airtable-ts] Invalid dateTime string');
+                }
+                return date.toJSON();
+            },
+            fromAirtable: (value) => {
+                const date = new Date(value ?? '');
+                if (Number.isNaN(date.getTime())) {
+                    throw new Error('[airtable-ts] Invalid dateTime string');
+                }
+                return date.toJSON();
+            },
+        },
+        multipleLookupValues: {
+            toAirtable: () => { throw new Error('[airtable-ts] multipleLookupValues type field is readonly'); },
+            fromAirtable: (value) => {
+                if (!value) {
+                    throw new Error('[airtable-ts] Failed to coerce multipleLookupValues type field to a single string, as it was blank');
+                }
+                if (value.length !== 1) {
+                    throw new Error(`[airtable-ts] Can't coerce multipleLookupValues to a single string, as there were ${value?.length} entries`);
+                }
+                if (typeof value[0] !== 'string') {
+                    throw new Error(`[airtable-ts] Can't coerce singular multipleLookupValues to a single string, as it was of type ${typeof value[0]}`);
+                }
+                return value[0];
+            },
+        },
+    },
+    'string | null': {
+        singleLineText: fallbackMapperPair(null, null),
+        email: fallbackMapperPair(null, null),
+        url: fallbackMapperPair(null, null),
+        multilineText: fallbackMapperPair(null, null),
+        richText: fallbackMapperPair(null, null),
+        phoneNumber: fallbackMapperPair(null, null),
+        multipleRecordLinks: {
+            toAirtable: (value) => {
+                return value ? [value] : [];
+            },
+            fromAirtable: (value) => {
+                if (!value || value.length === 0) {
+                    return null;
+                }
+                if (value.length !== 1) {
+                    throw new Error(`[airtable-ts] Can't coerce multipleRecordLinks to a single string, as there were ${value?.length} entries`);
+                }
+                return value[0];
+            },
+        },
+        dateTime: {
+            toAirtable: (value) => {
+                if (value === null)
+                    return null;
+                const date = new Date(value);
+                if (Number.isNaN(date.getTime())) {
+                    throw new Error('[airtable-ts] Invalid dateTime');
+                }
+                return date.toJSON();
+            },
+            fromAirtable: (value) => {
+                if (value === null || value === undefined)
+                    return null;
+                const date = new Date(value);
+                if (Number.isNaN(date.getTime())) {
+                    throw new Error('[airtable-ts] Invalid dateTime');
+                }
+                return date.toJSON();
+            },
+        },
+        multipleLookupValues: {
+            toAirtable: () => { throw new Error('[airtable-ts] multipleLookupValues type field is readonly'); },
+            fromAirtable: (value) => {
+                if (!value || value.length === 0) {
+                    return null;
+                }
+                if (value.length !== 1) {
+                    throw new Error(`[airtable-ts] Can't coerce multipleLookupValues to a single string, as there were ${value?.length} entries`);
+                }
+                if (typeof value[0] !== 'string') {
+                    throw new Error(`[airtable-ts] Can't coerce singular multipleLookupValues to a single string, as it was of type ${typeof value[0]}`);
+                }
+                return value[0];
+            },
+        },
+    },
+    boolean: {
+        checkbox: fallbackMapperPair(false, false),
+        multipleLookupValues: {
+            toAirtable: () => { throw new Error('[airtable-ts] multipleLookupValues type field is readonly'); },
+            fromAirtable: (value) => {
+                if (!value) {
+                    throw new Error('[airtable-ts] Failed to coerce multipleLookupValues type field to a single boolean, as it was blank');
+                }
+                if (value.length !== 1) {
+                    throw new Error(`[airtable-ts] Can't coerce multipleLookupValues to a single boolean, as there were ${value?.length} entries`);
+                }
+                if (typeof value[0] !== 'boolean') {
+                    throw new Error(`[airtable-ts] Can't coerce singular multipleLookupValues to a single boolean, as it was of type ${typeof value[0]}`);
+                }
+                return value[0];
+            },
+        },
+    },
+    'boolean | null': {
+        checkbox: fallbackMapperPair(null, null),
+        multipleLookupValues: {
+            toAirtable: () => { throw new Error('[airtable-ts] multipleLookupValues type field is readonly'); },
+            fromAirtable: (value) => {
+                if (!value || value.length === 0) {
+                    return null;
+                }
+                if (value.length !== 1) {
+                    throw new Error(`[airtable-ts] Can't coerce multipleLookupValues to a single boolean, as there were ${value?.length} entries`);
+                }
+                if (typeof value[0] !== 'boolean') {
+                    throw new Error(`[airtable-ts] Can't coerce singular multipleLookupValues to a single boolean, as it was of type ${typeof value[0]}`);
+                }
+                return value[0];
+            },
+        },
+    },
+    number: {
+        number: requiredMapperPair,
+        percent: requiredMapperPair,
+        currency: requiredMapperPair,
+        rating: requiredMapperPair,
+        duration: requiredMapperPair,
+        count: {
+            toAirtable: () => { throw new Error('[airtable-ts] count type field is readonly'); },
+            fromAirtable: (value) => required(value),
+        },
+        autoNumber: {
+            toAirtable: () => { throw new Error('[airtable-ts] autoNumber type field is readonly'); },
+            fromAirtable: (value) => required(value),
+        },
+        // Number assumed to be unix time in seconds
+        dateTime: {
+            toAirtable: (value) => {
+                const date = new Date(value * 1000);
+                if (Number.isNaN(date.getTime())) {
+                    throw new Error('[airtable-ts] Invalid dateTime');
+                }
+                return date.toJSON();
+            },
+            fromAirtable: (value) => {
+                const date = new Date(value ?? '');
+                if (Number.isNaN(date.getTime())) {
+                    throw new Error('[airtable-ts] Invalid dateTime');
+                }
+                return Math.floor(date.getTime() / 1000);
+            },
+        },
+        multipleLookupValues: {
+            toAirtable: () => { throw new Error('[airtable-ts] multipleLookupValues type field is readonly'); },
+            fromAirtable: (value) => {
+                if (!value) {
+                    throw new Error('[airtable-ts] Failed to coerce multipleLookupValues type field to a single number, as it was blank');
+                }
+                if (value.length !== 1) {
+                    throw new Error(`[airtable-ts] Can't coerce multipleLookupValues to a single number, as there were ${value?.length} entries`);
+                }
+                if (typeof value[0] !== 'number') {
+                    throw new Error(`[airtable-ts] Can't coerce singular multipleLookupValues to a single number, as it was of type ${typeof value[0]}`);
+                }
+                return value[0];
+            },
+        },
+    },
+    'number | null': {
+        number: fallbackMapperPair(null, null),
+        percent: fallbackMapperPair(null, null),
+        currency: fallbackMapperPair(null, null),
+        rating: fallbackMapperPair(null, null),
+        duration: fallbackMapperPair(null, null),
+        count: {
+            fromAirtable: (value) => value ?? null,
+            toAirtable: () => { throw new Error('[airtable-ts] count type field is readonly'); },
+        },
+        autoNumber: {
+            fromAirtable: (value) => value ?? null,
+            toAirtable: () => { throw new Error('[airtable-ts] autoNumber field is readonly'); },
+        },
+        // Number assumed to be unix time in seconds
+        dateTime: {
+            toAirtable: (value) => {
+                if (value === null)
+                    return null;
+                const date = new Date(value * 1000);
+                if (Number.isNaN(date.getTime())) {
+                    throw new Error('[airtable-ts] Invalid dateTime');
+                }
+                return date.toJSON();
+            },
+            fromAirtable: (value) => {
+                if (value === null || value === undefined)
+                    return null;
+                const date = new Date(value);
+                if (Number.isNaN(date.getTime())) {
+                    throw new Error('[airtable-ts] Invalid dateTime');
+                }
+                return Math.floor(date.getTime() / 1000);
+            },
+        },
+        multipleLookupValues: {
+            toAirtable: () => { throw new Error('[airtable-ts] multipleLookupValues type field is readonly'); },
+            fromAirtable: (value) => {
+                if (!value || value.length === 0) {
+                    return null;
+                }
+                if (value.length !== 1) {
+                    throw new Error(`[airtable-ts] Can't coerce multipleLookupValues to a single number, as there were ${value?.length} entries`);
+                }
+                if (typeof value[0] !== 'number') {
+                    throw new Error(`[airtable-ts] Can't coerce singular multipleLookupValues to a single number, as it was of type ${typeof value[0]}`);
+                }
+                return value[0];
+            },
+        },
+    },
+    'string[]': {
+        multipleRecordLinks: fallbackMapperPair([], []),
+        multipleLookupValues: {
+            toAirtable: () => { throw new Error('[airtable-ts] multipleLookupValues type field is readonly'); },
+            fromAirtable: (value) => {
+                if (!Array.isArray(value)) {
+                    throw new Error('[airtable-ts] Failed to coerce multipleLookupValues type field to a string array, as it was not an array');
+                }
+                if (value.some((v) => typeof v !== 'string')) {
+                    throw new Error('[airtable-ts] Can\'t coerce multipleLookupValues to a string array, as it had non string type');
+                }
+                return value;
+            },
+        },
+    },
+    'string[] | null': {
+        multipleRecordLinks: fallbackMapperPair(null, null),
+        multipleLookupValues: {
+            toAirtable: () => { throw new Error('[airtable-ts] multipleLookupValues type field is readonly'); },
+            fromAirtable: (value) => {
+                if (!value && !Array.isArray(value)) {
+                    return null;
+                }
+                if (!Array.isArray(value)) {
+                    throw new Error('[airtable-ts] Failed to coerce multipleLookupValues type field to a string array, as it was not an array');
+                }
+                if (value.some((v) => typeof v !== 'string')) {
+                    throw new Error('[airtable-ts] Can\'t coerce multipleLookupValues to a string array, as it had non string type');
+                }
+                return value;
+            },
+        },
+    },
+};

package/dist/mapping/nameMapper.d.ts

@@ -0,0 +1,55 @@
+import { Item, Table, FromTsTypeString, TsTypeString } from './typeUtils';
+/**
+ * Maps a TS object (matching table.mappings) to another TS object (matching table.schema),
+ * mapping columns based on the table definition.
+ *
+ * @param table Table definition
+ * @example {
+ *            schema: { someProp: 'string', otherProps: 'number[]', another: 'boolean' },
+ *            mappings: { someProp: 'Some_Airtable_Field', otherProps: ['Field1', 'Field2'], another: 'another' },
+ *            ...
+ *          }
+ *
+ * @param tsRecord The TS object to map
+ * @example {
+ *            Some_Airtable_Field: 'abcd',
+ *            Field1: 314,
+ *            Field2: 159,
+ *            another: true,
+ *          }
+ *
+ * @returns The TS object mapped via the table.mappings
+ * @example {
+ *            someProp: 'abcd',
+ *            otherProps: [314, 159],
+ *            another: true,
+ *          }
+ */
+export declare const mapRecordFieldNamesAirtableToTs: <T extends Item>(table: Table<T>, tsRecord: Record<string, FromTsTypeString<TsTypeString>>) => T;
+/**
+ * Maps a TS object (matching table.schema) to another TS object (matching table.mappings),
+ * mapping columns based on the table definition.
+ *
+ * @param table Table definition
+ * @example {
+ *            schema: { someProp: 'string', otherProps: 'number[]', another: 'boolean' },
+ *            mappings: { someProp: 'Some_Airtable_Field', otherProps: ['Field1', 'Field2'] },
+ *            ...
+ *          }
+ *
+ * @param item The TS object to map
+ * @example {
+ *            someProp: 'abcd',
+ *            otherProps: [314, 159],
+ *            another: true,
+ *          }
+ *
+ * @returns The TS object mapped via the table.mappings
+ * @example {
+ *            Some_Airtable_Field: 'abcd',
+ *            Field1: 314,
+ *            Field2: 159,
+ *            another: true,
+ *          }
+ */
+export declare const mapRecordFieldNamesTsToAirtable: <T extends Item>(table: Table<T>, item: Partial<T>) => Record<string, FromTsTypeString<TsTypeString>>;

package/dist/mapping/nameMapper.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapRecordFieldNamesTsToAirtable = exports.mapRecordFieldNamesAirtableToTs = void 0;
+/**
+ * Maps a TS object (matching table.mappings) to another TS object (matching table.schema),
+ * mapping columns based on the table definition.
+ *
+ * @param table Table definition
+ * @example {
+ *            schema: { someProp: 'string', otherProps: 'number[]', another: 'boolean' },
+ *            mappings: { someProp: 'Some_Airtable_Field', otherProps: ['Field1', 'Field2'], another: 'another' },
+ *            ...
+ *          }
+ *
+ * @param tsRecord The TS object to map
+ * @example {
+ *            Some_Airtable_Field: 'abcd',
+ *            Field1: 314,
+ *            Field2: 159,
+ *            another: true,
+ *          }
+ *
+ * @returns The TS object mapped via the table.mappings
+ * @example {
+ *            someProp: 'abcd',
+ *            otherProps: [314, 159],
+ *            another: true,
+ *          }
+ */
+const mapRecordFieldNamesAirtableToTs = (table, tsRecord) => {
+    const schemaEntries = Object.entries(table.schema);
+    const item = Object.fromEntries(schemaEntries.map(([outputFieldName]) => {
+        const mappingToAirtable = table.mappings?.[outputFieldName];
+        if (!mappingToAirtable) {
+            return [outputFieldName, tsRecord[outputFieldName]];
+        }
+        if (Array.isArray(mappingToAirtable)) {
+            return [outputFieldName, mappingToAirtable.map((airtableFieldName) => tsRecord[airtableFieldName])];
+        }
+        return [outputFieldName, tsRecord[mappingToAirtable]];
+    }));
+    return Object.assign(item, { id: tsRecord['id'] });
+};
+exports.mapRecordFieldNamesAirtableToTs = mapRecordFieldNamesAirtableToTs;
+/**
+ * Maps a TS object (matching table.schema) to another TS object (matching table.mappings),
+ * mapping columns based on the table definition.
+ *
+ * @param table Table definition
+ * @example {
+ *            schema: { someProp: 'string', otherProps: 'number[]', another: 'boolean' },
+ *            mappings: { someProp: 'Some_Airtable_Field', otherProps: ['Field1', 'Field2'] },
+ *            ...
+ *          }
+ *
+ * @param item The TS object to map
+ * @example {
+ *            someProp: 'abcd',
+ *            otherProps: [314, 159],
+ *            another: true,
+ *          }
+ *
+ * @returns The TS object mapped via the table.mappings
+ * @example {
+ *            Some_Airtable_Field: 'abcd',
+ *            Field1: 314,
+ *            Field2: 159,
+ *            another: true,
+ *          }
+ */
+const mapRecordFieldNamesTsToAirtable = (table, item) => {
+    const schemaEntries = Object.entries(table.schema);
+    const tsRecord = Object.fromEntries(schemaEntries.map(([outputFieldName, tsType]) => {
+        const mappingToAirtable = table.mappings?.[outputFieldName];
+        if (!(outputFieldName in item)) {
+            // If we don't have the field, just skip: this allows us to support partial updates
+            return [];
+        }
+        const value = item[outputFieldName];
+        if (!mappingToAirtable) {
+            return [[outputFieldName, value]];
+        }
+        if (Array.isArray(mappingToAirtable)) {
+            if (value === null) {
+                if (tsType.endsWith('| null')) {
+                    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.`);
+            }
+            if (!Array.isArray(value)) {
+                throw new Error(`[airtable-ts] Got non-array type ${typeof value} for ${table.name}.${outputFieldName}, but expected ${table.schema[outputFieldName]}.`);
+            }
+            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.`);
+            }
+            return mappingToAirtable.map((airtableFieldName, index) => [airtableFieldName, value[index]]);
+        }
+        return [[mappingToAirtable, value]];
+    }).flat(1));
+    return Object.assign(tsRecord, { id: item.id });
+};
+exports.mapRecordFieldNamesTsToAirtable = mapRecordFieldNamesTsToAirtable;

package/dist/mapping/recordMapper.d.ts

@@ -0,0 +1,17 @@
+import { FieldSet } from 'airtable';
+import { AirtableRecord, AirtableTable } 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 visibleForTesting: {
+    mapRecordTypeAirtableToTs: <T extends {
+        [fieldName: string]: TsTypeString;
+    }>(tsTypes: T, record: AirtableRecord) => { [F in keyof T]: FromTsTypeString<T[F]>; } & {
+        id: string;
+    };
+    mapRecordTypeTsToAirtable: <T_1 extends {
+        [fieldName: string]: TsTypeString;
+    }, R extends { [K in keyof T_1]?: FromTsTypeString<T_1[K]>; } & {
+        id?: string;
+    }>(tsTypes: T_1, tsRecord: R, airtableTable: AirtableTable) => FieldSet;
+};

package/dist/mapping/recordMapper.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.visibleForTesting = exports.mapRecordToAirtable = exports.mapRecordFromAirtable = void 0;
+const fieldMappers_1 = require("./fieldMappers");
+const nameMapper_1 = require("./nameMapper");
+const typeUtils_1 = require("./typeUtils");
+/**
+ * This function coerces an Airtable record to a TypeScript object, given an
+ * object type definition.  It will do this using the field mappers on each
+ * field, based on the tsTypes and Airtable table schema (via the record).
+ * It does NOT change any property names.
+ *
+ * @param tsTypes TypeScript types for the record.
+ * @example { a: 'string', b: 'number', c: 'boolean', d: 'string' }
+ *
+ * @param record The Airtable record to convert.
+ * @example { id: 'rec012', a: 'Some text', b: 123, d: ['rec345'] } // (c is an un-ticked checkbox, d is a multipleRecordLinks)
+ *
+ * @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 item = {};
+    Object.entries(tsTypes).forEach(([fieldName, tsType]) => {
+        const value = record.fields[fieldName];
+        // eslint-disable-next-line no-underscore-dangle
+        const airtableType = record._table.fields.find((f) => f.name === fieldName)?.type;
+        if (!airtableType) {
+            throw new Error(`[airtable-ts] Failed to get airtable type for field ${fieldName}`);
+        }
+        const tsMapper = fieldMappers_1.fieldMappers[tsType];
+        if (!tsMapper) {
+            throw new Error(`[airtable-ts] No mappers for ts type ${tsType}`);
+        }
+        const specificMapper = tsMapper[airtableType]?.fromAirtable;
+        if (!specificMapper) {
+            // eslint-disable-next-line no-underscore-dangle
+            throw new Error(`[airtable-ts] Expected field ${record._table.name}.${fieldName} to be able to map to ts type ${tsType}, but got airtable type ${airtableType} which can't.`);
+        }
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            item[fieldName] = specificMapper(value);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                // eslint-disable-next-line no-underscore-dangle
+                error.message = `Failed to map field ${record._table.name}.${fieldName}: ${error.message}`;
+                // eslint-disable-next-line no-underscore-dangle
+                error.stack = `Error: Failed to map field ${record._table.name}.${fieldName}: ${error.stack?.startsWith('Error: ') ? error.stack.slice('Error: '.length) : error.stack}`;
+            }
+            throw error;
+        }
+    });
+    return Object.assign(item, { id: record.id });
+};
+/**
+ * This function coerces a TypeScript object to a Airtable record, given an
+ * Airtable table. It will do this using the field mappers on each field, based
+ * on the tsTypes and Airtable table schema.
+ * It does NOT change any property names.
+ *
+ * @param tsTypes TypeScript types for the record (necessary to handle nullables).
+ * @example { a: 'string', b: 'number', c: 'boolean', d: 'string' }
+ *
+ * @param tsRecord TypeScript object to convert.
+ * @example { a: 'Some text', b: 123, c: false, d: 'rec123' }
+ *
+ * @param airtableTable 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 item = {};
+    Object.entries(tsTypes).forEach(([fieldName, tsType]) => {
+        const value = tsRecord[fieldName];
+        if (!(fieldName in tsRecord)) {
+            // If we don't have the field, just skip: this allows us to support partial updates
+            return;
+        }
+        if (!(0, typeUtils_1.matchesType)(value, tsType)) {
+            // This should be unreachable because of our types
+            throw new Error(`[airtable-ts] Expected field ${airtableTable.name}.${fieldName} 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.`);
+        }
+        const airtableType = airtableTable.fields.find((f) => f.name === fieldName)?.type;
+        if (!airtableType) {
+            throw new Error(`[airtable-ts] Failed to get airtable type for field ${fieldName}`);
+        }
+        const tsMapper = fieldMappers_1.fieldMappers[tsType];
+        if (!tsMapper) {
+            throw new Error(`[airtable-ts] No mappers for ts type ${tsType}`);
+        }
+        const specificMapper = tsMapper[airtableType]?.toAirtable;
+        if (!specificMapper) {
+            throw new Error(`[airtable-ts] Expected field ${airtableTable.name}.${fieldName} to be able to map to airtable type \`${airtableType}\`, but got ts type \`${tsType}\` which can't.`);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        item[fieldName] = specificMapper(value);
+    });
+    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;
+};
+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;
+};
+exports.mapRecordToAirtable = mapRecordToAirtable;
+exports.visibleForTesting = {
+    mapRecordTypeAirtableToTs,
+    mapRecordTypeTsToAirtable,
+};

package/dist/mapping/typeUtils.d.ts

@@ -0,0 +1,71 @@
+export type TsTypeString = NonNullToString<any> | ToTsTypeString<any>;
+type NonNullToString<T> = T extends string ? 'string' : T extends number ? 'number' : T extends boolean ? 'boolean' : T extends number[] ? 'number[]' : T extends string[] ? 'string[]' : T extends boolean[] ? 'boolean[]' : never;
+export type ToTsTypeString<T> = null extends T ? `${NonNullToString<T>} | null` : NonNullToString<T>;
+export type FromTsTypeString<T> = T extends 'string' ? string : T extends 'string | null' ? string | null : T extends 'number' ? number : T extends 'number | null' ? number | null : T extends 'boolean' ? boolean : T extends 'boolean | null' ? boolean | null : T extends 'string[]' ? string[] : T extends 'string[] | null' ? string[] | null : T extends 'number[]' ? number[] : T extends 'number[] | null' ? number[] | null : T extends 'boolean[]' ? boolean[] : T extends 'boolean[] | null' ? boolean[] | null : never;
+export type AirtableTypeString = 'singleLineText' | 'email' | 'url' | 'multilineText' | 'phoneNumber' | 'checkbox' | 'number' | 'percent' | 'currency' | 'count' | 'autoNumber' | 'rating' | 'richText' | 'duration' | 'multipleRecordLinks' | 'dateTime' | 'multipleLookupValues';
+export type FromAirtableTypeString<T> = null | (T extends 'singleLineText' ? string : T extends 'email' ? string : T extends 'url' ? string : T extends 'multilineText' ? string : T extends 'richText' ? string : T extends 'phoneNumber' ? string : T extends 'checkbox' ? boolean : T extends 'number' ? number : T extends 'percent' ? number : T extends 'currency' ? number : T extends 'rating' ? number : T extends 'duration' ? number : T extends 'count' ? number : T extends 'autoNumber' ? number : T extends 'multipleRecordLinks' ? string[] : T extends 'multipleLookupValues' ? FromAirtableTypeString<any>[] : T extends 'dateTime' ? string : never);
+/**
+ * Verifies whether the given value is assignable to the given type
+ *
+ * @param value
+ * @example [1, 2, 3]
+ *
+ * @param tsType
+ * @example 'number[]'
+ *
+ * @returns
+ * @example true
+ */
+export declare const matchesType: (value: unknown, tsType: TsTypeString) => boolean;
+/**
+ * Constructs a TypeScript object type definition given a table definition
+ *
+ * @param table Table definition
+ * @example {
+ *            schema: { someProp: 'string', otherProps: 'number[]', another: 'boolean' },
+ *            mappings: { someProp: 'Some_Airtable_Field', otherProps: ['Field1', 'Field2'], another: 'another' },
+ *            ...
+ *          }
+ *
+ * @returns The TypeScript object type we expect the Airtable record to coerce to
+ * @example {
+ *            Some_Airtable_Field: 'string',
+ *            Field1: 'number',
+ *            Field2: 'number',
+ *            another: 'boolean',
+ *          }
+ */
+export declare const airtableFieldNameTsTypes: <T extends Item>(table: Table<T>) => Record<string, TsTypeString>;
+export type MappingValue<T> = T extends unknown[] ? string | string[] : string;
+export interface Item {
+    /** Represents the Airtable record id, @example "rec1234" */
+    id: string;
+}
+export interface Table<T extends Item> {
+    /** A simple name for the entities in this table, to be used in error messages @example "person" */
+    name: string;
+    /** The base id for this table. You can get this from the URL when accessing the table in the web UI. @example "app1234" */
+    baseId: string;
+    /** The table id for this table. You can get this from the URL when accessing the table in the web UI. @example "tbl1234" */
+    tableId: string;
+    /** The schema. We need to define this as a real object (rather than a type) because we do checks at run-time. You should usually be able to just take the autocomplete suggestions (provided you gave a TypeScript type already). */
+    schema: {
+        [k in keyof Omit<T, 'id'>]: ToTsTypeString<T[k]>;
+    };
+    /**
+     * Optional name mappings. This allows you to detach the schema names from the names you want to use in your code.
+     * @example
+     * export const personTable: Table<{ id: string, firstName: string }> = {
+     *   name: 'person', baseId: 'app1234', tableId: 'tbl1234',
+     *   schema: { firstName: 'string' },
+     *   // The field is named '[core] First Name' in the base. If this ever changes, we just need to update it here.
+     *   mappings: { firstName: '[core] First Name' },
+     * };
+     * const people = await db.scan(studentTable);
+     * const firstPersonsFirstName = people[0].firstName;
+     * */
+    mappings?: {
+        [k in keyof Omit<T, 'id'>]: MappingValue<T[k]>;
+    };
+}
+export {};

package/dist/mapping/typeUtils.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.airtableFieldNameTsTypes = exports.matchesType = void 0;
+const parseType = (t) => {
+    if (t.endsWith('[] | null')) {
+        return {
+            single: t.slice(0, -('[] | null'.length)),
+            array: true,
+            nullable: true,
+        };
+    }
+    if (t.endsWith('[]')) {
+        return {
+            single: t.slice(0, -('[]'.length)),
+            array: true,
+            nullable: false,
+        };
+    }
+    if (t.endsWith(' | null')) {
+        return {
+            single: t.slice(0, -(' | null'.length)),
+            array: false,
+            nullable: true,
+        };
+    }
+    return {
+        single: t,
+        array: false,
+        nullable: false,
+    };
+};
+/**
+ * Verifies whether the given value is assignable to the given type
+ *
+ * @param value
+ * @example [1, 2, 3]
+ *
+ * @param tsType
+ * @example 'number[]'
+ *
+ * @returns
+ * @example true
+ */
+const matchesType = (value, tsType) => {
+    const expectedType = parseType(tsType);
+    if (expectedType.nullable && value === null) {
+        return true;
+    }
+    if (!expectedType.array && typeof value === expectedType.single) {
+        return true;
+    }
+    return (expectedType.array
+        && Array.isArray(value)
+        && value.every((entry) => typeof entry === expectedType.single));
+};
+exports.matchesType = matchesType;
+/**
+ * Returns a single type for an array type
+ *
+ * @param tsType
+ * @example 'string[]'
+ *
+ * @returns
+ * @example 'string'
+ */
+const arrayToSingleType = (tsType) => {
+    if (tsType.endsWith('[] | null')) {
+        // This results in:
+        // string[] | null -> string | null
+        // Going the other way might not work - e.g. we'd get (string | null)[]
+        return `${tsType.slice(0, -'[] | null'.length)} | null`;
+    }
+    if (tsType.endsWith('[]')) {
+        return tsType.slice(0, -'[]'.length);
+    }
+    throw new Error(`[airtable-ts] Not an array type: ${tsType}`);
+};
+/**
+ * Constructs a TypeScript object type definition given a table definition
+ *
+ * @param table Table definition
+ * @example {
+ *            schema: { someProp: 'string', otherProps: 'number[]', another: 'boolean' },
+ *            mappings: { someProp: 'Some_Airtable_Field', otherProps: ['Field1', 'Field2'], another: 'another' },
+ *            ...
+ *          }
+ *
+ * @returns The TypeScript object type we expect the Airtable record to coerce to
+ * @example {
+ *            Some_Airtable_Field: 'string',
+ *            Field1: 'number',
+ *            Field2: 'number',
+ *            another: 'boolean',
+ *          }
+ */
+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]];
+        }
+        if (Array.isArray(mappingToAirtable)) {
+            return mappingToAirtable.map((airtableFieldName) => [airtableFieldName, arrayToSingleType(tsType)]);
+        }
+        return [[mappingToAirtable, tsType]];
+    }).flat(1));
+};
+exports.airtableFieldNameTsTypes = airtableFieldNameTsTypes;

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+import type { FieldSet, Table as AirtableSdkTable, Record as AirtableSdkRecord, AirtableOptions } from 'airtable';
+export type AirtableRecord = Omit<AirtableSdkRecord<FieldSet>, '_table'> & {
+    _table: AirtableTable;
+};
+export type AirtableTable = AirtableSdkTable<FieldSet> & {
+    fields: {
+        name: string;
+        type: string;
+    }[];
+};
+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 */
+    baseSchemaCacheDurationMs?: number;
+}
+export type AirtableTsOptions = AirtableOptions & AirtableTsSpecificOptions;
+export type CompleteAirtableTsOptions = AirtableTsOptions & Required<AirtableTsSpecificOptions>;
+export {};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "airtable-ts",
+  "version": "1.0.0",
+  "description": "A type-safe Airtable SDK",
+  "license": "MIT",
+  "author": "Adam Jones (domdomegg)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/domdomegg/airtable-ts.git"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "lint": "eslint --ext .js,.jsx,.ts,.tsx .",
+    "clean": "rm -rf dist",
+    "build": "tsc --project tsconfig.build.json",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "devDependencies": {
+    "@tsconfig/node-lts": "^20.1.0",
+    "@tsconfig/strictest": "^2.0.2",
+    "eslint": "^8.56.0",
+    "eslint-config-domdomegg": "^1.2.3",
+    "typescript": "^5.3.3",
+    "vitest": "^1.0.4"
+  },
+  "eslintConfig": {
+    "extends": [
+      "eslint-config-domdomegg"
+    ]
+  },
+  "dependencies": {
+    "airtable": "^0.12.2",
+    "axios": "^1.6.8"
+  }
+}