feat: updateComments() function

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log (@egomobile/orm-pg)
 
+## 0.22.0
+
+- add `updateComments()` function
+- update to version `^0.15.0` of [node-orm](https://github.com/egomobile/node-orm)
+- `npm update`(s)
+
 ## 0.21.0
 
 - add `chunkSize` to [IWithPostgresOptions interface](https://egomobile.github.io/node-orm-pg/interfaces/IWithPostgresOptions.html)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@egomobile/orm-pg",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "A PostgreSQL data adapter and other utilities for @egomobile/orm module.",
   "main": "lib/index.js",
   "engines": {
@@ -49,23 +49,23 @@
     "sanitize-filename": "1.6.3"
   },
   "devDependencies": {
-    "@egomobile/orm": "^0.14.0",
+    "@egomobile/orm": "^0.15.0",
     "@egomobile/tsconfig": "^5.0.0",
     "@types/node": "18.17.6",
-    "@types/pg": "8.10.9",
+    "@types/pg": "8.11.0",
     "@types/pg-cursor": "2.7.2",
     "del-cli": "5.1.0",
     "eslint": "8.56.0",
     "eslint-config-ego": "^0.19.0",
-    "nodemon": "3.0.2",
+    "nodemon": "3.0.3",
     "pg": "8.11.3",
     "pg-cursor": "2.10.3",
     "ts-node": "10.9.2",
-    "typedoc": "0.25.6",
+    "typedoc": "0.25.8",
     "typescript": "4.7.4"
   },
   "peerDependencies": {
-    "@egomobile/orm": ">= 0.14.0",
+    "@egomobile/orm": ">= 0.15.0",
     "pg": ">= 8.11.3"
   }
 }

src/utils/index.ts

@@ -369,4 +369,5 @@ export function registerBigIntAsNumber(options?: Nilable<IRegisterBigIntAsNumber
     setTypeParser(isNil(customPgModule) ? pg : customPgModule);
 }
 
+export * from "./updateComments";
 export * from "./withPostgres";

src/utils/internal.ts

@@ -31,6 +31,11 @@ export function asList<T extends any = any>(
     return [itemOrList];
 }
 
+export function escapeStringForQuery(val: any): string {
+    return String(val ?? "")
+        .replace(/'/g, "''");
+}
+
 export function isIterable(obj: any): obj is List<any> {
     if (obj) {
         return typeof obj[Symbol.iterator] === "function";

src/utils/updateComments.ts

@@ -0,0 +1,81 @@
+// This file is part of the @egomobile/orm-pg distribution.
+// Copyright (c) Next.e.GO Mobile SE, Aachen, Germany (https://e-go-mobile.com/)
+//
+// @egomobile/orm-pg is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as
+// published by the Free Software Foundation, version 3.
+//
+// @egomobile/orm-pg is distributed in the hope that it will be useful, but
+// WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+import type { EntityConfigurations, IDataContext } from "@egomobile/orm";
+import { escapeStringForQuery } from "./internal";
+
+/**
+ * Options for `updateComments()` function.
+ */
+export interface IUpdateCommentsOptions {
+    /**
+     * The configurations from where to get the documentation/comments from.
+     */
+    configurations: EntityConfigurations;
+    /**
+     * The underlying database connection / context.
+     */
+    context: IDataContext;
+}
+
+/**
+ * Updates the COMMENT attributes of documented tables and columns.
+ *
+ * @param {IUpdateCommentsOptions} options The options.
+ */
+export async function updateComments(options: IUpdateCommentsOptions) {
+    const {
+        configurations,
+        context
+    } = options;
+
+    const entityConfigEntries = Object.entries(configurations);
+    for (const [tableName, tableConfig] of entityConfigEntries) {
+        const tableComment = tableConfig?.comment?.trim();
+        if (typeof tableComment === "string") {
+            let updateTableCommentQuery: string;
+            if (tableComment !== "") {
+                const escapedTableComment = escapeStringForQuery(tableComment);
+
+                updateTableCommentQuery = `COMMENT ON TABLE ${tableName} IS '${escapedTableComment}';`;
+            }
+            else {
+                updateTableCommentQuery = `COMMENT ON TABLE ${tableName} IS NULL;`;
+            }
+
+            await context.query(updateTableCommentQuery);
+        }
+
+        const tableColumnConfigEntries = Object.entries(tableConfig.fields ?? {});
+        for (const [columnName, columnConfig] of tableColumnConfigEntries) {
+            const fullColumnName = `${tableName}.${columnName}`;
+
+            const tableColumnComment = columnConfig?.comment?.trim();
+            if (typeof tableColumnComment === "string") {
+                let updateTableColumnCommentQuery: string;
+                if (tableColumnComment !== "") {
+                    const escapedTableColumnComment = escapeStringForQuery(tableColumnComment);
+
+                    updateTableColumnCommentQuery = `COMMENT ON TABLE ${fullColumnName} IS '${escapedTableColumnComment}';`;
+                }
+                else {
+                    updateTableColumnCommentQuery = `COMMENT ON TABLE ${fullColumnName} IS NULL;`;
+                }
+
+                await context.query(updateTableColumnCommentQuery);
+            }
+        }
+    }
+}