airtable-ts 1.2.0 → 1.3.1

package/README.md

@@ -27,21 +27,22 @@ const db = new AirtableTs({
   apiKey: 'pat1234.abcdef',
 });
 
-export const studentTable: Table<{ id: string, name: string, classes: string[] }> = {
+// Tip: use airtable-ts-codegen to autogenerate these from your Airtable base
+export const studentTable: Table<{ id: string, firstName: string, classes: string[] }> = {
   name: 'student',
   baseId: 'app1234',
   tableId: 'tbl1234',
-  schema: { name: 'string', classes: 'string[]' },
+  schema: { firstName: 'string', classes: 'string[]' },
   // optional: use mappings with field ids to prevent renamings breaking your app,
   //           or with field names to make handling renamings easy
-  mappings: { name: 'fld1234', classes: 'Classes student is enrolled in' },
+  mappings: { firstName: 'fld1234', classes: 'Classes student is enrolled in' },
 };
 
-export const classTable: Table<{ id: string, name: string }> = {
+export const classTable: Table<{ id: string, title: string }> = {
   name: 'class',
   baseId: 'app1234',
   tableId: 'tbl4567',
-  schema: { name: 'string' },
+  schema: { title: 'string' },
 };
 
 // Now we can get all the records in a table (a scan)
@@ -49,18 +50,18 @@ 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.update(studentTable, { id: 'rec1234', firstName: 'Adam' });
 await db.remove(studentTable, 'rec5678');
 
 // Or for a more involved example:
-async function prefixNameOfFirstClassOfFirstStudent(namePrefix: string) {
+async function prefixTitleOfFirstClassOfFirstStudent(prefix: string) {
   const students = await db.scan(studentTable);
   if (!students[0]) throw new Error('There are no students');
   if (!students[0].classes[0]) throw new Error('First student does not have a class');
 
   const currentClass = await db.get(classTable, students[0].classes[0]);
-  const newName = namePrefix + currentClass.name;
-  await db.update(classTable, { id: currentClass.id, name: newName });
+  const newTitle = prefix + currentClass.title;
+  await db.update(classTable, { id: currentClass.id, title: newTitle });
 }
 
 // And should you ever need it, access to the raw Airtable JS SDK

package/dist/assertMatchesSchema.js

@@ -12,7 +12,7 @@ const typeUtils_1 = require("./mapping/typeUtils");
  * @param table
  * @param data
  */
-function assertMatchesSchema(table, data, mode = 'full') {
+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`);
     }

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export declare class AirtableTs {
     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>;
+    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>;

package/dist/index.js

@@ -46,7 +46,7 @@ class AirtableTs {
         return (0, recordMapper_1.mapRecordFromAirtable)(table, record);
     }
     async update(table, data) {
-        (0, assertMatchesSchema_1.assertMatchesSchema)(table, { ...data }, 'partial');
+        (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));

package/dist/mapping/fieldMappers.d.ts

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

package/dist/mapping/fieldMappers.js

@@ -1,129 +1,56 @@
 "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 typeUtils_1 = require("./typeUtils");
 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: {
-        url: fallbackMapperPair('', ''),
-        email: fallbackMapperPair('', ''),
-        phoneNumber: fallbackMapperPair('', ''),
-        singleLineText: fallbackMapperPair('', ''),
-        multilineText: fallbackMapperPair('', ''),
-        richText: fallbackMapperPair('', ''),
-        singleSelect: fallbackMapperPair('', ''),
-        externalSyncSource: {
-            toAirtable: () => { throw new Error('[airtable-ts] externalSyncSource type field is readonly'); },
-            fromAirtable: (value) => value ?? '',
-        },
-        multipleSelects: {
-            toAirtable: (value) => {
-                return [value];
-            },
-            fromAirtable: (value) => {
-                if (!value) {
-                    throw new Error('[airtable-ts] Failed to coerce multipleSelects type field to a single string, as it was blank');
-                }
-                if (value.length !== 1) {
-                    throw new Error(`[airtable-ts] Can't coerce multipleSelects to a single string, as there were ${value?.length} entries`);
-                }
-                return value[0];
-            },
-        },
-        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];
-            },
-        },
-        date: {
-            toAirtable: (value) => {
-                const date = new Date(value);
-                if (Number.isNaN(date.getTime())) {
-                    throw new Error('[airtable-ts] Invalid date string');
-                }
-                return date.toJSON().slice(0, 10);
-            },
-            fromAirtable: (value) => {
-                const date = new Date(value ?? '');
-                if (Number.isNaN(date.getTime())) {
-                    throw new Error('[airtable-ts] Invalid date string');
-                }
-                return date.toJSON();
-            },
-        },
-        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] lookup type field is readonly'); },
-            fromAirtable: (value) => {
-                if (!value) {
-                    throw new Error('[airtable-ts] Failed to coerce lookup type field to a single string, as it was blank');
-                }
-                if (value.length !== 1) {
-                    throw new Error(`[airtable-ts] Can't coerce lookup to a single string, as there were ${value?.length} entries`);
-                }
-                if (typeof value[0] !== 'string') {
-                    throw new Error(`[airtable-ts] Can't coerce singular lookup to a single string, as it was of type ${typeof value[0]}`);
-                }
-                return value[0];
-            },
-        },
-        rollup: {
-            toAirtable: () => { throw new Error('[airtable-ts] rollup type field is readonly'); },
-            fromAirtable: (value) => {
-                if (typeof value === 'string')
-                    return value;
-                if (value === undefined || value === null)
-                    return '';
-                throw new Error(`[airtable-ts] Can't coerce rollup to a string, as it was of type ${typeof value}`);
-            },
-        },
-        formula: {
-            toAirtable: () => { throw new Error('[airtable-ts] formula type field is readonly'); },
-            fromAirtable: (value) => {
-                if (typeof value === 'string')
-                    return value;
-                if (value === undefined || value === null)
-                    return '';
-                throw new Error(`[airtable-ts] Can't coerce formula to a string, as it was of type ${typeof value}`);
-            },
-        },
+const dateTimeMapperPair = {
+    // Number assumed to be unix time in seconds
+    toAirtable: (value) => {
+        if (value === null)
+            return null;
+        const date = new Date(typeof value === 'number' ? value * 1000 : 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();
     },
+};
+const readonly = (airtableType) => () => { throw new Error(`[airtable-ts] ${airtableType} type field is readonly`); };
+const coerce = (airtableType, tsType) => (value) => {
+    const parsedType = (0, typeUtils_1.parseType)(tsType);
+    if (!parsedType.array && typeof value === parsedType.single) {
+        return value;
+    }
+    if (parsedType.array && Array.isArray(value) && value.every((v) => typeof v === parsedType.single)) {
+        return value;
+    }
+    if (parsedType.nullable && (value === undefined || value === null || (Array.isArray(value) && value.length === 0))) {
+        return null;
+    }
+    if (parsedType.array && typeof value === parsedType.single) {
+        return [value];
+    }
+    if (!parsedType.array && Array.isArray(value) && value.length === 1 && typeof value[0] === parsedType.single) {
+        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 Error(`[airtable-ts] Can't coerce ${airtableType} to a ${tsType}, as it was of type ${typeof value}`);
+};
+const stringOrNull = {
     'string | null': {
         url: fallbackMapperPair(null, null),
         email: fallbackMapperPair(null, null),
@@ -132,230 +59,57 @@ exports.fieldMappers = {
         multilineText: fallbackMapperPair(null, null),
         richText: fallbackMapperPair(null, null),
         singleSelect: fallbackMapperPair(null, null),
-        externalSyncSource: {
-            toAirtable: () => { throw new Error('[airtable-ts] externalSyncSource type field is readonly'); },
-            fromAirtable: (value) => value ?? null,
-        },
         multipleSelects: {
-            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 multipleSelects to a single string, as there were ${value?.length} entries`);
-                }
-                return value[0];
-            },
+            toAirtable: (value) => (value ? [value] : []),
+            fromAirtable: coerce('multipleSelects', 'string | 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];
-            },
+            toAirtable: (value) => (value ? [value] : []),
+            fromAirtable: coerce('multipleRecordLinks', 'string | null'),
         },
         date: {
-            toAirtable: (value) => {
-                if (value === null)
-                    return null;
-                const date = new Date(value);
-                if (Number.isNaN(date.getTime())) {
-                    throw new Error('[airtable-ts] Invalid date');
-                }
-                return date.toJSON().slice(0, 10);
-            },
-            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 date');
-                }
-                return date.toJSON();
-            },
-        },
-        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();
-            },
+            toAirtable: (value) => dateTimeMapperPair.toAirtable(value)?.slice(0, 10) ?? null,
+            fromAirtable: dateTimeMapperPair.fromAirtable,
         },
+        dateTime: dateTimeMapperPair,
+        createdTime: dateTimeMapperPair,
+        lastModifiedTime: dateTimeMapperPair,
         multipleLookupValues: {
-            toAirtable: () => { throw new Error('[airtable-ts] lookup 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 lookup to a single string, as there were ${value?.length} entries`);
-                }
-                if (typeof value[0] !== 'string') {
-                    throw new Error(`[airtable-ts] Can't coerce singular lookup to a single string, as it was of type ${typeof value[0]}`);
-                }
-                return value[0];
-            },
+            toAirtable: readonly('multipleLookupValues'),
+            fromAirtable: coerce('multipleLookupValues', 'string | null'),
+        },
+        externalSyncSource: {
+            toAirtable: readonly('externalSyncSource'),
+            fromAirtable: coerce('externalSyncSource', 'string | null'),
         },
         rollup: {
-            toAirtable: () => { throw new Error('[airtable-ts] rollup type field is readonly'); },
-            fromAirtable: (value) => {
-                if (typeof value === 'string')
-                    return value;
-                if (value === undefined || value === null)
-                    return null;
-                throw new Error(`[airtable-ts] Can't coerce rollup to a string, as it was of type ${typeof value}`);
-            },
+            toAirtable: readonly('rollup'),
+            fromAirtable: coerce('rollup', 'string | null'),
         },
         formula: {
-            toAirtable: () => { throw new Error('[airtable-ts] formula type field is readonly'); },
-            fromAirtable: (value) => {
-                if (typeof value === 'string')
-                    return value;
-                if (value === undefined || value === null)
-                    return null;
-                throw new Error(`[airtable-ts] Can't coerce formula to a string, as it was of type ${typeof value}`);
-            },
+            toAirtable: readonly('formula'),
+            fromAirtable: coerce('formula', 'string | null'),
         },
-    },
-    boolean: {
-        checkbox: fallbackMapperPair(false, false),
-        multipleLookupValues: {
-            toAirtable: () => { throw new Error('[airtable-ts] lookup type field is readonly'); },
-            fromAirtable: (value) => {
-                if (!value) {
-                    throw new Error('[airtable-ts] Failed to coerce lookup type field to a single boolean, as it was blank');
-                }
-                if (value.length !== 1) {
-                    throw new Error(`[airtable-ts] Can't coerce lookup to a single boolean, as there were ${value?.length} entries`);
-                }
-                if (typeof value[0] !== 'boolean') {
-                    throw new Error(`[airtable-ts] Can't coerce singular lookup to a single boolean, as it was of type ${typeof value[0]}`);
-                }
-                return value[0];
-            },
+        unknown: {
+            toAirtable: (value) => value,
+            fromAirtable: coerce('unknown', 'string | null'),
         },
     },
+};
+const booleanOrNull = {
     'boolean | null': {
         checkbox: fallbackMapperPair(null, null),
         multipleLookupValues: {
-            toAirtable: () => { throw new Error('[airtable-ts] lookup 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 lookup to a single boolean, as there were ${value?.length} entries`);
-                }
-                if (typeof value[0] !== 'boolean') {
-                    throw new Error(`[airtable-ts] Can't coerce singular lookup to a single boolean, as it was of type ${typeof value[0]}`);
-                }
-                return value[0];
-            },
+            toAirtable: readonly('multipleLookupValues'),
+            fromAirtable: coerce('multipleLookupValues', 'boolean | null'),
         },
-    },
-    number: {
-        number: requiredMapperPair,
-        rating: requiredMapperPair,
-        duration: requiredMapperPair,
-        currency: requiredMapperPair,
-        percent: 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
-        date: {
-            toAirtable: (value) => {
-                const date = new Date(value * 1000);
-                if (Number.isNaN(date.getTime())) {
-                    throw new Error('[airtable-ts] Invalid date');
-                }
-                return date.toJSON().slice(0, 10);
-            },
-            fromAirtable: (value) => {
-                const date = new Date(value ?? '');
-                if (Number.isNaN(date.getTime())) {
-                    throw new Error('[airtable-ts] Invalid date');
-                }
-                return Math.floor(date.getTime() / 1000);
-            },
-        },
-        // 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] lookup type field is readonly'); },
-            fromAirtable: (value) => {
-                if (!value) {
-                    throw new Error('[airtable-ts] Failed to coerce lookup type field to a single number, as it was blank');
-                }
-                if (value.length !== 1) {
-                    throw new Error(`[airtable-ts] Can't coerce lookup to a single number, as there were ${value?.length} entries`);
-                }
-                if (typeof value[0] !== 'number') {
-                    throw new Error(`[airtable-ts] Can't coerce singular lookup to a single number, as it was of type ${typeof value[0]}`);
-                }
-                return value[0];
-            },
-        },
-        rollup: {
-            toAirtable: () => { throw new Error('[airtable-ts] rollup type field is readonly'); },
-            fromAirtable: (value) => {
-                if (typeof value === 'number')
-                    return value;
-                throw new Error(`[airtable-ts] Can't coerce rollup to a number, as it was of type ${typeof value}`);
-            },
-        },
-        formula: {
-            toAirtable: () => { throw new Error('[airtable-ts] formula type field is readonly'); },
-            fromAirtable: (value) => {
-                if (typeof value === 'number')
-                    return value;
-                throw new Error(`[airtable-ts] Can't coerce formula to a number, as it was of type ${typeof value}`);
-            },
+        unknown: {
+            toAirtable: (value) => value,
+            fromAirtable: coerce('unknown', 'boolean | null'),
         },
     },
+};
+const numberOrNull = {
     'number | null': {
         number: fallbackMapperPair(null, null),
         rating: fallbackMapperPair(null, null),
@@ -364,150 +118,147 @@ exports.fieldMappers = {
         percent: fallbackMapperPair(null, null),
         count: {
             fromAirtable: (value) => value ?? null,
-            toAirtable: () => { throw new Error('[airtable-ts] count type field is readonly'); },
+            toAirtable: readonly('count'),
         },
         autoNumber: {
             fromAirtable: (value) => value ?? null,
-            toAirtable: () => { throw new Error('[airtable-ts] autoNumber field is readonly'); },
+            toAirtable: readonly('autoNumber'),
         },
-        // Number assumed to be unix time in seconds
         date: {
-            toAirtable: (value) => {
-                if (value === null)
+            toAirtable: (value) => dateTimeMapperPair.toAirtable(value)?.slice(0, 10) ?? null,
+            fromAirtable: (value) => {
+                const nullableValue = dateTimeMapperPair.fromAirtable(value);
+                if (nullableValue === null)
                     return null;
-                const date = new Date(value * 1000);
+                const date = new Date(nullableValue);
                 if (Number.isNaN(date.getTime())) {
                     throw new Error('[airtable-ts] Invalid date');
                 }
-                return date.toJSON().slice(0, 10);
+                return Math.floor(date.getTime() / 1000);
             },
+        },
+        dateTime: {
+            toAirtable: dateTimeMapperPair.toAirtable,
             fromAirtable: (value) => {
-                if (value === null || value === undefined)
+                const nullableValue = dateTimeMapperPair.fromAirtable(value);
+                if (nullableValue === null)
                     return null;
-                const date = new Date(value);
+                const date = new Date(nullableValue);
                 if (Number.isNaN(date.getTime())) {
                     throw new Error('[airtable-ts] Invalid date');
                 }
                 return Math.floor(date.getTime() / 1000);
             },
         },
-        // Number assumed to be unix time in seconds
-        dateTime: {
-            toAirtable: (value) => {
-                if (value === null)
+        createdTime: {
+            toAirtable: dateTimeMapperPair.toAirtable,
+            fromAirtable: (value) => {
+                const nullableValue = dateTimeMapperPair.fromAirtable(value);
+                if (nullableValue === null)
                     return null;
-                const date = new Date(value * 1000);
+                const date = new Date(nullableValue);
                 if (Number.isNaN(date.getTime())) {
-                    throw new Error('[airtable-ts] Invalid dateTime');
+                    throw new Error('[airtable-ts] Invalid date');
                 }
-                return date.toJSON();
+                return Math.floor(date.getTime() / 1000);
             },
+        },
+        lastModifiedTime: {
+            toAirtable: dateTimeMapperPair.toAirtable,
             fromAirtable: (value) => {
-                if (value === null || value === undefined)
+                const nullableValue = dateTimeMapperPair.fromAirtable(value);
+                if (nullableValue === null)
                     return null;
-                const date = new Date(value);
+                const date = new Date(nullableValue);
                 if (Number.isNaN(date.getTime())) {
-                    throw new Error('[airtable-ts] Invalid dateTime');
+                    throw new Error('[airtable-ts] Invalid date');
                 }
                 return Math.floor(date.getTime() / 1000);
             },
         },
         multipleLookupValues: {
-            toAirtable: () => { throw new Error('[airtable-ts] lookup 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 lookup to a single number, as there were ${value?.length} entries`);
-                }
-                if (typeof value[0] !== 'number') {
-                    throw new Error(`[airtable-ts] Can't coerce singular lookup to a single number, as it was of type ${typeof value[0]}`);
-                }
-                return value[0];
-            },
+            toAirtable: readonly('multipleLookupValues'),
+            fromAirtable: coerce('multipleLookupValues', 'number | null'),
         },
         rollup: {
-            toAirtable: () => { throw new Error('[airtable-ts] rollup type field is readonly'); },
-            fromAirtable: (value) => {
-                if (typeof value === 'number')
-                    return value;
-                if (value === null || value === undefined)
-                    return null;
-                throw new Error(`[airtable-ts] Can't coerce rollup to a number, as it was of type ${typeof value}`);
-            },
+            toAirtable: readonly('rollup'),
+            fromAirtable: coerce('rollup', 'number | null'),
         },
         formula: {
-            toAirtable: () => { throw new Error('[airtable-ts] formula type field is readonly'); },
-            fromAirtable: (value) => {
-                if (typeof value === 'number')
-                    return value;
-                if (value === null || value === undefined)
-                    return null;
-                throw new Error(`[airtable-ts] Can't coerce formula to a number, as it was of type ${typeof value}`);
-            },
+            toAirtable: readonly('formula'),
+            fromAirtable: coerce('formula', 'number | null'),
+        },
+        unknown: {
+            toAirtable: (value) => value,
+            fromAirtable: coerce('unknown', 'number | null'),
         },
     },
-    'string[]': {
+};
+const stringArrayOrNull = {
+    'string[] | null': {
         multipleSelects: fallbackMapperPair([], []),
         multipleRecordLinks: fallbackMapperPair([], []),
         multipleLookupValues: {
             toAirtable: () => { throw new Error('[airtable-ts] lookup type field is readonly'); },
-            fromAirtable: (value) => {
-                if (!Array.isArray(value)) {
-                    throw new Error('[airtable-ts] Failed to coerce lookup 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 lookup to a string array, as it had non string type');
-                }
-                return value;
-            },
+            fromAirtable: coerce('multipleLookupValues', 'string[] | null'),
         },
         formula: {
             toAirtable: () => { throw new Error('[airtable-ts] formula type field is readonly'); },
-            fromAirtable: (value) => {
-                if (!Array.isArray(value)) {
-                    throw new Error('[airtable-ts] Failed to coerce formula 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 formula to a string array, as it had non string type');
-                }
-                return value;
-            },
+            fromAirtable: coerce('multipleLookupValues', 'string[] | null'),
         },
-    },
-    'string[] | null': {
-        multipleSelects: fallbackMapperPair(null, null),
-        multipleRecordLinks: fallbackMapperPair(null, null),
-        multipleLookupValues: {
-            toAirtable: () => { throw new Error('[airtable-ts] lookup 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 lookup 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 lookup to a string array, as it had non string type');
-                }
-                return value;
-            },
-        },
-        formula: {
-            toAirtable: () => { throw new Error('[airtable-ts] formula 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 formula 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 formula to a string array, as it had non string type');
-                }
-                return value;
-            },
+        unknown: {
+            toAirtable: (value) => value,
+            fromAirtable: coerce('unknown', 'string[] | null'),
         },
     },
 };
+exports.fieldMappers = {
+    ...stringOrNull,
+    string: {
+        ...Object.fromEntries(Object.entries(stringOrNull['string | null']).map(([airtableType, nullablePair]) => {
+            return [airtableType, {
+                    toAirtable: nullablePair.toAirtable,
+                    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}`);
+                        }
+                        return nullableValue ?? '';
+                    },
+                }];
+        })),
+    },
+    ...booleanOrNull,
+    boolean: {
+        ...Object.fromEntries(Object.entries(booleanOrNull['boolean | null']).map(([airtableType, nullablePair]) => {
+            return [airtableType, {
+                    toAirtable: nullablePair.toAirtable,
+                    fromAirtable: (value) => nullablePair.fromAirtable(value) ?? false,
+                }];
+        })),
+    },
+    ...numberOrNull,
+    number: {
+        ...Object.fromEntries(Object.entries(numberOrNull['number | null']).map(([airtableType, nullablePair]) => {
+            return [airtableType, {
+                    toAirtable: nullablePair.toAirtable,
+                    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}`);
+                        }
+                        return nullableValue;
+                    },
+                }];
+        })),
+    },
+    ...stringArrayOrNull,
+    'string[]': {
+        ...Object.fromEntries(Object.entries(stringArrayOrNull['string[] | null']).map(([airtableType, nullablePair]) => {
+            return [airtableType, {
+                    toAirtable: nullablePair.toAirtable,
+                    fromAirtable: (value) => nullablePair.fromAirtable(value) ?? [],
+                }];
+        })),
+    },
+};

package/dist/mapping/recordMapper.js

@@ -4,6 +4,20 @@ exports.visibleForTesting = exports.mapRecordToAirtable = exports.mapRecordFromA
 const fieldMappers_1 = require("./fieldMappers");
 const nameMapper_1 = require("./nameMapper");
 const typeUtils_1 = require("./typeUtils");
+const getMapper = (tsType, airtableType) => {
+    const tsMapper = fieldMappers_1.fieldMappers[tsType];
+    if (!tsMapper) {
+        throw new Error(`[airtable-ts] No mappers for ts type ${tsType}`);
+    }
+    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.`);
+        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.`);
+};
 /**
  * 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
@@ -28,18 +42,10 @@ const mapRecordTypeAirtableToTs = (tsTypes, record) => {
             throw new Error(`[airtable-ts] Failed to get Airtable field ${fieldNameOrId}`);
         }
         const value = record.fields[fieldDefinition.name];
-        const tsMapper = fieldMappers_1.fieldMappers[tsType];
-        if (!tsMapper) {
-            throw new Error(`[airtable-ts] No mappers for ts type ${tsType}`);
-        }
-        const specificMapper = tsMapper[fieldDefinition.type]?.fromAirtable;
-        if (!specificMapper) {
-            // eslint-disable-next-line no-underscore-dangle
-            throw new Error(`[airtable-ts] Expected field ${record._table.name}.${fieldNameOrId} to be able to map to ts type ${tsType}, but got airtable type ${fieldDefinition.type} which can't.`);
-        }
         try {
+            const { fromAirtable } = getMapper(tsType, fieldDefinition.type);
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            item[fieldNameOrId] = specificMapper(value);
+            item[fieldNameOrId] = fromAirtable(value);
         }
         catch (error) {
             if (error instanceof Error) {
@@ -88,16 +94,20 @@ const mapRecordTypeTsToAirtable = (tsTypes, tsRecord, airtableTable) => {
         if (!fieldDefinition) {
             throw new Error(`[airtable-ts] Failed to get Airtable field ${fieldNameOrId}`);
         }
-        const tsMapper = fieldMappers_1.fieldMappers[tsType];
-        if (!tsMapper) {
-            throw new Error(`[airtable-ts] No mappers for ts type ${tsType}`);
+        try {
+            const { toAirtable } = getMapper(tsType, fieldDefinition.type);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            item[fieldNameOrId] = toAirtable(value);
         }
-        const specificMapper = tsMapper[fieldDefinition.type]?.toAirtable;
-        if (!specificMapper) {
-            throw new Error(`[airtable-ts] Expected field ${airtableTable.name}.${fieldNameOrId} to be able to map to airtable type \`${fieldDefinition.type}\`, but got ts type \`${tsType}\` which can't.`);
+        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;
         }
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        item[fieldNameOrId] = specificMapper(value);
     });
     return Object.assign(item, { id: tsRecord.id });
 };

package/dist/mapping/typeUtils.d.ts

@@ -3,7 +3,13 @@ type NonNullToString<T> = T extends string ? 'string' : T extends number ? 'numb
 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 = 'aiText' | 'autoNumber' | 'barcode' | 'button' | 'checkbox' | 'count' | 'createdBy' | 'createdTime' | 'currency' | 'date' | 'dateTime' | 'duration' | 'email' | 'externalSyncSource' | 'formula' | 'lastModifiedBy' | 'lastModifiedTime' | 'lookup' | 'multipleLookupValues' | 'multilineText' | 'multipleAttachments' | 'multipleCollaborators' | 'multipleRecordLinks' | 'multipleSelects' | 'number' | 'percent' | 'phoneNumber' | 'rating' | 'richText' | 'rollup' | 'singleCollaborator' | 'singleLineText' | 'singleSelect' | 'url';
-export type FromAirtableTypeString<T extends AirtableTypeString> = null | (T extends 'url' | 'email' | 'phoneNumber' | 'singleLineText' | 'multilineText' | 'richText' | 'singleSelect' | 'externalSyncSource' | 'date' | 'dateTime' | 'createdTime' | 'lastModifiedTime' ? string : T extends 'multipleRecordLinks' | 'multipleSelects' ? string[] : T extends 'number' | 'rating' | 'duration' | 'currency' | 'percent' | 'count' | 'autoNumber' ? number : T extends 'checkbox' ? boolean : T extends 'lookup' | 'multipleLookupValues' | 'rollup' | 'formula' ? FromAirtableTypeString<any>[] : never);
+export type FromAirtableTypeString<T extends AirtableTypeString | 'unknown'> = null | (T extends 'url' | 'email' | 'phoneNumber' | 'singleLineText' | 'multilineText' | 'richText' | 'singleSelect' | 'externalSyncSource' | 'date' | 'dateTime' | 'createdTime' | 'lastModifiedTime' ? string : T extends 'multipleRecordLinks' | 'multipleSelects' ? string[] : T extends 'number' | 'rating' | 'duration' | 'currency' | 'percent' | 'count' | 'autoNumber' ? number : T extends 'checkbox' ? boolean : T extends 'lookup' | 'multipleLookupValues' | 'rollup' | 'formula' ? FromAirtableTypeString<any>[] : T extends 'unknown' ? unknown : never);
+interface TypeDef {
+    single: 'string' | 'number' | 'boolean';
+    array: boolean;
+    nullable: boolean;
+}
+export declare const parseType: (t: TsTypeString) => TypeDef;
 /**
  * Verifies whether the given value is assignable to the given type
  *

package/dist/mapping/typeUtils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.airtableFieldNameTsTypes = exports.matchesType = void 0;
+exports.airtableFieldNameTsTypes = exports.matchesType = exports.parseType = void 0;
 const parseType = (t) => {
     if (t.endsWith('[] | null')) {
         return {
@@ -29,6 +29,7 @@ const parseType = (t) => {
         nullable: false,
     };
 };
+exports.parseType = parseType;
 /**
  * Verifies whether the given value is assignable to the given type
  *
@@ -42,7 +43,7 @@ const parseType = (t) => {
  * @example true
  */
 const matchesType = (value, tsType) => {
-    const expectedType = parseType(tsType);
+    const expectedType = (0, exports.parseType)(tsType);
     if (expectedType.nullable && value === null) {
         return true;
     }

package/package.json

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