airtable-ts-codegen 2.1.0 → 2.2.0

package/README.md

@@ -22,6 +22,18 @@ AIRTABLE_API_KEY=pat1234.abcd AIRTABLE_BASE_ID=app1234 AIRTABLE_VIEW_IDS=viw1234
 
 This will output a file `app1234.ts` that exports table definitions with only the fields visible in the specified views.
 
+### Attachment type (unstable)
+
+By default, `multipleAttachments` fields are typed as `string[]` (array of URLs). To get full attachment metadata (id, filename, size, type, etc.), set `UNSTABLE_AIRTABLE_ATTACHMENT_TYPE=Attachment`:
+
+```sh
+AIRTABLE_API_KEY=pat1234.abcd AIRTABLE_BASE_ID=app1234 UNSTABLE_AIRTABLE_ATTACHMENT_TYPE=Attachment npx airtable-ts-codegen
+```
+
+This will generate `Attachment[]` instead of `string[]` for attachment fields, giving you access to the full attachment object with properties like `id`, `url`, `filename`, `size`, `type`, `width`, `height`, and `thumbnails`.
+
+> **Note:** This option is unstable and may change or be removed in future versions.
+
 <details>
 <summary>Example generated file</summary>
 

package/dist/__fixture__/tablesMeta.json.d.ts

@@ -35,6 +35,8 @@ export declare const tablesMeta: {
                 isValid?: never;
                 formula?: never;
                 result?: never;
+                recordLinkFieldId?: never;
+                fieldIdInLinkedTable?: never;
             };
             id: string;
             name: string;
@@ -58,6 +60,8 @@ export declare const tablesMeta: {
                 isValid?: never;
                 formula?: never;
                 result?: never;
+                recordLinkFieldId?: never;
+                fieldIdInLinkedTable?: never;
             };
             id: string;
             name: string;
@@ -85,6 +89,8 @@ export declare const tablesMeta: {
                 isValid?: never;
                 formula?: never;
                 result?: never;
+                recordLinkFieldId?: never;
+                fieldIdInLinkedTable?: never;
             };
             id: string;
             name: string;
@@ -108,6 +114,8 @@ export declare const tablesMeta: {
                 isValid?: never;
                 formula?: never;
                 result?: never;
+                recordLinkFieldId?: never;
+                fieldIdInLinkedTable?: never;
             };
             id: string;
             name: string;
@@ -134,6 +142,8 @@ export declare const tablesMeta: {
                 isValid?: never;
                 formula?: never;
                 result?: never;
+                recordLinkFieldId?: never;
+                fieldIdInLinkedTable?: never;
             };
             id: string;
             name: string;
@@ -163,6 +173,8 @@ export declare const tablesMeta: {
                 isValid?: never;
                 formula?: never;
                 result?: never;
+                recordLinkFieldId?: never;
+                fieldIdInLinkedTable?: never;
             };
             id: string;
             name: string;
@@ -186,6 +198,8 @@ export declare const tablesMeta: {
                 isValid?: never;
                 formula?: never;
                 result?: never;
+                recordLinkFieldId?: never;
+                fieldIdInLinkedTable?: never;
             };
             id: string;
             name: string;
@@ -209,6 +223,8 @@ export declare const tablesMeta: {
                 isValid?: never;
                 formula?: never;
                 result?: never;
+                recordLinkFieldId?: never;
+                fieldIdInLinkedTable?: never;
             };
             id: string;
             name: string;
@@ -232,6 +248,8 @@ export declare const tablesMeta: {
                 isValid?: never;
                 formula?: never;
                 result?: never;
+                recordLinkFieldId?: never;
+                fieldIdInLinkedTable?: never;
             };
             id: string;
             name: string;
@@ -255,6 +273,8 @@ export declare const tablesMeta: {
                 isValid?: never;
                 formula?: never;
                 result?: never;
+                recordLinkFieldId?: never;
+                fieldIdInLinkedTable?: never;
             };
             id: string;
             name: string;
@@ -281,6 +301,8 @@ export declare const tablesMeta: {
                 symbol?: never;
                 durationFormat?: never;
                 max?: never;
+                recordLinkFieldId?: never;
+                fieldIdInLinkedTable?: never;
             };
             id: string;
             name: string;
@@ -300,6 +322,8 @@ export declare const tablesMeta: {
                             format: string;
                         };
                         timeZone: string;
+                        precision?: never;
+                        choices?: never;
                     };
                 };
                 choices?: never;
@@ -317,6 +341,8 @@ export declare const tablesMeta: {
                 max?: never;
                 isValid?: never;
                 formula?: never;
+                recordLinkFieldId?: never;
+                fieldIdInLinkedTable?: never;
             };
             id: string;
             name: string;
@@ -338,6 +364,8 @@ export declare const tablesMeta: {
                             format: string;
                         };
                         timeZone: string;
+                        precision?: never;
+                        choices?: never;
                     };
                 };
                 choices?: never;
@@ -353,6 +381,104 @@ export declare const tablesMeta: {
                 durationFormat?: never;
                 max?: never;
                 formula?: never;
+                recordLinkFieldId?: never;
+                fieldIdInLinkedTable?: never;
+            };
+            id: string;
+            name: string;
+            description?: never;
+        } | {
+            type: string;
+            options: {
+                isValid: boolean;
+                recordLinkFieldId: string;
+                fieldIdInLinkedTable: string;
+                result: {
+                    type: string;
+                    options?: never;
+                };
+                choices?: never;
+                isReversed?: never;
+                referencedFieldIds?: never;
+                prompt?: never;
+                icon?: never;
+                color?: never;
+                dateFormat?: never;
+                timeFormat?: never;
+                timeZone?: never;
+                precision?: never;
+                symbol?: never;
+                durationFormat?: never;
+                max?: never;
+                formula?: never;
+            };
+            id: string;
+            name: string;
+            description?: never;
+        } | {
+            type: string;
+            options: {
+                isValid: boolean;
+                recordLinkFieldId: string;
+                fieldIdInLinkedTable: string;
+                result: {
+                    type: string;
+                    options: {
+                        precision: number;
+                        dateFormat?: never;
+                        timeFormat?: never;
+                        timeZone?: never;
+                        choices?: never;
+                    };
+                };
+                choices?: never;
+                isReversed?: never;
+                referencedFieldIds?: never;
+                prompt?: never;
+                icon?: never;
+                color?: never;
+                dateFormat?: never;
+                timeFormat?: never;
+                timeZone?: never;
+                precision?: never;
+                symbol?: never;
+                durationFormat?: never;
+                max?: never;
+                formula?: never;
+            };
+            id: string;
+            name: string;
+            description?: never;
+        } | {
+            type: string;
+            options: {
+                isValid: boolean;
+                recordLinkFieldId: string;
+                fieldIdInLinkedTable: string;
+                result: {
+                    type: string;
+                    options: {
+                        choices: never[];
+                        dateFormat?: never;
+                        timeFormat?: never;
+                        timeZone?: never;
+                        precision?: never;
+                    };
+                };
+                choices?: never;
+                isReversed?: never;
+                referencedFieldIds?: never;
+                prompt?: never;
+                icon?: never;
+                color?: never;
+                dateFormat?: never;
+                timeFormat?: never;
+                timeZone?: never;
+                precision?: never;
+                symbol?: never;
+                durationFormat?: never;
+                max?: never;
+                formula?: never;
             };
             id: string;
             name: string;

package/dist/__fixture__/tablesMeta.json.js

@@ -63,7 +63,22 @@ exports.tablesMeta = {
                 { type: 'createdBy', id: 'fldDcRoVGJXIhVSAi', name: 'Created By' },
                 { type: 'autoNumber', id: 'fldGM8wIYk3G8WMiE', name: 'ID' },
                 { type: 'barcode', id: 'fldMPs1eLH8X5bWeS', name: 'Barcode' },
-                { type: 'button', id: 'fldAG3LTbJRwQVEvS', name: 'Button' }],
+                { type: 'button', id: 'fldAG3LTbJRwQVEvS', name: 'Button' },
+                {
+                    type: 'multipleLookupValues', options: {
+                        isValid: true, recordLinkFieldId: 'fldLinked', fieldIdInLinkedTable: 'fldName', result: { type: 'singleLineText' },
+                    }, id: 'fldLookupText', name: 'Lookup Text',
+                },
+                {
+                    type: 'multipleLookupValues', options: {
+                        isValid: true, recordLinkFieldId: 'fldLinked', fieldIdInLinkedTable: 'fldNumber', result: { type: 'number', options: { precision: 0 } },
+                    }, id: 'fldLookupNumber', name: 'Lookup Number',
+                },
+                {
+                    type: 'multipleLookupValues', options: {
+                        isValid: true, recordLinkFieldId: 'fldLinked', fieldIdInLinkedTable: 'fldTags', result: { type: 'multipleSelects', options: { choices: [] } },
+                    }, id: 'fldLookupTags', name: 'Lookup Tags',
+                }],
             views: [],
         }],
 };

package/dist/cli.js

@@ -13,7 +13,11 @@ if (!baseId) {
     throw new Error('No Airtable base id set. Make sure the AIRTABLE_BASE_ID environment variable is set.');
 }
 const viewIds = process.env.AIRTABLE_VIEW_IDS;
-const config = { apiKey, baseId, ...(viewIds && { viewIds: viewIds.split(',') }) };
+const unstableAttachmentTypeEnv = process.env.UNSTABLE_AIRTABLE_ATTACHMENT_TYPE;
+const unstable_attachmentType = unstableAttachmentTypeEnv === 'Attachment' ? 'Attachment' : 'string';
+const config = {
+    apiKey, baseId, ...(viewIds && { viewIds: viewIds.split(',') }), unstable_attachmentType,
+};
 const generateCode = async () => {
     console.log(`Generating TypeScript definitions for base ${baseId}${viewIds ? ` with views ${viewIds}` : ''}...`);
     return (0, _1.main)(config);

package/dist/index.d.ts

@@ -5,5 +5,13 @@ export type Config = {
     endpointUrl?: string;
     requestTimeout?: number;
     customHeaders?: Record<string, string | number | boolean>;
+    /**
+     * Type to use for multipleAttachments fields.
+     * - 'string': generates `string[]` (array of URLs only)
+     * - 'Attachment': generates `Attachment[]` (full metadata including id, filename, size, etc.)
+     * @default 'string'
+     * @unstable This option may change or be removed in future versions.
+     */
+    unstable_attachmentType?: 'string' | 'Attachment';
 };
 export declare const main: (config: Config) => Promise<string>;

package/dist/index.js

@@ -11,10 +11,15 @@ const view_1 = require("./view");
 const main = async (config) => {
     const baseSchema = await (0, getBaseSchema_1.getBaseSchema)(config.baseId, config);
     const filteredBaseSchema = await (0, view_1.filterBaseSchemaByView)(baseSchema, config);
+    // Determine if we need to import Attachment type
+    const useAttachmentType = config.unstable_attachmentType === 'Attachment';
+    const importTypes = useAttachmentType
+        ? 'import type { Attachment, Item, Table } from \'airtable-ts\';'
+        : 'import type { Item, Table } from \'airtable-ts\';';
     return [
         '/* DO NOT EDIT: this file was automatically generated by airtable-ts-codegen */',
         '/* eslint-disable */',
-        'import type { Item, Table } from \'airtable-ts\';',
+        importTypes,
         '',
         filteredBaseSchema.map((tableSchema) => generateCode(config, tableSchema)).join('\n\n'),
     ].join('\n');
@@ -45,11 +50,12 @@ const generateCode = (config, tableSchema) => {
     const itemNameRaw = (0, escapeIdentifier_1.escapeIdentifier)((0, recase_1.recase)(null, 'pascal', tableSchema.name));
     const itemName = /.s$/.test(itemNameRaw) ? itemNameRaw.slice(0, itemNameRaw.length - 1) : itemNameRaw;
     const tableName = (0, escapeIdentifier_1.escapeIdentifier)(`${(0, recase_1.recase)(null, 'camel', tableSchema.name)}Table`);
+    const jsTypeOptions = { attachmentType: config.unstable_attachmentType };
     const fields = tableSchema.fields.map((f) => ({
         ...f,
         originalName: f.name,
         jsName: (0, escapeIdentifier_1.escapeIdentifier)((0, recase_1.recase)(null, 'camel', (0, escapeIdentifier_1.escapeIdentifier)(f.name))),
-        jsType: (0, jsTypeForAirtableType_1.jsTypeForAirtableType)(f),
+        jsType: (0, jsTypeForAirtableType_1.jsTypeForAirtableType)(f, jsTypeOptions),
     }));
     return `export interface ${itemName} extends Item {
   id: string,${fields.map(generateInterfaceEntry).join('')}

package/dist/jsTypeForAirtableType.d.ts

@@ -1,7 +1,11 @@
 import { type FieldSchema } from './getBaseSchema';
+export type JsTypeOptions = {
+    /** Type to use for multipleAttachments fields */
+    attachmentType?: 'string' | 'Attachment' | undefined;
+};
 /**
  * Returns the corresponding Typescript type for the given Airtable field type.
  *
  * Unsupported fields return `null` and will be filtered out by the caller.
  */
-export declare const jsTypeForAirtableType: (field: FieldSchema) => string | null;
+export declare const jsTypeForAirtableType: (field: FieldSchema, options?: JsTypeOptions) => string | null;

package/dist/jsTypeForAirtableType.js

@@ -6,7 +6,7 @@ exports.jsTypeForAirtableType = void 0;
  *
  * Unsupported fields return `null` and will be filtered out by the caller.
  */
-const jsTypeForAirtableType = (field) => {
+const jsTypeForAirtableType = (field, options = {}) => {
     switch (field.type) {
         case 'url':
         case 'email':
@@ -25,6 +25,7 @@ const jsTypeForAirtableType = (field) => {
         case 'createdBy':
             return 'string';
         case 'multipleAttachments':
+            return options.attachmentType === 'Attachment' ? 'Attachment[]' : 'string[]';
         case 'multipleCollaborators':
         case 'multipleRecordLinks':
         case 'multipleSelects':
@@ -46,15 +47,33 @@ const jsTypeForAirtableType = (field) => {
             return 'number'; // Unix timestamp in seconds
         case 'checkbox':
             return 'boolean';
-        case 'lookup':
         case 'multipleLookupValues':
+            if (field.options
+                && 'result' in field.options
+                && typeof field.options.result === 'object'
+                && field.options.result !== null) {
+                const innerType = (0, exports.jsTypeForAirtableType)(field.options.result, options);
+                if (innerType === null) {
+                    return null;
+                }
+                // multipleLookupValues always returns an array
+                // Strip nullability from inner type since the array itself represents empty state
+                const baseType = innerType.replace(/ \| null$/, '').replace(/^null \| /, '');
+                // If inner type is already an array, Airtable flattens lookup results
+                if (baseType.endsWith('[]')) {
+                    return baseType;
+                }
+                return `${baseType}[]`;
+            }
+            throw new Error(`Invalid ${field.type} field (no options.result): ${field.id}`);
+        case 'lookup':
         case 'rollup':
         case 'formula':
             if (field.options
                 && 'result' in field.options
                 && typeof field.options.result === 'object'
                 && field.options.result !== null) {
-                const innerType = (0, exports.jsTypeForAirtableType)(field.options.result);
+                const innerType = (0, exports.jsTypeForAirtableType)(field.options.result, options);
                 if (innerType === null) {
                     return null;
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "airtable-ts-codegen",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Autogenerate TypeScript definitions for your Airtable base",
   "license": "MIT",
   "author": "Adam Jones (domdomegg)",