feat(src): A CloudEvent should be readonly but provide a way to augment itself. (cloudevents#234)

BREAKING CHANGE:

* This change makes the CloudEvent Read-only and validates the input during object creation.

* To augment an already created CloudEvent object, we have added a `cloneWith` method that takes attributes to add/update.

Signed-off-by: Lucas Holmquist <[email protected]>

Author: lholmquist

src/event/cloudevent.ts

@@ -1,7 +1,7 @@
 import { v4 as uuidv4 } from "uuid";
 
-import { CloudEventV1, validateV1, CloudEventV1Attributes } from "./v1";
-import { CloudEventV03, validateV03, CloudEventV03Attributes } from "./v03";
+import { CloudEventV1, validateV1, CloudEventV1Attributes, CloudEventV1OptionalAttributes } from "./v1";
+import { CloudEventV03, validateV03, CloudEventV03Attributes, CloudEventV03OptionalAttributes } from "./v03";
 import { ValidationError, isBinary, asBase64 } from "./validation";
 import CONSTANTS from "../constants";
 import { isString } from "util";
@@ -98,6 +98,10 @@ export class CloudEvent implements CloudEventV1, CloudEventV03 {
     for (const [key, value] of Object.entries(properties)) {
       this[key] = value;
     }
+
+    this.validate();
+
+    Object.freeze(this);
   }
 
   get time(): string | Date {
@@ -165,4 +169,22 @@ export class CloudEvent implements CloudEventV1, CloudEventV03 {
       }
     }
   }
+
+  /**
+   * Clone a CloudEvent with new/update attributes
+   * @param {object} options attributes to augment the CloudEvent with
+   * @throws if the CloudEvent does not conform to the schema
+   * @return {CloudEvent} returns a new CloudEvent
+   */
+  public cloneWith(
+    options:
+      | CloudEventV1
+      | CloudEventV1Attributes
+      | CloudEventV1OptionalAttributes
+      | CloudEventV03
+      | CloudEventV03Attributes
+      | CloudEventV03OptionalAttributes,
+  ): CloudEvent {
+    return new CloudEvent(Object.assign({}, this.toJSON(), options) as CloudEvent);
+  }
 }

src/event/v03/cloudevent.ts

@@ -25,7 +25,7 @@ export interface CloudEventV03 extends CloudEventV03Attributes {
   specversion: string;
 }
 
-export interface CloudEventV03Attributes {
+export interface CloudEventV03Attributes extends CloudEventV03OptionalAttributes {
   /**
    * [REQUIRED] Identifies the context in which an event happened. Often this
    * will include information such as the type of the event source, the
@@ -57,7 +57,9 @@ export interface CloudEventV03Attributes {
    * @example com.example.object.delete.v2
    */
   type: string;
+}
 
+export interface CloudEventV03OptionalAttributes {
   /**
    * The following fields are optional.
    */

src/event/v1/cloudevent.ts

@@ -25,7 +25,7 @@ export interface CloudEventV1 extends CloudEventV1Attributes {
   specversion: string;
 }
 
-export interface CloudEventV1Attributes {
+export interface CloudEventV1Attributes extends CloudEventV1OptionalAttributes {
   /**
    * [REQUIRED] Identifies the context in which an event happened. Often this
    * will include information such as the type of the event source, the
@@ -58,7 +58,9 @@ export interface CloudEventV1Attributes {
    * @example com.example.object.delete.v2
    */
   type: string;
+}
 
+export interface CloudEventV1OptionalAttributes {
   /**
    * The following fields are optional.
    */

test/integration/cloud_event_test.ts

@@ -139,7 +139,7 @@ describe("A 0.3 CloudEvent", () => {
   });
 
   it("can be constructed with a datacontentencoding", () => {
-    const ce = new CloudEvent({ datacontentencoding: "Base64", ...v03fixture });
+    const ce = new CloudEvent({ datacontentencoding: "Base64", ...v03fixture, data: "SSB3YXMgZnVubnkg8J+Ygg==" });
     expect(ce.datacontentencoding).to.equal("Base64");
   });
 

test/integration/http_binding_03.ts

@@ -38,9 +38,9 @@ const cloudevent = new CloudEvent({
   dataschema: "",
   datacontentencoding: "",
   data_base64: "",
+  [ext1Name]: ext1Value,
+  [ext2Name]: ext2Value,
 });
-cloudevent[ext1Name] = ext1Value;
-cloudevent[ext2Name] = ext2Value;
 
 const cebase64 = new CloudEvent({
   specversion: Version.V03,
@@ -51,9 +51,9 @@ const cebase64 = new CloudEvent({
   time,
   schemaurl,
   data: dataBase64,
+  [ext1Name]: ext1Value,
+  [ext2Name]: ext2Value,
 });
-cebase64[ext1Name] = ext1Value;
-cebase64[ext2Name] = ext2Value;
 
 const webhook = "https://cloudevents.io/webhook";
 const httpcfg = {

test/integration/http_binding_1.ts

@@ -25,7 +25,7 @@ const ext1Value = "foobar";
 const ext2Name = "extension2";
 const ext2Value = "acme";
 
-const cloudevent = new CloudEvent({
+let cloudevent = new CloudEvent({
   specversion: Version.V1,
   type,
   source,
@@ -35,8 +35,7 @@ const cloudevent = new CloudEvent({
   dataschema,
   data,
 });
-cloudevent[ext1Name] = ext1Value;
-cloudevent[ext2Name] = ext2Value;
+cloudevent = cloudevent.cloneWith({ [ext1Name]: ext1Value, [ext2Name]: ext2Value });
 
 const dataString = ")(*~^my data for ce#@#$%";
 
@@ -81,9 +80,9 @@ describe("HTTP Transport Binding - Version 1.0", () => {
             source,
             datacontenttype: "text/plain",
             data: bindata,
+            [ext1Name]: ext1Value,
+            [ext2Name]: ext2Value,
           });
-          binevent[ext1Name] = ext1Value;
-          binevent[ext2Name] = ext2Value;
 
           return emitStructured(binevent, httpcfg).then((response: AxiosResponse) => {
             expect(JSON.parse(response.config.data).data_base64).to.equal(expected);
@@ -96,9 +95,9 @@ describe("HTTP Transport Binding - Version 1.0", () => {
             source,
             datacontenttype: "text/plain",
             data: Uint32Array.from(dataString as string, (c) => c.codePointAt(0) as number),
+            [ext1Name]: ext1Value,
+            [ext2Name]: ext2Value,
           });
-          binevent[ext1Name] = ext1Value;
-          binevent[ext2Name] = ext2Value;
 
           return emitStructured(binevent, httpcfg).then((response: AxiosResponse) => {
             expect(JSON.parse(response.config.data)).to.have.property("data_base64");

test/integration/spec_03_tests.ts

@@ -13,7 +13,7 @@ const data = {
 };
 const subject = "subject-x0";
 
-const cloudevent = new CloudEvent({
+let cloudevent = new CloudEvent({
   specversion: Version.V03,
   id,
   source,
@@ -46,8 +46,13 @@ describe("CloudEvents Spec v0.3", () => {
 
   describe("OPTIONAL Attributes", () => {
     it("Should have 'datacontentencoding'", () => {
-      cloudevent.datacontentencoding = Constants.ENCODING_BASE64;
+      cloudevent = cloudevent.cloneWith({
+        datacontentencoding: Constants.ENCODING_BASE64,
+        data: "SSB3YXMgZnVubnkg8J+Ygg==",
+      });
       expect(cloudevent.datacontentencoding).to.equal(Constants.ENCODING_BASE64);
+
+      cloudevent = cloudevent.cloneWith({ datacontentencoding: undefined, data: data });
     });
 
     it("Should have 'datacontenttype'", () => {
@@ -71,116 +76,117 @@ describe("CloudEvents Spec v0.3", () => {
     });
 
     it("Should have the 'extension1'", () => {
-      cloudevent.extension1 = "value1";
+      cloudevent = cloudevent.cloneWith({ extension1: "value1" });
       expect(cloudevent.extension1).to.equal("value1");
     });
   });
 
   describe("The Constraints check", () => {
     describe("'id'", () => {
-      it("should throw an error when is absent", () => {
-        delete cloudevent.id;
-        expect(cloudevent.validate.bind(cloudevent)).to.throw(ValidationError, "invalid payload");
-        cloudevent.id = id;
+      it("should throw an error when trying to remove", () => {
+        expect(() => {
+          delete cloudevent.id;
+        }).to.throw(TypeError);
       });
 
-      it("should throw an error when is empty", () => {
-        cloudevent.id = "";
-        expect(cloudevent.validate.bind(cloudevent)).to.throw(ValidationError, "invalid payload");
-        cloudevent.id = id;
+      it("defaut ID create when an empty string", () => {
+        cloudevent = cloudevent.cloneWith({ id: "" });
+        expect(cloudevent.id.length).to.be.greaterThan(0);
       });
     });
 
     describe("'source'", () => {
-      it("should throw an error when is absent", () => {
-        delete cloudevent.source;
-        expect(cloudevent.validate.bind(cloudevent)).to.throw(ValidationError, "invalid payload");
-        cloudevent.source = source;
+      it("should throw an error when trying to remove", () => {
+        expect(() => {
+          delete cloudevent.source;
+        }).to.throw(TypeError);
       });
     });
 
     describe("'specversion'", () => {
-      it("should throw an error when is absent", () => {
-        delete cloudevent.specversion;
-        expect(cloudevent.validate.bind(cloudevent)).to.throw(ValidationError, "invalid payload");
-        cloudevent.specversion = Version.V03;
+      it("should throw an error when trying to remove", () => {
+        expect(() => {
+          delete cloudevent.specversion;
+        }).to.throw(TypeError);
       });
     });
 
     describe("'type'", () => {
-      it("should throw an error when is absent", () => {
-        delete cloudevent.type;
-        expect(cloudevent.validate.bind(cloudevent)).to.throw(ValidationError, "invalid payload");
-        cloudevent.type = type;
+      it("should throw an error when trying to remove", () => {
+        expect(() => {
+          delete cloudevent.type;
+        }).to.throw(TypeError);
       });
 
       it("should throw an error when is an empty string", () => {
-        cloudevent.type = "";
-        expect(cloudevent.validate.bind(cloudevent)).to.throw(ValidationError, "invalid payload");
-        cloudevent.type = type;
+        expect(() => {
+          cloudevent.cloneWith({ type: "" });
+        }).to.throw(ValidationError, "invalid payload");
       });
 
       it("must be a non-empty string", () => {
-        cloudevent.type = type;
+        cloudevent.cloneWith({ type: type });
         expect(cloudevent.type).to.equal(type);
       });
     });
 
     describe("'datacontentencoding'", () => {
       it("should throw an error when is a unsupported encoding", () => {
-        cloudevent.data = "Y2xvdWRldmVudHMK";
-        cloudevent.datacontentencoding = Mode.BINARY;
-        expect(cloudevent.validate.bind(cloudevent)).to.throw(ValidationError, "invalid payload");
-        delete cloudevent.datacontentencoding;
-        cloudevent.data = data;
+        expect(() => {
+          cloudevent.cloneWith({ data: "Y2xvdWRldmVudHMK", datacontentencoding: Mode.BINARY });
+        }).to.throw(ValidationError, "invalid payload");
+
+        cloudevent.cloneWith({ data: data, datacontentencoding: undefined });
       });
 
       it("should throw an error when 'data' does not carry base64", () => {
-        cloudevent.data = "no base 64 value";
-        cloudevent.datacontentencoding = Constants.ENCODING_BASE64;
-        cloudevent.datacontenttype = "text/plain";
-
-        expect(cloudevent.validate.bind(cloudevent)).to.throw(ValidationError, "invalid payload");
-
-        delete cloudevent.datacontentencoding;
-        cloudevent.data = data;
+        expect(() => {
+          cloudevent.cloneWith({
+            data: "no base 64 value",
+            datacontentencoding: Constants.ENCODING_BASE64,
+            datacontenttype: "text/plain",
+          });
+        }).to.throw(ValidationError, "invalid payload");
+
+        cloudevent.cloneWith({
+          data: data,
+          datacontentencoding: undefined,
+        });
       });
 
       it("should accept when 'data' is a string", () => {
-        cloudevent.data = "Y2xvdWRldmVudHMK";
-        cloudevent.datacontentencoding = Constants.ENCODING_BASE64;
+        cloudevent.cloneWith({ data: "Y2xvdWRldmVudHMK", datacontentencoding: Constants.ENCODING_BASE64 });
         expect(cloudevent.validate()).to.be.true;
-        delete cloudevent.datacontentencoding;
-        cloudevent.data = data;
+        cloudevent.cloneWith({ data: data, datacontentencoding: undefined });
       });
     });
 
     describe("'data'", () => {
       it("should maintain the type of data when no data content type", () => {
-        delete cloudevent.datacontenttype;
+        cloudevent = cloudevent.cloneWith({ datacontenttype: undefined });
         cloudevent.data = JSON.stringify(data);
 
         expect(typeof cloudevent.data).to.equal("string");
-        cloudevent.datacontenttype = Constants.MIME_JSON;
       });
 
       it("should convert data with stringified json to a json object", () => {
-        cloudevent.datacontenttype = Constants.MIME_JSON;
+        cloudevent = cloudevent.cloneWith({ datacontenttype: Constants.MIME_JSON });
         cloudevent.data = JSON.stringify(data);
         expect(cloudevent.data).to.deep.equal(data);
       });
     });
 
     describe("'subject'", () => {
       it("should throw an error when is an empty string", () => {
-        cloudevent.subject = "";
-        expect(cloudevent.validate.bind(cloudevent)).to.throw(ValidationError, "invalid payload");
-        cloudevent.subject = subject;
+        expect(() => {
+          cloudevent.cloneWith({ subject: "" });
+        }).to.throw(ValidationError);
       });
     });
 
     describe("'time'", () => {
       it("must adhere to the format specified in RFC 3339", () => {
+        cloudevent = cloudevent.cloneWith({ time: time });
         expect(cloudevent.time).to.equal(time.toISOString());
       });
     });