@oneuptime/common 14.0.7 → 14.0.9

package/Types/CustomField/CustomFieldOrder.ts

@@ -0,0 +1,55 @@
+/*
+ * The order a record's custom fields are shown in, wherever they are shown:
+ * the Custom Fields card, the Details step of declaring an incident, and the
+ * incident custom fields that go out in status page subscriber messages.
+ *
+ * Pure, with no database or React imports, so the dashboard and the server
+ * put fields in the same order.
+ */
+
+export type SortCustomFieldDefinitionsFunction = <
+  T extends { sortOrder?: number | null | undefined },
+>(
+  definitions: Array<T>,
+) => Array<T>;
+
+/**
+ * Fields with an order first, lowest first; fields without one after them.
+ * Stable, so fields with the same order (or none) keep the order they came
+ * in. Returns a new list.
+ */
+export const sortCustomFieldDefinitions: SortCustomFieldDefinitionsFunction = <
+  T extends { sortOrder?: number | null | undefined },
+>(
+  definitions: Array<T>,
+): Array<T> => {
+  const orderOf: (definition: T) => number = (definition: T): number => {
+    return typeof definition.sortOrder === "number" &&
+      Number.isFinite(definition.sortOrder)
+      ? definition.sortOrder
+      : Number.POSITIVE_INFINITY;
+  };
+
+  return definitions
+    .map((definition: T, index: number) => {
+      return { definition, index };
+    })
+    .sort(
+      (
+        a: { definition: T; index: number },
+        b: { definition: T; index: number },
+      ) => {
+        const difference: number =
+          orderOf(a.definition) - orderOf(b.definition);
+
+        if (difference !== 0 && !Number.isNaN(difference)) {
+          return difference;
+        }
+
+        return a.index - b.index;
+      },
+    )
+    .map((entry: { definition: T; index: number }) => {
+      return entry.definition;
+    });
+};

package/Types/CustomField/CustomFieldSavedViews.ts

@@ -0,0 +1,225 @@
+import { JSONObject } from "../JSON";
+
+/*
+ * How a saved table view (TableView) refers to a custom field, and what
+ * renaming a field does to those references.
+ *
+ * Custom field values are keyed by the field's display name, and so is
+ * everything a saved view remembers about one:
+ *
+ *   - TableView.columns = { order: [...ids], hidden: [...ids] }, where a
+ *     custom field's column id is "customFields.<name>"
+ *     (CustomFieldColumns.getCustomFieldColumns);
+ *   - TableView.facets.facetSelections and .facetOperators, keyed by the
+ *     facet chip's key "customField:<name>" (Dashboard CustomFieldFacets);
+ *   - TableView.query, the table's own filters, which would hold a custom
+ *     field under query.customFields["<name>"].
+ *
+ * A rename that moved the values but not these would leave every saved view
+ * pointing at a field that no longer exists: the column silently drops out
+ * and the filter chip is discarded as stale. Both prefixes live here so the
+ * table, the facet bar and the rename share one spelling.
+ */
+
+// Column id of a custom field column: "customFields.Severity".
+export const CUSTOM_FIELD_COLUMN_ID_PREFIX: string = "customFields.";
+
+// Facet chip key of a custom field: "customField:Severity".
+export const CUSTOM_FIELD_FACET_KEY_PREFIX: string = "customField:";
+
+/*
+ * The saved views whose table shows incident custom fields. Only tables that
+ * offer saved views (a saveFilterProps.tableId) can have any; today that is
+ * the Incidents list. App/Tests/Dashboard/IncidentCustomFieldSavedViews
+ * fails if a table of incidents gains saved views without being listed.
+ */
+export const INCIDENT_CUSTOM_FIELD_TABLE_VIEW_IDS: Array<string> = [
+  "all-incidents-table",
+];
+
+export interface CustomFieldSavedViewState {
+  query?: JSONObject | null | undefined;
+  facets?: JSONObject | null | undefined;
+  columns?: JSONObject | null | undefined;
+}
+
+export interface RenamedCustomFieldSavedViewState {
+  /*
+   * Only the parts that changed, as the whole new value of that column.
+   * Empty when the view does not mention the field.
+   */
+  changes: CustomFieldSavedViewState;
+  hasChanged: boolean;
+}
+
+type IsObjectFunction = (value: unknown) => value is JSONObject;
+
+const isObject: IsObjectFunction = (value: unknown): value is JSONObject => {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+};
+
+type RenameKeyFunction = (
+  object: JSONObject,
+  oldKey: string,
+  newKey: string,
+) => JSONObject | null;
+
+/*
+ * A copy of `object` with `oldKey` renamed, keeping the key's position, or
+ * null when there is no such key. The renamed value wins over anything the
+ * new key already held, as it does for the values themselves.
+ */
+const renameKey: RenameKeyFunction = (
+  object: JSONObject,
+  oldKey: string,
+  newKey: string,
+): JSONObject | null => {
+  if (!Object.prototype.hasOwnProperty.call(object, oldKey)) {
+    return null;
+  }
+
+  const renamed: JSONObject = {};
+
+  for (const [key, value] of Object.entries(object)) {
+    if (key === oldKey) {
+      renamed[newKey] = value;
+      continue;
+    }
+
+    if (key === newKey) {
+      continue;
+    }
+
+    renamed[key] = value;
+  }
+
+  return renamed;
+};
+
+type RenameInListFunction = (
+  list: unknown,
+  oldEntry: string,
+  newEntry: string,
+) => Array<unknown> | null;
+
+// A copy of the list with the entry renamed (and not doubled), or null.
+const renameInList: RenameInListFunction = (
+  list: unknown,
+  oldEntry: string,
+  newEntry: string,
+): Array<unknown> | null => {
+  if (!Array.isArray(list) || !list.includes(oldEntry)) {
+    return null;
+  }
+
+  const renamed: Array<unknown> = [];
+
+  for (const entry of list) {
+    const next: unknown = entry === oldEntry ? newEntry : entry;
+
+    if (next === newEntry && renamed.includes(newEntry)) {
+      continue;
+    }
+
+    renamed.push(next);
+  }
+
+  return renamed;
+};
+
+export type RenameCustomFieldInSavedViewFunction = (data: {
+  view: CustomFieldSavedViewState;
+  oldName: string;
+  newName: string;
+}) => RenamedCustomFieldSavedViewState;
+
+/**
+ * What a saved view has to become when a custom field it mentions is
+ * renamed from `oldName` to `newName`. Everything else in the view is kept
+ * exactly as it was.
+ */
+export const renameCustomFieldInSavedView: RenameCustomFieldInSavedViewFunction =
+  (data: {
+    view: CustomFieldSavedViewState;
+    oldName: string;
+    newName: string;
+  }): RenamedCustomFieldSavedViewState => {
+    const changes: CustomFieldSavedViewState = {};
+
+    if (!data.oldName || !data.newName || data.oldName === data.newName) {
+      return { changes, hasChanged: false };
+    }
+
+    // Columns: the column ids in the viewer's order and hidden lists.
+    if (isObject(data.view.columns)) {
+      const oldId: string = `${CUSTOM_FIELD_COLUMN_ID_PREFIX}${data.oldName}`;
+      const newId: string = `${CUSTOM_FIELD_COLUMN_ID_PREFIX}${data.newName}`;
+      const columns: JSONObject = { ...data.view.columns };
+      let changed: boolean = false;
+
+      for (const listName of ["order", "hidden"]) {
+        const renamed: Array<unknown> | null = renameInList(
+          columns[listName],
+          oldId,
+          newId,
+        );
+
+        if (renamed) {
+          columns[listName] = renamed as JSONObject[string];
+          changed = true;
+        }
+      }
+
+      if (changed) {
+        changes.columns = columns;
+      }
+    }
+
+    // Facets: the chip's selection and operator, keyed by the chip.
+    if (isObject(data.view.facets)) {
+      const oldKey: string = `${CUSTOM_FIELD_FACET_KEY_PREFIX}${data.oldName}`;
+      const newKey: string = `${CUSTOM_FIELD_FACET_KEY_PREFIX}${data.newName}`;
+      const facets: JSONObject = { ...data.view.facets };
+      let changed: boolean = false;
+
+      for (const mapName of ["facetSelections", "facetOperators"]) {
+        const map: unknown = facets[mapName];
+
+        if (!isObject(map)) {
+          continue;
+        }
+
+        const renamed: JSONObject | null = renameKey(map, oldKey, newKey);
+
+        if (renamed) {
+          facets[mapName] = renamed;
+          changed = true;
+        }
+      }
+
+      if (changed) {
+        changes.facets = facets;
+      }
+    }
+
+    // The table's own filters, should one ever filter on a custom field.
+    if (
+      isObject(data.view.query) &&
+      isObject(data.view.query["customFields"])
+    ) {
+      const renamed: JSONObject | null = renameKey(
+        data.view.query["customFields"],
+        data.oldName,
+        data.newName,
+      );
+
+      if (renamed) {
+        changes.query = { ...data.view.query, customFields: renamed };
+      }
+    }
+
+    return {
+      changes: changes,
+      hasChanged: Object.keys(changes).length > 0,
+    };
+  };

package/Types/CustomField/CustomFieldTemplateMerge.ts

@@ -0,0 +1,71 @@
+import { JSONObject } from "../JSON";
+
+/*
+ * An incident template's custom field values, copied onto an incident being
+ * declared from it.
+ *
+ * A MERGE, never a replacement: the template fills in the fields the incident
+ * does not set, and a value the incident does set - the answer someone typed
+ * on the Details step, or one an API caller sent - always wins. A key set to
+ * null or an empty string wins too: that is an explicit "no value" for that
+ * field, not a gap for the template to fill.
+ *
+ * Shared by the server, which copies a template's values when an incident is
+ * created with `createdIncidentTemplateId`, and kept pure so it is tested on
+ * its own. (The dashboard's Create page merges on the client instead, with
+ * the Details step's values on top: see packCustomFieldFormValues.)
+ */
+
+type IsPlainObjectFunction = (value: unknown) => value is JSONObject;
+
+const isPlainObject: IsPlainObjectFunction = (
+  value: unknown,
+): value is JSONObject => {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    !(value instanceof Date)
+  );
+};
+
+export type MergeTemplateCustomFieldsFunction = (data: {
+  // The template's bag, keyed by field name.
+  templateCustomFields: unknown;
+  // What the incident is being created with, if anything.
+  customFields: unknown;
+}) => JSONObject | undefined;
+
+/**
+ * The incident's bag with the template's values filled in, or undefined when
+ * there is nothing to change: the template has no values, or the incident's
+ * `customFields` is something other than a bag (which is left exactly as it
+ * was sent, for the caller's own mistake to surface as it would have).
+ */
+export const mergeTemplateCustomFields: MergeTemplateCustomFieldsFunction =
+  (data: {
+    templateCustomFields: unknown;
+    customFields: unknown;
+  }): JSONObject | undefined => {
+    if (
+      !isPlainObject(data.templateCustomFields) ||
+      Object.keys(data.templateCustomFields).length === 0
+    ) {
+      return undefined;
+    }
+
+    if (data.customFields === undefined || data.customFields === null) {
+      return { ...data.templateCustomFields };
+    }
+
+    if (!isPlainObject(data.customFields)) {
+      return undefined;
+    }
+
+    return {
+      ...data.templateCustomFields,
+      ...data.customFields,
+    };
+  };
+
+export default mergeTemplateCustomFields;

package/Types/CustomField/CustomFieldType.ts

@@ -32,6 +32,20 @@ enum CustomFieldType {
    * decommissioned at.
    */
   DateTime = "DateTime",
+
+  /**
+   * Several lines of plain text — additional information, affected users or
+   * systems. Stored as a string, exactly like `Text`; only the input (a text
+   * area) and the rendering (line breaks kept) differ.
+   */
+  LongText = "LongText",
+
+  /**
+   * Rich text, written in the Markdown editor (which has a visual mode) and
+   * stored as the Markdown source string. Anything that renders it must go
+   * through the Markdown renderer, never insert it as HTML.
+   */
+  Markdown = "Markdown",
 }
 
 export default CustomFieldType;

package/Types/CustomField/CustomFieldValueFormat.ts

@@ -0,0 +1,161 @@
+import { isCustomFieldValueEmpty } from "./CustomFieldValueMapping";
+
+/*
+ * How a stored custom field value reads as words, for everything that puts a
+ * value in front of a person outside the Custom Fields card: an incident
+ * note's {{customFields.<key>}} placeholder (Common/Utils/Incident/
+ * IncidentNoteTemplateVariables) and the status page subscriber messages
+ * (Common/Server/Utils/StatusPage/IncidentTemplateVariableBuilder).
+ *
+ * Only the reading is shared here. Where the words then go decides the rest:
+ * a note escapes them as Markdown, an email as HTML, an SMS takes them as
+ * they are. A date and time reads in the note author's time zone in a note,
+ * and in the status page's subscriber time zones in its emails, so that is
+ * left to the caller too.
+ *
+ * Pure, with no database or React imports, so the server and the dashboard
+ * share it and it is tested directly.
+ */
+
+/*
+ * A day with no time zone: "2026-09-27", or a wall-clock time on it with no
+ * offset ("2026-09-27T00:00:00"). Its day is the one it names, wherever it is
+ * read.
+ */
+const DAY_WITHOUT_TIME_ZONE_PATTERN: RegExp =
+  /^(\d{4}-\d{2}-\d{2})(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)?$/;
+
+/*
+ * What a Date value's instant is moved by before its UTC day is read; see
+ * formatCustomFieldCalendarDate.
+ */
+const PICKED_DAY_SHIFT_MS: number = 13 * 60 * 60 * 1000;
+
+export type CustomFieldValueToTextFunction = (value: unknown) => string;
+
+/**
+ * Plain text for a value of no particular type: a list joined with commas
+ * (its empty entries left out), a Date as its ISO string, an object as JSON,
+ * anything else as String() gives it. null and undefined are "".
+ */
+export const customFieldValueToText: CustomFieldValueToTextFunction = (
+  value: unknown,
+): string => {
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  if (Array.isArray(value)) {
+    return value
+      .filter((entry: unknown): boolean => {
+        return !isCustomFieldValueEmpty(entry);
+      })
+      .map((entry: unknown): string => {
+        return customFieldValueToText(entry);
+      })
+      .join(", ");
+  }
+
+  if (value instanceof Date) {
+    return isNaN(value.getTime()) ? "" : value.toISOString();
+  }
+
+  if (typeof value === "object") {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+
+  return String(value);
+};
+
+export type CustomFieldValueToDateFunction = (value: unknown) => Date | null;
+
+/**
+ * The instant a Date or DateTime value holds, or null when it holds none
+ * (an empty string, text that is not a date).
+ */
+export const customFieldValueToDate: CustomFieldValueToDateFunction = (
+  value: unknown,
+): Date | null => {
+  if (value instanceof Date) {
+    return isNaN(value.getTime()) ? null : value;
+  }
+
+  if (typeof value === "string" && value.trim().length > 0) {
+    const date: Date = new Date(value.trim());
+    return isNaN(date.getTime()) ? null : date;
+  }
+
+  return null;
+};
+
+export type FormatCustomFieldBooleanFunction = (value: unknown) => string;
+
+/**
+ * Yes or No for a Boolean value, which is stored as true or false (or, from
+ * an older form, as "true" or "false"). Anything else reads as it is.
+ */
+export const formatCustomFieldBoolean: FormatCustomFieldBooleanFunction = (
+  value: unknown,
+): string => {
+  if (value === true || value === "true") {
+    return "Yes";
+  }
+
+  if (value === false || value === "false") {
+    return "No";
+  }
+
+  return customFieldValueToText(value);
+};
+
+export type FormatCustomFieldCalendarDateFunction = (value: unknown) => string;
+
+/**
+ * A Date value - a calendar day with no time of day - as the day that was
+ * picked, "2026-09-27". A value that is no date reads as it is.
+ *
+ * The dashboard does not store the day itself. Its date input stores the
+ * picked day's midnight in the author's time zone, as a UTC instant: 27 Sep
+ * picked in Berlin (UTC+2) is "2026-09-26T22:00:00.000Z", in New York
+ * (UTC-4) "2026-09-27T04:00:00.000Z". So neither the UTC day of the instant
+ * (26 Sep for Berlin: every author east of UTC would get the day before) nor
+ * the reader's day (a reader in another zone than the author's) is the day
+ * that was picked, and who picked it, and where, is not stored.
+ *
+ * The instant is read as the nearest plausible local midnight instead: moved
+ * 13 hours on, its UTC day is the picked day for an author anywhere from
+ * UTC-10:59 to UTC+13:00 - Hawaii to New Zealand in summer - and for a value
+ * an API client stored as UTC midnight. Only an author in UTC-11 or UTC-12,
+ * or past UTC+13, gets the day after or the day before. It is the same day
+ * whoever reads it, so a note and an email about one incident agree.
+ *
+ * A bare day ("2026-09-27"), or a time with no offset, is the day it names.
+ */
+export const formatCustomFieldCalendarDate: FormatCustomFieldCalendarDateFunction =
+  (value: unknown): string => {
+    const match: RegExpMatchArray | null =
+      typeof value === "string"
+        ? value.trim().match(DAY_WITHOUT_TIME_ZONE_PATTERN)
+        : null;
+
+    if (match) {
+      return match[1]!;
+    }
+
+    const date: Date | null = customFieldValueToDate(value);
+
+    const pickedDay: Date | null = date
+      ? new Date(date.getTime() + PICKED_DAY_SHIFT_MS)
+      : null;
+
+    // Invalid only at the very end of the range a Date can hold.
+    if (!pickedDay || isNaN(pickedDay.getTime())) {
+      return customFieldValueToText(value);
+    }
+
+    return pickedDay.toISOString().slice(0, 10);
+  };