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

package/dist/connection/database.js

@@ -1,140 +1,204 @@
-/*
- * Copyright (c) 2023-2024. See LICENSE file for more information
- */
-import { FMError } from '../FMError.js';
 import { Layout } from '../layouts/layout.js';
-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.
- */
+import { ContainerSessionAffinityError, ProviderSessionExpiredError } from './databaseProvider.js';
 export class Database {
-    host;
     name;
     debug;
+    #provider;
     #layoutCache = new Map();
-    canOpenNewConnections = true;
-    /**
-     * Used during events where the application must logout
-     * @private
-     */
-    abortController = new AbortController();
-    constructor(host, conn) {
-        this.host = host;
-        this.name = conn.database;
-        this.debug = conn.debug ?? false;
-        process.on('SIGINT', () => { void this.close(); });
-        process.on('SIGTERM', () => { void this.close(); });
-        process.on('beforeExit', () => { void this.close(); });
+    #abortController = new AbortController();
+    #sessions = [];
+    #closingSessions = new Set();
+    #queue = [];
+    #connectionPromise;
+    #closed = false;
+    #draining = false;
+    constructor(options) {
+        this.#provider = options.provider;
+        this.name = options.name ?? options.provider.name ?? '';
+        this.debug = options.debug ?? false;
+    }
+    static create(options) {
+        return new Database(options);
+    }
+    async #connection() {
+        if (this.#closed)
+            throw new Error('Database is closed');
+        this.#connectionPromise ??= this.#provider.connect({ signal: this.#abortController.signal, debug: this.debug });
+        return await this.#connectionPromise;
+    }
+    async connect() {
+        await this.#connection();
+    }
+    get dateFormat() {
+        return this.#formatting('dateFormat', 'MM/DD/YYYY');
+    }
+    get timeFormat() {
+        return this.#formatting('timeFormat', 'HH:mm:ss');
+    }
+    get timeStampFormat() {
+        return this.#formatting('timeStampFormat', 'MM/DD/YYYY HH:mm:ss');
+    }
+    #formatting(key, fallback) {
+        return this.#provider.formatting[key] ?? fallback;
+    }
+    async #openSession() {
+        const connection = await this.#connection();
+        const session = await connection.openSession(this.#abortController.signal);
+        if (this.#closed) {
+            await session.close();
+            throw new Error('Database is closed');
+        }
+        const active = { binding: { id: Symbol('provider-session') }, session, busy: false, valid: true };
+        this.#sessions.push(active);
+        return active;
+    }
+    async #schedule(run, preferred) {
+        if (this.#closed)
+            throw new Error('Database is closed');
+        return await new Promise((resolve, reject) => {
+            this.#queue.push({ preferred, run, resolve, reject });
+            void this.#drain();
+        });
+    }
+    async #drain() {
+        if (this.#draining || this.#closed || this.#queue.length === 0)
+            return;
+        this.#draining = true;
+        try {
+            const connection = await this.#connection().catch(error => {
+                for (const job of this.#queue.splice(0))
+                    job.reject(error);
+                return undefined;
+            });
+            if (!connection)
+                return;
+            for (let index = 0; index < this.#queue.length;) {
+                const job = this.#queue[index];
+                let active = job.preferred
+                    ? this.#sessions.find(item => item.binding.id === job.preferred?.id && item.valid && !item.busy)
+                    : this.#sessions.find(item => item.valid && !item.busy);
+                if (!active && job.preferred) {
+                    if (!this.#sessions.some(item => item.binding.id === job.preferred?.id && item.valid)) {
+                        this.#queue.splice(index, 1);
+                        job.reject(new ContainerSessionAffinityError());
+                        continue;
+                    }
+                    index++;
+                    continue;
+                }
+                if (!active && !job.preferred && this.#sessions.filter(item => item.valid).length < Math.max(1, connection.maxSessions)) {
+                    try {
+                        active = await this.#openSession();
+                    }
+                    catch (error) {
+                        this.#queue.splice(index, 1);
+                        job.reject(error);
+                        continue;
+                    }
+                }
+                if (!active) {
+                    index++;
+                    continue;
+                }
+                this.#queue.splice(index, 1);
+                active.busy = true;
+                void job.run(active).then(job.resolve, job.reject).finally(() => {
+                    active.busy = false;
+                    void this.#drain();
+                });
+            }
+        }
+        finally {
+            this.#draining = false;
+        }
+    }
+    async execute(operation) {
+        const attempt = async () => await this.#schedule(async (active) => {
+            try {
+                return { value: await active.session.execute(operation), binding: active.binding };
+            }
+            catch (error) {
+                if (error instanceof ProviderSessionExpiredError)
+                    this.#invalidate(active);
+                throw error;
+            }
+        });
+        try {
+            return await attempt();
+        }
+        catch (error) {
+            if (error instanceof ProviderSessionExpiredError && isReadOnly(operation.type))
+                return await attempt();
+            throw error;
+        }
+    }
+    async fetchContainer(reference, binding, signal) {
+        return await this.#schedule(async (active) => {
+            try {
+                return await active.session.fetchContainer(reference, signal);
+            }
+            catch (error) {
+                if (error instanceof ProviderSessionExpiredError) {
+                    this.#invalidate(active);
+                    throw new ContainerSessionAffinityError(undefined, { cause: error });
+                }
+                throw error;
+            }
+        }, binding);
+    }
+    #invalidate(active) {
+        if (!active.valid)
+            return;
+        active.valid = false;
+        const index = this.#sessions.indexOf(active);
+        if (index >= 0)
+            this.#sessions.splice(index, 1);
+        const closing = active.session.close().catch(() => {
+        });
+        this.#closingSessions.add(closing);
+        void closing.finally(() => this.#closingSessions.delete(closing));
     }
     async login() {
-        await Promise.resolve();
+        await this.connect();
     }
     async logout() {
         await this.close();
     }
     async close() {
-        this.canOpenNewConnections = false;
-        if (!this.abortController.signal.aborted)
-            this.abortController.abort('Closing connection');
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#abortController.abort('Closing database');
+        for (const job of this.#queue.splice(0))
+            job.reject(new Error('Database is closed'));
+        const connection = await this.#connectionPromise?.catch(() => undefined);
+        await Promise.allSettled([...this.#closingSessions, ...this.#sessions.map(active => active.session.close())]);
+        this.#sessions.splice(0);
+        if (connection?.close)
+            await connection.close();
     }
     async [Symbol.asyncDispose]() {
         await this.close();
     }
-    /**
-     * Returns the endpoint URL for the database connection.
-     *
-     * @returns {string} The endpoint URL.
-     */
-    get endpoint() {
-        return `${this.host.protocol}//${this.host.hostname}/fmi/data/v2/databases/${this.name}`;
-    }
-    /**
-     * 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 data.response
-                // @ts-expect-error is correct
-                ? {
-                    ...data.response,
-                    httpStatus: res.status
-                }
-                // @ts-expect-error is correct
-                : { httpStatus: res.status };
-        }
-        const data = ApiResults.parse(rawData);
-        if (data.messages[0].code !== 0) {
-            throw new FMError(data.messages[0].code, res.status, data);
-        }
-        // @ts-expect-error is correct
-        return {
-            httpStatus: res.status
-        };
-    }
-    /**
-     * Retrieves a list of layouts in the current FileMaker database.
-     *
-     * @returns {Promise<Layout[]>} A promise that resolves to an array of Layout objects.
-     * @throws {FMError} If there was an error retrieving the layouts.
-     */
     async listLayouts(page = 0) {
-        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) {
-                if (layout.folderLayoutNames)
-                    names = names.concat(cycleLayoutNames(layout.folderLayoutNames));
-                else
-                    names.push(layout.name);
-            }
-            return names;
-        };
-        return cycleLayoutNames(res.layouts).map(layout => new Layout(this, layout));
+        const { value } = await this.execute({ type: 'layout.list', page });
+        return value.map(name => new Layout(this, name));
     }
-    /**
-     * Returns a FileMaker Layout object by name.
-     */
     layout(name) {
         let layout = this.#layoutCache.get(name);
-        if (layout)
-            return layout;
-        layout = new Layout(this, name);
-        this.#layoutCache.set(name, layout);
+        if (!layout) {
+            layout = new Layout(this, name);
+            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 };
     }
 }
+function isReadOnly(type) {
+    return type === 'layout.list' || type === 'layout.metadata' || type === 'record.list' || type === 'record.get';
+}

package/dist/connection/databaseBase.d.ts

@@ -1,28 +1,15 @@
-import { type HostBase } from './HostBase.js';
-import { type z, type ZodType } from 'zod';
+import type { DatabaseOperation, DatabaseOperationResult, DatabaseOperationType, SessionBinding } from './databaseProvider.js';
 export interface DatabaseBase {
-    host: HostBase;
     readonly name: string;
-    endpoint: string;
-    /**
-     * @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.
-     */
+    readonly timeFormat: string;
+    readonly dateFormat: string;
+    readonly timeStampFormat: string;
+    connect: () => Promise<void>;
     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;
+    execute: <K extends DatabaseOperationType>(operation: DatabaseOperation<K>) => Promise<{
+        value: DatabaseOperationResult<K>;
+        binding: SessionBinding;
     }>;
+    fetchContainer: (reference: string, binding: SessionBinding, signal?: AbortSignal) => Promise<Response>;
 }

package/dist/connection/databaseBase.js

@@ -1,4 +1 @@
-/*
- * Copyright (c) 2023-2024. See LICENSE file for more information
- */
 export {};

package/dist/connection/databaseProvider.d.ts

@@ -0,0 +1,196 @@
+import type { z } from 'zod';
+import type { ApiFieldData, ApiLayoutMetadata, ApiPortalData } from '../models/apiResults.js';
+export interface DatabaseFormatting {
+    readonly dateFormat: string;
+    readonly timeFormat: string;
+    readonly timeStampFormat: string;
+}
+export interface ProviderContext {
+    readonly signal: AbortSignal;
+    readonly debug: boolean;
+}
+export interface DatabaseProvider {
+    readonly name?: string;
+    /** Synchronous formatting defaults, refined in place when connect resolves. */
+    readonly formatting: DatabaseFormatting;
+    connect: (context: ProviderContext) => Promise<ProviderConnection>;
+}
+export interface ProviderConnection {
+    readonly formatting: DatabaseFormatting;
+    readonly maxSessions: number;
+    openSession: (signal: AbortSignal) => Promise<ProviderSession>;
+    close?: () => Promise<void>;
+}
+export interface ProviderSession {
+    execute: <K extends DatabaseOperationType>(operation: DatabaseOperation<K>) => Promise<DatabaseOperationResult<K>>;
+    /** Use this exact session. Non-HTTP transports may synthesize a Web Response. */
+    fetchContainer: (reference: string, signal?: AbortSignal) => Promise<Response>;
+    close: () => Promise<void>;
+}
+export interface ProviderRecord {
+    recordId: string;
+    modId: string;
+    fieldData: z.infer<typeof ApiFieldData>;
+    portalData?: z.infer<typeof ApiPortalData>;
+}
+export interface RecordQueryClause {
+    omit: boolean;
+    fields: Record<string, string>;
+}
+export interface RecordOperationOptions {
+    scripts: {
+        prerequest?: {
+            name: string;
+            parameter: string;
+        };
+        presort?: {
+            name: string;
+            parameter: string;
+        };
+        after?: {
+            name: string;
+            parameter: string;
+        };
+    };
+    portals: Record<string, {
+        limit: number;
+        offset: number;
+    }>;
+}
+export interface RecordQueryOptions extends RecordOperationOptions {
+    limit: number;
+    offset: number;
+    sort: Array<{
+        fieldName: string;
+        sortOrder: 'ascend' | 'descend';
+    }>;
+}
+export interface RecordWriteBody {
+    fieldData: Record<string, unknown>;
+    portalData?: Record<string, unknown>;
+    options?: Record<string, unknown>;
+    deleteRelatedRecords?: Array<{
+        table: string;
+        recordId: number;
+    }>;
+}
+export interface DatabaseOperationMap {
+    'layout.list': {
+        operation: {
+            page: number;
+        };
+        result: string[];
+    };
+    'layout.metadata': {
+        operation: {
+            layout: string;
+        };
+        result: z.infer<typeof ApiLayoutMetadata>;
+    };
+    'script.run': {
+        operation: {
+            layout: string;
+            script: string;
+            parameter?: string;
+        };
+        result: {
+            scriptError?: number;
+            scriptResult?: string;
+            status?: number;
+        };
+    };
+    'record.list': {
+        operation: {
+            layout: string;
+            query: RecordQueryClause[];
+            options: RecordQueryOptions;
+        };
+        result: ProviderRecord[];
+    };
+    'record.get': {
+        operation: {
+            layout: string;
+            recordId: number;
+            options: RecordOperationOptions;
+        };
+        result: ProviderRecord;
+    };
+    'record.create': {
+        operation: {
+            layout: string;
+            body: RecordWriteBody;
+            options: RecordOperationOptions;
+        };
+        result: {
+            recordId: string;
+            modId: string;
+            scriptError?: number;
+            status?: number;
+        };
+    };
+    'record.update': {
+        operation: {
+            layout: string;
+            recordId: number;
+            body: RecordWriteBody;
+            options: RecordOperationOptions;
+        };
+        result: {
+            modId: string;
+            scriptError?: number;
+            status?: number;
+        };
+    };
+    'record.duplicate': {
+        operation: {
+            layout: string;
+            recordId: number;
+            options: RecordOperationOptions;
+        };
+        result: {
+            recordId: string;
+            modId: string;
+            scriptError?: number;
+            status?: number;
+        };
+    };
+    'record.delete': {
+        operation: {
+            layout: string;
+            recordId: number;
+            options: RecordOperationOptions;
+        };
+        result: {
+            scriptError?: number;
+            status?: number;
+        };
+    };
+    'container.upload': {
+        operation: {
+            layout: string;
+            recordId: number;
+            field: string;
+            file: File;
+        };
+        result: undefined;
+    };
+}
+export type DatabaseOperationType = keyof DatabaseOperationMap;
+export type DatabaseOperation<K extends DatabaseOperationType = DatabaseOperationType> = K extends DatabaseOperationType ? {
+    type: K;
+} & DatabaseOperationMap[K]['operation'] : never;
+export type DatabaseOperationResult<K extends DatabaseOperationType> = DatabaseOperationMap[K]['result'];
+export declare class ProviderSessionExpiredError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class ContainerSessionAffinityError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export interface ContainerDownloadOptions {
+    signal?: AbortSignal;
+    refreshOnSessionLoss?: boolean;
+}
+/** @internal */
+export interface SessionBinding {
+    readonly id: symbol;
+}

package/dist/connection/databaseProvider.js

@@ -0,0 +1,6 @@
+export class ProviderSessionExpiredError extends Error {
+    constructor(message = 'Provider session expired', options) { super(message, options); this.name = 'ProviderSessionExpiredError'; }
+}
+export class ContainerSessionAffinityError extends Error {
+    constructor(message = 'The session associated with this container is no longer available', options) { super(message, options); this.name = 'ContainerSessionAffinityError'; }
+}

package/dist/connection/databaseSessionPool.d.ts

@@ -1,14 +1,15 @@
-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> {
+import { type DatabaseEndpoint } from './Session.js';
+import { type DatabaseProvider, type DatabaseExecutor } from './databaseProvider.js';
+/** Reserves independent FileMaker Data API sessions from a bounded pool. */
+export declare class DatabaseSessionPool<T extends DatabaseStructure = DatabaseStructure> implements DatabaseProvider {
     #private;
+    readonly host: FMHost;
     constructor(host: FMHost, connectionDetails: databaseOptionsWithExternalSources<loginOptionsFileMaker>);
+    get formatting(): FMHost;
+    get endpoint(): DatabaseEndpoint;
+    withSession<R>(callback: (executor: DatabaseExecutor) => Promise<R>): Promise<R>;
     close(): Promise<void>;
-    withSession<T>(callback: (session: Session) => Promise<T>, retry?: boolean): Promise<T>;
 }