@temporalio/common 1.11.8 → 1.12.0-rc.0

package/src/converter/payload-converter.ts

@@ -49,7 +49,10 @@ export function toPayloads(converter: PayloadConverter, ...values: unknown[]): P
  *
  * @throws {@link ValueError} if conversion of any value in the map fails
  */
-export function mapToPayloads<K extends string>(converter: PayloadConverter, map: Record<K, any>): Record<K, Payload> {
+export function mapToPayloads<K extends string, T = any>(
+  converter: PayloadConverter,
+  map: Record<K, T>
+): Record<K, Payload> {
   return Object.fromEntries(
     Object.entries(map).map(([k, v]): [K, Payload] => [k as K, converter.toPayload(v)])
   ) as Record<K, Payload>;
@@ -84,17 +87,17 @@ export function arrayFromPayloads(converter: PayloadConverter, payloads?: Payloa
   return payloads.map((payload: Payload) => converter.fromPayload(payload));
 }
 
-export function mapFromPayloads<K extends string>(
+export function mapFromPayloads<K extends string, T = unknown>(
   converter: PayloadConverter,
   map?: Record<K, Payload> | null | undefined
-): Record<K, unknown> | undefined {
+): Record<K, T> | undefined {
   if (map == null) return undefined;
   return Object.fromEntries(
     Object.entries(map).map(([k, payload]): [K, unknown] => {
       const value = converter.fromPayload(payload as Payload);
       return [k as K, value];
     })
-  ) as Record<K, unknown>;
+  ) as Record<K, T>;
 }
 
 export interface PayloadConverterWithEncoding {
@@ -252,73 +255,6 @@ export class JsonPayloadConverter implements PayloadConverterWithEncoding {
   }
 }
 
-/**
- * Converts Search Attribute values using JsonPayloadConverter
- */
-export class SearchAttributePayloadConverter implements PayloadConverter {
-  jsonConverter = new JsonPayloadConverter();
-  validNonDateTypes = ['string', 'number', 'boolean'];
-
-  public toPayload(values: unknown): Payload {
-    if (!Array.isArray(values)) {
-      throw new ValueError(`SearchAttribute value must be an array`);
-    }
-
-    if (values.length > 0) {
-      const firstValue = values[0];
-      const firstType = typeof firstValue;
-      if (firstType === 'object') {
-        for (const [idx, value] of values.entries()) {
-          if (!(value instanceof Date)) {
-            throw new ValueError(
-              `SearchAttribute values must arrays of strings, numbers, booleans, or Dates. The value ${value} at index ${idx} is of type ${typeof value}`
-            );
-          }
-        }
-      } else {
-        if (!this.validNonDateTypes.includes(firstType)) {
-          throw new ValueError(`SearchAttribute array values must be: string | number | boolean | Date`);
-        }
-
-        for (const [idx, value] of values.entries()) {
-          if (typeof value !== firstType) {
-            throw new ValueError(
-              `All SearchAttribute array values must be of the same type. The first value ${firstValue} of type ${firstType} doesn't match value ${value} of type ${typeof value} at index ${idx}`
-            );
-          }
-        }
-      }
-    }
-
-    // JSON.stringify takes care of converting Dates to ISO strings
-    const ret = this.jsonConverter.toPayload(values);
-    if (ret === undefined) {
-      throw new ValueError('Could not convert search attributes to payloads');
-    }
-    return ret;
-  }
-
-  /**
-   * Datetime Search Attribute values are converted to `Date`s
-   */
-  public fromPayload<T>(payload: Payload): T {
-    if (payload.metadata === undefined || payload.metadata === null) {
-      throw new ValueError('Missing payload metadata');
-    }
-
-    const value = this.jsonConverter.fromPayload(payload);
-    let arrayWrappedValue = Array.isArray(value) ? value : [value];
-
-    const searchAttributeType = decode(payload.metadata.type);
-    if (searchAttributeType === 'Datetime') {
-      arrayWrappedValue = arrayWrappedValue.map((dateString) => new Date(dateString));
-    }
-    return arrayWrappedValue as unknown as T;
-  }
-}
-
-export const searchAttributePayloadConverter = new SearchAttributePayloadConverter();
-
 export class DefaultPayloadConverter extends CompositePayloadConverter {
   // Match the order used in other SDKs, but exclude Protobuf converters so that the code, including
   // `proto3-json-serializer`, doesn't take space in Workflow bundles that don't use Protobufs. To use Protobufs, use

package/src/converter/payload-search-attributes.ts

@@ -0,0 +1,220 @@
+import { decode, encode } from '../encoding';
+import { ValueError } from '../errors';
+import { Payload } from '../interfaces';
+import {
+  TypedSearchAttributes,
+  SearchAttributeType,
+  SearchAttributes,
+  isValidValueForType,
+  TypedSearchAttributeValue,
+  SearchAttributePair,
+  SearchAttributeUpdatePair,
+  TypedSearchAttributeUpdateValue,
+} from '../search-attributes';
+import { PayloadConverter, JsonPayloadConverter, mapFromPayloads, mapToPayloads } from './payload-converter';
+
+/**
+ * Converts Search Attribute values using JsonPayloadConverter
+ */
+export class SearchAttributePayloadConverter implements PayloadConverter {
+  jsonConverter = new JsonPayloadConverter();
+  validNonDateTypes = ['string', 'number', 'boolean'];
+
+  public toPayload(values: unknown): Payload {
+    if (!Array.isArray(values)) {
+      throw new ValueError(`SearchAttribute value must be an array`);
+    }
+
+    if (values.length > 0) {
+      const firstValue = values[0];
+      const firstType = typeof firstValue;
+      if (firstType === 'object') {
+        for (const [idx, value] of values.entries()) {
+          if (!(value instanceof Date)) {
+            throw new ValueError(
+              `SearchAttribute values must arrays of strings, numbers, booleans, or Dates. The value ${value} at index ${idx} is of type ${typeof value}`
+            );
+          }
+        }
+      } else {
+        if (!this.validNonDateTypes.includes(firstType)) {
+          throw new ValueError(`SearchAttribute array values must be: string | number | boolean | Date`);
+        }
+
+        for (const [idx, value] of values.entries()) {
+          if (typeof value !== firstType) {
+            throw new ValueError(
+              `All SearchAttribute array values must be of the same type. The first value ${firstValue} of type ${firstType} doesn't match value ${value} of type ${typeof value} at index ${idx}`
+            );
+          }
+        }
+      }
+    }
+
+    // JSON.stringify takes care of converting Dates to ISO strings
+    const ret = this.jsonConverter.toPayload(values);
+    if (ret === undefined) {
+      throw new ValueError('Could not convert search attributes to payloads');
+    }
+    return ret;
+  }
+
+  /**
+   * Datetime Search Attribute values are converted to `Date`s
+   */
+  public fromPayload<T>(payload: Payload): T {
+    if (payload.metadata == null) {
+      throw new ValueError('Missing payload metadata');
+    }
+
+    const value = this.jsonConverter.fromPayload(payload);
+    let arrayWrappedValue = Array.isArray(value) ? value : [value];
+    const searchAttributeType = decode(payload.metadata.type);
+    if (searchAttributeType === 'Datetime') {
+      arrayWrappedValue = arrayWrappedValue.map((dateString) => new Date(dateString));
+    }
+    return arrayWrappedValue as unknown as T;
+  }
+}
+
+export const searchAttributePayloadConverter = new SearchAttributePayloadConverter();
+
+export class TypedSearchAttributePayloadConverter implements PayloadConverter {
+  jsonConverter = new JsonPayloadConverter();
+
+  public toPayload<T>(attr: T): Payload {
+    if (!(attr instanceof TypedSearchAttributeValue || attr instanceof TypedSearchAttributeUpdateValue)) {
+      throw new ValueError(
+        `Expect input to be instance of TypedSearchAttributeValue or TypedSearchAttributeUpdateValue, got: ${JSON.stringify(
+          attr
+        )}`
+      );
+    }
+
+    // We check for deletion as well as regular typed search attributes.
+    if (attr.value !== null && !isValidValueForType(attr.type, attr.value)) {
+      throw new ValueError(`Invalid search attribute value ${attr.value} for given type ${attr.type}`);
+    }
+
+    // For server search attributes to work properly, we cannot set the metadata
+    // type when we set null
+    if (attr.value === null) {
+      const payload = this.jsonConverter.toPayload(attr.value);
+      if (payload === undefined) {
+        throw new ValueError('Could not convert typed search attribute to payload');
+      }
+      return payload;
+    }
+
+    // JSON.stringify takes care of converting Dates to ISO strings
+    const payload = this.jsonConverter.toPayload(attr.value);
+    if (payload === undefined) {
+      throw new ValueError('Could not convert typed search attribute to payload');
+    }
+
+    // Note: this shouldn't be the case but the compiler complains without this check.
+    if (payload.metadata == null) {
+      throw new ValueError('Missing payload metadata');
+    }
+    // Add encoded type of search attribute to metatdata
+    payload.metadata['type'] = encode(TypedSearchAttributes.toMetadataType(attr.type));
+    return payload;
+  }
+
+  // Note: type casting undefined values is not clear to caller.
+  // We can't change the typing of the method to return undefined, it's not allowed by the interface.
+  public fromPayload<T>(payload: Payload): T {
+    if (payload.metadata == null) {
+      throw new ValueError('Missing payload metadata');
+    }
+
+    // If no 'type' metadata field or no given value, we skip.
+    if (payload.metadata.type == null) {
+      return undefined as T;
+    }
+    const type = TypedSearchAttributes.toSearchAttributeType(decode(payload.metadata.type));
+    // Unrecognized metadata type (sanity check).
+    if (type === undefined) {
+      return undefined as T;
+    }
+
+    let value = this.jsonConverter.fromPayload(payload);
+
+    // Handle legacy values without KEYWORD_LIST type.
+    if (type !== SearchAttributeType.KEYWORD_LIST && Array.isArray(value)) {
+      // Cannot have an array with multiple values for non-KEYWORD_LIST type.
+      if (value.length > 1) {
+        return undefined as T;
+      }
+      // Unpack single value array.
+      value = value[0];
+    }
+    if (type === SearchAttributeType.DATETIME && value) {
+      value = new Date(value as string);
+    }
+    // Check if the value is a valid for the given type. If not, skip.
+    if (!isValidValueForType(type, value)) {
+      return undefined as T;
+    }
+    return new TypedSearchAttributeValue(type, value) as T;
+  }
+}
+
+export const typedSearchAttributePayloadConverter = new TypedSearchAttributePayloadConverter();
+
+// If both params are provided, conflicting keys will be overwritten by typedSearchAttributes.
+export function encodeUnifiedSearchAttributes(
+  searchAttributes?: SearchAttributes, // eslint-disable-line deprecation/deprecation
+  typedSearchAttributes?: TypedSearchAttributes | SearchAttributeUpdatePair[]
+): Record<string, Payload> {
+  return {
+    ...(searchAttributes ? mapToPayloads(searchAttributePayloadConverter, searchAttributes) : {}),
+    ...(typedSearchAttributes
+      ? mapToPayloads<string, TypedSearchAttributeUpdateValue<SearchAttributeType>>(
+          typedSearchAttributePayloadConverter,
+          Object.fromEntries(
+            (Array.isArray(typedSearchAttributes) ? typedSearchAttributes : typedSearchAttributes.getAll()).map(
+              (pair) => {
+                return [pair.key.name, new TypedSearchAttributeUpdateValue(pair.key.type, pair.value)];
+              }
+            )
+          )
+        )
+      : {}),
+  };
+}
+
+// eslint-disable-next-line deprecation/deprecation
+export function decodeSearchAttributes(indexedFields: Record<string, Payload> | undefined | null): SearchAttributes {
+  if (!indexedFields) return {};
+  return Object.fromEntries(
+    // eslint-disable-next-line deprecation/deprecation
+    Object.entries(mapFromPayloads(searchAttributePayloadConverter, indexedFields) as SearchAttributes).filter(
+      ([_, v]) => v && v.length > 0
+    ) // Filter out empty arrays returned by pre 1.18 servers
+  );
+}
+
+export function decodeTypedSearchAttributes(
+  indexedFields: Record<string, Payload> | undefined | null
+): TypedSearchAttributes {
+  return new TypedSearchAttributes(
+    Object.entries(
+      mapFromPayloads<string, TypedSearchAttributeValue<SearchAttributeType> | undefined>(
+        typedSearchAttributePayloadConverter,
+        indexedFields
+      ) ?? {}
+    ).reduce<SearchAttributePair[]>((acc, [k, attr]) => {
+      // Filter out undefined values from converter.
+      if (!attr) {
+        return acc;
+      }
+      const key = { name: k, type: attr.type };
+      // Ensure is valid pair.
+      if (isValidValueForType(key.type, attr.value)) {
+        acc.push({ key, value: attr.value } as SearchAttributePair);
+      }
+      return acc;
+    }, [])
+  );
+}

package/src/errors.ts

@@ -20,7 +20,8 @@ export class ValueError extends Error {
 export class PayloadConverterError extends ValueError {}
 
 /**
- * Used in different parts of the SDK to note that something unexpected has happened.
+ * Signals that a requested operation can't be completed because it is illegal given the
+ * current state of the object; e.g. trying to use a resource after it has been closed.
  */
 @SymbolBasedInstanceOfError('IllegalStateError')
 export class IllegalStateError extends Error {}

package/src/failure.ts

@@ -101,6 +101,34 @@ export const [encodeRetryState, decodeRetryState] = makeProtoEnumConverters<
   'RETRY_STATE_'
 );
 
+/**
+ * A category to describe the severity and change the observability behavior of an application failure.
+ *
+ * Currently, observability behaviour changes are limited to:
+ * - activities that fail due to a BENIGN application failure emit DEBUG level logs and do not record metrics
+ *
+ * @experimental Category is a new feature and may be subject to change.
+ */
+export const ApplicationFailureCategory = {
+  BENIGN: 'BENIGN',
+} as const;
+
+export type ApplicationFailureCategory = (typeof ApplicationFailureCategory)[keyof typeof ApplicationFailureCategory];
+
+export const [encodeApplicationFailureCategory, decodeApplicationFailureCategory] = makeProtoEnumConverters<
+  temporal.api.enums.v1.ApplicationErrorCategory,
+  typeof temporal.api.enums.v1.ApplicationErrorCategory,
+  keyof typeof temporal.api.enums.v1.ApplicationErrorCategory,
+  typeof ApplicationFailureCategory,
+  'APPLICATION_ERROR_CATEGORY_'
+>(
+  {
+    [ApplicationFailureCategory.BENIGN]: 1,
+    UNSPECIFIED: 0,
+  } as const,
+  'APPLICATION_ERROR_CATEGORY_'
+);
+
 export type WorkflowExecution = temporal.api.common.v1.IWorkflowExecution;
 
 /**
@@ -172,7 +200,8 @@ export class ApplicationFailure extends TemporalFailure {
     public readonly nonRetryable?: boolean | undefined | null,
     public readonly details?: unknown[] | undefined | null,
     cause?: Error,
-    public readonly nextRetryDelay?: Duration | undefined | null
+    public readonly nextRetryDelay?: Duration | undefined | null,
+    public readonly category?: ApplicationFailureCategory | undefined | null
   ) {
     super(message, cause);
   }
@@ -195,8 +224,8 @@ export class ApplicationFailure extends TemporalFailure {
    * By default, will be retryable (unless its `type` is included in {@link RetryPolicy.nonRetryableErrorTypes}).
    */
   public static create(options: ApplicationFailureOptions): ApplicationFailure {
-    const { message, type, nonRetryable = false, details, nextRetryDelay, cause } = options;
-    return new this(message, type, nonRetryable, details, cause, nextRetryDelay);
+    const { message, type, nonRetryable = false, details, nextRetryDelay, cause, category } = options;
+    return new this(message, type, nonRetryable, details, cause, nextRetryDelay, category);
   }
 
   /**
@@ -261,6 +290,12 @@ export interface ApplicationFailureOptions {
    * Cause of the failure
    */
   cause?: Error;
+
+  /**
+   * Severity category of the application error.
+   * Affects worker-side logging and metrics behavior of this failure.
+   */
+  category?: ApplicationFailureCategory;
 }
 
 /**

package/src/index.ts

@@ -19,11 +19,24 @@ export * from './failure';
 export { Headers, Next } from './interceptors';
 export * from './interfaces';
 export * from './logger';
+export * from './priority';
+export * from './metrics';
 export * from './retry-policy';
 export type { Timestamp, Duration, StringValue } from './time';
+export * from './worker-deployments';
+export * from './workflow-definition-options';
 export * from './workflow-handle';
 export * from './workflow-options';
 export * from './versioning-intent';
+export {
+  SearchAttributes, // eslint-disable-line deprecation/deprecation
+  SearchAttributeValue, // eslint-disable-line deprecation/deprecation
+  SearchAttributeType,
+  SearchAttributePair,
+  SearchAttributeUpdatePair,
+  TypedSearchAttributes,
+  defineSearchAttributeKey,
+} from './search-attributes';
 
 /**
  * Encode a UTF-8 string into a Uint8Array

package/src/interfaces.ts

@@ -93,14 +93,6 @@ export interface QueryDefinition<Ret, Args extends any[] = [], Name extends stri
 /** Get the "unwrapped" return type (without Promise) of the execute handler from Workflow type `W` */
 export type WorkflowResultType<W extends Workflow> = ReturnType<W> extends Promise<infer R> ? R : never;
 
-/**
- * If another SDK creates a Search Attribute that's not an array, we wrap it in an array.
- *
- * Dates are serialized as ISO strings.
- */
-export type SearchAttributes = Record<string, SearchAttributeValue | Readonly<SearchAttributeValue> | undefined>;
-export type SearchAttributeValue = string[] | number[] | boolean[] | Date[];
-
 export interface ActivityFunction<P extends any[] = any[], R = any> {
   (...args: P): Promise<R>;
 }

package/src/internal-non-workflow/codec-helpers.ts

@@ -2,7 +2,7 @@ import { Payload } from '../interfaces';
 import { arrayFromPayloads, fromPayloadsAtIndex, toPayloads } from '../converter/payload-converter';
 import { PayloadConverterError } from '../errors';
 import { PayloadCodec } from '../converter/payload-codec';
-import { ProtoFailure, TemporalFailure } from '../failure';
+import { ProtoFailure } from '../failure';
 import { LoadedDataConverter } from '../converter/data-converter';
 import { DecodedPayload, DecodedProtoFailure, EncodedPayload, EncodedProtoFailure } from './codec-types';
 
@@ -109,7 +109,7 @@ export async function decodeFromPayloadsAtIndex<T>(
 export async function decodeOptionalFailureToOptionalError(
   converter: LoadedDataConverter,
   failure: ProtoFailure | undefined | null
-): Promise<TemporalFailure | undefined> {
+): Promise<Error | undefined> {
   const { failureConverter, payloadConverter, payloadCodecs } = converter;
   return failure
     ? failureConverter.failureToError(await decodeFailure(payloadCodecs, failure), payloadConverter)

package/src/internal-non-workflow/index.ts

@@ -9,4 +9,3 @@ export * from './data-converter-helpers';
 export * from './parse-host-uri';
 export * from './proxy-config';
 export * from './tls-config';
-export * from './utils';

package/src/internal-workflow/index.ts

@@ -1 +1,2 @@
 export * from './enums-helpers';
+export * from './objects-helpers';

package/src/internal-workflow/objects-helpers.ts

@@ -0,0 +1,37 @@
+/**
+ * Helper to prevent `undefined` and `null` values overriding defaults when merging maps.
+ */
+export function filterNullAndUndefined<T extends Record<string, any>>(obj: T): T {
+  return Object.fromEntries(Object.entries(obj).filter(([_k, v]) => v != null)) as any;
+}
+
+/**
+ * Merge two objects, possibly removing keys.
+ *
+ * More specifically:
+ * - Any key/value pair in `delta` overrides the corresponding key/value pair in `original`;
+ * - A key present in `delta` with value `undefined` removes the key from the resulting object;
+ * - If `original` is `undefined` or empty, return `delta`;
+ * - If `delta` is `undefined` or empty, return `original` (or undefined if `original` is also undefined);
+ * - If there are no changes, then return `original`.
+ */
+export function mergeObjects<T extends Record<string, any>>(original: T, delta: T | undefined): T;
+export function mergeObjects<T extends Record<string, any>>(
+  original: T | undefined,
+  delta: T | undefined
+): T | undefined {
+  if (original == null) return delta;
+  if (delta == null) return original;
+
+  const merged: Record<string, any> = { ...original };
+  let changed = false;
+  for (const [k, v] of Object.entries(delta)) {
+    if (v !== merged[k]) {
+      if (v == null) delete merged[k];
+      else merged[k] = v;
+      changed = true;
+    }
+  }
+
+  return changed ? (merged as T) : original;
+}

package/src/logger.ts

@@ -1,3 +1,5 @@
+import { filterNullAndUndefined, mergeObjects } from './internal-workflow';
+
 export type LogLevel = 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
 
 export type LogMetadata = Record<string | symbol, any>;
@@ -53,3 +55,109 @@ export enum SdkComponent {
    */
   core = 'core',
 }
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * @internal
+ * @hidden
+ */
+export type LogMetaOrFunc = LogMetadata | (() => LogMetadata);
+
+/**
+ * A logger implementation that adds metadata before delegating calls to a parent logger.
+ *
+ * @internal
+ * @hidden
+ */
+export class LoggerWithComposedMetadata implements Logger {
+  /**
+   * Return a {@link Logger} that adds metadata before delegating calls to a parent logger.
+   *
+   * New metadata may either be specified statically as a delta object, or as a function evaluated
+   * every time a log is emitted that will return a delta object.
+   *
+   * Some optimizations are performed to avoid creating unnecessary objects and to keep runtime
+   * overhead associated with resolving metadata as low as possible.
+   */
+  public static compose(logger: Logger, metaOrFunc: LogMetaOrFunc): Logger {
+    // Flatten recursive LoggerWithComposedMetadata instances
+    if (logger instanceof LoggerWithComposedMetadata) {
+      const contributors = appendToChain(logger.contributors, metaOrFunc);
+      // If the new contributor results in no actual change to the chain, then we don't need a new logger
+      if (contributors === undefined) return logger;
+      return new LoggerWithComposedMetadata(logger.parentLogger, contributors);
+    } else {
+      const contributors = appendToChain(undefined, metaOrFunc);
+      if (contributors === undefined) return logger;
+      return new LoggerWithComposedMetadata(logger, contributors);
+    }
+  }
+
+  constructor(
+    private readonly parentLogger: Logger,
+    private readonly contributors: LogMetaOrFunc[]
+  ) {}
+
+  log(level: LogLevel, message: string, extraMeta?: LogMetadata): void {
+    this.parentLogger.log(level, message, resolveMetadata(this.contributors, extraMeta));
+  }
+
+  trace(message: string, extraMeta?: LogMetadata): void {
+    this.parentLogger.trace(message, resolveMetadata(this.contributors, extraMeta));
+  }
+
+  debug(message: string, extraMeta?: LogMetadata): void {
+    this.parentLogger.debug(message, resolveMetadata(this.contributors, extraMeta));
+  }
+
+  info(message: string, extraMeta?: LogMetadata): void {
+    this.parentLogger.info(message, resolveMetadata(this.contributors, extraMeta));
+  }
+
+  warn(message: string, extraMeta?: LogMetadata): void {
+    this.parentLogger.warn(message, resolveMetadata(this.contributors, extraMeta));
+  }
+
+  error(message: string, extraMeta?: LogMetadata): void {
+    this.parentLogger.error(message, resolveMetadata(this.contributors, extraMeta));
+  }
+}
+
+function resolveMetadata(contributors: LogMetaOrFunc[], extraMeta?: LogMetadata): LogMetadata {
+  const resolved = {};
+  for (const contributor of contributors) {
+    Object.assign(resolved, typeof contributor === 'function' ? contributor() : contributor);
+  }
+  Object.assign(resolved, extraMeta);
+  return filterNullAndUndefined(resolved);
+}
+
+/**
+ * Append a metadata contributor to the chain, merging it with the former last contributor if both are plain objects
+ */
+function appendToChain(
+  existingContributors: LogMetaOrFunc[] | undefined,
+  newContributor: LogMetaOrFunc
+): LogMetaOrFunc[] | undefined {
+  // If the new contributor is an empty object, then it results in no actual change to the chain
+  if (typeof newContributor === 'object' && Object.keys(newContributor).length === 0) {
+    return existingContributors;
+  }
+
+  // If existing chain is empty, then the new contributor is the chain
+  if (existingContributors == null || existingContributors.length === 0) {
+    return [newContributor];
+  }
+
+  // If both last contributor and new contributor are plain objects, merge them to a single object.
+  const last = existingContributors[existingContributors.length - 1];
+  if (typeof last === 'object' && typeof newContributor === 'object') {
+    const merged = mergeObjects(last, newContributor);
+    if (merged === last) return existingContributors;
+    return [...existingContributors.slice(0, -1), merged];
+  }
+
+  // Otherwise, just append the new contributor to the chain.
+  return [...existingContributors, newContributor];
+}