Frontend made fully type-safe and without null checks. Part 1

// Ok means that operation was successful. In this case we can read value returned
export type Ok<T> = { kind: 'ok'; value: T };
// Failure means that operation failed. In this case we can read error, but can't read value, since there is no value
export type Failure<E> = { kind: 'failure'; error: E };
// Result can be either Ok or Failure
export type Result<T, E = any> = Ok<T> | Failure<E>;
// Bug means that something went wrong, that we didn't really expect.
// But instead of throwing an error, we return special kind of error that wraps bug with any data passed.
// This way we can structure it better in logs and not raise any errors in our application
export type Bug = { kind: 'bug'; data: any };

// These are just some helpers to make code more composable and easier to construct.
// Otherwise we would need to use explicit type casting, because typecsript is not always very smart
// { kind: 'ok', value: 1 } as Ok<number>
export function ok<T>(value: T): Ok<T> {
  return { kind: 'ok', value };
}

export function failure<E>(error: E): Failure<E> {
  return { kind: 'failure', error };
}

export function bug(data: any): Bug {
  return { kind: 'bug', data };
}

// Some means that there is some data
export type Some<T> = { kind: 'some'; value: T };
// None means that there is no data
export type None = { kind: 'none' };
// Option can be either Some or None
// Example:
// const player: Option<Player> = getPlayerFromDb(id)
export type Option<T> = Some<T> | None;

export function some<T>(value: T): Some<T> {
  return { kind: 'some', value };
}

export function none(): None {
  return { kind: 'none' };
}

// Easy to use wrapper
export function option<T>(value: T | undefined): Option<T> {
  if (value === null || value === undefined) {
    return none();
  } else {
    return some(value);
  }
}

type PluginCommand = {
  kind: string;
};
type PluginEvent = {
  kind: string;
};

// naming those above starting with "Plugin" has a reason: it makes it easier for your IDE to import because words like Command or Event are way more likely to conflict with other libs (Event is included in dom lib).

// This is type that insures proper typing for commands, so that handlers can be implemented very easily
type Handlers<Command extends PluginCommand, Event extends PluginEvent> = {
  [P in Command['kind']]: (
    command: Extract<Command, { kind: P }>,
  ) => Observable<Event>;
};

// If we have some external data sources (listening to external APIs for example), we need to define them explicitly
type ExternalDataSources<T extends string, Event extends PluginEvent> = {
  [P in T]: Observable<Event>;
};
// This is type of the function that will be called in reducer. It is proper typed: it accepts current state and event and returns new state
type PluginReducerFn<State, Event extends PluginEvent> = (
  state: State,
  event: Event,
) => State;

// This ensures that all the types for plugin passed properly and match all the requirements
type PluginConfig<
  Command extends PluginCommand,
  Event extends PluginEvent,
  State,
  InitialValue extends State,
  Reducer extends PluginReducerFn<State, Command | Event>,
  ExternalDataSource extends string = string,
> = {
  handlers: Handlers<Command, Event>;
  reducer: Reducer;
  initialValue: InitialValue;
  externalSources: ExternalDataSources<ExternalDataSource, Event>;
};

export interface AtomicPlugin<
  Command extends PluginCommand,
  Event extends PluginEvent,
  State,
> {
  connect(): Observable<Event>;

  state(): Observable<State>;

  send(command: Command): void;
}

// reactive-plugins.ts

export class AtomicPluginInstance<
  Command extends PluginCommand, // possible commands to accept
  Event extends PluginEvent, // possible events to emit
  State, // type of state
  InitialState extends State = State, // concrete type of the intial state
  ExternalSources extends string = string, // list of keys of external sources. For example, 'statusUpdated' | 'onShutdown'
> implements AtomicPlugin<Command, Event, State> // pass generics to the interface in order to ensure proper types in implemented methods `send`, `connect` and `state` 
{

  protected config!: PluginConfig<
    // same boilerplate as above =)
    Command,
    Event,
    State,
    InitialState,
    PluginReducerFn<State, Command | Event>,
    ExternalSources
  >;

  // accepts command from user 
  private command = new Subject<Command>();
  // processes commands and emits events back to the stream 
  private commandHandler!: Observable<Event | never>;
  // emits events from the system
  private events!: Observable<Event>;
  // emits current state
  private stateSource!: Observable<State>;

  constructor(
    // just accepts config from higher level APIs
    private configValue: PluginConfig<
      Command,
      Event,
      State,
      InitialState,
      PluginReducerFn<State, Command | Event>,
      ExternalSources
    >
  ) {
    this.config = configValue;
    this.init();
  }

  // essential interface implementation. Could've been done through abstract base class 
  public connect(): Observable<Event> {
    return this.events;
  }

  public state(): Observable<State> {
    if (!this.stateSource) {
      throw new Error('state source not defined');
    }
    return this.stateSource;
  }

  public send(command: Command): void {
    this.command.next(command);
  }

  public init(): void {
    // Here is how command handler works:
    //  It accepts command from user
    //  Then it gets handler from the config for that command
    //    - If there is no handler, then app is not configured properly, and we throw an error
    //    - If there is handler, then we call it with command, and return Observable of events.
    //   For now we use `mergeMap` here, because we need to make sure that all nested observables would complete if user sends multiple commands. This behavior can be extended later in order to handle different cases like http request canceling. But in this article we won't cover such scenarios.
    this.commandHandler = this.command.pipe(
      mergeMap((command) => {
        const handler = this.config.handlers[command.kind as Command['kind']] as
          | ((command: Command) => Observable<Event>)
          | undefined;

        if (!handler) {
          throw new Error('No handler found');
        }

        return handler(command);
      }),
      share({ connector: () => new ReplaySubject(1) }),
    );

    // here we want to merge received events and external sources into one stream
    const eventSources = merge(
      this.commandHandler,
      ...(Object.values(this.config.externalSources) as Observable<Event>[])
    );

    this.events = eventSources.pipe(
      share({ connector: () => new ReplaySubject(1) })
    );

    // This is our very simple state reducing pipeline
    this.stateSource = merge(this.command, this.events).pipe(
      // `scan` is just continous applying events over an accumulator state 
      scan<Command | Event, State, InitialState>((state, event) => {
        return this.config.reducer(state, event);
      }, this.config.initialValue),
      // `startWith` accepts initial state
      startWith(this.config.initialValue),
      // `shareReplay` means make this observable hot. It will buffer the last emitted value and replay it to new subscribers. 
      // That means that if value was emitted  before, but client subscribed later, it will be replayed to the client from buffer
      shareReplay({ bufferSize: 1, refCount: true })
    );
  }
}

// light-switch.plugin.ts

import { AtomicPlugin, AtomicPluginInstance } from './reactive-plugins.ts';
import { EMPTY, Observable } from 'rxjs';

// We assume the only action user can do with a switch light is to toggle it
type ToggleCommand = {
  kind: 'toggle';
};

export type LightSwitchCommand = | ToggleCommand;

// There is no real need for switch to return events, we can just subscribe to its state
export type LightSwitchEvent = never;

// Now we can see that light switch can have two states: on and off
type StateOn = {
  kind: 'on';
}

type StateOff = {
  kind: 'off';
}

// // define all possible states of light switch
export type LightSwitchState = StateOn | StateOff;

// Now let's create an implementation of our plugin which is basically simple state machine
// First we pass types to the plugin as generics
export class LightSwitchPlugin implements AtomicPlugin<LightSwitchCommand, LightSwitchEvent, LightSwitchState> {
  private plugin: AtomicPlugin<LightSwitchCommand, LightSwitchEvent, LightSwitchState>;

  constructor() {
    // initialize actual plugin with config
    this.plugin = new AtomicPluginInstance<LightSwitchCommand, LightSwitchEvent, LightSwitchState, StateOff>({
      handlers: {
        toggle: (cmd) => {
          // no need to handle command actually
          // `EMPTY` observable here is like a noop
          return EMPTY;
        }
      },
      reducer: (state, eventOrCommand) => {
        // check what event or command is passed
        switch (eventOrCommand.kind) {
          case 'toggle':
            // check current state
            switch (state.kind) {
              // if state is on and switch is toggled, then its state becomes off
              case 'on':
                return { kind: 'off' };
              // if state is off and switch is toggled, then its state becomes on
              case 'off':
                return { kind: 'on' };
            }
          default:
            throw new Error('Invalid event');
        }
      },
      externalSources: {},
      // switch is off on start
      initialValue: { kind: 'off' }
    });
  }

  // this is the required boilerplate
  public connect(): Observable<LightSwitchEvent> {
    return this.plugin.connect();
  }

  public state(): Observable<LightSwitchState> {
    return this.plugin.state();
  }

  public send(command: LightSwitchCommand): void {
    this.plugin.send(command);
  }

}

// app.component.ts

// ...


export class AppComponent {
  private lightSwitches = [
    new LightSwitchPlugin(),
    new LightSwitchPlugin(),
    new LightSwitchPlugin()
  ];

  private lightSwitchesState = toSignal(
    combineLatest(
      this.lightSwitches.map((lightSwitch) => lightSwitch.state())
    )
      .pipe(
        map((states) => states.map((state) => state.kind === 'on')),
        shareReplay({ bufferSize: 1, refCount: true })
      ),
    {
      requireSync: true
    }
  );

  public lightSwitchesWithState = computed(() => this.lightSwitchesState().map((state, index) => ({
    state,
    instance: this.lightSwitches[index]
  })));

  constructor() {

    // here we subscribe to light switches events stream to initialize plugins
    merge(...this.lightSwitches.map((lightSwitch) => lightSwitch.connect())).pipe(
      takeUntilDestroyed()
    ).subscribe();
  }
}

<!-- app.component.html -->

<div class="grid grid-cols-3 grid-rows-auto gap-4">
  @for (item of lightSwitchesWithState(); track $index) {
    <div class="h-24" (click)="item.instance.send({ kind: 'toggle' })"
         [ngClass]="{ 'bg-yellow': item.state, 'bg-gray': !item.state }"></div>
  }
</div>

/* styles.css */

.grid {
  display: grid;
}

.grid-cols-3 {
  grid-template-columns: repeat(3, minmax(0, 1fr));
}

.grid-rows-auto {
  grid-template-rows: auto;
}

.gap-4 {
  gap: 1rem;
}

.bg-yellow {
  background-color: yellow;
}

.bg-gray {
  background-color: gray;
}

.h-24 {
  height: 6rem;
}