@outputai/core 0.5.3-next.0eeffec.0 → 0.5.3-next.69060d7.0

package/src/interface/workflow.spec.js

@@ -1,4 +1,4 @@
-import { Signal } from '#consts';
+import { ACTIVITY_WRAPPER_VERSION_FIELD, Signal, WORKFLOW_WRAPPER_VERSION_FIELD } from '#consts';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { z } from 'zod';
 
@@ -65,12 +65,6 @@ vi.mock( '#consts', async importOriginal => {
   };
 } );
 
-const emptyAggregations = {
-  cost: { total: 0 },
-  tokens: { total: 0 },
-  httpRequests: { total: 0 }
-};
-
 describe( 'workflow()', () => {
   beforeEach( () => {
     vi.clearAllMocks();
@@ -236,94 +230,64 @@ describe( 'workflow()', () => {
   } );
 
   describe( 'root workflow (in workflow context)', () => {
-    it( 'calls getTraceDestinations, returns root trace data and assigns executionContext to memo', async () => {
+    it( 'unwraps wrapped trace destinations and assigns executionContext to memo', async () => {
+      traceDestinationsStepMock.mockResolvedValueOnce( {
+        output: { local: '/tmp/wrapped-trace' },
+        aggregations: null,
+        [ACTIVITY_WRAPPER_VERSION_FIELD]: 1
+      } );
       const { workflow } = await import( './workflow.js' );
 
       const wf = workflow( {
-        name: 'root_wf',
-        description: 'Root',
+        name: 'wrapped_trace_wf',
+        description: 'Wrapped trace',
         inputSchema: z.object( {} ),
-        outputSchema: z.object( { v: z.number() } ),
-        fn: async () => ( { v: 42 } )
+        outputSchema: z.object( { ok: z.boolean() } ),
+        fn: async () => ( { ok: true } )
       } );
 
       const result = await wf( {} );
       expect( traceDestinationsStepMock ).toHaveBeenCalledTimes( 1 );
       expect( result ).toEqual( {
-        output: { v: 42 },
-        trace: { destinations: { local: '/tmp/trace' } },
-        attributes: [],
-        aggregations: emptyAggregations
+        [WORKFLOW_WRAPPER_VERSION_FIELD]: 1,
+        output: { ok: true },
+        trace: { destinations: { local: '/tmp/wrapped-trace' } },
+        aggregations: null
       } );
       const memo = workflowInfoMock().memo;
       expect( memo.executionContext ).toEqual( {
         workflowId: 'wf-test-123',
-        workflowName: 'root_wf',
+        workflowName: 'wrapped_trace_wf',
         disableTrace: false,
         startTime: new Date( '2025-01-01T00:00:00Z' ).getTime()
       } );
     } );
 
-    it( 'collects attribute signals and returns aggregated attributes', async () => {
+    it( 'collects batched aggregation signals from failed activities', async () => {
       const { workflow } = await import( './workflow.js' );
-      const { Attribute } = await import( '#trace_attribute' );
-      const handlers = { addAttribute: () => {} };
+      const handlers = { sendAggregations: () => {} };
       setHandlerMock.mockImplementation( ( signalName, handler ) => {
-        if ( signalName === Signal.ADD_ATTRIBUTE ) {
-          handlers.addAttribute = handler;
+        if ( signalName === Signal.SEND_AGGREGATIONS ) {
+          handlers.sendAggregations = handler;
         }
       } );
 
-      const httpRequest = {
-        type: Attribute.HTTPRequestCount.TYPE,
-        url: 'https://api.example.test/items',
-        requestId: 'req-1'
-      };
-      const httpCost = {
-        type: Attribute.HTTPRequestCost.TYPE,
-        url: 'https://api.example.test/items',
-        requestId: 'req-1',
-        total: 2.5
-      };
-      const llmUsage = {
-        type: Attribute.LLMUsage.TYPE,
-        modelId: 'gpt-4o',
-        total: 0.25,
-        usage: [
-          { type: 'input', ppm: 5, amount: 20_000, total: 0.1 },
-          { type: 'output', ppm: 30, amount: 5_000, total: 0.15 }
-        ],
-        tokensUsed: 25_000
-      };
-
       const wf = workflow( {
-        name: 'attr_wf',
-        description: 'Attributes',
+        name: 'batched_attr_wf',
+        description: 'Batched aggregations',
         inputSchema: z.object( {} ),
         outputSchema: z.object( { ok: z.boolean() } ),
         fn: async () => {
-          handlers.addAttribute( httpRequest );
-          handlers.addAttribute( httpCost );
-          handlers.addAttribute( llmUsage );
+          handlers.sendAggregations( { cost: { total: 3 }, tokens: { total: 0 }, httpRequests: { total: 1 } } );
           return { ok: true };
         }
       } );
 
       const result = await wf( {} );
-      expect( result ).toEqual( {
-        output: { ok: true },
-        trace: { destinations: { local: '/tmp/trace' } },
-        attributes: [ httpRequest, httpCost, llmUsage ],
-        aggregations: {
-          cost: { total: 2.75 },
-          tokens: {
-            total: 25_000,
-            input: 20_000,
-            output: 5_000
-          },
-          httpRequests: { total: 1 }
-        }
-      } );
+      expect( result.cost ).toBeUndefined();
+      expect( result ).not.toHaveProperty( 'attributes' );
+      expect( result.aggregations.cost ).toEqual( { total: 3 } );
+      expect( result.aggregations.httpRequests ).toEqual( { total: 1 } );
     } );
 
     it( 'sets executionContext.disableTrace when options.disableTrace is true', async () => {
@@ -361,41 +325,39 @@ describe( 'workflow()', () => {
 
       const result = await wf( {} );
       expect( traceDestinationsStepMock ).not.toHaveBeenCalled();
-      expect( result ).toEqual( { output: { x: 'child' }, attributes: [] } );
+      expect( result ).toEqual( {
+        [WORKFLOW_WRAPPER_VERSION_FIELD]: 1,
+        output: { x: 'child' },
+        aggregations: null
+      } );
     } );
   } );
 
   describe( 'bound this: invokeStep, invokeSharedStep, invokeEvaluator', () => {
-    it( 'invokeStep calls steps with workflowName#stepName', async () => {
-      const getCalls = [];
-      proxyActivitiesMock.mockImplementation( () => new Proxy( {}, {
-        get: ( _, prop ) => {
-          if ( prop === '__internal#getTraceDestinations' ) {
-            return traceDestinationsStepMock;
-          }
-          if ( typeof prop === 'string' && prop.includes( '#' ) ) {
-            getCalls.push( prop );
-            return vi.fn().mockResolvedValue( {} );
-          }
-          return vi.fn();
-        }
-      } ) );
+    it( 'invokeStep unwraps step output and merges step aggregations', async () => {
+      const stepSpy = vi.fn().mockResolvedValue( {
+        output: { value: 'wrapped' },
+        aggregations: { cost: { total: 0 }, tokens: { total: 0 }, httpRequests: { total: 1 } },
+        [ACTIVITY_WRAPPER_VERSION_FIELD]: 1
+      } );
+      proxyActivitiesMock.mockImplementation( () => createStepsProxy( stepSpy ) );
 
       const { workflow } = await import( './workflow.js' );
 
       const wf = workflow( {
-        name: 'invoke_wf',
-        description: 'Invoke',
+        name: 'unwrap_step_wf',
+        description: 'Unwrap step',
         inputSchema: z.object( {} ),
-        outputSchema: z.object( {} ),
+        outputSchema: z.object( { value: z.string() } ),
         async fn() {
-          await this.invokeStep( 'myStep', { foo: 1 } );
-          return {};
+          return this.invokeStep( 'myStep', { foo: 1 } );
         }
       } );
 
-      await wf( {} );
-      expect( getCalls ).toContain( 'invoke_wf#myStep' );
+      const result = await wf( {} );
+      expect( result.output ).toEqual( { value: 'wrapped' } );
+      expect( result ).not.toHaveProperty( 'attributes' );
+      expect( result.aggregations.httpRequests ).toEqual( { total: 1 } );
     } );
 
     it( 'invokeSharedStep calls steps with SHARED_STEP_PREFIX#stepName', async () => {
@@ -464,7 +426,7 @@ describe( 'workflow()', () => {
     it( 'calls executeChild with correct args and TERMINATE when not detached', async () => {
       const { workflow } = await import( './workflow.js' );
       const { ParentClosePolicy } = await import( '@temporalio/workflow' );
-      executeChildMock.mockResolvedValueOnce( { output: {}, attributes: [] } );
+      executeChildMock.mockResolvedValueOnce( { output: {}, aggregations: null } );
 
       const wf = workflow( {
         name: 'parent_wf',
@@ -492,7 +454,7 @@ describe( 'workflow()', () => {
     it( 'uses ABANDON when extra.detached is true', async () => {
       const { workflow } = await import( './workflow.js' );
       const { ParentClosePolicy } = await import( '@temporalio/workflow' );
-      executeChildMock.mockResolvedValueOnce( { output: {}, attributes: [] } );
+      executeChildMock.mockResolvedValueOnce( { output: {}, aggregations: null } );
 
       const wf = workflow( {
         name: 'detach_wf',
@@ -513,7 +475,7 @@ describe( 'workflow()', () => {
 
     it( 'passes empty args when input is null/omitted', async () => {
       const { workflow } = await import( './workflow.js' );
-      executeChildMock.mockResolvedValueOnce( { output: {}, attributes: [] } );
+      executeChildMock.mockResolvedValueOnce( { output: {}, aggregations: null } );
 
       const wf = workflow( {
         name: 'no_input_wf',
@@ -532,26 +494,20 @@ describe( 'workflow()', () => {
       } ) );
     } );
 
-    it( 'returns child output and merges child attributes into the root result', async () => {
+    it( 'returns child output and merges child workflow aggregations into the root aggregations', async () => {
       const { workflow } = await import( './workflow.js' );
-      const { Attribute } = await import( '#trace_attribute' );
-      const childAttribute = {
-        type: Attribute.LLMUsage.TYPE,
-        modelId: 'gpt-4o',
-        total: 0.4,
-        tokensUsed: 20,
-        usage: [
-          { type: 'input', ppm: 10, amount: 20, total: 0.4 }
-        ]
-      };
       executeChildMock.mockResolvedValueOnce( {
         output: { child: 'ok' },
-        attributes: [ childAttribute ]
+        aggregations: {
+          cost: { total: 1.5 },
+          tokens: { total: 4, input: 4 },
+          httpRequests: { total: 2 }
+        }
       } );
 
       const wf = workflow( {
-        name: 'merge_child_wf',
-        description: 'Merge child attributes',
+        name: 'merge_child_aggregations_wf',
+        description: 'Merge child aggregations',
         inputSchema: z.object( {} ),
         outputSchema: z.object( { child: z.string() } ),
         async fn() {
@@ -561,40 +517,36 @@ describe( 'workflow()', () => {
 
       const result = await wf( {} );
       expect( result ).toEqual( {
+        [WORKFLOW_WRAPPER_VERSION_FIELD]: 1,
         output: { child: 'ok' },
         trace: { destinations: { local: '/tmp/trace' } },
-        attributes: [ childAttribute ],
         aggregations: {
-          cost: { total: 0.4 },
-          tokens: {
-            total: 20,
-            input: 20
-          },
-          httpRequests: { total: 0 }
+          cost: { total: 1.5 },
+          tokens: { total: 4, input: 4 },
+          httpRequests: { total: 2 }
         }
       } );
     } );
 
-    it( 'merges child error attributes before rethrowing to root metadata', async () => {
+    it( 'merges child error aggregations before rethrowing to root metadata', async () => {
       const { workflow } = await import( './workflow.js' );
       const { ChildWorkflowFailure } = await import( '@temporalio/workflow' );
       const { METADATA_ACCESS_SYMBOL } = await import( '#consts' );
-      const { Attribute } = await import( '#trace_attribute' );
-      const childAttribute = {
-        type: Attribute.HTTPRequestCost.TYPE,
-        url: 'https://api.example.test',
-        requestId: 'req-child',
-        total: 2
-      };
       const childError = new ChildWorkflowFailure( 'child failed', {
         message: 'Child workflow execution failed',
-        details: [ { attributes: [ childAttribute ] } ]
+        details: [ {
+          aggregations: {
+            cost: { total: 3 },
+            tokens: { total: 8, output: 8 },
+            httpRequests: { total: 0 }
+          }
+        } ]
       } );
       executeChildMock.mockRejectedValueOnce( childError );
 
       const wf = workflow( {
-        name: 'child_error_wf',
-        description: 'Child error attributes',
+        name: 'child_error_aggregations_wf',
+        description: 'Child error aggregations',
         inputSchema: z.object( {} ),
         outputSchema: z.object( {} ),
         async fn() {
@@ -605,11 +557,11 @@ describe( 'workflow()', () => {
 
       await expect( wf( {} ) ).rejects.toThrow( 'child failed' );
       expect( childError[METADATA_ACCESS_SYMBOL] ).toEqual( {
-        attributes: [ childAttribute ],
+        [WORKFLOW_WRAPPER_VERSION_FIELD]: 1,
         trace: { destinations: { local: '/tmp/trace' } },
         aggregations: {
-          cost: { total: 2 },
-          tokens: { total: 0 },
+          cost: { total: 3 },
+          tokens: { total: 8, output: 8 },
           httpRequests: { total: 0 }
         }
       } );
@@ -617,7 +569,7 @@ describe( 'workflow()', () => {
   } );
 
   describe( 'error handling (root workflow)', () => {
-    it( 'rethrows error from fn with trace attributes and aggregation metadata', async () => {
+    it( 'rethrows error from fn with trace and aggregation metadata', async () => {
       const { workflow } = await import( './workflow.js' );
       const { METADATA_ACCESS_SYMBOL } = await import( '#consts' );
       const error = new Error( 'workflow failed' );
@@ -634,9 +586,9 @@ describe( 'workflow()', () => {
 
       await expect( wf( {} ) ).rejects.toThrow( 'workflow failed' );
       expect( error[METADATA_ACCESS_SYMBOL] ).toEqual( {
+        [WORKFLOW_WRAPPER_VERSION_FIELD]: 1,
         trace: { destinations: { local: '/tmp/trace' } },
-        attributes: [],
-        aggregations: emptyAggregations
+        aggregations: null
       } );
     } );
   } );

package/src/internal_utils/aggregations.js

@@ -0,0 +1,54 @@
+import { deepMergeWithResolver } from '#utils';
+import { Attribute } from '#trace_attribute';
+import Decimal from 'decimal.js';
+
+/**
+ * @typedef {object} Aggregation
+ *
+ * @property {object} cost
+ * @property {object} cost.total - Total cost
+ * @property {object} tokens
+ * @property {object} tokens.total - Total tokens used
+ * @property {object} tokens.input  - Total input tokens used
+ * @property {object} tokens.input_cached - Total cached input tokens used
+ * @property {object} tokens.output - Total output tokens used
+ * @property {object} tokens.reasoning - Total reasoning tokens used
+ * @property {object} httpRequests
+ * @property {object} httpRequests.total - Total number of http requests made
+ */
+/**
+ * Aggregates a collection of Attributes into a object with totals
+ *
+ * @param {Attribute} attributes
+ * @returns {Aggregation} aggregation object
+ */
+export const aggregateAttributes = attributes => ( {
+  cost: {
+    total: attributes
+      .filter( a => [ Attribute.HTTPRequestCost.TYPE, Attribute.LLMUsage.TYPE ].includes( a.type ) )
+      .reduce( ( sum, a ) => sum.add( a.total ), Decimal( 0 ) ).toNumber()
+  },
+  tokens: {
+    total: attributes
+      .filter( a => Attribute.LLMUsage.TYPE === a.type )
+      .reduce( ( sum, a ) => sum.add( a.tokensUsed ), Decimal( 0 ) ).toNumber(),
+    ...Object.entries( attributes
+      .filter( a => Attribute.LLMUsage.TYPE === a.type )
+      .flatMap( a => a.usage )
+      .reduce( ( obj, a ) => Object.assign( obj, { [a.type]: ( obj[a.type] ?? Decimal( 0 ) ).add( a.amount ) } ), {} ) )
+      .reduce( ( obj, [ k, v ] ) => Object.assign( obj, { [k]: v.toNumber() } ), {} ) // convert all values to number
+
+  },
+  httpRequests: {
+    total: attributes.filter( a => Attribute.HTTPRequestCount.TYPE === a.type ).length
+  }
+} );
+
+/**
+ * Combine two or more aggregation objects into a single Aggregation, adding up the totals and merging keys.
+ *
+ * @param {Aggregation} aggregations
+ * @returns {Aggregation}
+ */
+export const mergeAggregations = ( ...aggregations ) =>
+  aggregations.reduce( ( final, item ) => deepMergeWithResolver( final, item, ( a, b ) => Decimal( a ?? 0 ).add( b ?? 0 ).toNumber() ), {} );

package/src/{interface → internal_utils}/aggregations.spec.js

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { Attribute } from '#trace_attribute';
-import { aggregateAttributes } from './aggregations.js';
+import { aggregateAttributes, mergeAggregations } from './aggregations.js';
 
 describe( 'aggregateAttributes', () => {
   it( 'returns zeroed aggregations when there are no attributes', () => {
@@ -89,3 +89,51 @@ describe( 'aggregateAttributes', () => {
     } );
   } );
 } );
+
+describe( 'mergeAggregations', () => {
+  it( 'returns an empty object when no aggregations are provided', () => {
+    expect( mergeAggregations() ).toEqual( {} );
+  } );
+
+  it( 'sums nested aggregation values', () => {
+    expect( mergeAggregations(
+      {
+        cost: { total: 1.2 },
+        tokens: { total: 10, input: 6 },
+        httpRequests: { total: 2 }
+      },
+      {
+        cost: { total: 0.3 },
+        tokens: { total: 5, input: 2, output: 3 },
+        httpRequests: { total: 1 }
+      }
+    ) ).toEqual( {
+      cost: { total: 1.5 },
+      tokens: { total: 15, input: 8, output: 3 },
+      httpRequests: { total: 3 }
+    } );
+  } );
+
+  it( 'handles undefined or partial aggregation objects', () => {
+    expect( mergeAggregations(
+      undefined,
+      { cost: { total: 2 } },
+      { tokens: { total: 4, reasoning: 1 } },
+      { httpRequests: { total: 3 } }
+    ) ).toEqual( {
+      cost: { total: 2 },
+      tokens: { total: 4, reasoning: 1 },
+      httpRequests: { total: 3 }
+    } );
+  } );
+
+  it( 'does not mutate source aggregation objects', () => {
+    const first = { cost: { total: 1 }, tokens: { total: 2 }, httpRequests: { total: 3 } };
+    const second = { cost: { total: 4 }, tokens: { total: 5 }, httpRequests: { total: 6 } };
+
+    mergeAggregations( first, second );
+
+    expect( first ).toEqual( { cost: { total: 1 }, tokens: { total: 2 }, httpRequests: { total: 3 } } );
+    expect( second ).toEqual( { cost: { total: 4 }, tokens: { total: 5 }, httpRequests: { total: 6 } } );
+  } );
+} );

package/src/internal_utils/errors.js

@@ -0,0 +1,10 @@
+/**
+ * Extract a property from the error .details.
+ * If error does not have details, navigate up the .cause chain.
+ *
+ * @param {Error} e
+ * @param {string} key
+ * @returns {any} The value of the property
+ */
+export const extractErrorDetail = ( e, key ) =>
+  e ? ( e.details?.find?.( d => d[key] )?.[key] ?? extractErrorDetail( e.cause, key ) ) : null;

package/src/tracing/trace_attribute.js

@@ -4,19 +4,12 @@ import Decimal from 'decimal.js';
  * All attributes inherit from this
  */
 export class BaseAttribute {
-  activityId;
-  activityName;
   date = Date.now();
   type;
 
   constructor( type ) {
     this.type = type;
   }
-
-  setActivity( id, name ) {
-    this.activityId = id;
-    this.activityName = name;
-  }
 }
 
 class HTTPRequestCount extends BaseAttribute {

package/src/tracing/trace_engine.js

@@ -93,13 +93,13 @@ export const addEventAction = ( action, { kind, name, id, parentId, details, exe
 export function addEventActionWithContext( action, options ) {
   const storeContent = Storage.load();
   if ( storeContent ) { // If there is no storageContext this was not called from a Temporal environment
-    const { parentId, executionContext, sendAttributeSignal } = storeContent;
+    const { parentId, executionContext, addAttribute } = storeContent;
     if ( action === EventAction.ADD_ATTR ) {
       const attribute = options.details;
       if ( !( attribute instanceof BaseAttribute ) ) {
         throw new Error( `Event ${EventAction.ADD_ATTR} argument is not a BaseAttribute instance` );
       } else {
-        sendAttributeSignal( options.details );
+        addAttribute( options.details );
       }
     }
     addEventAction( action, { ...options, parentId, executionContext } );

package/src/tracing/trace_engine.spec.js

@@ -123,14 +123,14 @@ describe( 'tracing/trace_engine', () => {
     expect( payload.entry.action ).toBe( 'tick' );
   } );
 
-  it( 'addEventActionWithContext() sends ADD_ATTR attributes through storage context', async () => {
+  it( 'addEventActionWithContext() records ADD_ATTR attributes through storage context', async () => {
     process.env.OUTPUT_TRACE_LOCAL_ON = 'true';
-    const sendAttributeSignalMock = vi.fn();
+    const addAttributeMock = vi.fn();
     const executionContext = { runId: 'r1', disableTrace: false };
     storageLoadMock.mockReturnValue( {
       parentId: 'ctx-p',
       executionContext,
-      sendAttributeSignal: sendAttributeSignalMock
+      addAttribute: addAttributeMock
     } );
     const { init, addEventActionWithContext } = await loadTraceEngine();
     const { EventAction } = await import( './trace_consts.js' );
@@ -140,8 +140,8 @@ describe( 'tracing/trace_engine', () => {
     const attribute = new Attribute.HTTPRequestCount( 'https://example.test', 'req-1' );
     addEventActionWithContext( EventAction.ADD_ATTR, { kind: 'http', name: 'request', id: 'req-1', details: attribute } );
 
-    expect( sendAttributeSignalMock ).toHaveBeenCalledTimes( 1 );
-    expect( sendAttributeSignalMock ).toHaveBeenCalledWith( attribute );
+    expect( addAttributeMock ).toHaveBeenCalledTimes( 1 );
+    expect( addAttributeMock ).toHaveBeenCalledWith( attribute );
     expect( localExecMock ).toHaveBeenCalledTimes( 1 );
     expect( localExecMock.mock.calls[0][0] ).toEqual( {
       executionContext,
@@ -159,11 +159,11 @@ describe( 'tracing/trace_engine', () => {
 
   it( 'addEventActionWithContext() throws on invalid ADD_ATTR signal payloads', async () => {
     process.env.OUTPUT_TRACE_LOCAL_ON = 'true';
-    const sendAttributeSignalMock = vi.fn();
+    const addAttributeMock = vi.fn();
     storageLoadMock.mockReturnValue( {
       parentId: 'ctx-p',
       executionContext: { runId: 'r1', disableTrace: false },
-      sendAttributeSignal: sendAttributeSignalMock
+      addAttribute: addAttributeMock
     } );
     const { init, addEventActionWithContext } = await loadTraceEngine();
     const { EventAction } = await import( './trace_consts.js' );
@@ -175,7 +175,7 @@ describe( 'tracing/trace_engine', () => {
       { kind: 'http', name: 'request', id: 'req-1', details: invalidAttribute }
     ) ).toThrow( /not a BaseAttribute instance/ );
 
-    expect( sendAttributeSignalMock ).not.toHaveBeenCalled();
+    expect( addAttributeMock ).not.toHaveBeenCalled();
     expect( localExecMock ).not.toHaveBeenCalled();
   } );
 

package/src/utils/index.d.ts

@@ -122,7 +122,21 @@ export function shuffleArray( arr: unknown[] ): unknown[];
  * @throws {Error} If either `a` or `b` is not a plain object.
  * @returns A new merged object.
  */
-export function deepMerge( a: object, b: object ): object;
+export function deepMerge( a: object, b: object | null | undefined ): object;
+
+/**
+ * Creates a new object by merging object `b` onto object `a`, biased toward `b`:
+ * - Fields in `b` that don't exist in `a` are created.
+ * - Fields in `a` that don't exist in `b` are left unchanged.
+ * - Fields in `a` and `b` are passed as arguments to the resolve function (a,b) and its return assigns the new value.
+ *
+ * @param a - The base object.
+ * @param b - The overriding object.
+ * @param resolver - The resolver function.
+ * @throws {Error} If either `a` or `b` is not a plain object.
+ * @returns A new merged object.
+ */
+export function deepMergeWithResolver( a: object, b: object | null | undefined, resolver: function ): object;
 
 /**
  * Shortens a UUID to a url-safe base64-like string (custom 64-char alphabet).

package/src/utils/utils.js

@@ -5,7 +5,13 @@ import { METADATA_ACCESS_SYMBOL } from '#consts';
  * @param {object} v
  * @returns {object}
  */
-export const clone = v => JSON.parse( JSON.stringify( v ) );
+export const clone = v => {
+  try {
+    return JSON.parse( JSON.stringify( v ) );
+  } catch {
+    return v;
+  }
+};
 
 /**
  * Detect a JS plain object.
@@ -170,18 +176,19 @@ export const shuffleArray = arr => arr
   .map( ( { v } ) => v );
 
 /**
- * Creates a new object merging object "b" onto object "a" biased to "b":
- * - Object "b" will overwrite fields on object "a";
- * - Object "b" fields that don't exist on object "a" will be created;
- * - Object "a" fields that don't exist on object "b" will not be touched;
+ * Creates a new object merging object "b" onto object "a", using a resolver function to define the value to keep.
+ * - Object "b" fields that also exists on "a" will have their value defined by the "resolver" function
+ * - Object "b" fields that don't exist on object "a" will be added;
+ * - Object "a" fields that don't exist on object "b" will be preserved;
  *
  * If "b" isn't an object, a new object equal to "a" is returned
  *
  * @param {object} a - The base object
  * @param {object} b - The target object
+ * @param {function} resolver - A function that return the value to be kept. First argument is value a, second is value b
  * @returns {object} A new object
  */
-export const deepMerge = ( a, b ) => {
+export const deepMergeWithResolver = ( a, b, resolver ) => {
   if ( !isPlainObject( a ) ) {
     throw new Error( 'Parameter "a" is not an object.' );
   }
@@ -189,10 +196,34 @@ export const deepMerge = ( a, b ) => {
     return clone( a );
   }
   return Object.entries( b ).reduce( ( obj, [ k, v ] ) =>
-    Object.assign( obj, { [k]: isPlainObject( v ) && isPlainObject( a[k] ) ? deepMerge( a[k], v ) : v } )
+    Object.assign( obj, {
+      [k]: ( () => {
+        if ( isPlainObject( v ) && isPlainObject( a[k] ) ) {
+          return deepMergeWithResolver( a[k], v, resolver );
+        }
+        if ( Object.hasOwn( a, k ) ) {
+          return resolver( a[k], v );
+        }
+        return v;
+      } )()
+    } )
   , clone( a ) );
 };
 
+/**
+ * Creates a new object merging object "b" onto object "a" biased to "b":
+ * - Object "b" will overwrite fields on object "a";
+ * - Object "b" fields that don't exist on object "a" will be added;
+ * - Object "a" fields that don't exist on object "b" will be preserved;
+ *
+ * If "b" isn't an object, a new object equal to "a" is returned
+ *
+ * @param {object} a - The base object
+ * @param {object} b - The target object
+ * @returns {object} A new object
+ */
+export const deepMerge = ( a, b ) => deepMergeWithResolver( a, b, ( _, b ) => b );
+
 /**
  * Shortens a UUID by re-encoding it to base62.
  *