matrix-js-sdk

Follow these rules for managing types and variables:

• Variable Declaration: One variable declaration per line. If a variable is not receiving a value on declaration, its type must be explicitly defined:

  let errorMessage: string;

• Booleans: Ensure variables intended to be boolean are explicitly cast to boolean (e.g., using !! or Boolean()) to avoid storing truthy/falsy values of other types.
• Constants and Mutability: Use const for constants and let for mutable variables.
• Type Exhaustiveness: Describe types exhaustively (ensure noImplicitAny would pass). Avoid any; if any is used, a comment explaining why must be included.
• Visibility: Always declare member visibility (public, private, or protected).
• Private Members: Private members should not be prefixed with an underscore unless required to resolve a naming conflict (e.g., a getter wanting the same name as an underlying variable).
• Readonly: Prefer readonly members over getters backed by a variable, unless an internal setter is required. public static members should also be readonly when possible.
• Interfaces vs Types:
  • Use Interfaces for object definitions.
  • Use Types for parameter-value-only declarations.
  • Prefer a type definition (like an interface) over an inline type.
• Optionality: Prefer a type like X | null instead of truly optional parameters (?). For example, when a room ID is required but might not be known yet, use room: string | null to force the caller to acknowledge the null state.
• Imports: Use import instead of require.

let errorMessage: string;

const isRealUser = !!userId && ...; // good
const isRealUser = userId && ...;   // bad: isRealUser is userId's type, not a boolean

interface MyObject {
    hasString: boolean;
}

type Options = MyObject | string;

function doThing(arg: Options) {
    // ...
}

function doThingWithRoom(
    thing: string,
    room: string | null, // require the caller to specify
) {
    // ...
}

If your application used the legacy MatrixClient.initLegacyCrypto() stack, you must migrate existing devices to the Rust stack.

Migration Steps:

1. When calling sdk.createClient, provide the legacy cryptoStore and pickleKey in the options object.
2. Call await matrixClient.initRustCrypto(). The migration will trigger automatically.

Monitoring Progress: You can listen to the CryptoEvent.LegacyCryptoStoreMigrationProgress event. The migration is complete when both progress and total equal -1.

Note: The legacy MatrixClient.crypto object is deprecated. You should now use MatrixClient.getCrypto() and migrate any calls to deprecated MatrixClient methods to the CryptoApi interface.

// You should provide the legacy crypto store and the pickle key to the matrix client in order to migrate the data.
const matrixClient = sdk.createClient({
    cryptoStore: myCryptoStore,
    pickleKey: myPickleKey,
    baseUrl: "http://localhost:8008",
    accessToken: myAccessToken,
    userId: myUserId,
});

// The migration will be done automatically when you call `initRustCrypto`.
await matrixClient.initRustCrypto();

// To follow the migration progress, listen to the LegacyCryptoStoreMigrationProgress event:
matrixClient.on(CryptoEvent.LegacyCryptoStoreMigrationProgress, (progress, total) => {
    // When progress === total === -1, the migration is finished.
});

To maintain consistency, organize files and imports as follows:

File Structure

• One Entity Per File: There should be approximately one interface, class, or enum per file.
• Exceptions: Files named types.ts, global.d.ts, or ending in -types.ts can contain multiple definitions.
• Naming: The file name should match the interface, class, or enum name.
• Bulk Functions: Utility functions can be grouped in files named foo-utils.ts or utils/foo.ts.

Import Ordering

1. External module imports first.
2. Internal imports second.

File Content Sequence

1. License header
2. Imports
3. Constants
4. Enums
5. Interfaces
6. Functions
7. Classes (ordered by: static properties $\rightarrow$ properties $\rightarrow$ constructors $\rightarrow$ getters/setters $\rightarrow$ protected/abstract functions $\rightarrow$ public/private functions $\rightarrow$ static functions)

Tests must be written in TypeScript and follow this structure:

1. Mocks: Declare mocks below imports, but above everything else.
2. Template: Use the describe/it pattern. Use "it should..." terminology for test descriptions.
3. Structure:
   • Use beforeEach and afterEach for setup/teardown.
   • Place test-specific variables and function calls/expectations inside the it block.

For utility classes, nest describe blocks for each function being tested.

// Describe the class, component, or file name.
describe("FooComponent", () => {
    // all test inspecific variables go here

    beforeEach(() => {
        // exclude if not used.
    });

    afterEach(() => {
        // exclude if not used.
    });

    // Use "it should..." terminology
    it("should call the correct API", async () => {
        // test-specific variables go here
        // function calls/state changes go here
        // expectations go here
    });
});

// If the file being tested is a utility class:
describe("foo-utils", () => {
    describe("firstUtilFunction", () => {
        it("should...", async () => {
            // ...
        });
    });
});