Nibbling Perfect Macaroni

    matrix-events-sdk
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.1 • Public • Published

    matrix-events-sdk

    JS/TS SDK for handling (extensible) events in Matrix

    🚨🚨 Project is a work in progress

    The architecture and approach of this repo is still being considered and is subject to breaking changes. Use at your own risk.

    As a general guide, functionality which is foundational to events (such as text, images, etc) should be incorporated in this repo before the more complex types. This is to ensure that the architecture is up to the task of handling proper extensible events.

    Usage: Parsing events

    const parsed = ExtensibleEvents.parse({
        type: "m.room.message",
        content: {
            "msgtype": "m.text",
            "body": "Hello world!"
        },
        // and other fields
    }) as MessageEvent;
    
    // 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)) {
        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.

    If you would like to register your own handling of events, use the following:

    type MyContent = M_MESSAGE_EVENT_CONTENT & {
        field: string;
    };
    
    class MyEvent extends MessageEvent {
        public readonly field: string;
    
        constructor(wireFormat: IPartialEvent<MyContent>) {
            // Parse the text bit of the event
            super(wireFormat);
    
            this.field = wireFormat.content?.field;
        }
    }
    
    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);
    }
    
    ExtensibleEvents.registerInterpreter("org.example.my_event_type", parseMyEvent);
    ExtensibleEvents.unknownInterpretOrder.push("org.example.my_event_type");

    Usage: Making events

    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.

    const userInput = "**hello**";
    const htmlInput = "<b>hello</b>"; // might be after running through a markdown processor
    
    const message = MessageEvent.from(userInput, htmlInput).serialize();
    
    // Finally, assuming your client instance is called `client`:
    client.sendEvent(message.type, message.content);

    Keywords

    none

    Install

    npm i matrix-events-sdk

    DownloadsWeekly Downloads

    7,062

    Version

    0.0.1

    License

    Apache-2.0

    Unpacked Size

    366 kB

    Total Files

    48

    Last publish

    Collaborators

    • matrixdotorg