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

package/src/records/getOperations/recordGetOperation.ts

@@ -2,35 +2,31 @@
  * Copyright (c) 2023-2024. See LICENSE file for more information
  */
 
-import {LayoutInterface} from "../../layouts/layoutInterface.js";
-import {PickPortals, ScriptRequestData} from "../../types.js";
-import {LayoutBase} from "../../layouts/layoutBase.js"
-import {LayoutRecord} from "../layoutRecord.js";
-import {ApiRecordResponseObj} from "../../models/apiResults.js";
-import {FMError} from "../../FMError.js";
-import {FindRequestSymbol, 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 = {
-    name: string,
+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 ApiRecordResponseObj} from '../../models/apiResults.js'
+import {FMError} from '../../FMError.js'
+import {FindRequestSymbol, 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"]]: {
-        limit: number,
+    [key in keyof T['portals']]: {
+        limit: number
         offset: number
     }
 }
-export type GetOperationOptions<T extends LayoutInterface> = {
-    portals: Partial<PortalData<T>>,
-    limit?: number,
+export interface GetOperationOptions<T extends LayoutInterface> {
+    portals: Partial<PortalData<T>>
+    limit?: number
     offset?: number
 }
 
@@ -38,158 +34,192 @@ export class RecordGetOperation<T extends LayoutInterface, OPTIONS extends GetOp
     protected layout: LayoutBase
     protected limit: number = 100
     protected scriptData: ScriptRequestData = {}
-    protected sortData: { fieldName: string, sortOrder: SortOrder }[] = []
+    protected sortData: Array<{ fieldName: string, sortOrder: SortOrder }> = []
     protected portals: Partial<PortalData<T>>
     protected offset: number = 1
-    protected queries: {req: FindRequestRaw, omit: boolean}[] = []
+    protected queries: Array<{ req: FindRequestRaw, omit: boolean }> = []
 
-    constructor(layout: LayoutBase, options: OPTIONS) {
+    constructor (layout: LayoutBase, options: OPTIONS) {
         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() {
+    get isFindRequest () {
         return this.queries.length !== 0
     }
 
-    private formatQueries() {
-        let test = this.queries.map(query => {
-            let out: any = {}
-            for (let key of Object.keys(query.req)) {
+    private formatQueries () {
+        const test = this.queries.map(query => {
+            const out: any = {}
+            for (const key of Object.keys(query.req)) {
                 if (query.req[key]) out[key] = query.req[key]
-                else {out[key] = query.req[key]}
+                else {
+                    out[key] = query.req[key]
+                }
             }
-            if (query.omit) out.omit = "true"
+            if (query.omit) out.omit = 'true'
             return out
         })
         return test
     }
 
-    protected generateParamsBody(offset: number, limit: number) {
-        const params: {[key: string]: any} = {
+    protected generateParamsBody (offset: number, limit: number) {
+        const params: Record<string, any> = {
             limit: limit.toString(),
             offset: offset.toString(),
             dateformats: 2 // Ensure dates are received in ISO8601 format
         }
         if (this.sortData.length !== 0) params.sort = this.sortData
 
+        if (this.scriptData.after) params.script = this.scriptData.after.name
+        if (this.scriptData.after?.parameter) params['script.param'] = this.scriptData.after.parameter
 
-        if (this.scriptData.after) params["script"] = this.scriptData.after.name
-        if (this.scriptData.after?.parameter) params["script.param"] = this.scriptData.after.parameter
-
-        if (this.scriptData.presort) params["script.presort"] = this.scriptData.presort.name
-        if (this.scriptData.presort?.parameter) params["script.presort.param"] = this.scriptData.presort.parameter
+        if (this.scriptData.presort) params['script.presort'] = this.scriptData.presort.name
+        if (this.scriptData.presort?.parameter) params['script.presort.param'] = this.scriptData.presort.parameter
 
-        if (this.scriptData.prerequest) params["script.prerequest"] = this.scriptData.prerequest.name
-        if (this.scriptData.prerequest?.parameter) params["script.prerequest.param"] = this.scriptData.prerequest.parameter
+        if (this.scriptData.prerequest) params['script.prerequest'] = this.scriptData.prerequest.name
+        if (this.scriptData.prerequest?.parameter) params['script.prerequest.param'] = this.scriptData.prerequest.parameter
 
-        if (this.queries.length !== 0) params["query"] = this.formatQueries()
+        if (this.queries.length !== 0) params.query = this.formatQueries()
 
-        let portals: (keyof typeof this.portals)[] = Object.keys(this.portals)
-        params["portal"] = portals
-        for (let portal of portals) {
+        const portals: Array<keyof typeof this.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
         }
 
         return params
     }
-    protected generateParamsURL(offset: number, limit: number) {
+
+    protected generateParamsURL (offset: number, limit: number) {
         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))
+        if (this.sortData.length !== 0) params.set('_sort', JSON.stringify(this.sortData))
 
-        if (this.scriptData.after) params.set("script", this.scriptData.after.name)
-        if (this.scriptData.after?.parameter) params.set("script.param", this.scriptData.after.parameter)
+        if (this.scriptData.after) params.set('script', this.scriptData.after.name)
+        if (this.scriptData.after?.parameter) params.set('script.param', this.scriptData.after.parameter)
 
-        if (this.scriptData.presort) params.set("script.presort", this.scriptData.presort.name)
-        if (this.scriptData.presort?.parameter) params.set("script.presort.param", this.scriptData.presort.parameter)
+        if (this.scriptData.presort) params.set('script.presort', this.scriptData.presort.name)
+        if (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)
-        if (this.scriptData.prerequest?.parameter) params.set("script.prerequest.param", this.scriptData.prerequest.parameter)
+        if (this.scriptData.prerequest) params.set('script.prerequest', this.scriptData.prerequest.name)
+        if (this.scriptData.prerequest?.parameter) params.set('script.prerequest.param', this.scriptData.prerequest.parameter)
 
-        let portals: (keyof typeof this.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())
+        const portals: Array<keyof typeof this.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
     }
 
-    scripts(scripts: ScriptRequestData) {
-        this.scriptData = scripts;
+    /**
+     * 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.scriptData = scripts
         return this
     }
 
-    sort(fieldName: string, sortOrder: SortOrder) {
+    /**
+     * 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.sortData.push({fieldName, sortOrder})
         return this
     }
 
-    private parseFindRequest<I extends FindRequest>(query: I): {[key in keyof I]: string} {
-        let out: any = {}
-        for (let key of Object.keys(query)) {
+    private parseFindRequest<I extends FindRequest>(query: I): { [key in keyof I]: string } {
+        const out: any = {}
+        for (const key of Object.keys(query)) {
             out[key] = query[key][FindRequestSymbol].map(item => {
-                if (typeof item === "string") return item
+                if (typeof item === 'string') return item
 
                 // Re-write date into correct format
                 return item
+                    .moment
                     .clone()
-                    .utcOffset(this.layout.database.host.timezoneOffset)
-                    .format("MM/DD/YYYY HH:mm:ss")
-            }).join("")
+                    .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('')
         }
         return out
     }
 
-    addRequest(query: FindRequest, omit = false) {
+    /**
+     * 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 = 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)
     }
 
-    private async performFind(offset: number, limit: number): Promise<LayoutRecord<
-        PickPortals<T, keyof OPTIONS["portals"]>
-    >[]> {
-        let trace = new Error()
+    private async performFind (offset: number, limit: number): Promise<Array<LayoutRecord<
+    PickPortals<T, keyof OPTIONS['portals']>
+    >>> {
+        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<ApiRecordResponseObj>(
+            const res = await this.layout.database._apiRequestJSON<ApiRecordResponseObj>(
                 endpoint,
                 reqData
             )
-            if (res.messages[0].code === "0" && res.response) {
+            if (res.messages[0].code === '0' && res.response) {
                 // console.log("RESOLVING")
                 if (!this.layout.metadata) await this.layout.getLayoutMeta()
                 return res.response.data.map(item => {
                     return new LayoutRecord(this.layout, item.recordId, item.modId, item.fieldData, item.portalData)
                 })
-            }
-            else {
+            } else {
                 throw new FMError(res.messages[0].code, res.httpStatus, res, trace)
             }
-        } catch(e) {
+        } catch (e) {
             if (e instanceof FMError) {
                 if (e.code === 401) {
                     // No records found, so return empty set
@@ -200,40 +230,39 @@ export class RecordGetOperation<T extends LayoutInterface, OPTIONS extends GetOp
         }
     }
 
-    [Symbol.asyncIterator]() {
+    [Symbol.asyncIterator] () {
         let nextOffset = this.offset
-        let startOffset: number = JSON.parse(JSON.stringify(this.offset))
-        let limit = this.limit
+        const startOffset: number = JSON.parse(JSON.stringify(this.offset))
+        const limit = this.limit
 
-        let exit_after_last_record = false
-        let records: LayoutRecord<PickPortals<T, keyof OPTIONS["portals"]>>[] = []
+        let exitAfterLastRecord = false
+        let records: Array<LayoutRecord<PickPortals<T, keyof OPTIONS['portals']>>> = []
 
         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);
-            nextOffset += 100;
-            if (records.length < 100) exit_after_last_record = true
+            records = await this.performFind(nextOffset, theoreticalLimit < 100 ? theoreticalLimit : 100)
+            nextOffset += 100
+            if (records.length < 100) exitAfterLastRecord = true
         }
 
         return {
             next: async () => {
-                if (records.length === 0 && !exit_after_last_record) {
-                    await fetch();
+                if (records.length === 0 && !exitAfterLastRecord) {
+                    await fetch()
                 }
 
-                if (records.length === 0 && exit_after_last_record) {
-                    return {done: true, value: undefined};
-                }
-                else {
+                if (records.length === 0 && exitAfterLastRecord) {
+                    return {done: true, value: undefined}
+                } else {
                     const record = records.shift()
-                    return {done: false, value: record};
+                    return {done: false, value: record}
                 }
             }
-        };
+        }
     }
-}
+}

package/src/records/layoutRecord.d.ts

@@ -1,22 +1,36 @@
-import { extraBodyOptions } from "../types.js";
-import { RecordBase } from "./recordBase.js";
-import { PortalRecord } from "./portalRecord.js";
-import { Portal } from "./portal.js";
-import { LayoutInterface } from "../layouts/layoutInterface.js";
-import { LayoutRecordBase } from "./layoutRecordBase.js";
-import { ApiPortalData, ApiRowDataDef } from "../models/apiResults.js";
-import { LayoutBase } from "../layouts/layoutBase.js";
-import { Field, FieldValue } from "./field.js";
-export declare class LayoutRecord<LAYOUT extends LayoutInterface> extends RecordBase<LAYOUT["fields"]> implements LayoutRecordBase {
-    portals: LAYOUT["portals"];
+import { type extraBodyOptions } from '../types.js';
+import { RecordBase } from './recordBase.js';
+import { PortalRecord } from './portalRecord.js';
+import { Portal } from './portal.js';
+import { type LayoutInterface } from '../layouts/layoutInterface.js';
+import { type LayoutRecordBase } from './layoutRecordBase.js';
+import { type ApiPortalData, type ApiRowDataDef } from '../models/apiResults.js';
+import { type LayoutBase } from '../layouts/layoutBase.js';
+import { type Field, type FieldValue } from './field.js';
+export declare class LayoutRecord<LAYOUT extends LayoutInterface> extends RecordBase<LAYOUT['fields']> implements LayoutRecordBase {
+    portals: LAYOUT['portals'];
     private readonly portalsToInclude;
-    constructor(layout: LayoutBase, recordId: number | string, modId?: string | number, fieldData?: Record<string, string | number>, portalData?: ApiPortalData | null, portalsToInclude?: (keyof LAYOUT["portals"])[]);
-    get portalsArray(): Portal<any>[];
+    constructor(layout: LayoutBase, recordId: number | string, modId?: string | number, fieldData?: Record<string, string | number>, portalData?: ApiPortalData | null, portalsToInclude?: Array<keyof LAYOUT['portals']>);
+    get portalsArray(): Array<Portal<any>>;
+    /**
+     * Asynchronously commits the changes made to the current record.
+     * @param {extraBodyOptions} extraBody - The options for the extra body elements.
+     * @returns {Promise<this>} - A promise that resolves with the modified object.
+     * @throws {FMError} - If an error occurs during the commit process.
+     */
     commit(extraBody?: extraBodyOptions): Promise<this>;
     protected processPortalData(portalData: ApiPortalData): void;
+    /**
+     * Re-fetches the current record from the database server.
+     * Throws an error if commit() has not been called.
+     *
+     * @return {Promise<this>} A Promise that resolves to this RecordBase instance if the record is successfully retrieved.
+     * @throws {Error} If commit() has not been called.
+     * @throws {FMError} If the retrieval fails.
+     */
     get(): Promise<this>;
     duplicate(): Promise<LayoutRecord<LAYOUT>>;
     delete(): Promise<void>;
-    fieldsToObject(filter?: (a: Field<FieldValue>) => boolean): Omit<ApiRowDataDef, "portalData">;
+    fieldsToObject(filter?: (a: Field<FieldValue>) => boolean): Omit<ApiRowDataDef, 'portalData'>;
     toObject(filter?: (a: Field<FieldValue>) => any, portalFilter?: (a: Portal<any>) => any, portalRowFilter?: (a: PortalRecord<never>) => any, portalFieldFilter?: (a: Field<FieldValue>) => any): ApiRowDataDef;
 }