feat(utils): Introduce envelope helper functions

This patch introduces functions that create, mutate and serialize
envelopes. It also adds some basic unit tests that sanity check their
functionality. It builds on top of the work done in
#4527.

Users are expected to not directly interact with the Envelope instance,
but instead use the helper functions to work with them. Essentially, we
can treat the envelope instance as an opaque handle, similar to how void
pointers are used in low-level languages. This was done to minimize the
bundle impact of working with the envelopes, and as the set of possible
envelope operations was fixed (and on the smaller end).

To directly create an envelope, the `createEnvelope()` function was
introduced. Users are encouraged to explicitly provide the generic type
arg to this function so that add headers/items are typed accordingly.

To add headers and items to envelopes, the `addHeaderToEnvelope()` and
`addItemToEnvelope()` functions are exposed respectively. The reason
that these functions are purely additive (or in the case of headers, can
re-write existing ones), instead of allow for headers/items to be
removed, is that removal functionality doesn't seem like it'll be used
at all. In the interest of keeping the API surface small, we settled
with these two functions, but we can come back and adjust this later on.

Finally, there is `serializeEnvelope()`, which is used to serialize an
envelope to a string. It does have some TypeScript complications, which
is explained in detail in a code comment, but otherwise is a pretty
simple implementation. You can notice the power of the tuple based
envelope implementation, where it becomes easy to access headers/items.

```js
const [headers, items] = envelope;
```

To illustrate how these functions will be used, another patch will be
added that adds a `createClientReportEnvelope()` util, and the base
transport in `@sentry/browser` will be updated to use that util.

Author: AbhiPrasad

packages/types/src/envelope.ts

@@ -25,15 +25,14 @@ type BaseEnvelopeItem<ItemHeader extends { type: string }, Payload = unknown> =
   Payload,
 ];
 
-type UnknownEnvelopeItem = BaseEnvelopeItem<{ type: '__unknown__' }>;
-
-type BaseEnvelope<
+/**
+ * 1st Item: Envelope headers
+ * 2nd Item: Envelope items {@see BaseEnvelopeItem}
+ */
+export type BaseEnvelope<
   EnvelopeHeaders extends Record<string, unknown>,
   EnvelopeItem extends BaseEnvelopeItem<{ type: string }>,
-> = {
-  headers: CommonEnvelopeHeaders & EnvelopeHeaders;
-  items: Array<EnvelopeItem | UnknownEnvelopeItem>;
-};
+> = [CommonEnvelopeHeaders & EnvelopeHeaders & Record<string, unknown>, EnvelopeItem[]];
 
 export type EventEnvelopeItem = BaseEnvelopeItem<{ type: 'event' | 'transaction' }, Event>;
 

packages/utils/src/envelope.ts

@@ -0,0 +1,48 @@
+import { Envelope } from '@sentry/types';
+
+/**
+ * Creates an envelope.
+ * Make sure to always explicitly provide the generic to this function
+ * so that the envelope types resolve correctly.
+ */
+export function createEnvelope<E extends Envelope>(headers: E[0], items: E[1]): E {
+  return [headers, items] as E;
+}
+
+/**
+ * Add a set of key value pairs to the envelope header.
+ * Make sure to always explicitly provide the generic to this function
+ * so that the envelope types resolve correctly.
+ */
+export function addHeaderToEnvelope<E extends Envelope>(envelope: E, newHeaders: E[0]): E {
+  const [headers, items] = envelope;
+  return [{ ...headers, ...newHeaders }, items] as E;
+}
+
+/**
+ * Add an item to an envelope.
+ * Make sure to always explicitly provide the generic to this function
+ * so that the envelope types resolve correctly.
+ */
+export function addItemToEnvelope<E extends Envelope>(envelope: E, newItem: E[1][number]): E {
+  const [headers, items] = envelope;
+  return [headers, [...items, newItem]] as E;
+}
+
+/**
+ * Serializes an envelope into a string.
+ */
+export function serializeEnvelope(envelope: Envelope): string {
+  const [headers, items] = envelope;
+  const serializedHeaders = JSON.stringify(headers);
+
+  // Have to cast items to any here since Envelope is a union type
+  // Fixed in Typescript 4.2
+  // TODO: Remove any[] cast when we upgrade to TS 4.2
+  // https://github.com/microsoft/TypeScript/issues/36390
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (items as any[]).reduce((acc, item: typeof items[number]) => {
+    const [itemHeaders, payload] = item;
+    return `${acc}\n${JSON.stringify(itemHeaders)}\n${JSON.stringify(payload)}`;
+  }, serializedHeaders);
+}

packages/utils/src/index.ts

@@ -21,3 +21,4 @@ export * from './supports';
 export * from './syncpromise';
 export * from './time';
 export * from './env';
+export * from './envelope';

packages/utils/test/envelope.test.ts

@@ -0,0 +1,42 @@
+import { createEnvelope, addHeaderToEnvelope, addItemToEnvelope, serializeEnvelope } from '../src/envelope';
+import { EventEnvelope } from '@sentry/types';
+
+describe('envelope', () => {
+  describe('createEnvelope()', () => {
+    const testTable: Array<[string, Parameters<typeof createEnvelope>[0], Parameters<typeof createEnvelope>[1]]> = [
+      ['creates an empty envelope', {}, []],
+      ['creates an envelope with a header but no items', { dsn: 'https://[email protected]/1', sdk: {} }, []],
+    ];
+    it.each(testTable)('%s', (_: string, headers, items) => {
+      const env = createEnvelope(headers, items);
+      expect(env).toHaveLength(2);
+      expect(env[0]).toStrictEqual(headers);
+      expect(env[1]).toStrictEqual(items);
+    });
+  });
+
+  describe('addHeaderToEnvelope()', () => {
+    it('adds a header to the envelope', () => {
+      const env = createEnvelope({}, []);
+      expect(serializeEnvelope(env)).toMatchInlineSnapshot(`"{}"`);
+      const newEnv = addHeaderToEnvelope(env, { dsn: 'https://[email protected]/' });
+      expect(serializeEnvelope(newEnv)).toMatchInlineSnapshot(`"{\\"dsn\\":\\"https://[email protected]/\\"}"`);
+    });
+  });
+
+  describe('addItemToEnvelope()', () => {
+    const env = createEnvelope<EventEnvelope>({ event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2', sent_at: '123' }, []);
+    expect(serializeEnvelope(env)).toMatchInlineSnapshot(
+      `"{\\"event_id\\":\\"aa3ff046696b4bc6b609ce6d28fde9e2\\",\\"sent_at\\":\\"123\\"}"`,
+    );
+    const newEnv = addItemToEnvelope<EventEnvelope>(env, [
+      { type: 'event' },
+      { event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2' },
+    ]);
+    expect(serializeEnvelope(newEnv)).toMatchInlineSnapshot(`
+      "{\\"event_id\\":\\"aa3ff046696b4bc6b609ce6d28fde9e2\\",\\"sent_at\\":\\"123\\"}
+      {\\"type\\":\\"event\\"}
+      {\\"event_id\\":\\"aa3ff046696b4bc6b609ce6d28fde9e2\\"}"
+    `);
+  });
+});