@jd-data-limited/easy-fm 3.1.5 → 3.1.6

package/README.md

@@ -20,8 +20,7 @@ or [FileMaker Cloud](https://store.claris.com/filemaker-cloud). This module inte
 ## Before you begin
 
 - You need to know what your server's UTC time offset (in minutes) is.
-  - Running `0 - (new Date()).getTimezoneOffset()` in javascript will the UTC time offset for your current timezone.
-
+    - Running `0 - (new Date()).getTimezoneOffset()` in javascript will the UTC time offset for your current timezone.
 
 ## Connecting to a database
 
@@ -40,7 +39,8 @@ const database = host.database({
         method: "filemaker",
         username: "<username>",
         password: "<password>"
-    }
+    },
+    externalSources: []
 })
 
 database.login().then(() => {
@@ -82,11 +82,11 @@ find_request.addRequests({"GroupID": "abc"}) // Find only the records with field
 find_request.setOffset(30) // Starting from the 30th matching record
 find_request.setLimit(10) // Fetch only 10 records
 
-let records = await range_request.run()
+let records = await range_request.fetch()
 console.log(records)
 ```
 
-### Fetch a record using its record ID
+### Fetch a record using its record ID (NOT RECOMMENDED)
 
 > Please note: When in FileMaker Pro, a record's ID is returned when using Get(RecordID). If you need to fetch a record
 > using a different ID, use the search method above.
@@ -103,9 +103,9 @@ console.log(record)
 let layout = database.getLayout("Your layout name")
 let record = await layout.records.create()
 
-record.getField("Field1").set("Value here")
-record.getField("Field2").set("Value here")
-record.getField("Field3").set("Value here")
+record.fields["Field1"].value = "Value here"
+record.fields["Field2"].value = "Value here"
+record.fields["Field3"].value = "Value here"
 
 await record.commit()
 ```
@@ -116,19 +116,72 @@ await record.commit()
 let layout = database.getLayout("Your layout name")
 let record = await layout.records.get(164)
 
-record.getField("Field1").set("Value here")
-record.getField("Field2").set("Value here")
-record.getField("Field3").set("Value here")
+record.fields["Field1"].value = "Value here"
+record.fields["Field2"].value = "Value here"
+record.fields["Field3"].value = "Value here"
 
 await record.commit()
 ```
 
-# Documentation
+# Field names
+
+When interacting with FileMaker, it is important to remember how FileMaker field names work.
+
+| Field name format             | Use when....                                                                                        |
+|-------------------------------|-----------------------------------------------------------------------------------------------------|
+| `FieldName`                   | Use this when the field you are accessing is in the same table that the layout has been assigned to |
+| `RelatedTableName::FieldName` | Use this when the field **is not** in the same table that the layout has been assigned to           |
+
+> **NOTE:** You will not be able to access any fields that are not on the layout.
+
+# Portal names
+
+> Please read this section carefully if you are working with portals
+
+It is important to note that a portal's name **is not** the same as the name of the table that it links to. The name of a
+portal matches the object name it was assigned in FileMaker's layout editor.
 
-## FMHost
+> **NOTE**: When no name has been manually assigned to it, it will default to the name of the related table.
 
-`hostname`: string
-> The hostname of the server you are connecting to
+# Typescript Implementation
+
+`easy-fm` supports the use of TypeScript. Here's an example of how this works with `easy-fm`:
+
+```typescript
+import FMHost, {Portal, Field, Container} from "@jd-data-limited/easy-fm";
+
+interface UsersLayout {
+    fields: {
+        // Map each field on the layout to a field type.
+        first_name: Field<string>
+        age: Field<number>
+        birthdate: Field<Date>
+        profile_picture: Field<Container>
+        "MyRelatedTable::MyRelatedField": Field<string>
+    },
+    portals: {
+        Files: {
+            "Files::Field1": Field<string>
+        }
+    }
+}
+
+interface DatabaseStructure {
+    layouts: {
+        users: UsersLayout
+    }
+}
+
+const host = new FMHost("https://example_filemaker_server.com")
+const database = host.database<DatabaseStructure>({
+    database: "ExampleDatabase.fmp12",
+    credentials: {method: "filemaker", username: "test", passsword: "test"},
+    externalSources: []
+})
+await database.login()
 
-`timezoneOffset`: number
-> The server's timezone offset
+const layout = database.getLayout("users") // The UsersLayout interface will be automatically applied to all records within this layout
+const record = await layout.records.create()
+record.fields["first_name"].value = "Joe"
+record.fields["age"].value = 38
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jd-data-limited/easy-fm",
-  "version": "3.1.5",
+  "version": "3.1.6",
   "dependencies": {
     "@types/btoa": "^1.2.3",
     "@types/events": "^3.0.0",

package/src/connection/FMHost.d.ts

@@ -1,12 +1,13 @@
 import { Database } from "./database.js";
-import { databaseOptionsWithExternalSources, FMHostMetadata, loginOptionsClaris, loginOptionsFileMaker, loginOptionsOAuth } from "../types.js";
-export default class FMHost {
+import { HostBase } from "./HostBase.js";
+import { databaseOptionsWithExternalSources, DatabaseStructure, FMHostMetadata, loginOptionsClaris, loginOptionsFileMaker, loginOptionsOAuth } from "../types.js";
+export default class FMHost implements HostBase {
     readonly hostname: string;
     readonly timezoneOffset: number;
     readonly verify: boolean;
     metadata: FMHostMetadata;
     constructor(_hostname: string, timezoneOffset?: number, verify?: boolean);
     listDatabases(credentials?: loginOptionsOAuth | loginOptionsFileMaker | loginOptionsClaris): Promise<any>;
-    database(data: databaseOptionsWithExternalSources): Database;
+    database<T extends DatabaseStructure>(data: databaseOptionsWithExternalSources): Database<T>;
     getMetadata(): Promise<any>;
 }

package/src/connection/FMHost.ts

@@ -6,8 +6,9 @@ import {generateAuthorizationHeaders} from "./generateAuthorizationHeaders.js";
 import fetch from "node-fetch";
 import {FMError} from "../FMError.js";
 import {Database} from "./database.js";
+import {HostBase} from "./HostBase.js"
 import {
-    databaseOptionsWithExternalSources,
+    databaseOptionsWithExternalSources, DatabaseStructure,
     fileMakerResponse,
     FMHostMetadata,
     loginOptionsClaris,
@@ -15,7 +16,7 @@ import {
     loginOptionsOAuth
 } from "../types.js";
 
-export default class FMHost {
+export default class FMHost implements HostBase {
     readonly hostname: string
     readonly timezoneOffset: number
     readonly verify: boolean
@@ -50,8 +51,8 @@ export default class FMHost {
         }
     }
 
-    database(data: databaseOptionsWithExternalSources) {
-        return new Database(this, data)
+    database<T extends DatabaseStructure>(data: databaseOptionsWithExternalSources) {
+        return new Database<T>(this, data)
     }
 
     async getMetadata() {

package/src/connection/HostBase.d.ts

@@ -0,0 +1,8 @@
+import { FMHostMetadata } from "../types";
+export interface HostBase {
+    readonly hostname: string;
+    readonly timezoneOffset: number;
+    readonly verify: boolean;
+    metadata: FMHostMetadata;
+    getMetadata(): PromiseLike<any>;
+}

package/src/connection/HostBase.js

@@ -0,0 +1,4 @@
+/*
+ * Copyright (c) 2023. See LICENSE file for more information
+ */
+export {};

package/src/connection/HostBase.ts

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) 2023. See LICENSE file for more information
+ */
+
+import {
+    FMHostMetadata
+} from "../types";
+
+export interface HostBase {
+    readonly hostname: string
+    readonly timezoneOffset: number
+    readonly verify: boolean
+    metadata: FMHostMetadata
+    getMetadata(): PromiseLike<any>
+}

package/src/connection/database.d.ts

@@ -2,25 +2,25 @@
 /// <reference types="node" />
 import { EventEmitter } from "events";
 import { Request } from "node-fetch";
-import { LayoutInterface } from "../layouts/layoutInterface.js";
 import { Layout } from "../layouts/layout.js";
 import * as http from "http";
-import { databaseOptionsWithExternalSources, Script } from "../types.js";
-import FMHost from "./FMHost.js";
-export declare class Database extends EventEmitter {
+import { databaseOptionsWithExternalSources, DatabaseStructure, Script } from "../types.js";
+import { HostBase } from "./HostBase.js";
+import { DatabaseBase } from "./databaseBase";
+export declare class Database<T extends DatabaseStructure> extends EventEmitter implements DatabaseBase {
     private _token;
-    readonly host: FMHost;
+    readonly host: HostBase;
     private connection_details;
     private cookies;
     readonly name: string;
-    constructor(host: FMHost, conn: databaseOptionsWithExternalSources);
+    constructor(host: HostBase, conn: databaseOptionsWithExternalSources);
     private generateExternalSourceLogin;
     logout(): Promise<void>;
     login(): Promise<string>;
     get token(): any;
     get endpoint(): string;
-    apiRequest(url: string | Request, options?: any, autoRelogin?: boolean): Promise<any>;
-    getLayout<T extends LayoutInterface>(name: any): Layout<T>;
+    apiRequest<T = any>(url: string | Request, options?: any, autoRelogin?: boolean): Promise<T>;
+    getLayout<R extends string>(name: R): Layout<T["layouts"][R]>;
     setGlobals(globalFields: any): Promise<void>;
     script(name: any, parameter?: string): Script;
     _tokenExpired(): void;

package/src/connection/database.ts

@@ -12,22 +12,23 @@ import * as http from "http";
 import * as https from "https";
 import {
     databaseOptionsBase,
-    databaseOptionsWithExternalSources,
+    databaseOptionsWithExternalSources, DatabaseStructure,
     fileMakerResponse,
     loginOptionsFileMaker,
     loginOptionsToken,
     Script
 } from "../types.js";
-import FMHost from "./FMHost.js";
+import {HostBase} from "./HostBase.js"
+import {DatabaseBase} from "./databaseBase";
 
-export class Database extends EventEmitter {
+export class Database<T extends DatabaseStructure> extends EventEmitter implements DatabaseBase {
     private _token: any;
-    readonly host: FMHost;
+    readonly host: HostBase;
     private connection_details: databaseOptionsWithExternalSources
     private cookies: { [key: string]: string } = {}
     readonly name: string;
 
-    constructor(host: FMHost, conn: databaseOptionsWithExternalSources) {
+    constructor(host: HostBase, conn: databaseOptionsWithExternalSources) {
         super()
         this.host = host
         this.name = conn.database
@@ -119,7 +120,7 @@ export class Database extends EventEmitter {
         return `${this.host.hostname}/fmi/data/v2/databases/${this.name}`
     }
 
-    async apiRequest(url: string | Request, options: any = {}, autoRelogin = true): Promise<any> {
+    async apiRequest<T = any>(url: string | Request, options: any = {}, autoRelogin = true): Promise<T> {
         if (!options.headers) options.headers = {}
         options.headers["content-type"] = options.headers["content-type"] ? options.headers["content-type"] : "application/json"
         options.headers["authorization"] = "Bearer " + this._token
@@ -142,8 +143,8 @@ export class Database extends EventEmitter {
         return (data as any)
     }
 
-    getLayout<T extends LayoutInterface>(name): Layout<T> {
-        return new Layout(this, name)
+    getLayout<R extends string>(name: R): Layout<T["layouts"][R]> {
+        return new Layout<T["layouts"][R]>(this, name)
     }
 
     setGlobals(globalFields): Promise<void> {

package/src/connection/databaseBase.d.ts

@@ -0,0 +1,8 @@
+import { HostBase } from "./HostBase.js";
+import { Request } from "node-fetch";
+export interface DatabaseBase {
+    host: HostBase;
+    readonly name: string;
+    endpoint: string;
+    apiRequest(url: string | Request, options?: any, autoRelogin?: boolean): Promise<any>;
+}

package/src/connection/databaseBase.js

@@ -0,0 +1,4 @@
+/*
+ * Copyright (c) 2023. See LICENSE file for more information
+ */
+export {};

package/src/connection/databaseBase.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2023. See LICENSE file for more information
+ */
+
+import {HostBase} from "./HostBase.js"
+import {Request} from "node-fetch";
+import {DatabaseStructure} from "../types";
+
+export interface DatabaseBase {
+    host: HostBase,
+    readonly name: string
+    endpoint: string
+
+    // layouts: DatabaseStructure["layouts"]
+
+    apiRequest(url: string | Request, options?: any, autoRelogin?: boolean): Promise<any>
+}

package/src/index.d.ts

@@ -5,7 +5,7 @@ import { Database } from "./connection/database.js";
 import { Layout } from "./layouts/layout.js";
 import { RecordBase } from "./records/recordBase.js";
 import { LayoutRecord } from "./records/layoutRecord.js";
-import { LayoutInterface, RecordFieldsMap, PortalInterface, Container } from "./layouts/layoutInterface.js";
+import { LayoutInterface, PortalInterface } from "./layouts/layoutInterface.js";
 import { PortalRecord } from "./records/portalRecord.js";
 import { Portal } from "./records/portal.js";
 import { Field } from "./records/field.js";
@@ -13,5 +13,7 @@ import { Find } from "./records/getOperations/find.js";
 import { RecordGetOperation } from "./records/getOperations/recordGetOperation.js";
 import { RecordGetRange } from "./records/getOperations/recordGetRange.js";
 import { LayoutRecordManager } from "./layouts/layoutRecordManager.js";
+import { RecordFieldsMap } from "./layouts/recordFieldsMap";
+import { Container } from "./records/field.js";
 export default FMHost;
 export { FMError, TYPES, Database, Layout, RecordBase, LayoutRecord, LayoutInterface, RecordFieldsMap, PortalInterface, PortalRecord, Portal, Field, Find, RecordGetOperation, RecordGetRange, LayoutRecordManager, Container };

package/src/index.ts

@@ -9,7 +9,7 @@ import {Database} from "./connection/database.js";
 import {Layout} from "./layouts/layout.js";
 import {RecordBase} from "./records/recordBase.js";
 import {LayoutRecord} from "./records/layoutRecord.js";
-import {LayoutInterface, RecordFieldsMap, PortalInterface, Container} from "./layouts/layoutInterface.js";
+import {LayoutInterface, PortalInterface} from "./layouts/layoutInterface.js";
 import {PortalRecord} from "./records/portalRecord.js";
 import {Portal} from "./records/portal.js";
 import {Field} from "./records/field.js";
@@ -17,6 +17,8 @@ import {Find} from "./records/getOperations/find.js";
 import {RecordGetOperation} from "./records/getOperations/recordGetOperation.js";
 import {RecordGetRange} from "./records/getOperations/recordGetRange.js";
 import {LayoutRecordManager} from "./layouts/layoutRecordManager.js";
+import {RecordFieldsMap} from "./layouts/recordFieldsMap";
+import {Container} from "./records/field.js";
 
 export default FMHost
 export {

package/src/layouts/layout.d.ts

@@ -1,16 +1,17 @@
 import { LayoutRecordManager } from "./layoutRecordManager.js";
 import { LayoutRecord } from "../records/layoutRecord.js";
-import { ScriptResult } from "../types.js";
+import { Script, ScriptResult } from "../types.js";
 import { LayoutInterface } from "./layoutInterface.js";
 import { Find } from "../records/getOperations/find.js";
 import { FMError } from "../FMError.js";
-import { Database } from "../connection/database.js";
-export declare class Layout<T extends LayoutInterface> {
-    readonly database: Database;
+import { LayoutBase } from "./layoutBase.js";
+import { DatabaseBase } from "../connection/databaseBase";
+export declare class Layout<T extends LayoutInterface> implements LayoutBase {
+    readonly database: DatabaseBase;
     readonly records: LayoutRecordManager<T>;
-    protected name: string;
+    readonly name: string;
     metadata: any;
-    constructor(database: Database, name: string);
+    constructor(database: DatabaseBase, name: string);
     get endpoint(): string;
     /**
      * @deprecated use layout.records.create() instead
@@ -24,6 +25,6 @@ export declare class Layout<T extends LayoutInterface> {
      * @deprecated use layout.records.find() instead
      */
     newFind(): Find<T>;
-    runScript(script: any): Promise<ScriptResult>;
+    runScript(script: Script): Promise<ScriptResult>;
     getLayoutMeta(): Promise<this | FMError>;
 }

package/src/layouts/layout.ts

@@ -4,19 +4,20 @@
 
 import {LayoutRecordManager} from "./layoutRecordManager.js";
 import {LayoutRecord} from "../records/layoutRecord.js";
-import {ScriptResult} from "../types.js";
+import {Script, ScriptResult} from "../types.js";
 import {LayoutInterface} from "./layoutInterface.js";
 import {Find} from "../records/getOperations/find.js";
 import {FMError} from "../FMError.js";
-import {Database} from "../connection/database.js";
+import {LayoutBase} from "./layoutBase.js"
+import {DatabaseBase} from "../connection/databaseBase";
 
-export class Layout<T extends LayoutInterface> {
-    readonly database: Database;
+export class Layout<T extends LayoutInterface> implements LayoutBase {
+    readonly database: DatabaseBase;
     readonly records = new LayoutRecordManager<T>(this)
-    protected name: string;
+    readonly name: string;
     metadata: any;
 
-    constructor(database: Database, name: string) {
+    constructor(database: DatabaseBase, name: string) {
         this.database = database
         this.name = name
     }
@@ -46,7 +47,7 @@ export class Layout<T extends LayoutInterface> {
         return this.records.find()
     }
 
-    runScript(script): Promise<ScriptResult> {
+    runScript(script: Script): Promise<ScriptResult> {
         let trace = new Error()
         return new Promise(async (resolve, reject) => {
             let url = `${this.endpoint}/script/${encodeURIComponent(script.name)}`

package/src/layouts/layoutBase.d.ts

@@ -0,0 +1,11 @@
+import { Script, ScriptResult } from "../types";
+import { FMError } from "../FMError";
+import { DatabaseBase } from "../connection/databaseBase";
+export interface LayoutBase {
+    readonly name: string;
+    metadata: any;
+    endpoint: string;
+    runScript(script: Script): Promise<ScriptResult>;
+    getLayoutMeta(): Promise<this | FMError>;
+    database: DatabaseBase;
+}

package/src/layouts/layoutBase.js

@@ -0,0 +1,4 @@
+/*
+ * Copyright (c) 2023. See LICENSE file for more information
+ */
+export {};

package/src/layouts/layoutBase.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2023. See LICENSE file for more information
+ */
+
+import {Script, ScriptResult} from "../types";
+import {FMError} from "../FMError";
+import {DatabaseBase} from "../connection/databaseBase";
+
+export interface LayoutBase {
+    readonly name: string
+    metadata: any
+    endpoint: string
+    runScript(script: Script): Promise<ScriptResult>
+    getLayoutMeta(): Promise<this | FMError>
+    database: DatabaseBase
+}

package/src/layouts/layoutInterface.d.ts

@@ -1,5 +1,5 @@
 import { Portal } from "../records/portal.js";
-import { Field } from "../records/field.js";
+import { RecordFieldsMap } from "./recordFieldsMap";
 export interface LayoutInterface {
     fields: RecordFieldsMap;
     portals: PortalInterface;
@@ -7,8 +7,3 @@ export interface LayoutInterface {
 export interface PortalInterface {
     [key: string]: Portal<RecordFieldsMap>;
 }
-export interface RecordFieldsMap {
-    [fieldName: string]: Field<FieldValue>;
-}
-export type Container = null;
-export type FieldValue = string | number | Date | Container;

package/src/layouts/layoutInterface.ts

@@ -3,7 +3,7 @@
  */
 
 import {Portal} from "../records/portal.js";
-import {Field} from "../records/field.js";
+import {RecordFieldsMap} from "./recordFieldsMap";
 
 export interface LayoutInterface {
     fields: RecordFieldsMap,
@@ -14,9 +14,3 @@ export interface PortalInterface {
     [key: string]: Portal<RecordFieldsMap>
 }
 
-export interface RecordFieldsMap {
-    [fieldName: string]: Field<FieldValue>
-}
-
-export type Container = null
-export type FieldValue = string | number | Date | Container

package/src/layouts/layoutRecordManager.d.ts

@@ -1,11 +1,11 @@
 import { LayoutRecord } from "../records/layoutRecord.js";
-import { Layout } from "./layout.js";
 import { LayoutInterface } from "./layoutInterface.js";
 import { RecordGetRange } from "../records/getOperations/recordGetRange.js";
 import { Find } from "../records/getOperations/find.js";
+import { LayoutBase } from "./layoutBase.js";
 export declare class LayoutRecordManager<T extends LayoutInterface> {
-    readonly layout: Layout<T>;
-    constructor(layout: Layout<T>);
+    readonly layout: LayoutBase;
+    constructor(layout: LayoutBase);
     create(): Promise<LayoutRecord<T["fields"], T["portals"]>>;
     get(recordId: any): Promise<LayoutRecord<T["fields"], T["portals"]>>;
     range(start?: number, limit?: number): RecordGetRange<T>;

package/src/layouts/layoutRecordManager.ts

@@ -3,15 +3,15 @@
  */
 
 import {LayoutRecord} from "../records/layoutRecord.js";
-import {Layout} from "./layout.js";
 import {LayoutInterface} from "./layoutInterface.js";
 import {RecordGetRange} from "../records/getOperations/recordGetRange.js";
 import {Find} from "../records/getOperations/find.js";
+import {LayoutBase} from "./layoutBase.js"
 
 export class LayoutRecordManager<T extends LayoutInterface> {
-    readonly layout: Layout<T>
+    readonly layout: LayoutBase
 
-    constructor(layout: Layout<T>) {
+    constructor(layout: LayoutBase) {
         this.layout = layout
     }
 

package/src/layouts/recordFieldsMap.d.ts

@@ -0,0 +1,4 @@
+import { Field, FieldValue } from "../records/field";
+export interface RecordFieldsMap {
+    [fieldName: string]: Field<FieldValue>;
+}

package/src/layouts/recordFieldsMap.js

@@ -0,0 +1,4 @@
+/*
+ * Copyright (c) 2023. See LICENSE file for more information
+ */
+export {};

package/src/layouts/recordFieldsMap.ts

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2023. See LICENSE file for more information
+ */
+
+import {Field, FieldValue} from "../records/field";
+
+export interface RecordFieldsMap {
+    [fieldName: string]: Field<FieldValue>
+}

package/src/records/field.d.ts

@@ -3,7 +3,8 @@
 import { RecordBase } from "./recordBase.js";
 import * as http from "http";
 import { ContainerBufferResult, DOWNLOAD_MODES, FieldMetaData } from "../types.js";
-import { FieldValue } from "../layouts/layoutInterface.js";
+export type FieldValue = string | number | Date | Container;
+export type Container = null;
 export declare class Field<T extends FieldValue> {
     record: RecordBase<any>;
     id: string;

package/src/records/field.js

@@ -10,9 +10,9 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+import { RecordTypes } from "./recordBase.js";
 import fetch, { File, FormData } from "node-fetch";
 import { DOWNLOAD_MODES } from "../types.js";
-import { PortalRecord } from "./portalRecord.js";
 import { FMError } from "../FMError.js";
 export class Field {
     constructor(record, id, contents) {
@@ -58,7 +58,8 @@ export class Field {
                 repetitionEnd: 1
             };
         }
-        if (this.record instanceof PortalRecord) {
+        if (this.record.type === RecordTypes.PORTAL) {
+            // @ts-ignore
             return this.record.layout.metadata.portalMetaData[this.record.portal.name || "portal not attached"].find(i => i.name === this.id) || {
                 name: this.id.toString(),
                 type: 'normal',
@@ -129,6 +130,7 @@ export class Field {
             form.append("upload", new File([buffer], filename, { type: mime }));
             let _fetch = yield fetch(`${this.record.endpoint}/containers/${this.id}/1`, {
                 method: "POST",
+                // @ts-ignore
                 headers: { "Authorization": "Bearer " + this.record.layout.database.token },
                 body: form
             }).then(res => res.json())
@@ -148,6 +150,7 @@ export class Field {
     }
     download(mode = DOWNLOAD_MODES.Stream) {
         return new Promise((resolve, reject) => {
+            // @ts-ignore
             this.record.layout.database.streamContainer(this, this._value)
                 .then(stream => {
                 if (mode === DOWNLOAD_MODES.Stream) {