refactor: add titles to context metadata + placeholder docs; add obje…

…ct id to logs
ahochsteger · May 4, 2024 · accd7e4 · accd7e4
1 parent fd87030
commit accd7e4
Show file tree

Hide file tree

Showing 20 changed files with 322 additions and 145 deletions.
diff --git a/docs/docs/reference/placeholder.mdx b/docs/docs/reference/placeholder.mdx
diff --git a/package.json b/package.json
@@ -55,13 +55,13 @@
     "sonar:local": "npx sonar-scanner -Dsonar.branch.name=local -Dsonar.branch.target=main -Dsonar.projectVersion=''",
     "start:docs": "npm run build:docs && cd docs && npm start",
     "test": "TZ=UTC jest --reporters=summary --silent",
-    "test:examples": "jest --reporters=summary --silent --testPathPattern src/examples",
-    "test:verbose": "jest --detectOpenHandles --reporters='default' --runInBand --verbose",
-    "update": "concurrently 'npm:update:*'",
+    "test:examples": "TZ=UTC jest --reporters=summary --silent --testPathPattern src/examples",
+    "test:verbose": "TZ=UTC jest --detectOpenHandles --reporters='default' --runInBand --verbose",
+    "update": "TZ=UTC concurrently 'npm:update:*'",
     "update:contributors": "npx all-contributors generate",
-    "update:docs": "scripts/update-docs.sh",
-    "update:examples": "scripts/update-examples.sh",
-    "update:schema": "scripts/update-schema.sh"
+    "update:docs": "TZ=UTC scripts/update-docs.sh",
+    "update:examples": "TZ=UTC scripts/update-examples.sh",
+    "update:schema": "TZ=UTC scripts/update-schema.sh"
   },
   "repository": {
     "type": "git",

diff --git a/scripts/update-docs-generate-placeholder.jq b/scripts/update-docs-generate-placeholder.jq
@@ -39,15 +39,16 @@ include "update-docs-generate-common";
     "",
     $map[.contextType].description,
     "",
-    "| Key | Description | Example |",
-    "|-----|-------------|---------|",
+    "| Key | Title | Description | Example |",
+    "|-----|-------|-------------|---------|",
     (
       .placeholder
       | sort_by(.key)
       | .[]
       | ("placeholder." + .key) as $placeholderAnchor
       | [
         "<a id=\"" + $placeholderAnchor + "\">`" + .key + "`</a>",
+        .title,
         generateDescription,
         (if (.example|length==0) then "" else "`" + (if (.example|length>32) then (.example[0:32]+"...") else .example end) + "`" end)
       ]

diff --git a/src/examples/advanced/logSheetLogging.ts b/src/examples/advanced/logSheetLogging.ts
@@ -36,10 +36,11 @@ export const runConfig: Config = {
       "log.timestamp",
       "log.level",
       "log.message",
-      "entity.date",
-      "entity.subject",
-      "entity.from",
-      "entity.url",
+      "object.id",
+      "object.date",
+      "object.subject",
+      "object.from",
+      "object.url",
       "attachment.name",
       "attachment.size",
       "attachment.contentType",

diff --git a/src/gas/examples/advanced/logSheetLogging.js b/src/gas/examples/advanced/logSheetLogging.js
@@ -32,10 +32,11 @@ function logSheetLoggingTest() {
         "log.timestamp",
         "log.level",
         "log.message",
-        "entity.date",
-        "entity.subject",
-        "entity.from",
-        "entity.url",
+        "object.id",
+        "object.date",
+        "object.subject",
+        "object.from",
+        "object.url",
         "attachment.name",
         "attachment.size",
         "attachment.contentType",

diff --git a/src/lib/Context.ts b/src/lib/Context.ts
@@ -52,18 +52,21 @@ type MetaInfoValueType =
 type MetaInfoEntry = {
   deprecationInfo?: string
   description: string
+  title: string
   type: MetaInfoType
   value: MetaInfoValueType
 }
 export function newMetaInfo(
   type: MetaInfoType,
   value: MetaInfoValueType,
+  title: string,
   description: string,
   deprecationInfo?: string,
 ): MetaInfoEntry {
   return {
     deprecationInfo,
     description,
+    title,
     type,
     value,
   }

diff --git a/src/lib/EnvProvider.ts b/src/lib/EnvProvider.ts
@@ -11,20 +11,28 @@ import { Logger as Log } from "./utils/Logger"
 export class EnvProvider {
   public static buildMetaInfo(ctx: EnvContext) {
     const m: MetaInfo = {
-      "date.now": mi(MIT.DATE, () => new Date(), "The current timestamp."),
+      "date.now": mi(
+        MIT.DATE,
+        () => new Date(),
+        "Current Timestamp",
+        "The current timestamp.",
+      ),
       "env.runMode": mi(
         MIT.STRING,
         () => ctx.env.runMode,
+        "Runmode",
         "The runMode used for processing.",
       ),
       "env.timezone": mi(
         MIT.STRING,
         () => ctx.env.timezone,
+        "Timezone",
         "The timezone used for processing.",
       ),
       "user.email": mi(
         MIT.STRING,
         () => ctx.env.session.getActiveUser().getEmail(),
+        "User Email",
         "The email address of the active user.",
       ),
     }

diff --git a/src/lib/actions/AttachmentActions.ts b/src/lib/actions/AttachmentActions.ts
@@ -55,6 +55,7 @@ export class AttachmentActions implements ActionProvider<AttachmentContext> {
       actionMeta["attachment.extracted"] = newMetaInfo(
         MetaInfoType.STRING,
         result.text,
+        "Extracted Text",
         "The extracted text from the attachment (using action `attachment.extractText`)",
       )
       if (args.extract) {

diff --git a/src/lib/actions/GlobalActions.spec.ts b/src/lib/actions/GlobalActions.spec.ts
@@ -52,13 +52,14 @@ it("should log with default level (info) to a logSheet", () => {
     `${fakedSystemDateTimeString}.000`,
     LogLevel.INFO,
     "Log message",
+    "aa0b8cc192a5d8d5b5d8ecda24fd0961b10ae283",
     "2019-05-02 07:15:28",
     "Message Subject 1",
     "message-from@example.com",
     "https://mail.google.com/mail/u/0/#inbox/message-id",
-    "",
-    "",
-    "",
+    "attachment1.pdf",
+    "18",
+    "application/pdf",
     "",
     "",
     "",

diff --git a/src/lib/adapter/GDriveAdapter.ts b/src/lib/adapter/GDriveAdapter.ts
@@ -465,21 +465,25 @@ export class GDriveAdapter extends BaseAdapter {
       actionMeta[`${keyPrefix}.stored.location`] = newMetaInfo(
         MetaInfoType.STRING,
         location,
+        "Stored Location",
         `The location ${desc}`,
       )
       actionMeta[`${keyPrefix}.stored.id`] = newMetaInfo(
         MetaInfoType.STRING,
         file.getId(),
+        "Stored ID",
         `The ID ${desc}`,
       )
       actionMeta[`${keyPrefix}.stored.url`] = newMetaInfo(
         MetaInfoType.STRING,
         file.getUrl(),
+        "Stored URL",
         `The URL ${desc}`,
       )
       actionMeta[`${keyPrefix}.stored.downloadUrl`] = newMetaInfo(
         MetaInfoType.STRING,
         file.getDownloadUrl(),
+        "Stored Download URL",
         `The download URL ${desc}`,
       )
     }

diff --git a/src/lib/adapter/LogAdapter.ts b/src/lib/adapter/LogAdapter.ts
@@ -38,19 +38,16 @@ export class LogAdapter extends BaseAdapter {
     fieldConfig: LogFieldConfig[],
     name: string,
   ): LogFieldConfig | undefined {
-    let field: LogFieldConfig | undefined
     const logConfigField = fieldConfig.find((f) => f.name == name)
-    if (logConfigField) {
-      field = logConfigField
-    } else {
-      const contextField = ctx.meta[name]?.value
-      if (contextField) {
-        field = {
-          name: name,
-          title: name,
-          value: `\${${name}}`,
-        } as LogFieldConfig
-      }
+    const contextField = ctx.meta[name]
+    const field: LogFieldConfig = {
+      name: name,
+      title: logConfigField?.title ?? contextField?.title ?? name,
+      value:
+        logConfigField?.ctxValues?.[ctx.type] ??
+        logConfigField?.value ??
+        `\${${name}}` ??
+        "",
     }
     return field
   }
@@ -83,7 +80,7 @@ export class LogAdapter extends BaseAdapter {
       value = message
     } else if (field.name === LOG_LEVEL_NAME) {
       value = level
-    } else if (field.ctxValues && field.ctxValues[ctx.type]) {
+    } else if (field?.ctxValues?.[ctx.type]) {
       value = field.ctxValues[ctx.type] as string
     } else if (field.value !== undefined) {
       value = field.value ?? ""

diff --git a/src/lib/config/SettingsConfig.ts b/src/lib/config/SettingsConfig.ts
@@ -5,10 +5,10 @@ import { RequiredDeep } from "../utils/UtilityTypes"
 
 // TODO: Use these constants in SettingsConfig below, when typescript-json-schema bug is resolved.
 // See https://github.com/YousefED/typescript-json-schema/issues/336#issuecomment-1528969616
+// PR: https://github.com/YousefED/typescript-json-schema/pull/600
 export const DEFAULT_SETTING_MAX_BATCH_SIZE = 10
 export const DEFAULT_SETTING_MAX_RUNTIME = 280
 export const DEFAULT_SETTING_SLEEP_TIME_THREADS = 100
-
 export const LOG_MESSAGE_NAME = "log.message"
 export const LOG_LEVEL_NAME = "log.level"
 
@@ -83,7 +83,7 @@ export class LogFieldConfig {
   /** The title of the log field that is used as the headline of the log sheet. */
   title: string = ""
   /** The value of the log field. Supports placeholder substitution. */
-  value?: string = ""
+  value?: string = undefined
   /** The context-dependent values. It allows different values depending on the context type. */
   ctxValues?: LogFieldContextConfig = {}
 }
@@ -116,10 +116,11 @@ export class SettingsConfig {
     "log.timestamp",
     "log.level",
     "log.message",
-    "entity.date",
-    "entity.subject",
-    "entity.from",
-    "entity.url",
+    "object.id",
+    "object.date",
+    "object.subject",
+    "object.from",
+    "object.url",
     "attachment.name",
     "attachment.size",
     "attachment.contentType",
@@ -139,18 +140,19 @@ export class SettingsConfig {
       value: "${date.now:date::yyyy-MM-dd HH:mm:ss.SSS}",
     },
     {
-      name: LOG_LEVEL_NAME,
+      name: "log.level",
       title: "Log Level",
     },
     {
-      // Special entry that represents the log message
-      name: LOG_MESSAGE_NAME,
+      name: "log.message",
       title: "Log Message",
     },
-    // TODO: Move title to meta info and use from there.
-    { name: "context.type", title: "Context Type", value: "${context.type}" },
     {
-      name: "entity.id",
+      name: "context.type",
+      title: "Context Type",
+    },
+    {
+      name: "object.id",
       title: "ID",
       ctxValues: {
         attachment: "${attachment.hash}",
@@ -159,7 +161,7 @@ export class SettingsConfig {
       },
     },
     {
-      name: "entity.url",
+      name: "object.url",
       title: "GMail URL",
       ctxValues: {
         attachment: "${message.url}",
@@ -168,7 +170,7 @@ export class SettingsConfig {
       },
     },
     {
-      name: "entity.date",
+      name: "object.date",
       title: "Message Date",
       ctxValues: {
         attachment: "${message.date}",
@@ -177,7 +179,7 @@ export class SettingsConfig {
       },
     },
     {
-      name: "entity.subject",
+      name: "object.subject",
       title: "Subject",
       ctxValues: {
         attachment: "${message.subject}",
@@ -186,7 +188,7 @@ export class SettingsConfig {
       },
     },
     {
-      name: "entity.from",
+      name: "object.from",
       title: "From",
       ctxValues: {
         attachment: "${message.from}",
@@ -208,17 +210,23 @@ export class SettingsConfig {
     {
       name: "stored.location",
       title: "Stored Location",
-      ctxValues: { attachment: "${attachment.stored.location}" },
+      ctxValues: {
+        attachment: "${attachment.stored.location}",
+      },
     },
     {
       name: "stored.url",
       title: "Stored URL",
-      ctxValues: { attachment: "${attachment.stored.url}" },
+      ctxValues: {
+        attachment: "${attachment.stored.url}",
+      },
     },
     {
       name: "stored.downloadUrl",
       title: "Download URL",
-      ctxValues: { attachment: "${attachment.stored.downloadUrl}" },
+      ctxValues: {
+        attachment: "${attachment.stored.downloadUrl}",
+      },
     },
   ]
   /**