@jd-data-limited/easy-fm 4.0.16 → 4.1.0

package/src/records/field.ts

@@ -2,39 +2,53 @@
  * Copyright (c) 2023-2024. See LICENSE file for more information
  */
 
-import * as http from "http";
-import {ContainerBufferResult, DownloadModes, FieldMetaData, RecordTypes} from "../types.js";
-import {ApiFieldDisplayTypes, ApiFieldMetadata, ApiFieldResultTypes, ApiFieldTypes} from "../models/apiResults.js";
-import {LayoutBase} from "../layouts/layoutBase.js";
-import {Moment} from "moment";
+import type * as http from 'http'
+import {type ContainerBufferResult, DownloadModes, RecordTypes} from '../types.js'
+import {ApiFieldDisplayTypes, type ApiFieldMetadata, ApiFieldResultTypes, ApiFieldTypes} from '../models/apiResults.js'
+import {type LayoutBase} from '../layouts/layoutBase.js'
+import {type Moment} from 'moment'
 
 export type FieldValue = string | number | Moment | Container
 export type Container = null
 
-export type Parentable = {layout: LayoutBase, type: RecordTypes, endpoint: string}
+export interface Parentable {
+    layout: LayoutBase
+    type: RecordTypes
+    endpoint: string
+    portal?: { name: string }
+}
+
+/**
+ * A class representing a field in a record.
+ *
+ * @template T - The type of the field value.
+ */
 export class Field<T extends FieldValue> {
-    parent: Parentable;
-    id: string;
-    protected _value: T;
-    edited: boolean;
+    parent: Parentable
+    id: string
+    protected _value: T | null
+    edited: boolean
 
-    constructor(record: Parentable, id: string, contents: T) {
+    constructor (record: Parentable, id: string, contents: T) {
         this.parent = record
         this.id = id
         this._value = contents
         this.edited = false
     }
 
-    set(content: T) {
-        if (this.metadata.result === "container") throw "Cannot set container value using set(). Use upload() instead."
-        // @ts-ignore
-        if (!content) this._value = ""
-        // @ts-ignore
+    /**
+     * Sets the value of the field.
+     *
+     * @param {T | null} content - The new content value to be set. Can be either the type T or null.
+     * @throws {Error} Cannot set container value using set(). Use upload() instead, if the result is a 'container'.
+     */
+    set (content: T | null) {
+        if (this.metadata.result === 'container') throw new Error('Cannot set container value using set(). Use upload() instead.')
         else this._value = content
         this.edited = true
     }
 
-    get metadata(): ApiFieldMetadata {
+    get metadata (): ApiFieldMetadata {
         if (!this.parent.layout.metadata) {
             // Default to a regular text field
             return {
@@ -51,30 +65,29 @@ export class Field<T extends FieldValue> {
                 numeric: false,
                 timeOfDay: false,
                 repetitions: 1,
-                valueList: ""
+                valueList: ''
             }
         }
-        if (this.parent.type === RecordTypes.PORTAL) {
-            // @ts-ignore
-            return this.parent.layout.metadata.portalMetaData[this.parent.portal.name || "portal not attached"].find(i => i.name === this.id) as FieldMetaData || {
-                name: this.id.toString(),
-                type: 'normal',
-                displayType: 'editText',
-                result: 'text',
-                global: false,
-                autoEnter: true,
-                fourDigitYear: false,
-                maxRepeat: 1,
-                maxCharacters: 0,
-                notEmpty: false,
-                numeric: false,
-                timeOfDay: false,
-                repetitionStart: 1,
-                repetitionEnd: 1
-            } as FieldMetaData
-        }
-        else {
-            return this.parent.layout.metadata.fieldMetaData.find(i => i.name === this.id) || {
+        if (this.parent.type === RecordTypes.PORTAL && this.parent.portal) {
+            return this.parent.layout.metadata.portalMetaData[this.parent.portal.name || 'portal not attached'].find(i => i.name === this.id) ??
+                {
+                    name: this.id.toString(),
+                    type: ApiFieldTypes.NORMAL,
+                    displayType: ApiFieldDisplayTypes.EDIT_TEXT,
+                    result: ApiFieldResultTypes.TEXT,
+                    global: false,
+                    autoEnter: true,
+                    fourDigitYear: false,
+                    maxRepeat: 1,
+                    maxCharacters: 0,
+                    notEmpty: false,
+                    numeric: false,
+                    timeOfDay: false,
+                    repetitions: 1,
+                    valueList: ''
+                }
+        } else {
+            return this.parent.layout.metadata.fieldMetaData.find(i => i.name === this.id) ?? {
                 name: this.id.toString(),
                 type: ApiFieldTypes.NORMAL,
                 displayType: ApiFieldDisplayTypes.EDIT_TEXT,
@@ -88,80 +101,88 @@ export class Field<T extends FieldValue> {
                 numeric: false,
                 timeOfDay: false,
                 repetitions: 1,
-                valueList: ""
+                valueList: ''
             }
         }
     }
 
-    get value(): T {
+    get value (): T | null {
         // 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
     }
 
-    set value(value: T) {
+    set value (value: T) {
         this._value = value
     }
 
-    get string(): string {
-        if (typeof this._value === "string") {
-            return this._value
-        }
-        throw "Field value is not a string"
-    }
-
-    get date(): Date {
-        if (this._value instanceof Date) {
+    get string (): string {
+        if (typeof this._value === 'string') {
             return this._value
         }
-        throw "Field value is not a date"
+        throw new Error('Field value is not a string')
     }
 
-    get number(): number {
-        if (typeof this._value === "number") {
-            return this._value
+    /**
+     * Uploads a file to the container field.
+     *
+     * @param {Buffer} buffer - The file content as a buffer.
+     * @param {string} filename - The filename of the file.
+     * @param {string} mime - The MIME type of the file.
+     *
+     * @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.
+     */
+    async upload (buffer: Buffer, filename: string, mime: string): Promise<void> {
+        if (this.metadata.result !== 'container') {
+            throw new Error('Cannot upload a file to the field; ' + this.id + ' (not a container field)')
         }
-        throw "Field value is not a number"
-    }
-
-    async upload(buffer: Buffer, filename: string, mime: string): Promise<void> {
-        let trace = new Error()
-        if (this.metadata.result !== "container") throw "Cannot upload a file to the field; " + this.id + " (not a container field)"
-        let form = new FormData()
-        form.append("upload", new File([buffer], filename, {type: mime}))
-
-        let res = await this.parent.layout.database.apiRequestRaw(`${this.parent.endpoint}/containers/${this.id}/1`, {
-            method: "POST",
-            // @ts-ignore
+        const form = new FormData()
+        form.append('upload', new File([buffer], filename, {type: mime}))
+
+        const res = await this.parent.layout.database._apiRequestRaw(`${this.parent.endpoint}/containers/${this.id}/1`, {
+            method: 'POST',
+            headers: {
+                Authorization: 'Bearer ' + this.parent.layout.database.token,
+                'Content-Type': 'multipart/form-data'
+            },
             body: form
         })
         if (!res.ok) throw new Error(`Upload failed with HTTP error: ${res.status} (${res.statusText})`)
     }
 
-    download(mode: DownloadModes.Stream): Promise<http.IncomingMessage>
-    download(mode: DownloadModes.Buffer): Promise<ContainerBufferResult>
-    async download(mode: DownloadModes = DownloadModes.Stream): Promise<http.IncomingMessage | ContainerBufferResult> {
-        if (this.metadata.result !== ApiFieldResultTypes.CONTAINER) throw new Error("Cannot perform download() on a non-container field")
-
-        let stream = await this.parent.layout.database.streamURL(this.string)
+    /**
+     * Downloads a resource from the server using the specified download mode.
+     *
+     * @param {DownloadModes} mode - The mode to use for downloading the resource.
+     * @return {Promise<http.IncomingMessage>} - A promise that resolves with the incoming message representing the downloaded resource.
+     */
+    download (mode: DownloadModes.Stream): Promise<http.IncomingMessage>
+    download (mode: DownloadModes.Buffer): Promise<ContainerBufferResult>
+    async download (mode: DownloadModes = DownloadModes.Stream): Promise<http.IncomingMessage | ContainerBufferResult> {
+        if (this.metadata.result !== ApiFieldResultTypes.CONTAINER) throw new Error('Cannot perform download() on a non-container field')
+
+        const stream = await this.parent.layout.database.streamURL(this.string)
         if (mode === DownloadModes.Stream) {
             return stream
         }
 
-        let body: Uint8Array[] = []
-        return new Promise((resolve, reject) => {
-            stream.on("data", chunk => {
+        const body: Uint8Array[] = []
+        return await new Promise((resolve, reject) => {
+            stream.on('data', (chunk: Uint8Array) => {
                 body.push(chunk)
             })
-            stream.on("error", (e) => {
+            stream.on('error', (e) => {
                 reject(e)
             })
-            stream.on("end", () => {
+            stream.on('end', () => {
                 resolve({
                     buffer: Buffer.concat(body),
-                    mime: stream.headers["content-type"],
+                    mime: stream.headers['content-type'],
                     request: stream
-                } as ContainerBufferResult)
+                } satisfies ContainerBufferResult)
             })
         })
     }
-}
+}

package/src/records/getOperations/recordGetOperation.d.ts

@@ -1,54 +1,74 @@
-import { LayoutInterface } from "../../layouts/layoutInterface.js";
-import { PickPortals, ScriptRequestData } from "../../types.js";
-import { LayoutBase } from "../../layouts/layoutBase.js";
-import { LayoutRecord } from "../layoutRecord.js";
-import { Query } from "../../utils/query.js";
-export type SortOrder = "ascend" | "descend";
-export type FindRequestRaw = {
-    [key: string]: string;
-};
-export type FindRequest = {
-    [key: string]: Query;
-};
-export type PortalRequest = {
+import { type LayoutInterface } from '../../layouts/layoutInterface.js';
+import { type PickPortals, type ScriptRequestData } from '../../types.js';
+import { type LayoutBase } from '../../layouts/layoutBase.js';
+import { LayoutRecord } from '../layoutRecord.js';
+import { type Query } from '../../utils/query.js';
+export type SortOrder = 'ascend' | 'descend';
+export type FindRequestRaw = Record<string, string>;
+export type FindRequest = Record<string, Query>;
+export interface PortalRequest {
     name: string;
-};
+}
 type PortalData<T extends LayoutInterface> = {
-    [key in keyof T["portals"]]: {
+    [key in keyof T['portals']]: {
         limit: number;
         offset: number;
     };
 };
-export type GetOperationOptions<T extends LayoutInterface> = {
+export interface GetOperationOptions<T extends LayoutInterface> {
     portals: Partial<PortalData<T>>;
     limit?: number;
     offset?: number;
-};
+}
 export declare class RecordGetOperation<T extends LayoutInterface, OPTIONS extends GetOperationOptions<T>> {
     protected layout: LayoutBase;
     protected limit: number;
     protected scriptData: ScriptRequestData;
-    protected sortData: {
+    protected sortData: Array<{
         fieldName: string;
         sortOrder: SortOrder;
-    }[];
+    }>;
     protected portals: Partial<PortalData<T>>;
     protected offset: number;
-    protected queries: {
+    protected queries: Array<{
         req: FindRequestRaw;
         omit: boolean;
-    }[];
+    }>;
     constructor(layout: LayoutBase, options: OPTIONS);
     get isFindRequest(): boolean;
     private formatQueries;
-    protected generateParamsBody(offset: number, limit: number): {
-        [key: string]: any;
-    };
+    protected generateParamsBody(offset: number, limit: number): Record<string, any>;
     protected generateParamsURL(offset: number, limit: number): URLSearchParams;
+    /**
+     * Configures any FileMaker scripts to be run as a part of the request
+     *
+     * @param {ScriptRequestData} scripts - The script request data to set.
+     * @return {this} - The current instance of the class.
+     */
     scripts(scripts: ScriptRequestData): this;
+    /**
+     * Sorts the data based on the given field name and sort order.
+     *
+     * @param {string} fieldName - The name of the field by which the data should be sorted.
+     * @param {SortOrder} sortOrder - The sort order to be applied (either "asc" for ascending or "desc" for descending).
+     *
+     * @return {this} - Returns the current instance of the object.
+     */
     sort(fieldName: string, sortOrder: SortOrder): this;
     private parseFindRequest;
+    /**
+     * Adds a new request/query to the list of queries.
+     *
+     * @param {FindRequest} query - The find request to be added.
+     * @param {boolean} [omit=false] - Flag to indicate if the find request should be omitted.
+     * @return {Object} - The current object instance.
+     */
     addRequest(query: FindRequest, omit?: boolean): this;
+    /**
+     * Perform a fetch operation.
+     *
+     * @returns {Promise} A promise that resolves with the result of the fetch operation.
+     */
     fetch(): Promise<LayoutRecord<PickPortals<T, keyof OPTIONS["portals"]>>[]>;
     private performFind;
     [Symbol.asyncIterator](): {

package/src/records/getOperations/recordGetOperation.js

@@ -1,9 +1,9 @@
 /*
  * Copyright (c) 2023-2024. See LICENSE file for more information
  */
-import { LayoutRecord } from "../layoutRecord.js";
-import { FMError } from "../../FMError.js";
-import { FindRequestSymbol } from "../../utils/query.js";
+import { LayoutRecord } from '../layoutRecord.js';
+import { FMError } from '../../FMError.js';
+import { FindRequestSymbol } from '../../utils/query.js';
 export class RecordGetOperation {
     layout;
     limit = 100;
@@ -16,16 +16,16 @@ export class RecordGetOperation {
         this.layout = layout;
         this.sortData = [];
         this.portals = options.portals;
-        this.offset = options.offset || 1; // Offset refers to the starting record. offset 1 is the same as no offset.
-        this.limit = options.limit || 100;
+        this.offset = options.offset ?? 1; // Offset refers to the starting record. offset 1 is the same as no offset.
+        this.limit = options.limit ?? 100;
     }
     get isFindRequest() {
         return this.queries.length !== 0;
     }
     formatQueries() {
-        let test = this.queries.map(query => {
-            let out = {};
-            for (let key of Object.keys(query.req)) {
+        const test = this.queries.map(query => {
+            const out = {};
+            for (const key of Object.keys(query.req)) {
                 if (query.req[key])
                     out[key] = query.req[key];
                 else {
@@ -33,7 +33,7 @@ export class RecordGetOperation {
                 }
             }
             if (query.omit)
-                out.omit = "true";
+                out.omit = 'true';
             return out;
         });
         return test;
@@ -47,22 +47,22 @@ export class RecordGetOperation {
         if (this.sortData.length !== 0)
             params.sort = this.sortData;
         if (this.scriptData.after)
-            params["script"] = this.scriptData.after.name;
+            params.script = this.scriptData.after.name;
         if (this.scriptData.after?.parameter)
-            params["script.param"] = this.scriptData.after.parameter;
+            params['script.param'] = this.scriptData.after.parameter;
         if (this.scriptData.presort)
-            params["script.presort"] = this.scriptData.presort.name;
+            params['script.presort'] = this.scriptData.presort.name;
         if (this.scriptData.presort?.parameter)
-            params["script.presort.param"] = this.scriptData.presort.parameter;
+            params['script.presort.param'] = this.scriptData.presort.parameter;
         if (this.scriptData.prerequest)
-            params["script.prerequest"] = this.scriptData.prerequest.name;
+            params['script.prerequest'] = this.scriptData.prerequest.name;
         if (this.scriptData.prerequest?.parameter)
-            params["script.prerequest.param"] = this.scriptData.prerequest.parameter;
+            params['script.prerequest.param'] = this.scriptData.prerequest.parameter;
         if (this.queries.length !== 0)
-            params["query"] = this.formatQueries();
-        let portals = Object.keys(this.portals);
-        params["portal"] = portals;
-        for (let portal of portals) {
+            params.query = this.formatQueries();
+        const portals = Object.keys(this.portals);
+        params.portal = portals;
+        for (const portal of portals) {
             params[`offset.${portal.toString()}`] = this.portals[portal]?.offset;
             params[`limit.${portal.toString()}`] = this.portals[portal]?.limit;
         }
@@ -72,80 +72,106 @@ export class RecordGetOperation {
         const params = new URLSearchParams({
             _limit: limit.toString(),
             _offset: offset.toString(),
-            dateformats: "2" // Ensure dates are received in ISO8601 format
+            dateformats: '2' // Ensure dates are received in ISO8601 format
         });
         if (this.sortData.length !== 0)
-            params.set("_sort", JSON.stringify(this.sortData));
+            params.set('_sort', JSON.stringify(this.sortData));
         if (this.scriptData.after)
-            params.set("script", this.scriptData.after.name);
+            params.set('script', this.scriptData.after.name);
         if (this.scriptData.after?.parameter)
-            params.set("script.param", this.scriptData.after.parameter);
+            params.set('script.param', this.scriptData.after.parameter);
         if (this.scriptData.presort)
-            params.set("script.presort", this.scriptData.presort.name);
+            params.set('script.presort', this.scriptData.presort.name);
         if (this.scriptData.presort?.parameter)
-            params.set("script.presort.param", this.scriptData.presort.parameter);
+            params.set('script.presort.param', this.scriptData.presort.parameter);
         if (this.scriptData.prerequest)
-            params.set("script.prerequest", this.scriptData.prerequest.name);
+            params.set('script.prerequest', this.scriptData.prerequest.name);
         if (this.scriptData.prerequest?.parameter)
-            params.set("script.prerequest.param", this.scriptData.prerequest.parameter);
-        let portals = Object.keys(this.portals);
-        for (let portal of portals) {
-            params.set(`_offset.${portal.toString()}`, (this.portals[portal]?.limit || "").toString());
-            params.set(`_offset.${portal.toString()}`, (this.portals[portal]?.offset || "").toString());
+            params.set('script.prerequest.param', this.scriptData.prerequest.parameter);
+        const portals = Object.keys(this.portals);
+        for (const portal of portals) {
+            params.set(`_offset.${portal.toString()}`, (this.portals[portal]?.limit ?? '').toString());
+            params.set(`_offset.${portal.toString()}`, (this.portals[portal]?.offset ?? '').toString());
         }
         params.set('portal', JSON.stringify(portals));
         return params;
     }
+    /**
+     * Configures any FileMaker scripts to be run as a part of the request
+     *
+     * @param {ScriptRequestData} scripts - The script request data to set.
+     * @return {this} - The current instance of the class.
+     */
     scripts(scripts) {
         this.scriptData = scripts;
         return this;
     }
+    /**
+     * Sorts the data based on the given field name and sort order.
+     *
+     * @param {string} fieldName - The name of the field by which the data should be sorted.
+     * @param {SortOrder} sortOrder - The sort order to be applied (either "asc" for ascending or "desc" for descending).
+     *
+     * @return {this} - Returns the current instance of the object.
+     */
     sort(fieldName, sortOrder) {
         this.sortData.push({ fieldName, sortOrder });
         return this;
     }
     parseFindRequest(query) {
-        let out = {};
-        for (let key of Object.keys(query)) {
+        const out = {};
+        for (const key of Object.keys(query)) {
             out[key] = query[key][FindRequestSymbol].map(item => {
-                if (typeof item === "string")
+                if (typeof item === 'string')
                     return item;
                 // Re-write date into correct format
                 return item
                     .moment
                     .clone()
                     .utcOffset(this.layout.database.host.timezoneOffsetFunc(item.moment))
-                    .format(item.type === "date" ?
-                    this.layout.database.host.dateFormat :
-                    item.type == "time" ?
-                        this.layout.database.host.timeFormat :
-                        this.layout.database.host.timeStampFormat);
-            }).join("");
+                    .format(item.type === 'date'
+                    ? this.layout.database.host.dateFormat
+                    : item.type == 'time'
+                        ? this.layout.database.host.timeFormat
+                        : this.layout.database.host.timeStampFormat);
+            }).join('');
         }
         return out;
     }
+    /**
+     * Adds a new request/query to the list of queries.
+     *
+     * @param {FindRequest} query - The find request to be added.
+     * @param {boolean} [omit=false] - Flag to indicate if the find request should be omitted.
+     * @return {Object} - The current object instance.
+     */
     addRequest(query, omit = false) {
         this.queries.push({ req: this.parseFindRequest(query), omit });
         return this;
     }
-    fetch() {
-        return this.performFind(this.offset, this.limit);
+    /**
+     * Perform a fetch operation.
+     *
+     * @returns {Promise} A promise that resolves with the result of the fetch operation.
+     */
+    async fetch() {
+        return await this.performFind(this.offset, this.limit);
     }
     async performFind(offset, limit) {
-        let trace = new Error();
+        const trace = new Error();
         await this.layout.getLayoutMeta();
-        const is_find = this.isFindRequest;
-        let endpoint = this.layout.endpoint + (is_find ? "/_find" : "/records");
-        if (!is_find)
-            endpoint += "?" + new URLSearchParams(this.generateParamsURL(offset, limit)).toString();
+        const isFind = this.isFindRequest;
+        let endpoint = this.layout.endpoint + (isFind ? '/_find' : '/records');
+        if (!isFind)
+            endpoint += '?' + new URLSearchParams(this.generateParamsURL(offset, limit)).toString();
         const reqData = {
             // port: 443,
-            method: is_find ? "POST" : "GET",
-            body: is_find ? JSON.stringify(this.generateParamsBody(offset, limit)) : undefined,
+            method: isFind ? 'POST' : 'GET',
+            body: isFind ? JSON.stringify(this.generateParamsBody(offset, limit)) : undefined
         };
         try {
-            let res = await this.layout.database.apiRequestJSON(endpoint, reqData);
-            if (res.messages[0].code === "0" && res.response) {
+            const res = await this.layout.database._apiRequestJSON(endpoint, reqData);
+            if (res.messages[0].code === '0' && res.response) {
                 // console.log("RESOLVING")
                 if (!this.layout.metadata)
                     await this.layout.getLayoutMeta();
@@ -169,28 +195,28 @@ export class RecordGetOperation {
     }
     [Symbol.asyncIterator]() {
         let nextOffset = this.offset;
-        let startOffset = JSON.parse(JSON.stringify(this.offset));
-        let limit = this.limit;
-        let exit_after_last_record = false;
+        const startOffset = JSON.parse(JSON.stringify(this.offset));
+        const limit = this.limit;
+        let exitAfterLastRecord = false;
         let records = [];
         const fetch = async () => {
-            const theoretical_limit = (limit - nextOffset) + startOffset;
-            if (theoretical_limit === 0) {
-                exit_after_last_record = true;
+            const theoreticalLimit = (limit - nextOffset) + startOffset;
+            if (theoreticalLimit === 0) {
+                exitAfterLastRecord = true;
                 records = [];
                 return;
             }
-            records = await this.performFind(nextOffset, theoretical_limit < 100 ? theoretical_limit : 100);
+            records = await this.performFind(nextOffset, theoreticalLimit < 100 ? theoreticalLimit : 100);
             nextOffset += 100;
             if (records.length < 100)
-                exit_after_last_record = true;
+                exitAfterLastRecord = true;
         };
         return {
             next: async () => {
-                if (records.length === 0 && !exit_after_last_record) {
+                if (records.length === 0 && !exitAfterLastRecord) {
                     await fetch();
                 }
-                if (records.length === 0 && exit_after_last_record) {
+                if (records.length === 0 && exitAfterLastRecord) {
                     return { done: true, value: undefined };
                 }
                 else {