@jd-data-limited/easy-fm 5.0.0-beta.1 → 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. */
@@ -13,7 +13,7 @@ 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';
+export { type LayoutInterface, type PortalInterface, type RecordFieldsMap } 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. */
@@ -22,14 +22,18 @@ export { Portal } from './records/portal.js';
 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';
+/** Conversion helpers for FileMaker-formatted Temporal values. */
+export * from './records/fields/valueField.js';
+export * from './records/fields/containerField.js';
+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 Container, Field } from './records/field.js';
-/** Default export. Represents FileMaker host/server. */
-export default FMHost;
+export { type BaseField } from './records/fields/baseField.js';
+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. */
@@ -22,7 +21,10 @@ export { RecordGetOperation } from './records/getOperations/recordGetOperation.j
 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;
+/** Conversion helpers for FileMaker-formatted Temporal values. */
+export * from './records/fields/valueField.js';
+export * from './records/fields/containerField.js';
+export { stringToTemporal, temporalToString } from './utils/temporal.js';
+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,7 +1,10 @@
 import { type Portal } from '../records/portal.js';
-import { type RecordFieldsMap } from './recordFieldsMap.js';
 export interface LayoutInterface {
     fields: RecordFieldsMap;
     portals: PortalInterface;
 }
+/** 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/models/apiResults.d.ts

@@ -21,6 +21,7 @@ export declare const ApiFieldResultTypes: {
     readonly TIMESTAMP: "timeStamp";
     readonly CONTAINER: "container";
 };
+export type FieldResultTypes = z.infer<typeof ApiFieldResultTypes>;
 export declare const ApiMessage: z.ZodObject<{
     code: z.ZodCoercedNumber<unknown>;
     message: z.ZodString;
@@ -166,7 +167,7 @@ export declare const ApiScriptResult: z.ZodObject<{
     scriptError: z.ZodString;
     scriptResult: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export declare const ApiFieldData: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+export declare const ApiFieldData: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodNull]>>;
 export declare const ApiResultSetObj: z.ZodObject<{
     database: z.ZodString;
     layout: z.ZodString;
@@ -175,10 +176,10 @@ export declare const ApiResultSetObj: z.ZodObject<{
     foundCount: z.ZodNumber;
     returnedCount: z.ZodNumber;
 }, z.core.$strip>;
-export declare const ApiPortalData: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>>;
+export declare const ApiPortalData: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodNull]>>>>;
 export declare const ApiRowDataDef: z.ZodObject<{
-    fieldData: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
-    portalData: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>>;
+    fieldData: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodNull]>>;
+    portalData: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodNull]>>>>;
     modId: z.ZodString;
     recordId: z.ZodString;
     portalDataInfo: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -190,8 +191,8 @@ export declare const ApiRowDataDef: z.ZodObject<{
 }, z.core.$strip>;
 export declare const ApiRecordResponseObj: z.ZodObject<{
     data: z.ZodArray<z.ZodObject<{
-        fieldData: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
-        portalData: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>>;
+        fieldData: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodNull]>>;
+        portalData: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodNull]>>>>;
         modId: z.ZodString;
         recordId: z.ZodString;
         portalDataInfo: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/dist/models/apiResults.js

@@ -70,7 +70,7 @@ export const ApiScriptResult = z.object({
     scriptError: z.string(),
     scriptResult: z.string().optional()
 });
-export const ApiFieldData = z.record(z.string(), z.union([z.string(), z.number()]));
+export const ApiFieldData = z.record(z.string(), z.union([z.string(), z.number(), z.null()]));
 export const ApiResultSetObj = z.object({
     database: z.string(),
     layout: z.string(),

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

@@ -0,0 +1,60 @@
+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.
+ */
+export type RawValueData = string | number | null;
+export interface Parentable {
+    layout: LayoutBase;
+    type: RecordTypes;
+    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.
+ * API_FIELD_RESULT defines the value of field.metadata.result for the abstracted field type
+ *
+ * @template T - The type of the field value.
+ */
+export declare abstract class BaseField<T extends unknown, API_FIELD_RESULT extends FieldResultTypes> {
+    parent: Parentable;
+    id: string;
+    protected _value: T;
+    /**
+     * @internal
+     * Use `layout.records.create()` instead to create a new LayoutRecord, as this may be safer.
+     * @param record
+     * @param id
+     * @param value
+     * @protected
+     */
+    protected constructor(record: Parentable, id: string, value: RawValueData);
+    /**
+     * Takes in data in the format that FileMaker gives us and converts it to a more JavaScript-friendly format.
+     * This method is intended to be overriden.
+     * @param value
+     */
+    parseRawValue(value: RawValueData): T;
+    /**
+     * Converts data back into a format that can be sent to FileMaker. Intended to be overriden if conversion is non-standard.
+     */
+    serializeRawValue(): RawValueData;
+    updateFromRawValue(value: RawValueData): void;
+    /** Returns the FileMaker metadata for this field. */
+    get metadata(): z.infer<typeof ApiFieldMetadata> & {
+        result: API_FIELD_RESULT;
+    };
+    /** Gets or sets the current field value. */
+    get value(): T;
+    isCalculationField(): boolean;
+    isSummaryField(): boolean;
+}

package/dist/records/fields/baseField.js

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2023-2024. See LICENSE file for more information
+ */
+/**
+ * A class representing a field in a record.
+ * API_FIELD_RESULT defines the value of field.metadata.result for the abstracted field type
+ *
+ * @template T - The type of the field value.
+ */
+export class BaseField {
+    parent;
+    id;
+    _value;
+    /**
+     * @internal
+     * Use `layout.records.create()` instead to create a new LayoutRecord, as this may be safer.
+     * @param record
+     * @param id
+     * @param value
+     * @protected
+     */
+    constructor(record, id, value) {
+        this.parent = record;
+        this.id = id;
+        this._value = this.parseRawValue(value);
+    }
+    /**
+     * Takes in data in the format that FileMaker gives us and converts it to a more JavaScript-friendly format.
+     * This method is intended to be overriden.
+     * @param value
+     */
+    parseRawValue(value) {
+        return value;
+    }
+    /**
+     * Converts data back into a format that can be sent to FileMaker. Intended to be overriden if conversion is non-standard.
+     */
+    serializeRawValue() {
+        return this._value;
+    }
+    updateFromRawValue(value) {
+        this._value = this.parseRawValue(value);
+    }
+    /** Returns the FileMaker metadata for this field. */
+    get metadata() {
+        return this.parent.getFieldMetadata(this.id);
+    }
+    /** Gets or sets the current field value. */
+    get value() {
+        // if (this.metadata.result === "container") throw "Use await field.stream() to get the contents of a container field, instead of field.value"
+        return this._value;
+    }
+    isCalculationField() {
+        return this.metadata.type === 'calculation';
+    }
+    isSummaryField() {
+        return this.metadata.type === 'summary';
+    }
+}

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

@@ -0,0 +1,18 @@
+import { Readable } from 'node:stream';
+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;
+    constructor(record: Parentable, id: string, value: RawValueData);
+    upload(file: File): Promise<void>;
+    /** @deprecated Use webStream instead. */
+    stream(options?: ContainerDownloadOptions): Promise<{
+        data: Readable;
+        mime: string;
+    }>;
+    webStream(options?: ContainerDownloadOptions): Promise<Response>;
+    arrayBuffer(options?: ContainerDownloadOptions): Promise<{
+        data: ArrayBuffer;
+        mime: string;
+    }>;
+}

package/dist/records/fields/containerField.js

@@ -0,0 +1,44 @@
+import { Readable } from 'node:stream';
+import { BaseField } from './baseField.js';
+import { ContainerSessionAffinityError } from '../../connection/databaseProvider.js';
+export class ContainerField extends BaseField {
+    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)`);
+        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 #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;
+        }
+        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 });
+        }
+    }
+    /** @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') ?? '' };
+    }
+    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/field.d.ts

@@ -0,0 +1,3 @@
+import { ValueField } from "./valueField.js";
+import { ContainerField } from "./containerField.js";
+export type Field = ValueField | ContainerField;

package/dist/records/fields/field.js

@@ -0,0 +1 @@
+export {};