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

package/dist/connection/databaseBase.d.ts

@@ -1,16 +1,28 @@
 import { type HostBase } from './HostBase.js';
-import { type ApiResults } from '../models/apiResults.js';
-import { type RequestInfo, type RequestInit, type Response } from 'node-fetch';
+import { type z, type ZodType } from 'zod';
 export interface DatabaseBase {
     host: HostBase;
     readonly name: string;
     endpoint: string;
-    token: string;
-    _apiRequestJSON: <T = unknown>(url: URL | RequestInfo, options?: RequestInit & {
-        headers?: Record<string, string>;
-    } | undefined, autoRelogin?: boolean) => Promise<ApiResults<T>>;
-    _apiRequestRaw: (url: URL | RequestInfo, options?: RequestInit & {
-        headers?: Record<string, string>;
-        useCookieJar?: boolean;
-    } | undefined) => Promise<Response>;
+    /**
+     * @deprecated login is deprecated and is now handled by newer session management. This function is simply a placeholder.
+     */
+    login: () => Promise<void>;
+    /**
+     * Immediately closes all open sessions and prevents new ones from being created.
+     */
+    close: () => Promise<void>;
+    /**
+     * Immediately closes all open sessions and prevents new ones from being created.
+     * Alias of {@link close}
+     */
+    logout: () => Promise<void>;
+    fetch: (url: string | URL, options?: RequestInit) => Promise<Response>;
+    fetchJSON: <T extends ZodType | null = null>(url: string | URL, options: RequestInit & {
+        type: T;
+    }) => Promise<T extends ZodType ? z.infer<T> & {
+        httpStatus: number;
+    } : {
+        httpStatus: number;
+    }>;
 }

package/dist/connection/databaseConstantSession.d.ts

@@ -0,0 +1,15 @@
+import { Database } from './database.js';
+import type { DatabaseStructure } from '../databaseStructure.js';
+import { type Session } from './Session.js';
+import { type databaseOptionsWithExternalSources, type loginOptionsClaris, type loginOptionsOAuth, type loginOptionsToken } from '../types.js';
+import type FMHost from './FMHost.js';
+/**
+ * DatabaseConstantSession handles database connections that must live on a single session which is kept alive.
+ * For example, connections that rely on OAuth.
+ */
+export declare class DatabaseConstantSession<T extends DatabaseStructure> extends Database<T> {
+    #private;
+    constructor(host: FMHost, connectionDetails: databaseOptionsWithExternalSources<loginOptionsOAuth | loginOptionsClaris | loginOptionsToken>, structure: T);
+    close(): Promise<void>;
+    withSession<T>(callback: (session: Session) => Promise<T>): Promise<T>;
+}

package/dist/connection/databaseConstantSession.js

@@ -0,0 +1,70 @@
+import { Database } from './database.js';
+import { session } from './Session.js';
+import { generateAuthorizationHeaders } from './generateAuthorizationHeaders.js';
+import { FMError } from '../FMError.js';
+import { ApiResults } from '../models/apiResults.js';
+import { CookieJar } from './CookieJar.js';
+/**
+ * DatabaseConstantSession handles database connections that must live on a single session which is kept alive.
+ * For example, connections that rely on OAuth.
+ */
+export class DatabaseConstantSession extends Database {
+    #session;
+    constructor(host, connectionDetails, structure) {
+        super(host, connectionDetails);
+        if (connectionDetails.externalSources.length !== 0)
+            throw new Error('External sources are currently only supported for connections with the \'FileMaker\' login method.');
+        this.#session = (async () => {
+            // Ensure we have host metadata
+            await this.host.getMetadata();
+            if (connectionDetails.credentials.method === 'token') {
+                return session({
+                    token: (connectionDetails.credentials).token,
+                    keepAlive: 60_000,
+                    endpoint: this.endpoint,
+                    abortSignal: this.abortController.signal
+                });
+            }
+            const url = new URL(`${this.endpoint}/sessions`);
+            url.hostname = this.host.hostname;
+            const cookiejar = new CookieJar();
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: generateAuthorizationHeaders(connectionDetails.credentials),
+                body: JSON.stringify({
+                    fmDataSource: connectionDetails.externalSources.map(data => ({
+                        database: data.database,
+                        username: data.credentials.username,
+                        password: data.credentials.password
+                    }))
+                })
+            });
+            for (const cookie of res.headers.getSetCookie())
+                cookiejar.addCookie(url, cookie);
+            const json = ApiResults.parse(await res.json());
+            if (res.status === 200) {
+                return session({
+                    token: res.headers.get('x-fm-data-access-token') ?? '',
+                    keepAlive: 60_000,
+                    endpoint: this.endpoint,
+                    baseCookieJar: cookiejar,
+                    abortSignal: this.abortController.signal
+                });
+            }
+            else {
+                throw new FMError(json.messages[0].code, res.status, res);
+            }
+        })();
+    }
+    async close() {
+        if (this.abortController.signal.aborted)
+            return;
+        await super.close();
+        await (await this.#session).logout();
+    }
+    async withSession(callback) {
+        if (!this.canOpenNewConnections)
+            throw new Error('Cannot open new connections');
+        return await callback(await this.#session);
+    }
+}

package/dist/connection/databaseSessionPool.d.ts

@@ -0,0 +1,14 @@
+import { Database } from './database.js';
+import type { DatabaseStructure } from '../databaseStructure.js';
+import { type Session } from './Session.js';
+import { type databaseOptionsWithExternalSources, type loginOptionsFileMaker } from '../types.js';
+import type FMHost from './FMHost.js';
+/**
+ * DatabaseSessionPool handles database connections that can be pooled.
+ */
+export declare class DatabaseSessionPool<T extends DatabaseStructure> extends Database<T> {
+    #private;
+    constructor(host: FMHost, connectionDetails: databaseOptionsWithExternalSources<loginOptionsFileMaker>);
+    close(): Promise<void>;
+    withSession<T>(callback: (session: Session) => Promise<T>, retry?: boolean): Promise<T>;
+}

package/dist/connection/databaseSessionPool.js

@@ -0,0 +1,148 @@
+import { Database } from './database.js';
+import { HttpError, session } from './Session.js';
+import { generateAuthorizationHeaders } from './generateAuthorizationHeaders.js';
+import { FMError } from '../FMError.js';
+import { ApiResults } from '../models/apiResults.js';
+import { CookieJar } from './CookieJar.js';
+/**
+ * DatabaseSessionPool handles database connections that can be pooled.
+ */
+export class DatabaseSessionPool extends Database {
+    #connectionDetails;
+    #activeSessions = new Set();
+    #withSessionQueue = [];
+    constructor(host, connectionDetails) {
+        super(host, connectionDetails);
+        this.#connectionDetails = connectionDetails;
+    }
+    async close() {
+        if (this.abortController.signal.aborted)
+            return;
+        await super.close();
+        // System might be shutting down, so we want to make sure we're quick
+        const sessions = [...this.#activeSessions];
+        this.#activeSessions.clear();
+        await Promise.allSettled(sessions.map(session => session.session.logout()));
+    }
+    get #maxSessions() {
+        return this.#connectionDetails.credentials.sessionPoolSize ?? 8;
+    }
+    // Opens a new database session
+    async #openSession() {
+        if (!this.canOpenNewConnections)
+            throw new Error('Cannot open new connections');
+        await this.host.getMetadata();
+        const url = new URL(`${this.endpoint}/sessions`);
+        url.hostname = this.host.hostname;
+        const cookiejar = new CookieJar();
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: generateAuthorizationHeaders(this.#connectionDetails.credentials),
+            body: JSON.stringify({
+                fmDataSource: this.#connectionDetails.externalSources.map(data => ({
+                    database: data.database,
+                    username: data.credentials.username,
+                    password: data.credentials.password
+                }))
+            })
+        });
+        for (const cookie of res.headers.getSetCookie())
+            cookiejar.addCookie(url, cookie);
+        const _res = ApiResults.parse(await res.json());
+        if (res.status === 200) {
+            return session({
+                token: res.headers.get('x-fm-data-access-token') ?? '',
+                endpoint: this.endpoint,
+                baseCookieJar: cookiejar,
+                abortSignal: this.abortController.signal
+            });
+        }
+        else {
+            throw new FMError(_res.messages[0].code, res.status, res);
+        }
+    }
+    /**
+     *
+     * @param session
+     * @param callback
+     * @param retry when true, if an HTTP 401 error occurs, we'll re-attempt it with another session.
+     * @private
+     */
+    async #withSessionInternal(session, callback, retry) {
+        try {
+            session.working = true;
+            const result = await callback(session.session);
+            return result;
+        }
+        catch (e) {
+            if (e instanceof HttpError && e.status === 401) {
+                // Invalidate this session
+                this.#activeSessions.delete(session);
+                if (retry)
+                    return await this.withSession(callback, false);
+            }
+            throw e;
+        }
+        finally {
+            if (this.#activeSessions.has(session)) {
+                session.working = false;
+            }
+            await this.#scheduleQueuedWork();
+        }
+    }
+    async #processWithSessionQueue(session) {
+        const job = this.#withSessionQueue.shift();
+        if (!job)
+            return;
+        await this.#withSessionInternal(session, job.callback, job.retry).then(job.resolve).catch(job.reject);
+    }
+    async #scheduleQueuedWork() {
+        if (this.#withSessionQueue.length === 0)
+            return;
+        for (const session of this.#activeSessions) {
+            if (!session.working) {
+                session.working = true;
+                void this.#processWithSessionQueue(session);
+                return;
+            }
+        }
+        if (this.#activeSessions.size < this.#maxSessions) {
+            void this.#openSession().then(async (session) => {
+                const newSession = {
+                    working: true,
+                    session,
+                    disconnectTimeout: null
+                };
+                this.#activeSessions.add(newSession);
+                await this.#processWithSessionQueue(newSession);
+            });
+        }
+    }
+    async withSession(callback, retry = true) {
+        return await new Promise((resolve, reject) => {
+            // First, see if there's an available session
+            for (const session of this.#activeSessions) {
+                if (!session.working) {
+                    session.working = true;
+                    this.#withSessionInternal(session, callback, retry).then(resolve).catch(reject);
+                    return;
+                }
+            }
+            // If there's no available sessions, next check if we can open a new one
+            if (this.#activeSessions.size < this.#maxSessions) {
+                this.#openSession().then(async (session) => {
+                    const newSession = {
+                        working: true,
+                        session,
+                        disconnectTimeout: null
+                    };
+                    this.#activeSessions.add(newSession);
+                    return await this.#withSessionInternal(newSession, callback, retry);
+                }).then(resolve).catch(reject);
+                return;
+            }
+            // Finally if all else fails, queue the job
+            this.#withSessionQueue.push({ callback, resolve, reject, retry });
+        });
+    }
+}

package/dist/index.d.ts

@@ -1,18 +1,35 @@
 import FMHost from './connection/FMHost.js';
 import type * as TYPES from './types.js';
+/** Error type returned for FileMaker Data API failures. */
 export { FMError } from './FMError.js';
+/** Utility type for narrowing portal data on typed layouts. */
 export { type PickPortals } from './types.js';
+/** Base database connection abstraction used by all auth modes. */
 export { Database } from './connection/database.js';
+/** Layout-scoped API wrapper for metadata, scripts, and record operations. */
 export { Layout } from './layouts/layout.js';
+/** Base record implementation shared by layout and portal records. */
 export { RecordBase } from './records/recordBase.js';
+/** Record returned from a layout. Supports fetch, commit, duplicate, and delete. */
 export { LayoutRecord } from './records/layoutRecord.js';
+/** Type helpers for describing typed layouts and portals. */
 export { type LayoutInterface, type PortalInterface } from './layouts/layoutInterface.js';
+/** Record returned from a portal row. */
 export { PortalRecord } from './records/portalRecord.js';
+/** Wrapper around portal rows included in a layout record. */
 export { Portal } from './records/portal.js';
+/** Types and builder used for list/find record operations. */
 export { type FindRequest, type FindRequestRaw, RecordGetOperation } from './records/getOperations/recordGetOperation.js';
+/** Entry point for `layout.records.*` operations. */
 export { LayoutRecordManager } from './layouts/layoutRecordManager.js';
+/** Type alias for map of fields on a typed record. */
 export { type RecordFieldsMap } from './layouts/recordFieldsMap.js';
+/** Helpers for safe FileMaker find query construction and date/time formatting. */
 export { asDate, asTime, asTimestamp, query, queryEscape } from './utils/query.js';
+/** Field wrapper used for reading, editing, and container access. */
 export { type Container, Field } from './records/field.js';
+/** Default export. Represents FileMaker host/server. */
 export default FMHost;
-export { type TYPES };
+export { 
+/** Namespace re-export of library public types. */
+type TYPES };

package/dist/index.js

@@ -2,15 +2,27 @@
  * Copyright (c) 2023-2024. See LICENSE file for more information
  */
 import FMHost from './connection/FMHost.js';
+/** Error type returned for FileMaker Data API failures. */
 export { FMError } from './FMError.js';
+/** Base database connection abstraction used by all auth modes. */
 export { Database } from './connection/database.js';
+/** Layout-scoped API wrapper for metadata, scripts, and record operations. */
 export { Layout } from './layouts/layout.js';
+/** Base record implementation shared by layout and portal records. */
 export { RecordBase } from './records/recordBase.js';
+/** Record returned from a layout. Supports fetch, commit, duplicate, and delete. */
 export { LayoutRecord } from './records/layoutRecord.js';
+/** Record returned from a portal row. */
 export { PortalRecord } from './records/portalRecord.js';
+/** Wrapper around portal rows included in a layout record. */
 export { Portal } from './records/portal.js';
+/** Types and builder used for list/find record operations. */
 export { RecordGetOperation } from './records/getOperations/recordGetOperation.js';
+/** Entry point for `layout.records.*` operations. */
 export { LayoutRecordManager } from './layouts/layoutRecordManager.js';
+/** Helpers for safe FileMaker find query construction and date/time formatting. */
 export { asDate, asTime, asTimestamp, query, queryEscape } from './utils/query.js';
+/** Field wrapper used for reading, editing, and container access. */
 export { Field } from './records/field.js';
+/** Default export. Represents FileMaker host/server. */
 export default FMHost;

package/dist/layouts/layout.d.ts

@@ -3,13 +3,15 @@ import { type Script, type ScriptResult } from '../types.js';
 import { type LayoutInterface } from './layoutInterface.js';
 import { type LayoutBase } from './layoutBase.js';
 import { type DatabaseBase } from '../connection/databaseBase.js';
-import { type ApiLayoutMetadata } from '../models/apiResults.js';
+import { ApiLayoutMetadata } from '../models/apiResults.js';
+import { type z } from 'zod';
 export declare class Layout<T extends LayoutInterface> implements LayoutBase {
     readonly database: DatabaseBase;
     readonly name: string;
     readonly records: LayoutRecordManager<T>;
-    metadata: ApiLayoutMetadata | null;
+    metadata: z.infer<typeof ApiLayoutMetadata> | null;
     constructor(database: DatabaseBase, name: string);
+    /** Base endpoint for this layout on FileMaker Data API. */
     get endpoint(): string;
     /**
      * Executes a FileMaker script on this layout asynchronously and returns the result.
@@ -23,5 +25,5 @@ export declare class Layout<T extends LayoutInterface> implements LayoutBase {
      * @returns {Promise<ApiLayoutMetadata>} The layout metadata.
      * @throws {FMError} If an error occurs during the API request.
      */
-    getLayoutMeta(): Promise<ApiLayoutMetadata>;
+    getLayoutMeta(): Promise<z.infer<typeof ApiLayoutMetadata>>;
 }

package/dist/layouts/layout.js

@@ -3,6 +3,7 @@
  */
 import { LayoutRecordManager } from './layoutRecordManager.js';
 import { FMError } from '../FMError.js';
+import { ApiLayoutMetadata, ApiScriptResult } from '../models/apiResults.js';
 export class Layout {
     database;
     name;
@@ -12,6 +13,7 @@ export class Layout {
         this.database = database;
         this.name = name;
     }
+    /** Base endpoint for this layout on FileMaker Data API. */
     get endpoint() {
         return `${this.database.endpoint}/layouts/${this.name}`;
     }
@@ -24,19 +26,15 @@ export class Layout {
         let url = `${this.endpoint}/script/${encodeURIComponent(script.name)}`;
         if (script.parameter)
             url += '?script.param=' + encodeURIComponent(script.parameter);
-        const res = await this.database._apiRequestJSON(url, {
+        const res = await this.database.fetchJSON(url, {
+            type: ApiScriptResult,
             method: 'GET'
         });
-        if (res.response && res.messages[0].code === '0') {
-            const error = parseInt(res.response.scriptError);
-            return {
-                scriptError: error ? new FMError(error, 200, res) : undefined,
-                scriptResult: res.response.scriptResult
-            };
-        }
-        else {
-            throw new FMError(res.messages[0].code, res.httpStatus, res);
-        }
+        const error = parseInt(res.scriptError);
+        return {
+            scriptError: error ? new FMError(error, 200, res) : undefined,
+            scriptResult: res.scriptResult
+        };
     }
     /**
      * Retrieves the layout metadata
@@ -48,10 +46,8 @@ export class Layout {
         if (this.metadata) {
             return this.metadata;
         }
-        const res = await this.database._apiRequestJSON(this.endpoint);
-        if (!res.response)
-            throw new FMError(res.messages[0].code, res.httpStatus, res);
-        this.metadata = res.response;
+        const res = await this.database.fetchJSON(this.endpoint, { type: ApiLayoutMetadata });
+        this.metadata = res;
         return this.metadata;
     }
 }

package/dist/layouts/layoutBase.d.ts

@@ -1,11 +1,12 @@
 import { type Script, type ScriptResult } from '../types.js';
 import { type DatabaseBase } from '../connection/databaseBase.js';
 import { type ApiLayoutMetadata } from '../models/apiResults.js';
+import { type z } from 'zod';
 export interface LayoutBase {
     readonly name: string;
-    metadata: ApiLayoutMetadata | null;
+    metadata: z.infer<typeof ApiLayoutMetadata> | null;
     endpoint: string;
     runScript: (script: Script) => Promise<ScriptResult>;
-    getLayoutMeta: () => Promise<ApiLayoutMetadata>;
+    getLayoutMeta: () => Promise<z.infer<typeof ApiLayoutMetadata>>;
     database: DatabaseBase;
 }

package/dist/layouts/layoutRecordManager.d.ts

@@ -3,33 +3,24 @@ import { type LayoutInterface } from './layoutInterface.js';
 import { type LayoutBase } from './layoutBase.js';
 import { type GetOperationOptions, RecordGetOperation } from '../records/getOperations/recordGetOperation.js';
 import { type PickPortals, type RecordFetchOptions } from '../types.js';
-/**
- * Manager class for handling layout records.
- */
+/** Provides the `layout.records.*` methods for a Layout. */
 export declare class LayoutRecordManager<T extends LayoutInterface> {
     readonly layout: LayoutBase;
     constructor(layout: LayoutBase);
     /**
-     * Creates a new layout record with the provided options.
+     * Creates a new unsaved record for this layout.
      *
-     * @param {OPTIONS} options - The options for creating the layout record.
-     * @return {Promise<LayoutRecord<PickPortals<T, OPTIONS['portals'][number]>>>}
-     * The newly created layout record.
+     * Set field values, then call `commit()` to save it.
      */
     create<OPTIONS extends RecordFetchOptions>(options: OPTIONS): Promise<LayoutRecord<PickPortals<T, OPTIONS['portals'][number]>>>;
     /**
-     * Retrieves a layout record based on the given recordId.
+     * Returns one record by FileMaker `recordId`.
      *
-     * @param {number} recordId - The identifier of the record to retrieve.
-     *
-     * @returns {Promise<LayoutRecord<PickPortals<T, never>>>} - A Promise that resolves with the retrieved layout record.
+     * Prefer a normal find when you have a business field you can search by.
      */
     get(recordId: number): Promise<LayoutRecord<PickPortals<T, never>>>;
     /**
-     * Creates a new instance of RecordGetOperation with the given options.
-     *
-     * @param {Array} options - An array of options for the operation.
-     * @return {RecordGetOperation} - A new instance of RecordGetOperation.
+     * Starts a list or find request for this layout.
      */
     list<OPTIONS extends GetOperationOptions<T>>(options: OPTIONS): RecordGetOperation<T, OPTIONS>;
 }

package/dist/layouts/layoutRecordManager.js

@@ -3,20 +3,16 @@
  */
 import { LayoutRecord } from '../records/layoutRecord.js';
 import { RecordGetOperation } from '../records/getOperations/recordGetOperation.js';
-/**
- * Manager class for handling layout records.
- */
+/** Provides the `layout.records.*` methods for a Layout. */
 export class LayoutRecordManager {
     layout;
     constructor(layout) {
         this.layout = layout;
     }
     /**
-     * Creates a new layout record with the provided options.
+     * Creates a new unsaved record for this layout.
      *
-     * @param {OPTIONS} options - The options for creating the layout record.
-     * @return {Promise<LayoutRecord<PickPortals<T, OPTIONS['portals'][number]>>>}
-     * The newly created layout record.
+     * Set field values, then call `commit()` to save it.
      */
     async create(options) {
         const metadata = await this.layout.getLayoutMeta();
@@ -30,11 +26,9 @@ export class LayoutRecordManager {
         return new LayoutRecord(this.layout, -1, 0, fields, portals);
     }
     /**
-     * Retrieves a layout record based on the given recordId.
-     *
-     * @param {number} recordId - The identifier of the record to retrieve.
+     * Returns one record by FileMaker `recordId`.
      *
-     * @returns {Promise<LayoutRecord<PickPortals<T, never>>>} - A Promise that resolves with the retrieved layout record.
+     * Prefer a normal find when you have a business field you can search by.
      */
     async get(recordId) {
         await this.layout.getLayoutMeta();
@@ -43,10 +37,7 @@ export class LayoutRecordManager {
         return record;
     }
     /**
-     * Creates a new instance of RecordGetOperation with the given options.
-     *
-     * @param {Array} options - An array of options for the operation.
-     * @return {RecordGetOperation} - A new instance of RecordGetOperation.
+     * Starts a list or find request for this layout.
      */
     list(options) {
         return new RecordGetOperation(this.layout, options);