Welcome to ManagementJS

ManagementJS is vanilla TypeScript/JavaScript and can be used in any frontend or backend app (React, Angular, Vue, Node, etc.). It is a small, opinionated layer on top of RxJS that provides a request/response event system with built-in correlation by ID. That single idea simplifies local and network flows, plus distributed loading states. On top of that, it provides:

1. A local event bus with typed specifications and built-in tracking.
2. A CloudEvent-compatible request/response layer (optional).
3. WebSocket server/client helpers (optional).
4. A global reactive store (deep change tracking with zero boilerplate).

It is designed so you can use only the pieces you need: store only, events only, or the full stack.

Installation

via npm

npm i management-core

That's it.

Why use this over RxJS alone?

RxJS gives you powerful streams but no architecture. ManagementJS adds conventions and defaults:

• Typed event specifications: define actions once and use them consistently across your app.
• Global store with deep tracking: no manual next() calls for every mutation.
• Action tracking: built-in tracking of ongoing tasks (useful for global loading states).
• Optional cloud layer: common event shape for client/server communication.
• Singleton services: avoids multiple instances when imported from different places.

If you already have a strong architecture, RxJS alone might be enough. If you want a ready-made structure that stays small, ManagementJS can save time.

Why an event-driven architecture?

Event-driven systems are useful when your app is complex or distributed:

• Decentralization: features communicate through events instead of direct calls, reducing tight coupling.
• Simpler coordination: a single action can notify multiple parts of the app without wiring them together.
• Scalable mental model: you add new consumers without changing existing producers.
• Async-friendly: works well with network calls and background tasks.
• Onboarding-friendly: clear event names and flows make it easier for new developers to understand where things happen.

In practice, this often means less glue code and fewer “who depends on whom” problems.

Modular usage (you can pick only what you need)

• Store only: global reactive store with change tracking.
• Events only: local event bus with typed actions.
• Cloud layer: request/response events with CloudEvent format.
• WebSocket: server/client helpers to transport CloudEvents.

You are not forced to use the full stack.

Local vs Network Events (and how they map)

Think of ManagementJS as a small router for events:

• Local events are in-process signals (no network).
• Network events are CloudEvents that cross process boundaries (WS/HTTP/etc).
• You can map a local event to a network event (and vice-versa) to bridge UI and backend.

In other words:

• Local = fast, synchronous to your app runtime.
• Network = structured request/response across services.
• Mapping = your glue layer; you decide which local actions trigger network calls or how network responses update local state.

The key simplification: correlation by ID (not provided by RxJS)

RxJS gives you streams, but it does not give you request/response correlation. ManagementJS adds that missing layer. It couples request/response events by id, turning your app into a local + network event router:

• Local: Manager.trigger() generates a tracking_id and waits for the matching response on the same spec.
• Network: Api.emitCustom() generates a CloudEvent id and resolves the response with the same id.

This creates a clean request/response flow without manual wiring, and makes ManagementJS a true event router for frontend apps.

Distributed loading indicators

There is no isLoading flag, but the built-in tracker provides the same capability:

• Start is automatic when you trigger or emit.
• Finish happens when the response arrives (or on error/timeout).
• You can query or observe ongoing work to drive global or local loading UI.

Use cases:

• Global spinner for any ongoing action.
• Per-action loader for specific specs or ids.

Local flow (in-process)

sequenceDiagram
  participant UIA as UI / Domain A
  participant UIB as UI / Domain B
  participant M as Manager
  participant H as Local Handler
  participant S as Store

  UIA->>M: trigger(spec)
  M->>H: on(spec)
  H->>S: update
  S-->>UIA: onChange
  S-->>UIB: onChange

Network flow (CloudEvents)

sequenceDiagram
  participant UI as UI / Domain
  participant API as Api
  participant NET as Network (WS/HTTP)
  participant SRV as Server / Handler
  UI->>API: emit(spec, request)
  API->>NET: CloudEvent
  NET->>SRV: CloudEvent
  SRV-->>NET: CloudEvent response
  NET-->>API: CloudEvent response
  API-->>UI: on(spec)

Mapping local and network events

sequenceDiagram
  participant L as Local Event
  participant N as Network Event
  participant S as Store / UI Update
  L->>N: map
  N-->>S: response

Getting started

Global Store

Want to share data globally and know when a variable is updated and which one? The store is here for you.

To get started you want to create a Store first. A store is simply a class that extends the ManagementJS Store abstract class and then is transformed through the getStore function. Here an example:

import { Store, getStore } from 'management-core';

class MyStore extends Store {
  root_string_variable_undefined?: string;
  root_string_variable_defined: string = 'root_string_variable_defined';
  root_number_variable_undefined?: number;
  root_number_variable_defined: number = 5;

  root_string_array_undefined?: Array<string>;
  root_string_array_defined: Array<string> = ['root_string_array_defined'];

  root_object_undefined?: {
    object_string_variable_defined: 'object_string_variable_defined';
    object_string_variable_undefined: 'object_string_variable_undefined';
  };
  root_object_defined: {
    object_string_variable_defined: 'object_string_variable_defined';
    object_string_variable_undefined?: 'object_string_variable_undefined';
  } = {
    object_string_variable_defined: 'object_string_variable_defined'
  };

  constructor () {
    super();
  }
}

const S = getStore(MyStore);

Now that you have an instance of your store you can keep working on your MyStore class (treat it like you would any other class) or use it somewhere else.

Maybe you just want to know when a variable is updated at any time.

const test_value = 'new value';
// currently S.root_string_variable_undefined = root_string_variable_defined
const terminate = S.onChange(
  S, // Here you are observing the whole store, you could also go deeper into a nested object and observe only a specific part of it.
  (val) => { // here we have our callback which will trigger anytime the object or any variable within the object is updated
    // val = 'new value'
  },
  'root_string_variable_undefined' // optional discriminator specifying the primitive variable within the targeted object that we are interested in
);

S.root_string_variable_undefined = test_value; // triggers callback at end of current lifecycle

Local Events (no network)

Define a specification and emit/listen to typed events.

import { SpecificationPrototype, Manager } from 'management-core';

class UserEvents {
  UserLoggedIn = new (class extends SpecificationPrototype<{ userId: string }> {})();

  constructor () {
    this.UserLoggedIn.init(this.UserLoggedIn, this);
  }
}

const Events = new UserEvents();

Manager.on(Events.UserLoggedIn, (data) => {
  console.log('User logged in', data.userId);
});

Manager.trigger(Events.UserLoggedIn, { userId: '42' });

Cloud Events (optional)

Use a CloudEvent-compatible request/response flow for network calls.

import { CloudSpecificationPrototype, Api } from 'management-core';

type Query = { request: { name: string }, response?: { id: string } };

class UserQueries {
  CreateUser = new (class extends CloudSpecificationPrototype<Query, Query['request'], Query['response']> {})();

  constructor () {
    this.CreateUser.init(this.CreateUser, this);
  }
}

const Q = new UserQueries();
const api = new Api();

api.on(Q.CreateUser).subscribe((data) => {
  console.log('response', data.response);
});

api.emit(Q.CreateUser, { name: 'Ada' });

React architecture usage

ManagementJS can be used as an app-level domain layer sitting below React.

Goals in React

• Centralize domain state that is shared across screens.
• Avoid prop-drilling or ad-hoc event emitters.
• Provide a consistent place for async requests and loading states.

How it fits

• Store becomes a global reactive source of truth.
• Events become your domain actions.
• Tracker can drive loading indicators.

Practical pattern (React + Store)

// store.ts
import { Store, getStore } from 'management-core';

class AppStore extends Store {
  user?: { id: string, name: string };
}

export const S = getStore(AppStore);

// useStore.ts
import { useEffect, useState } from 'react';
import { S } from './store';

export function useUser () {
  const [user, setUser] = useState(S.user);
  useEffect(() => S.onChange(S, () => setUser(S.user), 'user'), []);
  return user;
}

Positives in React

• Small surface area: easy to reason about.
• Global state without Redux boilerplate.
• Consistent domain actions via event specs.
• Easy to bridge client/server events when needed.

Important: lifecycle

When you subscribe to observables in React, always clean them up.

Browser Events

Handle events throughout the frontend anywhere while retaining typesafety?

Cloud Events

Connect any backend (REST / WS / custom) to your Browser Events and make the whole infrastructure reactive.