This package is designed to make working with the FileMaker Data API much easier. Here's just a few key features:
- Otto Data API proxy support
- TypeScript support for easy auto-completion of your fields
- Automated type generation based on layout metadata
- Supports both node and edge runtimes (v3.0+)
This library requires zod as a peer depenency and Node 18 or later
npm install @proofgeist/fmdapi zodyarn add @proofgeist/fmdapi zodAdd the following envnironment variables to your project's .env file:
FM_DATABASE=filename.fmp12
FM_SERVER=https://filemaker.example.com
# if you want to use the Otto Data API Proxy
OTTO_API_KEY=KEY_123456...789
# otherwise
FM_USERNAME=admin
FM_PASSWORD=passwordInitialize the client with your FileMaker Server credentials:
import { DataApi } from "@proofgeist/fmdapi";
const client = DataApi({
auth: { apiKey: process.env.OTTO_API_KEY },
db: process.env.FM_DATABASE,
server: process.env.FM_SERVER,
});Then, use the client to query your FileMaker database. Availble methods:
listreturn all records from a given layoutfindperform a FileMaker findgetreturn a single record by recordIDcreatereturn a new recordupdatemodify a single record by recordIDdeletedelete a single record by recordIDexecuteScriptexecute a FileMaker script direcltylayoutsreturn a list of all layouts in the databasescriptsreturn a list of all scripts in the databasemetadatareturn metadata for a given layoutdisconnectforcibly logout of your FileMaker session (available when not using Otto Data API proxy)
This package also includes some helper methods to make working with Data API responses a little easier:
findOnereturn the first record from a find instead of an array. This method will error unless exactly 1 record is found.findFirstreturn the first record from a find instead of an array, but will not error if multiple records are found.findAllreturn all found records from a find, automatically handling pagination. Use caution with large datasets!listAllreturn all records from a given layout, automatically handling pagination. Use caution with large datasets!
Basic Example:
const result = await client.list({ layout: "Contacts" });| Option | Type | Description |
|---|---|---|
auth |
object |
Authentication object. Must contain either apiKey or username and password |
db |
string |
FileMaker database name |
server |
string |
FileMaker server URL (must include https://) |
layout |
string |
(optional) If provided, will be the default layout used for all methods (can be overridden on a per-call basis) |
tokenStore |
TokenStore |
(optional) If provided, will use the custom set of functions to store and retrieve the short-lived access token. This only used for the username/password authenication method. See below for more details |
The basic client will return the generic FileMaker response object by default. You can also create a type for your exepcted response and get a fully typed response that includes your own fields.
type TContact = {
name: string;
email: string;
phone: string;
};
const result = await client.list<TContact>({ layout: "Contacts" });💡 TIP: For a more ergonomic TypeScript experience, use the included codegen tool to generate these types based on your FileMaker layout metadata.
A (nearly) identical client designed to be used with the fm-webviewer-fetch library when integrating within a FileMaker WebViewer instead of the browser. Using this client requires a bit extra configuration within your FileMaker file, but provides great developer experience, especially when using TypeScript and the codegen features.
(v3.5+) Support for write operations in FileMaker 2024
Install the fm-webviewer-fetch library to your project:
npm install @proofgeist/fm-webviewer-fetch
# or
yarn add @proofgeist/fm-webviewer-fetchConfigure a script in your FileMaker file to execute the Data API
import { DataApiWV } from "@proofgeist/fmdapi";
const client = DataApiWV({
scriptName: "ExecuteDataApi", // you must configure this script!
});| Option | Type | Description |
|---|---|---|
scriptName |
string |
FileMaker Script name that passes the parameter to the Execute Data API Script Step and returns the results according to the fm-webviewer-fetch spec |
layout |
string |
(optional) If provided, will be the default layout used for all methods (can be overridden on a per-call basis) |
If you are using username/password authentication, this library will manage your access token for you. By default, the token is kept in memory only, but you can provide other getter and setter methods to store the token in a database or other location. Included in this package are helper functions for file storage if you have access to the filesystem, or Upstash if running in a serverless environment.
import { DataApi } from "@proofgeist/fmdapi";
// using file storage
import { fileTokenStore } from "@proofgeist/fmdapi/dist/tokenStore/file";
const client = DataApi({
auth: {
username: process.env.FM_USERNAME,
password: process.env.FM_PASSWORD,
},
db: process.env.FM_DATABASE,
server: process.env.FM_SERVER,
tokenStore: fileTokenStore(),
});
// or with Upstash, requires `@upstash/redis` as peer dependency
import { upstashTokenStore } from "@proofgeist/fmdapi/dist/tokenStore/upstash";
const client = DataApi({
auth: {
username: process.env.FM_USERNAME,
password: process.env.FM_PASSWORD,
},
db: process.env.FM_DATABASE,
server: process.env.FM_SERVER,
tokenStore: upstashTokenStore({
token: process.env.UPSTASH_TOKEN,
url: process.env.UPSTASH_URL,
}),
});Since version 3.0 uses the native fetch API, it is compatible with edge runtimes, but there are some additional considerations to avoid overwhelming your FileMaker server with too many connections. If you are developing for the edge, be sure to implement one of the following strategies:
- ✅ Use a custom token store (see above) with a persistent storage method such as Upstash
- ✅ Use a proxy such as the Otto Data API Proxy which handles management of the access tokens itself.
- Providing an API key to the client instead of username/password will automatically use the Otto proxy
⚠️ Call thedisconnectmethod on the client after each request to avoid leaving open sessions on your server- this method works, but is not recommended in most scenarios as it reuires a new session to be created for each request
This package also includes a helper function that will automatically generate types for each of your layouts. Use this tool regularly during development to easily keep your types updated with any schema changes in FileMaker. 🤯
The generated file also produces a layout-specific client instance that will automatically type all of the methods for that layout and validates the response using the zod library. This validation happens at runtime so you can protect against dangerous field changes even when you haven't ran the code generator recently, or in your production deployment!
- Add a schema configuation file to the root of your project
yarn codegen --init- Edit the configuration file (
fmschema.config.js) to include your FileMaker layouts (see more configuration options below). - Run the
codegencommand to generate your types!
yarn codegenAssuming you have a layout called customer_api containing name phone and email fields for a customer, the generated code will look something like this:
// schema/Customer.ts
import { z } from "zod";
export const ZCustomer = z.object({
name: z.string(),
phone: z.string(),
email: z.string(),
});
export type TCustomer = z.infer<typeof ZCustomer>;
// schema/client/Customer.ts
import { DataApi } from "@proofgeist/fmdapi";
export const client = DataApi<any, TCustomer>(
{
auth: { apiKey: process.env.OTTO_API_KEY },
db: process.env.FM_DATABASE,
server: process.env.FM_SERVER,
layout: "customer_api",
},
{ fieldData: ZCustomer }
);You can use the exported types to type your own client, or simply use the generated client to get typed and validated results, like so:
import { CustomerClient } from "schema/client";
...
const result = await CustomerClient.list(); // result will be fully typed and validated!| Option | Type | Default | Description |
|---|---|---|---|
| envNames | object |
undefined | This object has the same structure as the client config parameters and is used to overrride the environment variable names used for the generated client. |
| schemas | Schema[] |
(required) | An array of Schema objects to generate types for (see below) |
| path | string |
"./schema" |
Path to folder where generated files should be saved. |
| generateClient | boolean |
true |
Will generate a layout-specific typed client for you. Set to false if you only want to generate the types. |
| useZod | boolean |
true |
When enabled, will generate Zod schema in addition to TypeScript types and add validation to the generated client for each layout |
| tokenStore | function |
memoryStore |
A custom token store function to be included in the generated client |
In order to support whatever token store you may import, all import statements from your config file will be copied into the generated client files by default. To exclude certain imports, add a comment containing codegen-ignore in the line above the import statement you wish to exclude. e.g.
// codegen-ignore
import something from "whatever"; // <-- won't be included in the generated client
import { fileTokenStore } from "@proofgeist/fmdapi/dist/tokenStore/file.js"; // <-- will be included| Option | Type | Default | Description |
|---|---|---|---|
| layout | string |
(required) | The FileMaker source layout name |
| schemaName | string |
(required) | The label for your schema (will also be the name of the generated file) |
| valueLists | strict allowEmpty ignore |
ignore |
If strict, will add enum types based on the value list defined for the field. If allowEmpty, will append "" to the value list. Otherwise, fields are typed as normal. |
| strictNumbers | boolean |
false |
(v2.2.11+) If true, the zod schema will apply a transformer to force all number fields to be either number or null. WARNING: If you are not using Zod or the auto-generated layout specific client, enabling this option may result in false types! |
| generateClient | boolean |
none | If present, override the generateClient option for this schema only. |
| Option | Default | Description |
|---|---|---|
| --init | false | Run with this flag to add the config file to your project |
| --config | - | path to a non-default config file |
| --env-path | .env.local | path to your .env file |
| --skip-env-check | - | Ignore loading environment variables from a file. |
They are just files added to your project, so you technically can, but we don't recommend it, as it would undermine the main benefit of being able to re-run the script at a later date when the schema changes—all your edits would be overritten. If you need to extend the types, it's better to do extend them into a new type/zod schema in another file. Or, if you have suggesstions for the underlying engine, Pull Requests are welcome!
FileMaker may return numbers as strings in certain cases (such as very large numbers in scientific notation or blank fields). This ensures you properly account for this in your frontend code. If you wish to force all numbers to be typed as number | null, you can enable the strictNumbers flag per schema in your definition.
WARNING: the strictNumbers setting is disabled by default because it may result in false types if you are not using Zod or the auto-generated layout specific client. It works by applying a transformer to the zod schema to force all number fields to be either number or null.
Values lists are exported as their own types within the schema file, but they are not enforced within the schema by default because the actual data in the field may not be fully validated.
If you want the type to be enforced to a value from the value list, you can enable the strictValueLists flag per schema in your definition. This feature is only reccommended when you're also using the Zod library, as your returned data will fail the validation if the value is not in the value list.
For now, these are all typed as strings. You probably want to transform these values anyway, so we keep it simple at the automated level.
Yes, great idea! This could be a great way to catch errors that would arise from any changes to the FileMaker schema.
In short: Zod is a TypeScript-first schema declaration and validation library. When you use it, you get runtime validation of your data instead of just compile-time validation.
FileMaker is great for being able to change schema very quickly and easily. Yes, you probably have naming conventions in place that help protect against these changes in your web apps, but no system is perfect. Zod lets you start with the assumption that any data coming from an external API might be in a format that you don't expect and then valdiates it so that you can catch errors early. This allows the typed object that it returns to you to be much more trusted throughout your app.
But wait, does this mean that I might get a fatal error in my production app if the FileMaker schema changes? Yes, yes it does. This is actually what you'd want to happen. Without validating the data returned from an API, it's possible to get other unexpcted side-effects in your app that don't present as errors, which may lead to bugs that are hard to track down or inconsistencies in your data.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "github-actions[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent