feat: add stackTraceOverride option to MetadataOptions

src/construct.ts

@@ -305,12 +305,19 @@ export class Node {
       return;
     }
 
-    const shouldTrace = options.stackTrace ?? false;
-    const trace = shouldTrace ? captureStackTrace(options.traceFromFunction ?? this.addMetadata) : undefined;
+    const node = this;
+    function getTrace() {
+      if (options.stackTraceOverride && options.stackTraceOverride.length > 0) {
+        return options.stackTraceOverride;
+      }
+      const shouldTrace = options.stackTrace ?? false;
+      return shouldTrace ? captureStackTrace(options.traceFromFunction ?? node.addMetadata) : undefined;
+    }
+
     if (!this._metadata) {
       this._metadata = [];
     }
-    this._metadata.push({ type, data, trace });
+    this._metadata.push({ type, data, trace: getTrace() });
   }
 
   /**
@@ -621,6 +628,12 @@ export interface MetadataOptions {
    * @default addMetadata()
    */
   readonly traceFromFunction?: any;
+
+  /**
+   * The actual stack trace to be added to the metadata. If this
+   * parameter is passed, the stackTrace parameter is ignored.
+   */
+  readonly stackTraceOverride?: string[];
 }
 
 // Mark all instances of 'Construct'

test/construct.test.ts

@@ -297,6 +297,22 @@ test('addMetadata() respects the "stackTrace" option', () => {
   expect(con.node.metadata[1]?.trace).toBeUndefined();
 });
 
+test('addMetadata() respects the "stackTraceOverride" option', () => {
+  const root = new Root();
+  const con = new Construct(root, 'Foo');
+  const customTrace = ['custom/path/file.ts:10', 'custom/path/other.ts:20'];
+
+  con.node.addMetadata('foo', 'bar1', { stackTraceOverride: customTrace });
+  con.node.addMetadata('foo', 'bar2', { stackTrace: true, stackTraceOverride: customTrace });
+  con.node.addMetadata('foo', 'bar3', { stackTraceOverride: [] });
+  con.node.addMetadata('foo', 'bar4', { stackTrace: true });
+
+  expect(con.node.metadata[0].trace).toEqual(customTrace);
+  expect(con.node.metadata[1].trace).toEqual(customTrace);
+  expect(con.node.metadata[2].trace).toBeUndefined();
+  expect(con.node.metadata[3].trace?.length).toBeGreaterThan(0);
+});
+
 test('addMetadata(type, undefined/null) is ignored', () => {
   const root = new Root();
   const con = new Construct(root, 'Foo');