airtable-ts-codegen 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,82 @@
+# airtable-ts-codegen
+
+Autogenerate TypeScript definitions for your Airtable base
+
+## Usage
+
+Run with:
+
+```sh
+AIRTABLE_API_KEY=pat1234.abcd AIRTABLE_BASE_ID=app1234 npx airtable-ts-codegen
+```
+
+This will output a file `app1234.ts` that exports all the table definitions
+
+<details>
+<summary>Example generated file</summary>
+
+```ts
+/* DO NOT EDIT: this file was automatically generated by airtable-ts-codegen */
+/* eslint-disable */
+import { Item, Table } from 'airtable-ts';
+
+export interface Task extends Item {
+  id: string,
+  name: string,
+  status: string,
+  dueAt: number,
+  isOptional: boolean,
+}
+
+export const tasksTable: Table<Task> = {
+  name: 'Tasks',
+  baseId: 'app1234',
+  tableId: 'tbl5678',
+  mappings: {
+    name: 'fld9012',
+    status: 'fld3456',
+    dueAt: 'fld7890',
+    isOptional: 'fld1234',
+  },
+  schema: {
+    name: 'string',
+    status: 'string',
+    dueAt: 'number',
+    isOptional: 'boolean',
+  },
+};
+```
+
+</details>
+
+You can then easily use this with [airtable-ts](https://github.com/domdomegg/airtable-ts), for example:
+
+```ts
+import { AirtableTs } from 'airtable-ts';
+import { tasksTable } from './generated/app1234';
+
+const db = new AirtableTs({ apiKey: 'pat1234.abcdef' });
+const allTasks = await db.scan(tasksTable);
+
+// You now have all the benefits of airtable-ts, without having to define schemas manually 🎉
+```
+
+## 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/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const _1 = require(".");
+const escapeIdentifier_1 = require("./escape/escapeIdentifier");
+/* eslint-disable no-console */
+const apiKey = process.env.AIRTABLE_API_KEY;
+if (!apiKey)
+    throw new Error('No Airtable API key set. Make sure the AIRTABLE_API_KEY environment variable is set.');
+const baseId = process.env.AIRTABLE_BASE_ID;
+if (!baseId)
+    throw new Error('No Airtable base id set. Make sure the AIRTABLE_BASE_ID environment variable is set.');
+(0, _1.main)({ apiKey, baseId }).then((result) => {
+    (0, fs_1.writeFileSync)(`${(0, escapeIdentifier_1.escapeIdentifier)(baseId)}.ts`, result);
+});

package/dist/escape/escapeIdentifier.d.ts

@@ -0,0 +1,2 @@
+/** Used for identifiers. If the name has symbols or is illegal Typescript, strip out symbols and make it PascalCase. */
+export declare const escapeIdentifier: (name: string) => string;

package/dist/escape/escapeIdentifier.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeIdentifier = void 0;
+const recase_1 = require("@kristiandupont/recase");
+const toPascalCase = (0, recase_1.recase)(null, 'pascal');
+/** Used for identifiers. If the name has symbols or is illegal Typescript, strip out symbols and make it PascalCase. */
+// NB: A wider set of things than are accepted by this function are valid identifiers in TypeScript (see https://stackoverflow.com/a/9337047). However, this works well for our purposes.
+const escapeIdentifier = (name) => {
+    const trimmed = name.trim();
+    let isLegalIdentifier = true;
+    if (!/^[$A-Z_a-z][\w$]*$/.test(trimmed)) {
+        isLegalIdentifier = false;
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new
+        new Function(`const ${trimmed} = 1;`);
+    }
+    catch {
+        isLegalIdentifier = false;
+    }
+    if (isLegalIdentifier) {
+        return trimmed;
+    }
+    const snaked = trimmed.replace(/[^$A-Z_a-z]/g, '_').replace(/_+/g, '_');
+    const result = toPascalCase(snaked);
+    if (result.length === 0) {
+        throw new Error(`Invalid and unsalvageable identifier: ${name}`);
+    }
+    return result;
+};
+exports.escapeIdentifier = escapeIdentifier;

package/dist/escape/escapeString.d.ts

@@ -0,0 +1,2 @@
+/** Used for single-quoted strings. */
+export declare const escapeString: (str: string) => string;

package/dist/escape/escapeString.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeString = void 0;
+/** Used for single-quoted strings. */
+const escapeString = (str) => str.replace(/'/g, "\\'").replace(/\n/g, '\\n');
+exports.escapeString = escapeString;

package/dist/getBaseSchema.d.ts

@@ -0,0 +1,20 @@
+import { Config } from '.';
+export type FieldSchema = {
+    id: string;
+    type: string;
+    name: string;
+    description?: string;
+    options?: object;
+};
+export type BaseSchema = {
+    id: string;
+    name: string;
+    description?: string;
+    fields: FieldSchema[];
+}[];
+/**
+ * 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
+ */
+export declare const getBaseSchema: (baseId: string, options: Config) => Promise<BaseSchema>;

package/dist/getBaseSchema.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBaseSchema = void 0;
+const axios_1 = __importDefault(require("axios"));
+/**
+ * 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 getBaseSchema = async (baseId, options) => {
+    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,
+        },
+    });
+    return res.data.tables;
+};
+exports.getBaseSchema = getBaseSchema;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export interface Config {
+    apiKey: string;
+    baseId: string;
+    endpointUrl?: string;
+    requestTimeout?: number;
+    customHeaders?: Record<string, string | number | boolean>;
+}
+export declare const main: (config: Config) => Promise<string>;

package/dist/index.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = void 0;
+const recase_1 = require("@kristiandupont/recase");
+const getBaseSchema_1 = require("./getBaseSchema");
+const escapeString_1 = require("./escape/escapeString");
+const escapeIdentifier_1 = require("./escape/escapeIdentifier");
+const jsTypeForAirtableType_1 = require("./jsTypeForAirtableType");
+// This will output a folder named `app1234` with:
+// - an `index.ts` that exports all the tables
+// - (under the hood?) various `tbl1234.ts` files that contain table definitions
+const main = async (config) => {
+    const baseSchema = await (0, getBaseSchema_1.getBaseSchema)(config.baseId, config);
+    return `/* DO NOT EDIT: this file was automatically generated by airtable-ts-codegen */\n/* eslint-disable */\nimport { Item, Table } from 'airtable-ts';\n\n${baseSchema.map((tableSchema) => generateCode(config, tableSchema)).join('\n\n')}`;
+};
+exports.main = main;
+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 fields = tableSchema.fields.map((f) => ({
+        ...f,
+        jsName: (0, escapeIdentifier_1.escapeIdentifier)((0, recase_1.recase)(null, 'camel', (0, escapeIdentifier_1.escapeIdentifier)(f.name))),
+        jsType: (0, jsTypeForAirtableType_1.jsTypeForAirtableType)(f),
+    }));
+    return `export interface ${itemName} extends Item {
+  id: string,${fields.map((f) => `\n  ${f.jsName}: ${f.jsType},`).join('')}
+}
+
+export const ${tableName}: Table<${itemName}> = {
+  name: '${(0, escapeString_1.escapeString)(tableSchema.name)}',
+  baseId: '${(0, escapeString_1.escapeString)(config.baseId)}',
+  tableId: '${(0, escapeString_1.escapeString)(tableSchema.id)}',
+  mappings: {${fields.map((f) => `\n    ${f.jsName}: '${(0, escapeString_1.escapeString)(f.id)}',`).join('')}
+  },
+  schema: {${fields.map((f) => `\n    ${f.jsName}: '${(0, escapeString_1.escapeString)(f.jsType)}',`).join('')}
+  },
+};`;
+};

package/dist/jsTypeForAirtableType.d.ts

@@ -0,0 +1,2 @@
+import { FieldSchema } from './getBaseSchema';
+export declare const jsTypeForAirtableType: (field: FieldSchema) => string;

package/dist/jsTypeForAirtableType.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsTypeForAirtableType = void 0;
+const jsTypeForAirtableType = (field) => {
+    switch (field.type) {
+        case 'url':
+        case 'email':
+        case 'phoneNumber':
+        case 'singleLineText':
+        case 'multilineText':
+        case 'richText':
+        case 'singleSelect':
+        case 'externalSyncSource':
+            return 'string';
+        case 'multipleRecordLinks':
+        case 'multipleSelects':
+            return 'string[]';
+        case 'number':
+        case 'rating':
+        case 'duration':
+        case 'currency':
+        case 'percent':
+        case 'count':
+        case 'autoNumber':
+            return 'number';
+        case 'date':
+        case 'dateTime':
+        case 'createdTime':
+        case 'lastModifiedTime':
+            return 'number'; // Unix timestamp in seconds
+        case 'checkbox':
+            return 'boolean';
+        case 'lookup':
+        case 'multipleLookupValues':
+        case 'rollup':
+        case 'formula':
+            if (field.options
+                && 'result' in field.options
+                && typeof field.options.result === 'object'
+                && field.options.result != null) {
+                return `${(0, exports.jsTypeForAirtableType)(field.options.result)} | null`;
+            }
+            throw new Error(`Invalid ${field.type} field (no options.result): ${field.id}`);
+        // Special cases we don't yet support
+        case 'aiText':
+            return 'AiTextObject';
+        case 'singleCollaborator':
+        case 'createdBy':
+        case 'lastModifiedBy':
+            return 'CollaboratorObject';
+        case 'multipleCollaborators':
+            return 'CollaboratorObject[]';
+        case 'multipleAttachments':
+            return 'AttachmentObject[]';
+        case 'barcode':
+            return 'BarcodeObject';
+        case 'button':
+            return 'ButtonObject';
+        default:
+            throw new Error(`Could not convert Airtable type '${field.type}' to a TypeScript type for field ${field.id}`);
+    }
+};
+exports.jsTypeForAirtableType = jsTypeForAirtableType;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "airtable-ts-codegen",
+  "version": "1.0.0",
+  "description": "Autogenerate TypeScript definitions for your Airtable base",
+  "license": "MIT",
+  "author": "Adam Jones (domdomegg)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/domdomegg/airtable-ts-codegen.git"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "airtable-ts-codegen": "dist/cli.js"
+  },
+  "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"
+  },
+  "dependencies": {
+    "@kristiandupont/recase": "^1.2.1",
+    "axios": "^1.6.8"
+  },
+  "devDependencies": {
+    "@tsconfig/node-lts": "^20.1.3",
+    "@types/node": "^20.12.8",
+    "airtable-ts": "^1.1.0",
+    "eslint": "^8.57.0",
+    "eslint-config-domdomegg": "^1.2.3",
+    "tsconfig-domdomegg": "^1.0.0",
+    "typescript": "^5.4.4",
+    "vitest": "^1.4.0"
+  },
+  "eslintConfig": {
+    "extends": [
+      "eslint-config-domdomegg"
+    ]
+  }
+}