From a417aa43c9c608da5e07855a09b27ba87cbbf2c2 Mon Sep 17 00:00:00 2001
From: mike12345567 <me@michaeldrury.co.uk>
Date: Wed, 19 Jan 2022 10:24:15 +0000
Subject: [PATCH] Adding comments to a few SQL table schema building functions
 to explain their function.

---
 packages/server/src/integrations/utils.ts | 34 ++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/packages/server/src/integrations/utils.ts b/packages/server/src/integrations/utils.ts
index df716b1fb9..b8c96efffe 100644
--- a/packages/server/src/integrations/utils.ts
+++ b/packages/server/src/integrations/utils.ts
@@ -143,16 +143,41 @@ export function isIsoDateString(str: string) {
   return d.toISOString() === str
 }
 
+/**
+ * This function will determine whether a column is a relationship and whether it
+ * is currently valid. The reason for the validity check is that tables can be deleted
+ * outside of Budibase control and if this is the case it will break Budibase relationships.
+ * The tableIds is a list passed down from the main finalise tables function, which is
+ * based on the tables that have just been fetched. This will only really be used on subsequent
+ * fetches to the first one - if the user is periodically refreshing Budibase knowledge of tables.
+ * @param column The column to check, to see if it is a valid relationship.
+ * @param tableIds The IDs of the tables which currently exist.
+ */
 function shouldCopyRelationship(column: { type: string, tableId?: string }, tableIds: [string]) {
   return column.type === FieldTypes.LINK && column.tableId && tableIds.includes(column.tableId)
 }
 
+/**
+ * Similar function to the shouldCopyRelationship function, but instead this looks for options and boolean
+ * types. It is possible to switch a string -> options and a number -> boolean (and vice versus) need to make
+ * sure that these get copied over when tables are fetched. Also checks whether they are still valid, if a
+ * column has changed type in the external database then copying it over may not be possible.
+ * @param column The column to check for options or boolean type.
+ * @param fetchedColumn The fetched column to check for the type in the external database.
+ */
 function shouldCopySpecialColumn(column: { type: string }, fetchedColumn: { type: string } | undefined) {
   return column.type === FieldTypes.OPTIONS ||
     ((!fetchedColumn || fetchedColumn.type === FieldTypes.NUMBER) && column.type === FieldTypes.BOOLEAN)
 }
 
-// add the existing relationships from the entities if they exist, to prevent them from being overridden
+/**
+ * Looks for columns which need to be copied over into the new table definitions, like relationships
+ * and options types.
+ * @param tableName The name of the table which is being checked.
+ * @param table The specific table which is being checked.
+ * @param entities All the tables that existed before - the old table definitions.
+ * @param tableIds The IDs of the tables which exist now, to check if anything has been removed.
+ */
 function copyExistingPropsOver(
   tableName: string,
   table: Table,
@@ -180,6 +205,13 @@ function copyExistingPropsOver(
   return table
 }
 
+/**
+ * Look through the final table definitions to see if anything needs to be
+ * copied over from the old and if any errors have occurred mark them so
+ * that the user can be made aware.
+ * @param tables The list of tables that have been retrieved from the external database.
+ * @param entities The old list of tables, if there was any to look for definitions in.
+ */
 export function finaliseExternalTables(
   tables: { [key: string]: any },
   entities: { [key: string]: any }