Command Bus¶

One of the buses used in storefront to handle commands in the application in a clean and robust way. Commands usually represent actions or state changes. They encapsulate all the information needed to perform an action but do not return data themselves.

Each command can have only one listener at a time to ensure it is executed by a single listener, maintaining clear responsibility and predictable behavior.

Command Bus Methods¶

The Command Bus utilizes methods that allow to handle commands depending on your needs.

on - allows to listen to the event similarly to how addEventListener works for DOM events.
once - allows to listen to an event only until it fires once. Then the listener is being removed.
off - allows to remove a listener from the event similarly to how removeEventListener works for DOM events.
execute - allows to execute a command asynchronously.
executeSync - allows to execute a command synchronously.
getListeners - allows to get all listeners of given message.
getListenersCount - allows to get the count of all listeners of given message.

Example¶

To listen to any command emitted by the Command Bus you can use the on method:

useStorefront(async (storefront) => {
    storefront.commandBus.on('example-command', () => {
        console.log('Listening to the command...')
    });
});

Example¶

Remember that the command bus does not allow two listeners:

useStorefront(async (storefront) => {
    storefront.commandBus.on('example-command', () => {
        console.log('Listening to the command...')
    });

    storefront.commandBus.on('example-command', () => { // Error: Maximum number of listeners reached
        console.log('Listening to the command for the second time...')
    });
});

Listening with on and once at the same time is also not allowed:

useStorefront(async (storefront) => {
    storefront.commandBus.once('example-command', () => {
        console.log('Listening to the command...')
    });

    storefront.commandBus.on('example-command', () => { // Error: Maximum number of listeners reached
        console.log('Listening to the command with on...')
    });
});

Example¶

To remove a listener from any command of the Command Bus you can use the off method:

useStorefront(async (storefront) => {
    function myFunction(command) {
        console.log('Command:', command.name);
    }

    storefront.commandBus.on('command-name', myFunction);

    storefront.commandBus.off('command-name', myFunction);
});

Example¶

To execute a command asynchronously of the Command Bus you can use the execute method:

useStorefront(async (storefront) => {
    storefront.commandBus.execute({
        name: 'my-command',
        type: 'command',
        body: 'command body'
    });
});

Your body can contain any data type you need:

useStorefront(async (storefront) => {
    storefront.commandBus.execute({
        name: 'my-command',
        type: 'command',
        body: [
            {
                name: 'example1',
                values: [1, 2, 3]
            },
            {
                name: 'example2',
                values: [10, 20, 30]
            }
        ]
    });
});

Example¶

In this example we execute a command of the Command Bus synchronously and listen to it:

useStorefront(async (storefront) => {
    storefront.commandBus.on('get-body-length', function ({ body }) {
        const bodyLength = typeof body === 'string' ? body.length : 0;

        return bodyLength;
    });

    const bodyLength = storefront.commandBus.executeSync({
        name: 'get-body-length',
        type: 'command',
        body: 'command body'
    });

    console.log('body length:', bodyLength);
});

Your body can contain any data type you need:

useStorefront(async (storefront) => {
    storefront.commandBus.on('get-body-length', function ({ body }) {
        const bodyLength = typeof body === 'string' || Array.isArray(command.body) ? body.length : 0;

        return bodyLength;
    });

    const bodyLength = storefront.commandBus.executeSync({
        name: 'get-body-length',
        type: 'command',
        body: [
            {
                name: 'example1',
                values: [1, 2, 3]
            },
            {
                name: 'example2',
                values: [10, 20, 30]
            }
        ]
    });

    console.log('body length:', bodyLength);
});

Example¶

To get the count of all listeners for a given message using the Command Bus you can use the getListenersCount method:

useStorefront(async (storefront) => {
    const listenersCount = storefront.commandBus.getListenersCount('my-command');

    console.log('listeners of my-command:', listenersCount);
});