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

package/dist/connection/FMHost.d.ts

@@ -1,22 +1,24 @@
-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;
-    constructor(_hostname: string, timezoneOffset?: (moment: Moment) => number, verify?: boolean);
-    get metadata(): FMHostMetadata;
+    readonly protocol: DatabaseProtocol;
+    _metadata: z.infer<typeof FMHostMetadata> | null;
+    constructor(_hostname: string, verify?: boolean);
+    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 +27,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 +38,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,24 +3,25 @@
  */
 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;
-    timezoneOffsetFunc;
     verify;
     protocol;
     _metadata = null;
-    constructor(_hostname, timezoneOffset = (moment) => 0 - (new Date()).getTimezoneOffset(), verify = true) {
+    constructor(_hostname, verify = true) {
         if (!(/^https?:\/\//).test(_hostname))
             throw new Error('hostname MUST begin with either http:// or https://');
         const url = new URL(_hostname);
         this.protocol = url.protocol;
         this.hostname = url.hostname;
-        this.timezoneOffsetFunc = timezoneOffset;
         this.verify = verify;
     }
     get metadata() {
@@ -35,12 +36,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 +68,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 +91,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,11 @@
 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 timezoneOffsetFunc: (moment: Moment) => number;
+    readonly protocol: DatabaseProtocol;
     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;
 }