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

package/dist/connection/databaseSessionPool.js

@@ -1,40 +1,37 @@
-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 {
+import { generateAuthorizationHeaders } from './generateAuthorizationHeaders.js';
+import { HttpError, session } from './Session.js';
+import { DataApiDatabaseSession } from './dataApiDatabaseSession.js';
+/** Reserves independent FileMaker Data API sessions from a bounded pool. */
+export class DatabaseSessionPool {
+    host;
     #connectionDetails;
     #activeSessions = new Set();
-    #withSessionQueue = [];
+    #waiters = [];
+    #abortController = new AbortController();
+    #openingSessions = 0;
+    #closed = false;
     constructor(host, connectionDetails) {
-        super(host, connectionDetails);
+        this.host = host;
         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 formatting() {
+        return this.host;
+    }
+    get endpoint() {
+        return `${this.host.protocol}//${this.host.hostname}/fmi/data/v2/databases/${this.#connectionDetails.database}`;
     }
     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');
+        if (this.#closed)
+            throw new Error('Database provider is closed');
         await this.host.getMetadata();
         const url = new URL(`${this.endpoint}/sessions`);
-        url.hostname = this.host.hostname;
-        const cookiejar = new CookieJar();
+        const cookieJar = new CookieJar();
         const res = await fetch(url, {
             method: 'POST',
             headers: generateAuthorizationHeaders(this.#connectionDetails.credentials),
@@ -44,105 +41,112 @@ export class DatabaseSessionPool extends Database {
                     username: data.credentials.username,
                     password: data.credentials.password
                 }))
-            })
+            }),
+            signal: this.#abortController.signal
         });
         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);
-        }
+            cookieJar.addCookie(url, cookie);
+        const data = ApiResults.parse(await res.json());
+        if (res.status !== 200)
+            throw new FMError(data.messages[0].code, res.status, data);
+        return session({
+            token: res.headers.get('x-fm-data-access-token') ?? '',
+            endpoint: this.endpoint,
+            baseCookieJar: cookieJar,
+            abortSignal: this.#abortController.signal
+        });
     }
-    /**
-     *
-     * @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) {
+    async #createReservedSession() {
+        this.#openingSessions++;
         try {
-            session.working = true;
-            const result = await callback(session.session);
-            return result;
+            const active = { working: true, session: await this.#openSession() };
+            this.#activeSessions.add(active);
+            return active;
         }
-        catch (e) {
-            if (e instanceof HttpError && e.status === 401) {
-                // Invalidate this session
-                this.#activeSessions.delete(session);
-                if (retry)
-                    return await this.withSession(callback, false);
+        finally {
+            this.#openingSessions--;
+        }
+    }
+    async #acquire() {
+        if (this.#closed)
+            throw new Error('Database provider is closed');
+        for (const active of this.#activeSessions) {
+            if (!active.working) {
+                active.working = true;
+                return active;
             }
-            throw e;
         }
-        finally {
-            if (this.#activeSessions.has(session)) {
-                session.working = false;
+        if (this.#activeSessions.size + this.#openingSessions < this.#maxSessions) {
+            try {
+                return await this.#createReservedSession();
+            }
+            catch (error) {
+                this.#serveWaitingRequest();
+                throw error;
             }
-            await this.#scheduleQueuedWork();
         }
+        return await new Promise((resolve, reject) => {
+            this.#waiters.push({ resolve, reject });
+        });
     }
-    async #processWithSessionQueue(session) {
-        const job = this.#withSessionQueue.shift();
-        if (!job)
+    #release(active) {
+        if (!this.#activeSessions.has(active))
+            return;
+        const waiter = this.#waiters.shift();
+        if (waiter) {
+            waiter.resolve(active);
             return;
-        await this.#withSessionInternal(session, job.callback, job.retry).then(job.resolve).catch(job.reject);
+        }
+        active.working = false;
     }
-    async #scheduleQueuedWork() {
-        if (this.#withSessionQueue.length === 0)
+    async #discard(active) {
+        if (!this.#activeSessions.delete(active))
+            return;
+        await active.session.logout().catch(() => undefined);
+        this.#serveWaitingRequest();
+    }
+    #serveWaitingRequest() {
+        const waiter = this.#waiters.shift();
+        if (!waiter)
+            return;
+        if (this.#closed) {
+            waiter.reject(new Error('Database provider is closed'));
             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);
-            });
+        void this.#createReservedSession()
+            .then(waiter.resolve)
+            .catch(error => {
+            waiter.reject(error);
+            this.#serveWaitingRequest();
+        });
+    }
+    async withSession(callback) {
+        const active = await this.#acquire();
+        let discard = false;
+        try {
+            return await callback(new DataApiDatabaseSession(this.endpoint, active.session, this.#connectionDetails.debug ?? false));
+        }
+        catch (error) {
+            discard = error instanceof HttpError && error.status === 401;
+            throw error;
+        }
+        finally {
+            if (discard)
+                await this.#discard(active);
+            else
+                this.#release(active);
         }
     }
-    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 });
-        });
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#abortController.abort('Closing database provider');
+        const error = new Error('Database provider is closed');
+        for (const waiter of this.#waiters.splice(0))
+            waiter.reject(error);
+        const sessions = [...this.#activeSessions];
+        this.#activeSessions.clear();
+        await Promise.allSettled(sessions.map(active => active.session.logout()));
     }
 }

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-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';
+export { type DatabaseStructure } from './databaseStructure.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. */
@@ -31,8 +31,9 @@ export { type Field } from './records/fields/field.js';
 export { stringToTemporal, temporalToString, type TemporalValue, type TemporalValueType } from './utils/temporal.js';
 /** Field wrapper used for reading, editing, and container access. */
 export { type BaseField } from './records/fields/baseField.js';
-/** Default export. Represents FileMaker host/server. */
-export default FMHost;
+export { SchemaDriftError, withSchemaValidation, zodValidator, type DatabaseRuntimeSchema, type LayoutRuntimeSchema, type ReadonlyField, type RuntimeValidator, type ValidationIssue, type ValidationResult } from './schema.js';
+export { DataApiProvider, type DataApiProviderOptions } from './connection/DataApiProvider.js';
+export { type DatabaseProvider, type ProviderConnection, type ProviderSession, type ProviderContext, type DatabaseFormatting, type DatabaseOperation, type DatabaseOperationResult, type DatabaseOperationType, type ContainerDownloadOptions, ProviderSessionExpiredError, ContainerSessionAffinityError } from './connection/databaseProvider.js';
 export { 
 /** Namespace re-export of library public types. */
 type TYPES };

package/dist/index.js

@@ -1,7 +1,6 @@
 /*
  * 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. */
@@ -26,5 +25,6 @@ export { asDate, asTime, asTimestamp, query, queryEscape } from './utils/query.j
 export * from './records/fields/valueField.js';
 export * from './records/fields/containerField.js';
 export { stringToTemporal, temporalToString } from './utils/temporal.js';
-/** Default export. Represents FileMaker host/server. */
-export default FMHost;
+export { SchemaDriftError, withSchemaValidation, zodValidator } from './schema.js';
+export { DataApiProvider } from './connection/DataApiProvider.js';
+export { ProviderSessionExpiredError, ContainerSessionAffinityError } from './connection/databaseProvider.js';

package/dist/layouts/layout.d.ts

@@ -11,8 +11,6 @@ export declare class Layout<T extends LayoutInterface> implements LayoutBase {
     readonly records: LayoutRecordManager<T>;
     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.
      * @param {Script} script - The script to be executed.

package/dist/layouts/layout.js

@@ -3,7 +3,7 @@
  */
 import { LayoutRecordManager } from './layoutRecordManager.js';
 import { FMError } from '../FMError.js';
-import { ApiLayoutMetadata, ApiScriptResult } from '../models/apiResults.js';
+import { ApiLayoutMetadata } from '../models/apiResults.js';
 export class Layout {
     database;
     name;
@@ -13,26 +13,16 @@ 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}`;
-    }
     /**
      * Executes a FileMaker script on this layout asynchronously and returns the result.
      * @param {Script} script - The script to be executed.
      * @returns {Promise<ScriptResult>} - A promise that resolves to the script result or rejects with an error.
      */
     async runScript(script) {
-        let url = `${this.endpoint}/script/${encodeURIComponent(script.name)}`;
-        if (script.parameter)
-            url += '?script.param=' + encodeURIComponent(script.parameter);
-        const res = await this.database.fetchJSON(url, {
-            type: ApiScriptResult,
-            method: 'GET'
-        });
-        const error = parseInt(res.scriptError);
+        const { value: res } = await this.database.execute({ type: 'script.run', layout: this.name, script: script.name, parameter: script.parameter || undefined });
+        const error = res.scriptError ?? 0;
         return {
-            scriptError: error ? new FMError(error, 200, res) : undefined,
+            scriptError: error ? new FMError(error, res.status ?? 200, res) : undefined,
             scriptResult: res.scriptResult
         };
     }
@@ -46,8 +36,8 @@ export class Layout {
         if (this.metadata) {
             return this.metadata;
         }
-        const res = await this.database.fetchJSON(this.endpoint, { type: ApiLayoutMetadata });
-        this.metadata = res;
+        const { value: res } = await this.database.execute({ type: 'layout.metadata', layout: this.name });
+        this.metadata = ApiLayoutMetadata.parse(res);
         return this.metadata;
     }
 }

package/dist/layouts/layoutBase.d.ts

@@ -5,7 +5,6 @@ import { type z } from 'zod';
 export interface LayoutBase {
     readonly name: string;
     metadata: z.infer<typeof ApiLayoutMetadata> | null;
-    endpoint: string;
     runScript: (script: Script) => Promise<ScriptResult>;
     getLayoutMeta: () => Promise<z.infer<typeof ApiLayoutMetadata>>;
     database: DatabaseBase;

package/dist/layouts/layoutInterface.d.ts

@@ -1,8 +1,10 @@
 import { type Portal } from '../records/portal.js';
-import { type Field } from '../records/fields/field.js';
 export interface LayoutInterface {
     fields: RecordFieldsMap;
     portals: PortalInterface;
 }
-export type RecordFieldsMap = Record<string, Field>;
+/** Public field views, including generated read-only views, satisfy this shape. */
+export type RecordFieldsMap = Record<string, {
+    readonly value: unknown;
+}>;
 export type PortalInterface = Record<string | number | symbol, Portal<RecordFieldsMap>>;

package/dist/records/fields/baseField.d.ts

@@ -2,6 +2,7 @@ import { RecordTypes } from '../../types.js';
 import { type ApiFieldMetadata, FieldResultTypes } from '../../models/apiResults.js';
 import { type LayoutBase } from '../../layouts/layoutBase.js';
 import { type z } from 'zod';
+import { type SessionBinding } from '../../connection/databaseProvider.js';
 export type ContainerValue = null;
 /**
  * RawValueData refers to the raw shapes of data we receive from or sent to FileMaker.
@@ -10,11 +11,13 @@ export type RawValueData = string | number | null;
 export interface Parentable {
     layout: LayoutBase;
     type: RecordTypes;
-    endpoint: string;
+    recordId: number;
+    sessionBinding?: SessionBinding;
     portal?: {
         name: string;
     };
     getFieldMetadata(fieldId: string): z.infer<typeof ApiFieldMetadata>;
+    refreshContainer(fieldId: string): Promise<import('./containerField.js').ContainerField>;
 }
 /**
  * A class representing a field in a record.

package/dist/records/fields/containerField.d.ts

@@ -1,35 +1,18 @@
-import { BaseField, Parentable, RawValueData } from "./baseField.js";
 import { Readable } from 'node:stream';
-interface StreamOptions {
-    abortSignal?: AbortSignal;
-}
+import { BaseField, type Parentable, type RawValueData } from './baseField.js';
+import { type ContainerDownloadOptions } from '../../connection/databaseProvider.js';
 export declare class ContainerField extends BaseField<string, 'container'> {
     #private;
-    static firstContainerDownload: Promise<any> | null;
     constructor(record: Parentable, id: string, value: RawValueData);
-    /**
-     * Uploads a file to the container field.
-     *
-     * @param {Buffer} file - The file content as a buffer.
-     *
-     * @throws {Error} - Cannot upload a file to the field if it's not a container field.
-     * @throws {Error} - Upload failed with HTTP error.
-     *
-     * @returns {Promise<void>} - A promise that resolves when the file is successfully uploaded.
-     */
     upload(file: File): Promise<void>;
-    stream(): Promise<{
+    /** @deprecated Use webStream instead. */
+    stream(options?: ContainerDownloadOptions): Promise<{
         data: Readable;
         mime: string;
     }>;
-    /**
-     * Returns the container download as a Web `Response`.
-     */
-    webStream(options: StreamOptions): Promise<Response>;
-    /** Downloads the full container contents into memory. */
-    arrayBuffer(): Promise<{
+    webStream(options?: ContainerDownloadOptions): Promise<Response>;
+    arrayBuffer(options?: ContainerDownloadOptions): Promise<{
         data: ArrayBuffer;
         mime: string;
     }>;
 }
-export {};

package/dist/records/fields/containerField.js

@@ -1,78 +1,44 @@
-import { BaseField } from "./baseField.js";
-import { FMError } from '../../FMError.js';
 import { Readable } from 'node:stream';
-import { HttpError } from '../../connection/Session.js';
-import { ApiResults } from "../../models/apiResults.js";
+import { BaseField } from './baseField.js';
+import { ContainerSessionAffinityError } from '../../connection/databaseProvider.js';
 export class ContainerField extends BaseField {
-    static firstContainerDownload = null;
-    constructor(record, id, value) {
-        super(record, id, value);
-    }
-    /**
-     * Uploads a file to the container field.
-     *
-     * @param {Buffer} file - The file content as a buffer.
-     *
-     * @throws {Error} - Cannot upload a file to the field if it's not a container field.
-     * @throws {Error} - Upload failed with HTTP error.
-     *
-     * @returns {Promise<void>} - A promise that resolves when the file is successfully uploaded.
-     */
+    constructor(record, id, value) { super(record, id, value); }
     async upload(file) {
-        if (this.metadata.result !== 'container') {
-            throw new Error('Cannot upload a file to the field; ' + this.id + ' (not a container field)');
-        }
-        const form = new FormData();
-        form.append('upload', file);
-        const res = await this.parent.layout.database.fetch(`${this.parent.endpoint}/containers/${this.id}/1`, {
-            method: 'POST',
-            body: form
-        });
-        if (!res.ok) {
-            throw await HttpError.new(res);
-        }
-        const data = ApiResults.parse(await res.json());
-        if (data.messages[0].code === 0)
-            return;
-        else {
-            throw new FMError(data.messages[0].code, res.status, res);
-        }
+        if (this.metadata.result !== 'container')
+            throw new Error(`Cannot upload a file to the field; ${this.id} (not a container field)`);
+        if (this.parent.recordId === -1)
+            throw new Error('Cannot upload to an unsaved record');
+        await this.parent.layout.database.execute({ type: 'container.upload', layout: this.parent.layout.name, recordId: this.parent.recordId, field: this.id, file });
     }
-    async #streamAsync(options = {}) {
-        const req = await this.parent.layout.database.fetch(this.value, {
-            signal: options.abortSignal ?? null
-        });
-        // const req = await this.parent.layout.database._apiRequestRaw(this.string, {useCookieJar: true})
-        if (!req.ok || !req.body) {
-            throw new Error(`HTTP Error: ${req.status} (${req.statusText})`);
+    async #response(options = {}) {
+        if (!this.value)
+            throw new Error(`Container field ${this.id} is empty`);
+        const binding = this.parent.sessionBinding;
+        if (!binding)
+            throw new ContainerSessionAffinityError('Container has no originating provider session');
+        try {
+            const response = await this.parent.layout.database.fetchContainer(this.value, binding, options.signal);
+            if (!response.ok || !response.body)
+                throw new Error(`Container response failed: ${response.status} (${response.statusText})`);
+            return response;
         }
-        return req;
-    }
-    /**
-     * @deprecated use webStream instead.
-     */
-    async stream() {
-        const stream = await this.#streamAsync();
-        if (!stream.body) {
-            throw await HttpError.new(stream);
+        catch (error) {
+            if (!(error instanceof ContainerSessionAffinityError) || !options.refreshOnSessionLoss)
+                throw error;
+            const refreshed = await this.parent.refreshContainer(this.id);
+            this.updateFromRawValue(refreshed.value);
+            this.parent.sessionBinding = refreshed.parent.sessionBinding;
+            return await this.#response({ ...options, refreshOnSessionLoss: false });
         }
-        return {
-            // @ts-expect-error stream types are correct
-            data: Readable.fromWeb(stream.body),
-            mime: stream.headers.get('Content-Type') ?? ''
-        };
     }
-    /**
-     * Returns the container download as a Web `Response`.
-     */
-    async webStream(options) {
-        return await this.#streamAsync(options);
+    /** @deprecated Use webStream instead. */
+    async stream(options = {}) {
+        const response = await this.#response(options);
+        return { data: Readable.fromWeb(response.body), mime: response.headers.get('Content-Type') ?? '' };
     }
-    /** Downloads the full container contents into memory. */
-    async arrayBuffer() {
-        const stream = await this.#streamAsync();
-        if (!stream.ok)
-            throw await HttpError.new(stream);
-        return { data: await stream.arrayBuffer(), mime: stream.headers.get('Content-Type') ?? '' };
+    async webStream(options = {}) { return await this.#response(options); }
+    async arrayBuffer(options = {}) {
+        const response = await this.#response(options);
+        return { data: await response.arrayBuffer(), mime: response.headers.get('Content-Type') ?? '' };
     }
 }

package/dist/records/fields/valueField.js

@@ -56,7 +56,7 @@ export class TimeStampField extends ValueFieldBase {
         if (typeof value !== 'string')
             throw new Error("Received an invalid value for a temporal field.");
         try {
-            return stringToTemporal(value, 'timestamp', this.parent.layout.database.host.timeStampFormat);
+            return stringToTemporal(value, 'timestamp', this.parent.layout.database.timeStampFormat);
         }
         catch {
             return Temporal.PlainDateTime.from(value);
@@ -65,7 +65,7 @@ export class TimeStampField extends ValueFieldBase {
     serializeRawValue() {
         if (this._value === null)
             return '';
-        return temporalToString(this._value, this.parent.layout.database.host.timeStampFormat);
+        return temporalToString(this._value, this.parent.layout.database.timeStampFormat);
     }
 }
 export class DateField extends ValueFieldBase {
@@ -75,7 +75,7 @@ export class DateField extends ValueFieldBase {
         if (typeof value !== 'string')
             throw new Error("Received an invalid value for a temporal field.");
         try {
-            return stringToTemporal(value, 'date', this.parent.layout.database.host.dateFormat);
+            return stringToTemporal(value, 'date', this.parent.layout.database.dateFormat);
         }
         catch {
             return Temporal.PlainDate.from(value);
@@ -84,7 +84,7 @@ export class DateField extends ValueFieldBase {
     serializeRawValue() {
         if (this._value === null)
             return '';
-        return temporalToString(this._value, this.parent.layout.database.host.dateFormat);
+        return temporalToString(this._value, this.parent.layout.database.dateFormat);
     }
 }
 export class TimeField extends ValueFieldBase {
@@ -94,7 +94,7 @@ export class TimeField extends ValueFieldBase {
         if (typeof value !== 'string')
             throw new Error("Received an invalid value for a temporal field.");
         try {
-            return stringToTemporal(value, 'time', this.parent.layout.database.host.timeFormat);
+            return stringToTemporal(value, 'time', this.parent.layout.database.timeFormat);
         }
         catch {
             return Temporal.PlainTime.from(value);
@@ -103,6 +103,6 @@ export class TimeField extends ValueFieldBase {
     serializeRawValue() {
         if (this._value === null)
             return '';
-        return temporalToString(this._value, this.parent.layout.database.host.timeFormat);
+        return temporalToString(this._value, this.parent.layout.database.timeFormat);
     }
 }