@jd-data-limited/easy-fm 4.1.15 → 5.0.0-beta.1

package/dist/records/layoutRecord.js

@@ -5,7 +5,9 @@ import { RecordBase } from './recordBase.js';
 import { PortalRecord } from './portalRecord.js';
 import { Portal } from './portal.js';
 import { FMError } from '../FMError.js';
+import { ApiRecordResponseObj } from '../models/apiResults.js';
 import moment from 'moment';
+import z from 'zod';
 export class LayoutRecord extends RecordBase {
     portals = {};
     portalsToInclude;
@@ -16,11 +18,12 @@ export class LayoutRecord extends RecordBase {
             this.processPortalData(portalData);
         }
     }
+    /** Returns all loaded portals on this record as an array. */
     get portalsArray() {
         return Object.values(this.portals);
     }
     /**
-     * Asynchronously commits the changes made to the current record.
+     * Saves this record back to FileMaker.
      * @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.
@@ -50,44 +53,42 @@ export class LayoutRecord extends RecordBase {
             data.fieldData.deleteRelated = extraBody.deleteRelatedRecords.map(i => `${i.table}.${i.recordId}`);
         if (this.recordId === -1) {
             // This is a new LayoutRecord
-            const res = await this.layout.database._apiRequestJSON(`${this.layout.endpoint}/records`, {
+            const res = await this.layout.database.fetchJSON(`${this.layout.endpoint}/records`, {
                 method: 'POST',
-                body: JSON.stringify(data)
+                body: JSON.stringify(data),
+                type: z.object({
+                    recordId: z.string(),
+                    modId: z.string(),
+                    scriptError: z.string().optional()
+                })
             });
-            if (!res.response) {
-                throw new FMError(res.messages[0].code, res.httpStatus, res);
-            }
-            else if (typeof res.response.scriptError !== 'undefined' && res.response.scriptError !== '0') {
-                throw new FMError(res.response.scriptError, res.httpStatus, res);
-            }
-            else if (res.messages[0].code === '0') {
-                this.recordId = parseInt(res.response.recordId);
-                this.modId = parseInt(res.response.modId);
-                return this;
-            }
-            else {
-                throw new FMError(res.messages[0].code, res.httpStatus, res);
+            if (typeof res.scriptError !== 'undefined' && res.scriptError !== '0') {
+                throw new FMError(res.scriptError, res.httpStatus, res);
             }
+            this.recordId = parseInt(res.recordId);
+            this.modId = parseInt(res.modId);
+            return this;
         }
         // for (let item of Object.keys(data)) extraBody[item] = data[item]
-        const res = await this.layout.database._apiRequestJSON(this.endpoint, {
+        const res = await this.layout.database.fetchJSON(this.endpoint, {
             method: 'PATCH',
-            body: JSON.stringify(data)
+            body: JSON.stringify(data),
+            type: z.object({
+                modId: z.string(),
+                newPortalRecordInfo: z.array(z.object({
+                    tableName: z.string(),
+                    recordId: z.string(),
+                    modId: z.string()
+                })).optional(),
+                scriptError: z.string().optional()
+            })
         });
-        if (!res.response) {
-            throw new FMError(res.messages[0].code, res.httpStatus, res);
-        }
-        else if (typeof res.response.scriptError !== 'undefined' && res.response.scriptError !== '0') {
-            throw new FMError(res.response.scriptError, res.httpStatus, res);
-        }
-        else if (res.messages[0].code === '0') {
-            this.modId = +res.response.modId;
-            this._onSave();
-            return this;
-        }
-        else {
-            throw new FMError(res.messages[0].code, res.httpStatus, res);
+        if (typeof res.scriptError !== 'undefined' && res.scriptError !== '0') {
+            throw new FMError(res.scriptError, res.httpStatus, res);
         }
+        this.modId = +res.modId;
+        this._onSave();
+        return this;
     }
     processPortalData(portalData) {
         for (const portalName of Object.keys(portalData)) {
@@ -103,8 +104,8 @@ export class LayoutRecord extends RecordBase {
         }
     }
     /**
-     * Re-fetches the current record from the database server.
-     * Throws an error if commit() has not been called.
+     * Reloads this record from FileMaker.
+     * Throws if this record has not been saved yet.
      *
      * @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.
@@ -116,57 +117,50 @@ export class LayoutRecord extends RecordBase {
         }
         if (!this.layout.metadata)
             await this.layout.getLayoutMeta();
-        const res = await this.layout.database._apiRequestJSON(this.endpoint, {
-            method: 'GET'
+        const res = await this.layout.database.fetchJSON(this.endpoint, {
+            type: ApiRecordResponseObj
         });
-        if (res.response && res.messages[0].code === '0') {
-            // console.log(res, res.response.data)
-            this.modId = +res.response.data[0].modId;
-            this.processFieldData(res.response.data[0].fieldData);
-            this.portalData = [];
-            if (res.response.data[0].portalData)
-                this.processPortalData(res.response.data[0].portalData);
-            return this;
-        }
-        else {
-            throw new FMError(res.messages[0].code, res.httpStatus, res);
-        }
+        // console.log(res, res.response.data)
+        this.modId = +res.data[0].modId;
+        this.processFieldData(res.data[0].fieldData);
+        this.portalData = [];
+        if (res.data[0].portalData)
+            this.processPortalData(res.data[0].portalData);
+        return this;
     }
+    /** Creates a duplicate of this record in FileMaker. */
     async duplicate() {
         const trace = new Error();
-        const res = await this.layout.database._apiRequestJSON(this.endpoint, {
-            method: 'POST'
+        const res = await this.layout.database.fetchJSON(this.endpoint, {
+            method: 'POST',
+            type: z.object({
+                recordId: z.string(),
+                modId: z.string(),
+                scriptError: z.string().optional()
+            })
         });
-        if (!res.response) {
-            throw new FMError(res.messages[0].code, res.httpStatus, res, trace);
-        }
-        else if (typeof res.response.scriptError !== 'undefined' && res.response.scriptError !== '0') {
-            throw new FMError(res.response.scriptError, res.httpStatus, res, trace);
-        }
-        else if (res.messages[0].code === '0') {
-            const data = this.toObject((a) => true, (a) => true, (a) => false, (a) => false);
-            const _res = new LayoutRecord(this.layout, res.response.recordId, res.response.modId, data.fieldData, data.portalData);
-            this.emit('duplicated');
-            return _res;
-        }
-        else {
-            throw new FMError(res.messages[0].code, res.httpStatus, res, trace);
+        if (typeof res.scriptError !== 'undefined' && res.scriptError !== '0') {
+            throw new FMError(res.scriptError, res.httpStatus, res, trace);
         }
+        const data = this.toObject((a) => true, (a) => true, (a) => false, (a) => false);
+        const _res = new LayoutRecord(this.layout, res.recordId, res.modId, data.fieldData, data.portalData);
+        this.emit('duplicated');
+        return _res;
     }
+    /** Deletes this record from FileMaker. */
     async delete() {
-        const res = await this.layout.database._apiRequestJSON(this.endpoint, {
-            method: 'DELETE'
+        const res = await this.layout.database.fetchJSON(this.endpoint, {
+            method: 'DELETE',
+            type: z.object({
+                scriptError: z.string().optional()
+            }).optional()
         });
-        if (typeof res.response?.scriptError !== 'undefined' && res.response?.scriptError !== '0') {
-            throw new FMError(res.response.scriptError, res.httpStatus, res);
-        }
-        else if (res.messages[0].code === '0') {
-            this.emit('deleted');
-        }
-        else {
-            throw new FMError(res.messages[0].code, res.httpStatus, res);
+        if (typeof res.scriptError !== 'undefined' && res.scriptError !== '0') {
+            throw new FMError(res.scriptError, res.httpStatus, res);
         }
+        this.emit('deleted');
     }
+    /** Returns this record's edited fields as a FileMaker API payload. */
     fieldsToObject(filter = (a) => a.edited) {
         const fieldsProcessed = {};
         let field;
@@ -196,6 +190,7 @@ export class LayoutRecord extends RecordBase {
         };
         return obj;
     }
+    /** Returns this record and its portal edits as a FileMaker API payload. */
     toObject(filter = (a) => a.edited, portalFilter = (a) => a.records.find(record => record.edited), portalRowFilter = (a) => a.edited, portalFieldFilter = (a) => a.edited) {
         const obj = {
             ...this.fieldsToObject(filter),

package/dist/records/portal.d.ts

@@ -6,8 +6,6 @@ import { type LayoutRecord } from './layoutRecord.js';
  * Represents a portal.
  *
  * @template T - The type of RecordFieldsMap.
- * @class
- * @implements {PortalBase<T>}
  */
 export declare class Portal<T extends RecordFieldsMap> implements PortalBase<T> {
     readonly record: LayoutRecord<any>;
@@ -16,8 +14,6 @@ export declare class Portal<T extends RecordFieldsMap> implements PortalBase<T>
     constructor(record: LayoutRecord<any>, name: string);
     /**
      * Add a new record to the portal
-     * @function create
-     * @async
      * @summary Creates a new record.
      * @returns {Promise<PortalRecord<T>>} A Promise that resolves to the newly created record.
      */

package/dist/records/portal.js

@@ -6,8 +6,6 @@ import { PortalRecord } from './portalRecord.js';
  * Represents a portal.
  *
  * @template T - The type of RecordFieldsMap.
- * @class
- * @implements {PortalBase<T>}
  */
 export class Portal {
     record;
@@ -19,8 +17,6 @@ export class Portal {
     }
     /**
      * Add a new record to the portal
-     * @function create
-     * @async
      * @summary Creates a new record.
      * @returns {Promise<PortalRecord<T>>} A Promise that resolves to the newly created record.
      */

package/dist/records/recordBase.d.ts

@@ -4,6 +4,7 @@ import { type RecordFieldsMap } from '../layouts/recordFieldsMap.js';
 import { type LayoutBase } from '../layouts/layoutBase.js';
 import { type ApiFieldData } from '../models/apiResults.js';
 import { Field, type FieldValue } from './field.js';
+import { type z } from 'zod';
 export declare abstract class RecordBase<T extends RecordFieldsMap> extends EventEmitter {
     readonly layout: LayoutBase;
     readonly type: RecordTypes;
@@ -16,7 +17,7 @@ export declare abstract class RecordBase<T extends RecordFieldsMap> extends Even
      */
     fields: T;
     protected portalData: any[];
-    protected constructor(layout: LayoutBase, recordId: number, modId: number | undefined, fieldData: ApiFieldData);
+    protected constructor(layout: LayoutBase, recordId: number, modId: number | undefined, fieldData: z.infer<typeof ApiFieldData>);
     get endpoint(): string;
     /**
      * A boolean indicating whether this record has been modified and should be committed
@@ -25,6 +26,6 @@ export declare abstract class RecordBase<T extends RecordFieldsMap> extends Even
      */
     get edited(): boolean;
     get fieldsArray(): Array<Field<FieldValue>>;
-    protected processFieldData(fieldData: ApiFieldData): T;
+    protected processFieldData(fieldData: z.infer<typeof ApiFieldData>): T;
     _onSave(): void;
 }

package/dist/types.d.ts

@@ -1,24 +1,29 @@
 import type * as http from 'http';
 import { type FMError } from './FMError.js';
 import { type LayoutInterface } from './layouts/layoutInterface.js';
+import z from "zod";
 export type PickPortals<LAYOUT extends LayoutInterface, PORTALS extends string | number | symbol = ''> = Omit<LAYOUT, 'portals'> & {
     portals: Pick<LAYOUT['portals'], PORTALS>;
 };
-export interface databaseOptionsBase {
+/** Shared database connection options. */
+export interface databaseOptionsBase<CREDENTAILS = loginOptionsOAuth | loginOptionsFileMaker | loginOptionsClaris | loginOptionsToken> {
     database: string;
     debug?: boolean;
-    credentials: loginOptionsOAuth | loginOptionsFileMaker | loginOptionsClaris | loginOptionsToken;
+    credentials: CREDENTAILS;
 }
-export interface databaseOptionsWithExternalSources extends databaseOptionsBase {
+/** Database options including any external FileMaker sources. */
+export interface databaseOptionsWithExternalSources<CREDENTIALS = loginOptionsOAuth | loginOptionsFileMaker | loginOptionsClaris | loginOptionsToken> extends databaseOptionsBase<CREDENTIALS> {
     database: string;
     debug?: boolean;
-    credentials: loginOptionsOAuth | loginOptionsFileMaker | loginOptionsClaris | loginOptionsToken;
-    externalSources: databaseOptionsBase[];
+    credentials: CREDENTIALS;
+    externalSources: Array<databaseOptionsBase<loginOptionsFileMaker>>;
 }
+/** Use an existing FileMaker Data API token. */
 export interface loginOptionsToken {
     method: 'token';
     token: string;
 }
+/** Use FileMaker Data API OAuth headers to create session. */
 export interface loginOptionsOAuth {
     method: 'oauth';
     oauth: {
@@ -26,27 +31,36 @@ export interface loginOptionsOAuth {
         requestIdentifier: string;
     };
 }
+/** Use standard FileMaker username/password login. */
 export interface loginOptionsFileMaker {
     method: 'filemaker';
     username: string;
     password: string;
+    /**
+     * sessionPoolSize - The maximum number of sessions to keep open in the pool. Default is 4.
+     */
+    sessionPoolSize?: number;
 }
+/** Use Claris authentication for session creation. */
 export interface loginOptionsClaris {
     method: 'claris';
     claris: {
         fmid: string;
     };
 }
+/** Portal fetch paging options for one portal. */
 export interface portalFetchData<T = string> {
     portalName: T;
     offset: number;
     limit: number;
 }
+/** FileMaker scripts to run before, during, or after request processing. */
 export interface ScriptRequestData {
     prerequest?: Script;
     presort?: Script;
     after?: Script;
 }
+/** Additional body options accepted by write operations. */
 export interface extraBodyOptions {
     scripts?: ScriptRequestData;
     options?: {
@@ -68,10 +82,12 @@ export interface extraBodyOptions {
         recordId: number;
     }>;
 }
+/** Simple script reference with optional parameter. */
 export interface Script {
     name: string;
     parameter: string;
 }
+/** Raw record payload shape returned by FileMaker Data API. */
 export interface recordObject {
     recordId: number;
     modId: number;
@@ -79,6 +95,7 @@ export interface recordObject {
     portalData?: portalDataObject;
 }
 export type portalDataObject = Record<string, recordObject>;
+/** Field metadata returned by layout metadata endpoint. */
 export interface FieldMetaData {
     name: string;
     type: string;
@@ -95,38 +112,45 @@ export interface FieldMetaData {
     repetitionStart: number;
     repetitionEnd: number;
 }
+/** Layout metadata for top-level fields and portals. */
 export interface LayoutMetaData {
     fieldMetaData: FieldMetaData[];
     portalMetaData?: Record<string, FieldMetaData[]>;
 }
-export interface FMHostMetadata {
-    productInfo: {
-        buildDate: Date;
-        name: string;
-        version: string;
-        dateFormat: string;
-        timeFormat: string;
-        timeStampFormat: string;
-    };
-}
+/** FileMaker host metadata returned by `/productInfo`. */
+export declare const FMHostMetadata: z.ZodObject<{
+    productInfo: z.ZodObject<{
+        buildDate: z.ZodOptional<z.z.ZodCoercedDate<unknown>>;
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        dateFormat: z.ZodString;
+        timeFormat: z.ZodString;
+        timeStampFormat: z.ZodString;
+    }, z.z.core.$strip>;
+}, z.z.core.$strip>;
+/** Result returned when a script executes through API call. */
 export interface ScriptResult {
     scriptError?: FMError;
     scriptResult?: string;
 }
+/** Container download result with payload and response metadata. */
 export interface ContainerBufferResult {
     buffer: Buffer;
     mime?: string;
     request: http.IncomingMessage;
 }
-export interface AuthorizationHeaders {
+/** Standard JSON request headers with bearer authorization. */
+export interface AuthorizationHeaders extends Record<string, string> {
     'Content-Type': 'application/json';
     Authorization: string;
 }
-export interface AuthorizationHeadersOAuth {
+/** OAuth request headers required by FileMaker Data API. */
+export interface AuthorizationHeadersOAuth extends Record<string, string> {
     'Content-Type': 'application/json';
     'X-FM-Data-OAuth-RequestId': string;
     'X-FM-Data-OAuth-Identifier': string;
 }
+/** Options used when creating empty record shells. */
 export interface RecordFetchOptions {
     readonly portals: readonly string[];
 }

package/dist/types.js

@@ -1,6 +1,18 @@
 /*
  * Copyright (c) 2022-2024. See LICENSE file for more information
  */
+import z from "zod";
+/** FileMaker host metadata returned by `/productInfo`. */
+export const FMHostMetadata = z.object({
+    productInfo: z.object({
+        buildDate: z.coerce.date().optional(),
+        name: z.string(),
+        version: z.string().optional(),
+        dateFormat: z.string(),
+        timeFormat: z.string(),
+        timeStampFormat: z.string()
+    })
+});
 export var RecordTypes;
 (function (RecordTypes) {
     RecordTypes[RecordTypes["UNKNOWN"] = 0] = "UNKNOWN";

package/dist/utils/addHeaders.d.ts

@@ -0,0 +1,5 @@
+/**
+ * addHeaders adds headers to the inputted request header object
+ * @param headers
+ */
+export declare function addHeaders(req: RequestInit, headers: Record<string, string>): void;

package/dist/utils/addHeaders.js

@@ -0,0 +1,24 @@
+/**
+ * addHeaders adds headers to the inputted request header object
+ * @param headers
+ */
+export function addHeaders(req, headers) {
+    if (!req.headers) {
+        req.headers = headers;
+    }
+    else if (req.headers instanceof Headers) {
+        for (const key of Object.keys(headers)) {
+            req.headers.set(key, headers[key]);
+        }
+    }
+    else if (Array.isArray(req.headers)) {
+        for (const [key, value] of Object.entries(headers)) {
+            req.headers.push([key, value]);
+        }
+    }
+    else {
+        for (const key of Object.keys(headers)) {
+            req.headers[key] = headers[key];
+        }
+    }
+}

package/dist/utils/query.d.ts

@@ -1,16 +1,23 @@
 import { type Moment } from 'moment';
 export declare const FindRequestSymbol: unique symbol;
+/** Represents a date, time, or timestamp value passed into `query(...)`. */
 export interface TimestampType {
     type: 'date' | 'time' | 'timestamp';
     moment: Moment;
 }
 type QueryParameter = string | number | TimestampType;
+/** Represents a FileMaker find value produced by `query(...)`. */
 export interface Query {
     [FindRequestSymbol]: Array<string | TimestampType>;
 }
+/** Escapes special characters in a raw FileMaker find string. */
 export declare function queryEscape(str: string): string;
+/** Builds a FileMaker find value using template-string syntax. */
 export declare function query(strings: TemplateStringsArray, ...args: QueryParameter[]): Query;
+/** Marks a value as a FileMaker date for use inside `query(...)`. */
 export declare function asDate(date: Date | Moment): TimestampType;
+/** Marks a value as a FileMaker time for use inside `query(...)`. */
 export declare function asTime(date: Date | Moment): TimestampType;
+/** Marks a value as a FileMaker timestamp for use inside `query(...)`. */
 export declare function asTimestamp(date: Date | Moment): TimestampType;
 export {};

package/dist/utils/query.js

@@ -4,12 +4,14 @@
 import moment from 'moment';
 export const FindRequestSymbol = Symbol('easyfm-findrequest');
 const SPECIAL_CHARACTERS = ['\\', '=', '<', '≤', '≥', '>', '…', '...', '//', '@', '#', '*', '"', '~'];
+/** Escapes special characters in a raw FileMaker find string. */
 export function queryEscape(str) {
     for (const char of SPECIAL_CHARACTERS) {
         str = str.replace(char, `\\${char}`);
     }
     return str;
 }
+/** Builds a FileMaker find value using template-string syntax. */
 export function query(strings, ...args) {
     const argStrings = args.map(item => {
         if (typeof item === 'number') {
@@ -26,18 +28,21 @@ export function query(strings, ...args) {
     }).flat(1);
     return { [FindRequestSymbol]: query };
 }
+/** Marks a value as a FileMaker date for use inside `query(...)`. */
 export function asDate(date) {
     return {
         type: 'date',
         moment: moment(date)
     };
 }
+/** Marks a value as a FileMaker time for use inside `query(...)`. */
 export function asTime(date) {
     return {
         type: 'time',
         moment: moment(date)
     };
 }
+/** Marks a value as a FileMaker timestamp for use inside `query(...)`. */
 export function asTimestamp(date) {
     return {
         type: 'timestamp',

package/package.json

@@ -1,14 +1,10 @@
 {
   "name": "@jd-data-limited/easy-fm",
-  "version": "4.1.15",
+  "version": "5.0.0-beta.1",
   "dependencies": {
-    "@types/follow-redirects": "^1.14.4",
-    "@types/node": "^22.7.7",
-    "commander": "^14.0.0",
-    "follow-redirects": "^1.15.5",
-    "moment": "^2.29.4",
-    "node-fetch": "^3.3.2",
-    "node-fetch-cookies": "^2.1.1"
+    "commander": "^14.0.3",
+    "moment": "^2.30.1",
+    "zod": "^4.4.3"
   },
   "type": "module",
   "main": "dist/index.js",
@@ -41,37 +37,44 @@
     "url": "https://github.com/JD-Data-Limited/easy-fm/issues"
   },
   "engines": {
-    "node": ">=20.9.0"
+    "node": ">=22.22.3"
   },
   "devDependencies": {
-    "@babel/cli": "^7.25.7",
-    "@babel/core": "^7.25.8",
-    "@babel/preset-env": "^7.25.8",
-    "@babel/preset-typescript": "^7.25.7",
-    "@types/btoa": "^1.2.3",
-    "@types/events": "^3.0.0",
-    "@types/inquirer": "^9.0.7",
-    "@types/jest": "^29.5.13",
+    "@babel/cli": "^7.29.7",
+    "@babel/core": "^7.29.7",
+    "@babel/preset-env": "^7.29.7",
+    "@babel/preset-typescript": "^7.29.7",
+    "@types/btoa": "^1.2.5",
+    "@types/events": "^3.0.3",
+    "@types/inquirer": "^9.0.10",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.19.21",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
     "babel-jest": "^29.7.0",
-    "dotenv": "^16.3.1",
-    "eslint": "^8.57.0",
+    "dotenv": "^16.6.1",
+    "eslint": "^8.57.1",
     "eslint-config-standard-with-typescript": "^43.0.1",
-    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-n": "^16.6.2",
-    "eslint-plugin-promise": "^6.1.1",
-    "inquirer": "^9.2.13",
+    "eslint-plugin-promise": "^6.6.0",
+    "inquirer": "^9.3.8",
     "jest": "^29.7.0",
-    "ts-jest": "^29.2.5",
+    "ts-jest": "^29.4.11",
     "ts-morph": "^21.0.1",
-    "tsx": "^4.19.4",
-    "typescript": "^5.6.3"
+    "tsx": "^4.22.4",
+    "typedoc": "^0.28.19",
+    "typescript": "^5.9.3"
   },
   "bin": {
     "easyfm": "dist/bin/cli.js"
   },
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && jest"
+    "test": "npm run build && jest",
+    "test:coverage": "jest --coverage --testPathIgnorePatterns='/__tests__/database.test.ts$'",
+    "test:integration": "npm run build && jest __tests__/database.test.ts --runInBand",
+    "test:unit": "jest __tests__/query.test.ts __tests__/CookieJar.test.ts --runInBand",
+    "stress:search": "tsx src/bin/stressSearch.ts",
+    "docs:build": "typedoc --options ./docs/theme.json"
   }
 }