@jd-data-limited/easy-fm 5.0.0-beta.2 → 5.0.0-beta.4

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2022 JD-Data-Limited
-
-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.
+MIT License
+
+Copyright (c) 2022 JD-Data-Limited
+
+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

@@ -1,93 +1,95 @@
-# easy-fm
-
-`easy-fm` is a Node.js client for Claris FileMaker Data API.
-
-It helps you connect Node.js code to FileMaker Server or FileMaker Cloud so you can fetch records, run finds, edit data, work with portals, and run scripts using a typed JavaScript or TypeScript API.
-
-## Requirements
-
-- Node.js `22+`
-- FileMaker Data API enabled
-- account with `fmrest` privilege
-- at least one accessible layout
-
-Claris Data API reference:
-[`help.claris.com/en/data-api-guide/content/index.html`](https://help.claris.com/en/data-api-guide/content/index.html)
-
-## Install
-
-```sh
-npm install @jd-data-limited/easy-fm
-```
-
-## Quick Start
-
-```ts
-import {FMHost} from "@jd-data-limited/easy-fm"
-
-const host = new FMHost("https://example.com")
-
-const database = host.database({
-  database: "Contacts",
-  credentials: {
-    method: "filemaker",
-    username: "api-user",
-    password: "secret"
-  },
-  externalSources: []
+# easy-fm
+
+`easy-fm` is a Node.js client for Claris FileMaker Data API.
+
+It helps you connect Node.js code to FileMaker Server or FileMaker Cloud so you can fetch records, run finds, edit data, work with portals, and run scripts using a typed JavaScript or TypeScript API.
+
+## Requirements
+
+- Node.js `22+`
+- FileMaker Data API enabled
+- account with `fmrest` privilege
+- at least one accessible layout
+
+Claris Data API reference:
+[`help.claris.com/en/data-api-guide/content/index.html`](https://help.claris.com/en/data-api-guide/content/index.html)
+
+## Install
+
+```sh
+npm install @jd-data-limited/easy-fm
+```
+
+## Quick Start
+
+```ts
+import {Database, DataApiProvider} from "@jd-data-limited/easy-fm"
+
+const database = Database.create({
+  provider: new DataApiProvider({
+    hostname: "https://example.com",
+    database: "Contacts",
+    credentials: {
+      method: "filemaker",
+      username: "api-user",
+      password: "secret"
+    },
+    externalSources: []
+  })
 })
-
-const layout = database.layout("Contacts_API")
-const records = await layout.records.list({
-  portals: {},
-  limit: 25
-}).fetch()
-
-for (const record of records) {
-  console.log(record.fields.FirstName.value, record.fields.LastName.value)
-}
-```
-
-## Important Notes
-
-- FileMaker Data API is layout-based, so fields and portals must be available on the layout you use.
-- Portal data is not fetched unless you request it.
-- `recordId` and `modId` are internal FileMaker IDs. Avoid treating `recordId` as a business ID; `modId` can still be useful for change or concurrency checks.
-- Date and timestamp formatting follows the host timezone rules you configure, with defaults chosen to better match FileMaker UI expectations.
-
-## Documentation
-
-> Updating from v4 to v5? Check the guide here; [`docs/upgrade-to-v5.md`](./docs/upgrade-to-v5.md)
-
-Start here:
-
-- [`docs/getting-started.md`](./docs/getting-started.md): first connection, first find, closing sessions
-- [`docs/core-concepts.md`](./docs/core-concepts.md): host, database, layout, record, portal, IDs
-
-Task guides:
-
-- [`docs/working-with-records.md`](./docs/working-with-records.md): list, create, update, duplicate, delete, portal rows
-- [`docs/query-recipes.md`](./docs/query-recipes.md): find requests, sorting, paging, script hooks
+
+const layout = database.layout("Contacts_API")
+const records = await layout.records.list({
+  portals: {},
+  limit: 25
+}).fetch()
+
+for (const record of records) {
+  console.log(record.fields.FirstName.value, record.fields.LastName.value)
+}
+```
+
+## Important Notes
+
+- FileMaker Data API is layout-based, so fields and portals must be available on the layout you use.
+- Portal data is not fetched unless you request it.
+- `recordId` and `modId` are internal FileMaker IDs. Avoid treating `recordId` as a business ID; `modId` can still be useful for change or concurrency checks.
+- Date and timestamp formatting follows the host timezone rules you configure, with defaults chosen to better match FileMaker UI expectations.
+
+## Documentation
+
+> Updating from v4 to v5? Check the guide here; [`docs/upgrade-to-v5.md`](./docs/upgrade-to-v5.md)
+
+Start here:
+
+- [`docs/getting-started.md`](./docs/getting-started.md): first connection, first find, closing sessions
+- [`docs/core-concepts.md`](./docs/core-concepts.md): host, database, layout, record, portal, IDs
+
+Task guides:
+
+- [`docs/working-with-records.md`](./docs/working-with-records.md): list, create, update, duplicate, delete, portal rows
+- [`docs/query-recipes.md`](./docs/query-recipes.md): find requests, sorting, paging, script hooks
 - [`docs/authentication-and-sessions.md`](./docs/authentication-and-sessions.md): auth modes, pooling, lifecycle
-- [`docs/typescript-layouts.md`](./docs/typescript-layouts.md): typed layouts and stronger autocomplete
-- [`docs/testGuide.md`](./docs/testGuide.md): local test commands
-
-API reference:
-
-- [`docs_out/index.html`](./docs_out/index.html): generated TypeDoc site
-
-## Build Docs
-
-```sh
-npm run docs:build
-```
-
-## Test
-
-```sh
-npm test
-npm run test:unit
-npm run test:integration
-```
-
-Integration tests require a working FileMaker environment and credentials.
+- [`docs/provider-api.md`](./docs/provider-api.md): custom transports and provider sessions
+- [`docs/typescript-layouts.md`](./docs/typescript-layouts.md): typed layouts and stronger autocomplete
+- [`docs/testGuide.md`](./docs/testGuide.md): local test commands
+
+API reference:
+
+- [`docs_out/index.html`](./docs_out/index.html): generated TypeDoc site
+
+## Build Docs
+
+```sh
+npm run docs:build
+```
+
+## Test
+
+```sh
+npm test
+npm run test:unit
+npm run test:integration
+```
+
+Integration tests require a working FileMaker environment and credentials.

package/dist/bin/cli.js

@@ -3,15 +3,44 @@
  * Copyright (c) 2024. See LICENSE file for more information
  */
 import { Command } from 'commander';
-import { generateTypesCLI } from './generateTypes.js';
+import { pathToFileURL } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { loadEnvFile } from 'node:process';
+import chalk from 'chalk';
+import { configExists, initializeTypegen } from './init.js';
 const program = new Command();
 program
     .name('easyfm')
     .description('A NodeJS wrapper for the FileMaker Data CLI');
 program
-    .command('generate-types')
-    .description('Automatically generate layout interfaces from your database')
-    .action(async () => {
-    await generateTypesCLI();
+    .command('init')
+    .description('Interactively create an EasyFM typegen configuration')
+    .option('-c, --config <path>', 'config module', 'easyfm.config.js')
+    .action(async ({ config }) => {
+    await initializeTypegen({ config });
+});
+program
+    .command('typegen')
+    .description('Generate a typed, runtime-validated EasyFM client')
+    .option('-c, --config <path>', 'config module', 'easyfm.config.js')
+    .action(async ({ config }) => {
+    const configPath = resolve(config);
+    if (!await configExists(configPath)) {
+        console.log(chalk.yellow(`No config found at ${configPath}; starting setup.`));
+        await initializeTypegen({ config: configPath });
+    }
+    try {
+        loadEnvFile(resolve(dirname(configPath), '.env'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const typegen = await import('../typegen/index.js');
+    if (await typegen.ensureZodInstalled(dirname(configPath)))
+        console.log(chalk.green('Installed Zod for generated runtime validation.'));
+    const loaded = await import(pathToFileURL(configPath).href);
+    const result = await typegen.generate(loaded.default);
+    console.log(chalk.green(`Generated ${result.layouts} layouts in ${result.output}`));
 });
 program.parse(process.argv);

package/dist/bin/generateClient.d.ts

@@ -0,0 +1 @@
+export declare function generateClient(): Promise<void>;

package/dist/bin/generateClient.js

@@ -0,0 +1,48 @@
+import { Database } from '../connection/database.js';
+import { DataApiProvider } from '../connection/DataApiProvider.js';
+import * as fs from "node:fs";
+const DATABASE_HOST = process?.env.FM_DB_HOST ?? 'http://localhost';
+const DATABASE_NAME = process.env.FM_DB_NAME ?? 'EasyFMBenchmark.fmp12';
+const DATABASE_ACCOUNT = process.env.FM_DB_ACCOUNT ?? 'Admin';
+const DATABASE_PASSWORD = process.env.FM_DB_PASSWORD ?? 'Admin';
+const FIELD_TYPE_MAP = {
+    number: { class: "NumberField", zodType: "z.string()" },
+    date: { class: "DateField", zodType: "z.string()" },
+    text: { class: "TextField", zodType: "z.string()" },
+    time: { class: "TimeField", zodType: "z.string()" },
+    timeStamp: { class: "TimeStampField", zodType: "z.string()" },
+    container: { class: "ContainerField", zodType: "z.string()" }
+};
+export async function generateClient() {
+    const DATABASE = Database.create({ provider: new DataApiProvider({
+            hostname: DATABASE_HOST,
+            database: 'EasyFMBenchmark',
+            credentials: {
+                method: 'filemaker',
+                username: DATABASE_ACCOUNT,
+                password: DATABASE_PASSWORD
+            },
+            externalSources: [],
+            debug: true
+        }), debug: true });
+    const LAYOUTS = await DATABASE.listLayouts();
+    const schema = await Promise.all(LAYOUTS.map(async (layout) => {
+        const metadata = await layout.getLayoutMeta();
+        // Generate type maps
+        const fieldTypesMap = metadata.fieldMetaData.map(field => {
+            return `${JSON.stringify(field.name)}: ${FIELD_TYPE_MAP[field.result].class}`;
+        });
+        // Generate validation
+        const fieldValidation = `z.object({${metadata.fieldMetaData.map(field => {
+            return `${JSON.stringify(field.name)}: ${FIELD_TYPE_MAP[field.result].zodType}`;
+        })})`;
+        return { layout, fieldTypesMap, fieldValidation };
+    }));
+    // Generate DB schema
+    const typeScriptSchema = `interface DatabaseSchema extends __DatabaseSchema {${schema.map(layout => {
+        return `${JSON.stringify(layout.layout.name)}: {${layout.fieldTypesMap.join(",")}}`;
+    })}}`;
+    fs.writeFileSync("./easyFMClient.ts", `import {Database, DataApiProvider, DatabaseSchema as __DatabaseSchema} from "@jd-data-limited/easy-fm"
+
+${typeScriptSchema}`);
+}

package/dist/bin/generateTypes.js

@@ -3,7 +3,8 @@
  */
 import { ApiFieldResultTypes } from '../models/apiResults.js';
 import inquirer from 'inquirer';
-import FMHost from '../connection/FMHost.js';
+import { Database } from '../connection/database.js';
+import { DataApiProvider } from '../connection/DataApiProvider.js';
 import * as fs from 'node:fs';
 function sub(str) {
     return str
@@ -98,21 +99,22 @@ export async function generateTypesCLI() {
             mask: '*'
         }
     ]);
-    const HOST = new FMHost(data.hostname, data.verify);
-    const DATABASE = HOST.database({
-        database: data.database,
-        credentials: {
-            method: 'filemaker',
-            username: data.username,
-            password: data.password
-        },
-        externalSources: []
-    });
+    const DATABASE = Database.create({ provider: new DataApiProvider({
+            hostname: data.hostname,
+            verify: data.verify,
+            database: data.database,
+            credentials: {
+                method: 'filemaker',
+                username: data.username,
+                password: data.password
+            },
+            externalSources: []
+        }) });
     // await DATABASE.login()
     // Create file write stream
     const stream = fs.createWriteStream('./types.ts');
     const layouts = await DATABASE.listLayouts();
-    stream.write('import FMHost, {Container, FieldBase, LayoutInterface, Portal} from "@jd-data-limited/easy-fm";\n');
+    stream.write('import {Database, DataApiProvider, ContainerField, BaseField, LayoutInterface, Portal} from "@jd-data-limited/easy-fm";\n');
     stream.write('// ' + layouts.length + ' layouts found\n\n');
     const layoutInterfaces = new Map();
     for (const layout of layouts) {
@@ -129,9 +131,9 @@ export async function generateTypesCLI() {
         const interfaceName = substituteName + 'LayoutInterface';
         layoutInterfaces.set(layout.name, {
             interfaceName,
-            interface: `export interface ${interfaceName} extends LayoutInterface {
-            fields: {${fields.join(',\n    ')}},
-            portals: {${portalsProcessed.join(',\n   ')}}
+            interface: `export interface ${interfaceName} extends LayoutInterface {
+            fields: {${fields.join(',\n    ')}},
+            portals: {${portalsProcessed.join(',\n   ')}}
         }`
         });
     }
@@ -139,11 +141,10 @@ export async function generateTypesCLI() {
     for (const layout of layoutInterfaces) {
         layoutInterfaceLinks.push([
             `${JSON.stringify(layout[0])}: ${layout[1].interfaceName}`,
-            `${sub(camelToSnakeCase(layout[0]).toUpperCase().replace(' ', '_'))}: HOST.getLayout<${layout[1].interfaceName}>(${JSON.stringify(layout[0])})`
+            `${sub(camelToSnakeCase(layout[0]).toUpperCase().replace(' ', '_'))}: DATABASE.layout<${layout[1].interfaceName}>(${JSON.stringify(layout[0])})`
         ]);
     }
-    stream.write(safeStringInjection `const HOST = new FMHost(${data.hostname}, ${data.timezoneOffset}, ${data.verify});`);
-    stream.write(`HOST.database<{layouts:{${layoutInterfaceLinks.map(i => i[0]).join(',')}}}>();`);
+    stream.write(`const DATABASE = Database.create<{layouts:{${layoutInterfaceLinks.map(i => i[0]).join(',')}}}>({provider: new DataApiProvider({hostname: ${JSON.stringify(data.hostname)}, database: ${JSON.stringify(data.database)}, credentials: {method: 'filemaker', username: ${JSON.stringify(data.username)}, password: ${JSON.stringify(data.password)}}, externalSources: []})});`);
     stream.write('\n\n');
     stream.write(`const LAYOUTS = {${layoutInterfaceLinks.map(i => i[1]).join(',')}};`);
     for (const layout of layoutInterfaces) {

package/dist/bin/init.d.ts

@@ -0,0 +1,6 @@
+export { configExists } from '../typegen/init.js';
+export interface InitOptions {
+    config: string;
+}
+/** Interactive initializer shared by `easyfm init` and first `easyfm typegen`. */
+export declare function initializeTypegen({ config }: InitOptions): Promise<boolean>;

package/dist/bin/init.js

@@ -0,0 +1,46 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { dirname, resolve } from 'node:path';
+import { configExists, readEnvironment, writeDataApiInitialization } from '../typegen/init.js';
+export { configExists } from '../typegen/init.js';
+/** Interactive initializer shared by `easyfm init` and first `easyfm typegen`. */
+export async function initializeTypegen({ config }) {
+    const configPath = resolve(config);
+    if (await configExists(configPath)) {
+        console.log(chalk.yellow(`Config already exists: ${configPath}`));
+        return false;
+    }
+    console.log(chalk.bold.cyan('EasyFM typegen setup'));
+    const envPath = resolve(dirname(configPath), '.env');
+    const existingEnvironment = await readEnvironment(envPath);
+    const answers = await inquirer.prompt([
+        { type: 'select', name: 'provider', message: 'Provider', choices: [{ name: 'Data API/OData', value: 'data-api/odata' }] },
+        { type: 'select', name: 'transports', message: 'Transports', default: 'both', choices: [
+                { name: 'Both', value: 'both' },
+                { name: 'Data API', value: 'data-api' },
+                { name: 'OData', value: 'odata' }
+            ] },
+        { type: 'input', name: 'hostname', message: 'FileMaker host URL', default: existingEnvironment.FM_HOST ?? 'https://', validate: validHost },
+        { type: 'input', name: 'database', message: 'Database filename', default: existingEnvironment.FM_DATABASE, validate: required('Database filename') },
+        { type: 'input', name: 'username', message: 'Username', default: existingEnvironment.FM_USERNAME, validate: required('Username') },
+        { type: 'password', name: 'password', message: existingEnvironment.FM_PASSWORD ? 'Password (leave blank to keep existing)' : 'Password', mask: '*', validate: value => existingEnvironment.FM_PASSWORD || value ? true : 'Password is required' },
+        { type: 'input', name: 'output', message: 'Generated client directory', default: './src/easyfm-generated', validate: required('Output directory') }
+    ]);
+    if (!answers.password)
+        answers.password = existingEnvironment.FM_PASSWORD ?? '';
+    await writeDataApiInitialization(configPath, answers);
+    console.log(chalk.green(`Created ${configPath}`));
+    console.log(chalk.green(`Saved Data API credentials in ${envPath}`));
+    console.log(chalk.dim('Keep .env out of version control.'));
+    return true;
+}
+function required(label) { return (value) => value.trim() ? true : `${label} is required`; }
+function validHost(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' || url.protocol === 'https:' ? true : 'Use an http:// or https:// URL';
+    }
+    catch {
+        return 'Use a valid http:// or https:// URL';
+    }
+}

package/dist/bin/stressSearch.js

@@ -4,7 +4,7 @@
  */
 import { Command, Option } from 'commander';
 import { config } from 'dotenv';
-import FMHost, { query } from '../index.js';
+import { DataApiProvider, Database, query } from '../index.js';
 config();
 function parseIntegerList(value) {
     return value
@@ -175,18 +175,18 @@ async function main() {
         warmup,
         concurrencyLevels
     });
-    const fmHost = new FMHost(host, false);
     const rows = [];
-    const connection = fmHost.database({
-        database,
-        credentials: {
-            method: 'filemaker',
-            username,
-            password
-        },
-        externalSources: [],
-        debug: options.debug
-    });
+    const connection = Database.create({ provider: new DataApiProvider({
+            hostname: host,
+            database,
+            credentials: {
+                method: 'filemaker',
+                username,
+                password
+            },
+            externalSources: [],
+            debug: options.debug
+        }), debug: options.debug });
     try {
         const layout = connection.layout(options.layout);
         await layout.getLayoutMeta();

package/dist/connection/DataApiProvider.d.ts

@@ -0,0 +1,15 @@
+import type { databaseOptionsWithExternalSources, loginOptionsClaris, loginOptionsFileMaker, loginOptionsOAuth, loginOptionsToken } from '../types.js';
+import type { DatabaseFormatting, DatabaseProvider, ProviderConnection, ProviderContext } from './databaseProvider.js';
+type Credentials = loginOptionsOAuth | loginOptionsFileMaker | loginOptionsClaris | loginOptionsToken;
+export interface DataApiProviderOptions extends databaseOptionsWithExternalSources<Credentials> {
+    hostname: string;
+    verify?: boolean;
+}
+export declare class DataApiProvider implements DatabaseProvider {
+    #private;
+    readonly name: string;
+    readonly formatting: DatabaseFormatting;
+    constructor(options: DataApiProviderOptions);
+    connect(context: ProviderContext): Promise<ProviderConnection>;
+}
+export {};