Rewrite to support content blocks & improved parser

.ctiignore

@@ -0,0 +1,5 @@
+{
+    "src/events/EventParser.ts": ["addInternalKnownEventParser", "addInternalUnknownEventParser", "InternalOrderCategorization"],
+    "**/*.d.ts": "*",
+    "test/**": "*"
+}

.husky/pre-commit

@@ -1,4 +1,4 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-yarn format
+yarn idx && yarn format

README.md

@@ -14,56 +14,170 @@ architecture is up to the task of handling proper extensible events.
 ## Usage: Parsing events
 
 ```typescript
-const parsed = ExtensibleEvents.parse({
-    type: "m.room.message",
+const parser = new EventParser();
+const parsed = parser.parse({
+    type: "org.matrix.msc1767.message",
     content: {
-        "msgtype": "m.text",
-        "body": "Hello world!"
+        "org.matrix.msc1767.markup": [
+            { "body": "this is my message text" },
+        ],
     },
-    // and other fields
-}) as MessageEvent;
+    // and other required fields
+});
 
-// Using instanceof can be unsafe in some cases, but casting the
-// response in TypeScript (as above) should be safe given this
-// if statement will block non-message types anyhow.
-if (parsed?.isEquivalentTo(M_MESSAGE)) {
+if (parsed instanceof MessageEvent) {
     console.log(parsed.text);
 }
 ```
 
-*Note*: `instanceof` isn't considered safe for projects which might be running multiple copies
-of the library, such as in clients which have layers needing access to the events-sdk individually.
+It is recommended to cache your `EventParser` instance for performance reasons, and for ease of use
+when adding custom events.
 
-If you would like to register your own handling of events, use the following:
+Registering your own events is easy, and we recommend creating your own block objects for handling the
+contents of events:
 
 ```typescript
-type MyContent = M_MESSAGE_EVENT_CONTENT & {
-    field: string;
-};
+// There are a number of built-in block types for simple primitives
+// BooleanBlock, IntegerBlock, StringBlock
 
-class MyEvent extends MessageEvent {
-    public readonly field: string;
+// For object-based blocks, the following can be used:
+type MyObjectBlockWireType = {
+    my_property: string; // or whatever your block's properties are on the wire
+};
 
-    constructor(wireFormat: IPartialEvent<MyContent>) {
-        // Parse the text bit of the event
-        super(wireFormat);
+class MyObjectBlock extends ObjectBlock<MyObjectBlockWireType> {
+    public static readonly schema: Schema = {
+        // This is a JSON Schema
+        type: "object",
+        properties: {
+            my_property: {
+                type: "string",
+                nullable: false,
+            },
+        },
+        required: ["my_property"],
+        errorMessage: {
+            properties: {
+                my_property: "my_property should be a non-null string and is required",
+            },
+        },
+    };
+
+    public static readonly validateFn = AjvContainer.ajv.compile(MyObjectBlock.schema);
+
+    public static readonly type = new UnstableValue(null, "org.example.my_custom_block");
+
+    public constructor(raw: MyObjectBlockWireType) {
+        super(MyObjectBlock.type.name, raw);
+        if (!MyObjectBlock.validateFn(raw)) {
+            throw new InvalidBlockError(this.name, MyObjectBlock.validateFn.errors);
+        }
+    }
+}
 
-        this.field = wireFormat.content?.field;
+// For array-based blocks, we define the contents (items) slightly differently:
+type MyArrayItemWireType = {
+    my_property: string; // or whatever
+}; // your item type can also be a primitive, like integers, booleans, and strings.
+
+class MyArrayBlock extends ArrayBlock<MyArrayItemWireType> {
+    public static readonly schema = ArrayBlock.schema;
+    public static readonly validateFn = ArrayBlock.validateFn;
+
+    public static readonly itemSchema: Schema = {
+        // This is a JSON Schema
+        type: "object",
+        properties: {
+            my_property: {
+                type: "string",
+                nullable: false,
+            },
+        },
+        required: ["my_property"],
+        errorMessage: {
+            properties: {
+                my_property: "my_property should be a non-null string and is required",
+            },
+        },
+    };
+    public static readonly itemValidateFn = AjvContainer.ajv.compile(MyArrayBlock.itemSchema);
+
+    public static readonly type = new UnstableValue(null, "org.example.my_custom_block");
+
+    public constructor(raw: MyArrayItemWireType[]) {
+        super(MyArrayBlock.type.name, raw);
+        this.raw = raw.filter(x => {
+            const bool = MyArrayBlock.itemValidateFn(x);
+            if (!bool) {
+                // Do something with the error. It might be valid to throw, as we do here, or
+                // use `.filter()`'s ability to exclude items from the final array.
+                throw new InvalidBlockError(this.name, MyArrayBlock.itemValidateFn.errors);
+            }
+            return bool;
+        });
     }
 }
+```
 
-function parseMyEvent(wireEvent: IPartialEvent<MyContent>): Optional<MyEvent> {
-    // If you need to convert a legacy format, this is where you'd do it. Your
-    // event class should be able to be instatiated outside of this parse function.
-    return new MyEvent(wireEvent);
+Then, we can define a custom event:
+
+```typescript
+type MyWireContent = EitherAnd<
+    { [MyObjectBlock.type.name]: MyObjectBlockWireType },
+    { [MyObjectBlock.type.altName]: MyObjectBlockWireType }
+>;
+
+class MyCustomEvent extends RoomEvent<MyWireContent> {
+    public static readonly contentSchema: Schema = AjvContainer.eitherAnd(MyObjectBlock.type, MyObjectBlock.schema);
+    public static readonly contentValidateFn = AjvContainer.ajv.compile(MyCustomEvent.contentSchema);
+
+    public static readonly type = new UnstableValue(null, "org.example.my_custom_event");
+
+    public constructor(raw: WireEvent.RoomEvent<MyWireContent>) {
+        super(MyCustomEvent.type.name, raw, false); // see docs
+        if (!MyCustomEvent.contentValidateFn(this.content)) {
+            throw new InvalidEventError(this.name, MyCustomEvent.contentValidateFn.errors);
+        }
+    }
 }
+```
+
+and finally we can register it in a parser instance:
 
-ExtensibleEvents.registerInterpreter("org.example.my_event_type", parseMyEvent);
-ExtensibleEvents.unknownInterpretOrder.push("org.example.my_event_type");
+```typescript
+const parser = new EventParser();
+parser.addKnownType(MyCustomEvent.type, x => new MyCustomEvent(x));
 ```
 
+If you'd also like to register an "unknown event type" handler, that can be done like so:
+
+```typescript
+const myParser: UnknownEventParser<MyWireContent> = x => {
+    const possibleBlock = MyObjectBlock.type.findIn(x.content);
+    if (!!possibleBlock) {
+        const block = new MyObjectBlock(possibleBlock as MyObjectBlockWireType);
+        return new MyCustomEvent({
+            ...x,
+            type: MyCustomEvent.type.name, // required - override the event type
+            content: {
+                [MyObjectBlock.name]: block.raw,
+            }, // technically optional, but good practice: clean up the event's content for handling.
+        });
+    }
+    return undefined; // else, we don't care about it
+};
+parser.setUnknownParsers([myParser, ...parser.defaultUnknownEventParsers]);
+```
+
+Putting your parser at the start of the array will ensure it gets called first. Including the default parsers
+is also optional, though recommended.
+
 ## Usage: Making events
 
+<!-- ------------------------- -->
+***TODO: This needs refactoring***
+<!-- ------------------------- -->
+
 Most event objects have a `from` static function which takes common details of an event
 and returns an instance of that event for later serialization.
 

jest.config.js

@@ -1,15 +1,15 @@
 /** @type {import('ts-jest/dist/types').InitialOptionsTsJest} */
 module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  collectCoverage: true,
-  collectCoverageFrom: ["./src/**"],
-  coverageThreshold: {
-    global: {
-      lines: 100,
-      branches: 100,
-      functions: 100,
-      statements: -1,
+    preset: "ts-jest",
+    testEnvironment: "node",
+    collectCoverage: true,
+    collectCoverageFrom: ["./src/**"],
+    coverageThreshold: {
+        global: {
+            lines: 100,
+            branches: 100,
+            functions: 100,
+            statements: -1,
+        },
     },
-  },
 };

package.json

@@ -18,7 +18,8 @@
     "prepare": "husky install",
     "prepublishOnly": "yarn build",
     "clean": "rimraf lib",
-    "build": "yarn clean && tsc -p tsconfig.build.json",
+    "idx": "ctix single -p tsconfig.build.json --startAt src --output src/index.ts --overwrite --noBackup --useComment && yarn format",
+    "build": "yarn clean && yarn idx && tsc -p tsconfig.build.json",
     "start": "tsc -p tsconfig.build.json -w",
     "test": "jest",
     "format": "prettier --config .prettierrc \"{src,test}/**/*.ts\" --write",
@@ -27,11 +28,16 @@
   "devDependencies": {
     "@types/jest": "^29.2.3",
     "@types/node": "^16",
+    "ctix": "^1.7.0",
     "husky": "^8.0.2",
     "jest": "^29.3.1",
     "prettier": "^2.8.0",
     "rimraf": "^3.0.2",
     "ts-jest": "^29.0.3",
     "typescript": "^4.9.3"
+  },
+  "dependencies": {
+    "ajv": "^8.11.2",
+    "ajv-errors": "^3.0.0"
   }
 }

src/AjvContainer.ts

@@ -0,0 +1,97 @@
+/*
+Copyright 2022 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import Ajv, {Schema, SchemaObject} from "ajv";
+import AjvErrors from "ajv-errors";
+import {NamespacedValue} from "./NamespacedValue";
+
+/**
+ * Container for the ajv instance, the SDK's schema validator of choice.
+ */
+export class AjvContainer {
+    public static readonly ajv = new Ajv({
+        allErrors: true,
+    });
+
+    static {
+        AjvErrors(AjvContainer.ajv);
+    }
+
+    /* istanbul ignore next */
+    // noinspection JSUnusedLocalSymbols
+    private constructor() {}
+
+    /**
+     * Creates a JSON Schema representation of the EitherAnd<> TypeScript type.
+     * @param ns The namespace to use in the EitherAnd<> type.
+     * @param schema The schema to use as a value type for the namespace options.
+     * @returns The EitherAnd<> type as a JSON Schema.
+     */
+    public static eitherAnd<S extends string = string, U extends string = string>(
+        ns: NamespacedValue<S, U>,
+        schema: Schema,
+    ): {anyOf: SchemaObject[]; errorMessage: string} {
+        // Dev note: ajv currently doesn't have a useful type for this stuff, but ideally it'd be smart enough to
+        // have an "anyOf" type we can return.
+        // Also note that we don't use oneOf: we manually construct it through a Type A, or Type B, or Type A+B list.
+        if (!ns.altName) {
+            throw new Error("Cannot create an EitherAnd<> JSON schema type without both stable and unstable values");
+        }
+        return {
+            errorMessage: `schema does not apply to ${ns.stable} or ${ns.unstable}`,
+            anyOf: [
+                {
+                    type: "object",
+                    properties: {
+                        [ns.name]: schema,
+                    },
+                    required: [ns.name],
+                    errorMessage: {
+                        properties: {
+                            [ns.name]: `${ns.name} is required`,
+                        },
+                    },
+                },
+                {
+                    type: "object",
+                    properties: {
+                        [ns.altName]: schema,
+                    },
+                    required: [ns.altName],
+                    errorMessage: {
+                        properties: {
+                            [ns.altName]: `${ns.altName} is required`,
+                        },
+                    },
+                },
+                {
+                    type: "object",
+                    properties: {
+                        [ns.name]: schema,
+                        [ns.altName]: schema,
+                    },
+                    required: [ns.name, ns.altName],
+                    errorMessage: {
+                        properties: {
+                            [ns.name]: `${ns.name} is required`,
+                            [ns.altName]: `${ns.altName} is required`,
+                        },
+                    },
+                },
+            ],
+        };
+    }
+}