@jd-data-limited/easy-fm 4.1.14 → 5.0.0-beta.1

package/dist/connection/FMHost.d.ts

@@ -1,22 +1,26 @@
-import { Database } from './database.js';
+import { type Database } from './database.js';
 import { type HostBase } from './HostBase.js';
-import { type databaseOptionsWithExternalSources, type FMHostMetadata, type loginOptionsClaris, type loginOptionsFileMaker, type loginOptionsOAuth } from '../types.js';
+import { type databaseOptionsWithExternalSources, FMHostMetadata, type loginOptionsClaris, type loginOptionsFileMaker, type loginOptionsOAuth } from '../types.js';
 import { type DatabaseStructure } from '../databaseStructure.js';
 import { type Moment } from 'moment';
+import z from 'zod';
+import { type DatabaseProtocol } from './Session.js';
 /**
  * Represents a FileMaker host.
- * @implements {HostBase}
  */
 export default class FMHost implements HostBase {
     readonly hostname: string;
     readonly timezoneOffsetFunc: (moment: Moment) => number;
     readonly verify: boolean;
-    readonly protocol: 'http:' | 'https:';
-    _metadata: FMHostMetadata | null;
+    readonly protocol: DatabaseProtocol;
+    _metadata: z.infer<typeof FMHostMetadata> | null;
     constructor(_hostname: string, timezoneOffset?: (moment: Moment) => number, verify?: boolean);
-    get metadata(): FMHostMetadata;
+    get metadata(): z.infer<typeof FMHostMetadata>;
+    /** FileMaker host date format converted to Moment-compatible tokens. */
     get dateFormat(): string;
+    /** FileMaker host time format. */
     get timeFormat(): string;
+    /** FileMaker host timestamp format converted to Moment-compatible tokens. */
     get timeStampFormat(): string;
     /**
      * Retrieves a list of databases from the FileMaker Server.
@@ -25,7 +29,9 @@ export default class FMHost implements HostBase {
      * @throws {FMError} If the request to the FileMaker Server fails or if the response contains an error.
      * @returns {Promise<any[]>} A promise that resolves to an array of database objects if successful.
      */
-    listDatabases(credentials?: loginOptionsOAuth | loginOptionsFileMaker | loginOptionsClaris): Promise<any>;
+    listDatabases(credentials?: loginOptionsOAuth | loginOptionsFileMaker | loginOptionsClaris): Promise<{
+        name: string;
+    }[]>;
     /**
      * Creates a new database connection with the specified options.
      *
@@ -34,5 +40,15 @@ export default class FMHost implements HostBase {
      * @return {Database<T>} A new Database instance.
      */
     database<T extends DatabaseStructure>(data: databaseOptionsWithExternalSources): Database<T>;
-    getMetadata(): Promise<FMHostMetadata>;
+    /** Fetch and cache FileMaker host product metadata. */
+    getMetadata(): Promise<{
+        productInfo: {
+            name: string;
+            dateFormat: string;
+            timeFormat: string;
+            timeStampFormat: string;
+            buildDate?: Date | undefined;
+            version?: string | undefined;
+        };
+    }>;
 }

package/dist/connection/FMHost.js

@@ -3,10 +3,13 @@
  */
 import { generateAuthorizationHeaders } from './generateAuthorizationHeaders.js';
 import { FMError } from '../FMError.js';
-import { Database } from './database.js';
+import { FMHostMetadata } from '../types.js';
+import { ApiResults } from '../models/apiResults.js';
+import z from 'zod';
+import { DatabaseSessionPool } from './databaseSessionPool.js';
+import { DatabaseConstantSession } from './databaseConstantSession.js';
 /**
  * Represents a FileMaker host.
- * @implements {HostBase}
  */
 export default class FMHost {
     hostname;
@@ -35,12 +38,17 @@ export default class FMHost {
             }
         };
     }
+    /** FileMaker host date format converted to Moment-compatible tokens. */
     get dateFormat() {
         return this.metadata.productInfo.dateFormat
             .replace('dd', 'DD')
             .replace('yyyy', 'YYYY');
     }
-    get timeFormat() { return this.metadata.productInfo.timeFormat; }
+    /** FileMaker host time format. */
+    get timeFormat() {
+        return this.metadata.productInfo.timeFormat;
+    }
+    /** FileMaker host timestamp format converted to Moment-compatible tokens. */
     get timeStampFormat() {
         return this.metadata.productInfo.timeStampFormat
             .replace('dd', 'DD')
@@ -62,9 +70,15 @@ export default class FMHost {
             method: 'GET',
             headers
         });
-        const data = await _fetch.json();
+        const data = ApiResults.extend({
+            response: z.object({
+                databases: z.array(z.object({
+                    name: z.string()
+                }))
+            }).optional()
+        }).parse(await _fetch.json());
         // console.log(data.messages[0])
-        if (data.messages[0].code === '0' && data.response) {
+        if (data.messages[0].code === 0 && data.response) {
             return data.response.databases;
         }
         else {
@@ -79,17 +93,23 @@ export default class FMHost {
      * @return {Database<T>} A new Database instance.
      */
     database(data) {
-        return new Database(this, data);
+        if (data.credentials.method === 'filemaker')
+            return new DatabaseSessionPool(this, data);
+        // @ts-expect-error types are correct here
+        return new DatabaseConstantSession(this, data);
     }
+    /** Fetch and cache FileMaker host product metadata. */
     async getMetadata() {
         if (this._metadata)
             return this._metadata;
         const _fetch = await fetch(`${this.protocol}//${this.hostname}/fmi/data/v2/productInfo`, {
             method: 'GET'
         });
-        const data = await _fetch.json();
+        const raw = await _fetch.json();
+        console.log(raw);
+        const data = ApiResults.extend({ response: FMHostMetadata.optional() }).parse(raw);
         // console.log(data.messages[0])
-        if (data.messages[0].code === '0' && data.response) {
+        if (data.messages[0].code === 0 && data.response) {
             this._metadata = data.response;
             return data.response;
         }

package/dist/connection/HostBase.d.ts

@@ -1,11 +1,13 @@
 import { type FMHostMetadata } from '../types.js';
 import { type Moment } from 'moment';
+import { type z } from 'zod';
+import { type DatabaseProtocol } from './Session.js';
 export interface HostBase {
     readonly hostname: string;
-    readonly protocol: string;
+    readonly protocol: DatabaseProtocol;
     readonly timezoneOffsetFunc: (moment: Moment) => number;
     readonly verify: boolean;
-    metadata: FMHostMetadata;
+    metadata: z.infer<typeof FMHostMetadata>;
     getMetadata: () => PromiseLike<any>;
     timeFormat: string;
     dateFormat: string;

package/dist/connection/Session.d.ts

@@ -0,0 +1,34 @@
+import { CookieJar } from './CookieJar.js';
+export type DatabaseProtocol = 'http:' | 'https:';
+export type DatabaseEndpoint = `${DatabaseProtocol}//${string}/fmi/data/v2/databases/${string}`;
+interface SessionProps {
+    token: string;
+    /**
+     * A cookie jar that will be automatically cloned and used for this session
+     */
+    baseCookieJar?: CookieJar;
+    /**
+     * The full database endpoint
+     */
+    endpoint: DatabaseEndpoint;
+    /**
+     * Defines if a session should be kept alive, and how often to ping the database (in milliseconds)
+     */
+    keepAlive?: number;
+    abortSignal: AbortSignal;
+}
+export type Session = ReturnType<typeof session>;
+export declare function session(props: SessionProps): {
+    fetch: (url: string | URL, init?: RequestInit) => Promise<Response>;
+    logout(): Promise<void>;
+    validate: () => Promise<void>;
+};
+export declare class HttpError extends Error {
+    readonly res: Response;
+    readonly message: string;
+    static new(res: Response): Promise<HttpError>;
+    protected constructor(res: Response, message: string);
+    get status(): number;
+    get statusText(): string;
+}
+export {};

package/dist/connection/Session.js

@@ -0,0 +1,109 @@
+// import fetchWithCookies, {CookieJar} from 'node-fetch-cookies'
+import { CookieJar } from './CookieJar.js';
+import { ApiResults } from '../models/apiResults.js';
+import { z } from 'zod';
+export function session(props) {
+    const cookieJar = props.baseCookieJar ? CookieJar.clone(props.baseCookieJar) : new CookieJar();
+    let keepAliveInterval;
+    const shouldRedirectWithGet = (status, method) => (status === 303 ||
+        ((status === 301 || status === 302) && method === 'POST'));
+    const sessionFetch = async (url, init = {}) => {
+        let urlParsed = url instanceof URL ? url : new URL(url);
+        let requestInit = { ...init };
+        requestInit.signal = requestInit.signal ? AbortSignal.any([requestInit.signal, props.abortSignal]) : props.abortSignal;
+        for (let redirectCount = 0; redirectCount < 10; redirectCount++) {
+            /**
+             * Bind the authorization token to the request
+             */
+            const headers = new Headers(requestInit.headers);
+            headers.set('Authorization', 'Bearer ' + props.token);
+            const cookieHeader = cookieJar.getCookieHeader(urlParsed);
+            if (cookieHeader)
+                headers.set('Cookie', cookieHeader);
+            else
+                headers.delete('Cookie');
+            const res = await fetch(urlParsed, {
+                ...requestInit,
+                headers,
+                redirect: 'manual'
+            });
+            for (const header of res.headers.getSetCookie()) {
+                cookieJar.addCookie(urlParsed, header);
+            }
+            if (res.status >= 300 && res.status < 400) {
+                const location = res.headers.get('location');
+                if (!location) {
+                    throw new Error(`Redirect response missing Location header for ${urlParsed.toString()}`);
+                }
+                urlParsed = new URL(location, urlParsed);
+                const method = (requestInit.method ?? 'GET').toUpperCase();
+                if (shouldRedirectWithGet(res.status, method)) {
+                    requestInit = {
+                        ...requestInit,
+                        method: 'GET',
+                        body: undefined
+                    };
+                }
+                continue;
+            }
+            if (!res.ok) {
+                throw await HttpError.new(res);
+            }
+            return res;
+        }
+        throw new Error(`Too many redirects while fetching ${urlParsed.toString()}`);
+    };
+    /**
+     * sessionValidate throws an error if the session is invalid
+     */
+    const sessionValidate = async () => {
+        const res = await sessionFetch(`${props.endpoint}/validateSession`);
+        ApiResults.extend({
+            isSessionInUse: z.boolean()
+        }).parse(await res.json());
+    };
+    if (props.keepAlive) {
+        keepAliveInterval = setInterval(() => {
+            void sessionValidate().catch(() => {
+                // Keep-alive failures should not create unhandled rejections.
+            });
+        }, props.keepAlive);
+        keepAliveInterval.unref?.();
+    }
+    return {
+        fetch: sessionFetch,
+        async logout() {
+            if (keepAliveInterval)
+                clearInterval(keepAliveInterval);
+            await fetch(`${props.endpoint}/sessions/${props.token}`, {
+                method: 'DELETE'
+            });
+        },
+        validate: sessionValidate
+    };
+}
+export class HttpError extends Error {
+    res;
+    message;
+    static async new(res) {
+        let message = `HTTP Error: [${res.status} ${res.statusText}]:`;
+        try {
+            message += await res.text();
+        }
+        catch {
+            message += ' (failed to read response body)';
+        }
+        return new this(res, message);
+    }
+    constructor(res, message) {
+        super();
+        this.res = res;
+        this.message = message;
+    }
+    get status() {
+        return this.res.status;
+    }
+    get statusText() {
+        return this.res.statusText;
+    }
+}

package/dist/connection/database.d.ts

@@ -1,58 +1,59 @@
-import { EventEmitter } from 'events';
 import { type LayoutInterface } from '../layouts/layoutInterface.js';
 import { Layout } from '../layouts/layout.js';
 import { type databaseOptionsWithExternalSources, type Script } from '../types.js';
 import { type HostBase } from './HostBase.js';
 import { type DatabaseBase } from './databaseBase.js';
-import { type ApiResults } from '../models/apiResults.js';
 import { type DatabaseStructure } from '../databaseStructure.js';
-import { type RequestInfo, type RequestInit, type Response } from 'node-fetch';
+import { type DatabaseEndpoint, type Session } from './Session.js';
+import { z, type ZodType } from 'zod';
 /**
  * Represents a database connection.
  * @template T - The structure of the database.
  */
-export declare class Database<T extends DatabaseStructure> extends EventEmitter implements DatabaseBase {
+export declare abstract class Database<T extends DatabaseStructure> implements DatabaseBase {
     #private;
-    private _token;
     readonly host: HostBase;
-    private readonly connection_details;
-    private cookies;
     readonly name: string;
     readonly debug: boolean;
-    constructor(host: HostBase, conn: databaseOptionsWithExternalSources);
-    private generateExternalSourceLogin;
+    protected canOpenNewConnections: boolean;
     /**
-     * Logs out the user by deleting the current session token.
-     * Throws an error if the user is not logged in.
-     *
-     * @returns {Promise<void>} A promise that resolves with no value once the logout is successful.
-     * @throws {Error} Throws an error if the user is not logged in.
+     * Used during events where the application must logout
+     * @private
      */
+    protected abortController: AbortController;
+    protected constructor(host: HostBase, conn: databaseOptionsWithExternalSources<unknown>);
+    login(): Promise<void>;
     logout(): Promise<void>;
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     /**
-     * Logs in to the database. Not required, as this is often done automatically
-     *
-     * @param {boolean} [forceLogin=false] - Whether to force login even if already logged in.
-     * @throws {Error} - Throws an error if already logged in and forceLogin is false.
-     * @throws {FMError} - Throws an FMError if login fails.
-     * @return {Promise<string>} - Returns a promise that resolves to the access token upon successful login.
+     * The inheriting database class must implement this method to provide a session object.
+     * @param callback
+     * @protected
      */
-    login(forceLogin?: boolean): Promise<string | undefined>;
-    get token(): string;
+    protected abstract withSession<T>(callback: (session: Session) => Promise<T>): Promise<T>;
     /**
      * Returns the endpoint URL for the database connection.
      *
      * @returns {string} The endpoint URL.
      */
-    get endpoint(): string;
-    _apiRequestRaw(url: URL | RequestInfo, options?: RequestInit & {
-        headers?: Record<string, string>;
-        useCookieJar?: boolean;
-        retries?: number;
-    }, autoRelogin?: boolean): Promise<Response>;
-    _apiRequestJSON<T = any>(url: URL | RequestInfo, options?: RequestInit & {
-        headers?: Record<string, string>;
-    }): Promise<ApiResults<T>>;
+    get endpoint(): DatabaseEndpoint;
+    /**
+     * Uses an available session to run a fetch
+     * @param url
+     * @param options
+     */
+    fetch(url: string | URL, options?: RequestInit): Promise<Response>;
+    /**
+     * Uses an available session to run a fetch on a FileMaker Data API JSON endpoint. Also applies JSON/Zod type enforcement on result.
+     */
+    fetchJSON<T extends ZodType | null = null>(url: string | URL, options: RequestInit & {
+        type: T;
+    }): Promise<T extends ZodType ? z.infer<T> & {
+        httpStatus: number;
+    } : {
+        httpStatus: number;
+    }>;
     /**
      * Retrieves a list of layouts in the current FileMaker database.
      *
@@ -62,6 +63,8 @@ export declare class Database<T extends DatabaseStructure> extends EventEmitter
     listLayouts(page?: number): Promise<Layout<LayoutInterface>[]>;
     layout<R extends keyof T['layouts']>(name: R): Layout<T['layouts'][R]>;
     layout<R extends LayoutInterface>(name: string): Layout<R>;
+    /** Clears any Layout objects previously returned by `database.layout(...)`. */
     clearLayoutCache(): void;
+    /** Creates a script reference you can pass to read and write helpers. */
     script(name: string, parameter?: string): Script;
 }

package/dist/connection/database.js

@@ -1,106 +1,48 @@
 /*
  * Copyright (c) 2023-2024. See LICENSE file for more information
  */
-import { EventEmitter } from 'events';
-import { generateAuthorizationHeaders } from './generateAuthorizationHeaders.js';
 import { FMError } from '../FMError.js';
 import { Layout } from '../layouts/layout.js';
-import fetch from 'node-fetch';
-// @ts-expect-error - fetchWithCookies does not have available typescript types
-import fetchWithCookies, { CookieJar } from 'node-fetch-cookies';
+import { ApiLayout, ApiResults } from '../models/apiResults.js';
+import { z } from 'zod';
+import { addHeaders } from '../utils/addHeaders.js';
+import process from 'node:process';
 /**
  * Represents a database connection.
  * @template T - The structure of the database.
  */
-export class Database extends EventEmitter {
-    _token = '';
+export class Database {
     host;
-    connection_details;
-    cookies = new CookieJar();
     name;
     debug;
     #layoutCache = new Map();
+    canOpenNewConnections = true;
+    /**
+     * Used during events where the application must logout
+     * @private
+     */
+    abortController = new AbortController();
     constructor(host, conn) {
-        super();
         this.host = host;
         this.name = conn.database;
-        this.connection_details = conn;
         this.debug = conn.debug ?? false;
+        process.on('SIGINT', () => { void this.close(); });
+        process.on('SIGTERM', () => { void this.close(); });
+        process.on('beforeExit', () => { void this.close(); });
     }
-    // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-    generateExternalSourceLogin(data) {
-        if (data.credentials.method === 'filemaker') {
-            const _data = data.credentials;
-            return {
-                database: data.database,
-                username: _data.username,
-                password: _data.password
-            };
-        }
-        else {
-            throw new Error('Not yet supported login method');
-        }
+    async login() {
+        await Promise.resolve();
     }
-    /**
-     * Logs out the user by deleting the current session token.
-     * Throws an error if the user is not logged in.
-     *
-     * @returns {Promise<void>} A promise that resolves with no value once the logout is successful.
-     * @throws {Error} Throws an error if the user is not logged in.
-     */
     async logout() {
-        if (this.token === '')
-            throw new Error('Not logged in');
-        const _fetch = await fetch(`${this.endpoint}/sessions/${this.token}`, {
-            method: 'DELETE',
-            headers: {
-                'content-type': 'application/json'
-            }
-        });
-        await _fetch.json();
-        this._token = '';
+        await this.close();
     }
-    /**
-     * Logs in to the database. Not required, as this is often done automatically
-     *
-     * @param {boolean} [forceLogin=false] - Whether to force login even if already logged in.
-     * @throws {Error} - Throws an error if already logged in and forceLogin is false.
-     * @throws {FMError} - Throws an FMError if login fails.
-     * @return {Promise<string>} - Returns a promise that resolves to the access token upon successful login.
-     */
-    async login(forceLogin = false) {
-        if (this.token !== '' && !forceLogin)
-            return;
-        // Reset cookies
-        this.cookies = new CookieJar();
-        await this.host.getMetadata();
-        if (this.connection_details.credentials.method === 'token') {
-            this._token = (this.connection_details.credentials).token;
-            return this.token;
-        }
-        const url = new URL(`${this.endpoint}/sessions`);
-        url.hostname = this.host.hostname;
-        const res = await fetch(url, {
-            method: 'POST',
-            headers: generateAuthorizationHeaders(this.connection_details.credentials),
-            body: JSON.stringify({
-                fmDataSource: this.connection_details.externalSources.map(i => {
-                    const _i = i;
-                    return this.generateExternalSourceLogin(_i);
-                })
-            })
-        });
-        const _res = (await res.json());
-        if (res.status === 200) {
-            this._token = res.headers.get('x-fm-data-access-token') ?? '';
-            return this._token;
-        }
-        else {
-            throw new FMError(_res.messages[0].code, _res.status, res);
-        }
+    async close() {
+        this.canOpenNewConnections = false;
+        if (!this.abortController.signal.aborted)
+            this.abortController.abort('Closing connection');
     }
-    get token() {
-        return this._token;
+    async [Symbol.asyncDispose]() {
+        await this.close();
     }
     /**
      * Returns the endpoint URL for the database connection.
@@ -110,57 +52,49 @@ export class Database extends EventEmitter {
     get endpoint() {
         return `${this.host.protocol}//${this.host.hostname}/fmi/data/v2/databases/${this.name}`;
     }
-    async _apiRequestRaw(url, options = {}, autoRelogin = true) {
-        if (this.debug) {
-            console.log(`EASYFM DEBUG: ${JSON.stringify(options)} ${url instanceof URL
-                ? url.toString()
-                : typeof url === 'string' ? url : url.url}`);
-        }
-        const urlParsed = (url instanceof URL
-            ? url
-            : typeof url === 'string'
-                ? new URL(url)
-                : new URL(url.url));
-        const reqIsToDBHost = urlParsed.hostname === this.host.hostname && urlParsed.pathname.startsWith("/fmi/data");
-        if (reqIsToDBHost && this.token === '')
-            await this.login(true);
-        if (!options.headers)
-            options.headers = {};
-        if (reqIsToDBHost)
-            options.headers.authorization = 'Bearer ' + this._token;
-        const _fetch = options.useCookieJar
-            ? await fetchWithCookies(this.cookies, url, options)
-            : await fetch(url, options);
-        if (!_fetch.ok && (!options.retries || options.retries > 0)) {
-            if (this.debug) {
-                console.log(`EASYFM DEBUG: RE-ATTEMPTING REQUEST (${_fetch.status}) ${url instanceof URL
-                    ? url.toString()
-                    : typeof url === 'string' ? url : url.url}`);
+    /**
+     * Uses an available session to run a fetch
+     * @param url
+     * @param options
+     */
+    async fetch(url, options) {
+        return await this.withSession(async (session) => await session.fetch(url, options));
+    }
+    /**
+     * Uses an available session to run a fetch on a FileMaker Data API JSON endpoint. Also applies JSON/Zod type enforcement on result.
+     */
+    async fetchJSON(url, options) {
+        const _options = options ?? {};
+        addHeaders(_options, {
+            'Content-Type': 'application/json'
+        });
+        const res = await this.fetch(url, _options);
+        const rawData = await res.json();
+        if (this.debug)
+            console.log(rawData.response);
+        if (options.type !== null) {
+            const data = ApiResults.extend({ response: options.type.optional() })
+                .parse(rawData);
+            if (data.messages[0].code !== 0) {
+                throw new FMError(data.messages[0].code, res.status, data);
             }
-            return await this._apiRequestRaw(url, { ...options, retries: (options?.retries ?? 1) - 1 });
-        }
-        else if (_fetch.status === 401 && reqIsToDBHost && autoRelogin) {
-            await this.login(true);
-            return await this._apiRequestRaw(url, options, false);
+            return data.response
+                // @ts-expect-error is correct
+                ? {
+                    ...data.response,
+                    httpStatus: res.status
+                }
+                // @ts-expect-error is correct
+                : { httpStatus: res.status };
         }
-        else
-            return _fetch;
-    }
-    async _apiRequestJSON(url, options = {}) {
-        if (!options.headers)
-            options.headers = {};
-        options.headers['content-type'] = options.headers['content-type'] ? options.headers['content-type'] : 'application/json';
-        const _fetch = await this._apiRequestRaw(url, options);
-        const data = await _fetch.json();
-        // Remove response if it is empty. This makes checking for an empty response easier
-        if (data.response && Object.keys(data.response).length === 0)
-            delete data.response;
-        // console.log(data.messages[0])
-        if (data.messages[0].code !== '0') {
-            throw new FMError(data.messages[0].code, _fetch.status, data);
+        const data = ApiResults.parse(rawData);
+        if (data.messages[0].code !== 0) {
+            throw new FMError(data.messages[0].code, res.status, data);
         }
-        data.httpStatus = _fetch.status;
-        return data;
+        // @ts-expect-error is correct
+        return {
+            httpStatus: res.status
+        };
     }
     /**
      * Retrieves a list of layouts in the current FileMaker database.
@@ -169,9 +103,9 @@ export class Database extends EventEmitter {
      * @throws {FMError} If there was an error retrieving the layouts.
      */
     async listLayouts(page = 0) {
-        const req = await this._apiRequestJSON(`${this.endpoint}/layouts?page=${encodeURIComponent(page)}`);
-        if (!req.response)
-            throw new FMError(req.messages[0].code, req.httpStatus, req.messages[0].message);
+        const res = await this.fetchJSON(`${this.endpoint}/layouts?page=${encodeURIComponent(page)}`, {
+            type: z.object({ layouts: z.array(ApiLayout) })
+        });
         const cycleLayoutNames = (layouts) => {
             let names = [];
             for (const layout of layouts) {
@@ -182,8 +116,11 @@ export class Database extends EventEmitter {
             }
             return names;
         };
-        return cycleLayoutNames(req.response.layouts).map(layout => new Layout(this, layout));
+        return cycleLayoutNames(res.layouts).map(layout => new Layout(this, layout));
     }
+    /**
+     * Returns a FileMaker Layout object by name.
+     */
     layout(name) {
         let layout = this.#layoutCache.get(name);
         if (layout)
@@ -192,9 +129,11 @@ export class Database extends EventEmitter {
         this.#layoutCache.set(name, layout);
         return layout;
     }
+    /** Clears any Layout objects previously returned by `database.layout(...)`. */
     clearLayoutCache() {
         this.#layoutCache.clear();
     }
+    /** Creates a script reference you can pass to read and write helpers. */
     script(name, parameter = '') {
         return { name, parameter };
     }