@bett3r-dev/pv3 1.0.0

package/src/ports/eventsourcing/commandHandlers/index.ts

@@ -0,0 +1,625 @@
+import { ensureArray, map, reduce } from '@bett3r-dev/bett3r-utils';
+import S, { ObjectSchema } from '@bett3r-dev/jsonschema-definer';
+import {
+  Aggregate,
+  AggregateReducedState, Builder, Command,
+  CommandEndpointQuerySchema,
+  CommandExecutionResponse,
+  CommandHandlerFunction,
+  CommandHandlerState, CommittedEvent,
+  CommittedEventSchema, DatabasePort, DatabaseTransaction, EndpointActionParams,
+  EndpointSchemas,
+  EndpointsPort, EventFactory, EventSourcingCommandHandlers, EventStorePort, EventToCommit, InvariantType, LoggerType, ReadStreamOptions, System,
+  SystemEndpointParamsSchema,
+  SystemGetQuerySchema,
+  SystemGetQueryType
+} from '@bett3r-dev/pv3-types';
+import { paramCase, pascalCase } from 'change-case';
+import { randomUUID } from 'crypto';
+import { assoc, clone, mergeRight, objOf, omit, path, pick } from 'ramda';
+import { validateSchema, validateEndpoint } from '../../../libraries/validation';
+import { formatStream } from '../utils';
+
+export const formatAggregateGetQueryParams = (
+  params: SystemGetQueryType
+): ReadStreamOptions => ({
+  stream: params.stream,
+  events: params.names,
+  direction: params.backward ? 'backwards' : 'forwards',
+  from: params.from,
+  limit: params.limit,
+  after: params.after,
+  before: params.before,
+});
+
+export const getEventReducers =
+  (
+    aggregate: Aggregate,
+    reducedState: AggregateReducedState = { state: aggregate.initialValue() }
+  ) =>
+    ( event: EventToCommit ): AggregateReducedState => {
+      return ( reducedState = {
+        state: aggregate.eventReducers[event.name as string](
+          reducedState.state,
+          event.data,
+          event.metadata
+        ),
+        lastEvent: pick([ 'id', 'version' ], event ),
+      });
+    };
+
+export const appendEventsToStream =
+  (
+    eventstore: EventStorePort,
+    expectedVersion?: number,
+    transaction?: DatabaseTransaction
+  ) =>
+    ( events: EventToCommit[]) => {
+      const stream = events[0].stream;
+      return events.length
+        ? eventstore.appendToStream( stream, events, expectedVersion, transaction )
+        : Promise.resolve([]);
+    };
+
+export const addMetadata =
+  ({ metadata, context, stream }: CommandHandlerState ) =>
+    ( event: ReturnType<EventFactory> ): EventToCommit =>
+      ({
+        stream,
+        metadata: {
+          ...metadata,
+          ...( context?.user ? { user: context.user } : {}),
+        },
+        ...event,
+      } as EventToCommit );
+
+export const prepareEventsToCommit = (
+  handlerState: CommandHandlerState
+): Promise<EventToCommit[]> => {
+  return Promise.resolve( handlerState.events )
+    .then( ensureArray )
+    .then(
+      map(( eventFactory: EventFactory ) => {
+        return { ...( eventFactory() as ReturnType<EventFactory> ) };
+      })
+    )
+    .then( map( addMetadata( handlerState ))) as Promise<EventToCommit[]>;
+};
+
+export const commitEvents =
+  ( eventstore: EventStorePort ) =>
+    (
+      handlerState: CommandHandlerState,
+      transaction?: DatabaseTransaction
+    ): Promise<CommandHandlerState> => {
+      if ( !handlerState.events.length ) return Promise.resolve( handlerState );
+      return prepareEventsToCommit( handlerState )
+        .then(
+          appendEventsToStream(
+            eventstore,
+            handlerState.expectedVersion,
+            transaction
+          )
+        )
+        .then( objOf( 'committedEvents' ))
+        .then( mergeRight( handlerState ));
+    };
+
+export const getStreamReducer =
+  ( state: Record<string, any> = {}) =>
+    ( event: CommittedEvent ) => {
+      state[event.stream] ||= { events: [], state: null };
+      state[event.stream].events?.push( event );
+      return state;
+    };
+
+export const loadStream =
+  ( eventstore: EventStorePort ) =>
+    ( stream: string, options?: ReadStreamOptions ) => {
+      return eventstore
+        .readStream(
+          {
+            ...options,
+            stream,
+          },
+          getStreamReducer()
+        )
+        .then(( state ) =>
+          !Object.keys( state ).length
+            ? undefined
+            : ( state[stream].events as CommittedEvent[])
+        );
+    };
+export const loadAggregateState =
+  ( eventstore: EventStorePort ) =>
+    (
+      system: Aggregate,
+      stream: string,
+      options?: ReadStreamOptions,
+      state?: any
+    ): Promise<AggregateReducedState | null> => {
+      return !stream || !system.isAggregate
+        ? Promise.resolve( null )
+        : eventstore
+          .readStream(
+            { ...options, stream },
+            getEventReducers( system, { state })
+          )
+          .then(( _state ) => {
+            return _state || { state };
+          });
+    };
+
+export const domainModelLoad =
+  ( database: DatabasePort, collection: string ) =>
+    ( handlerState: CommandHandlerState ) => {
+      return database
+        .getCollection( collection )
+        .readById( handlerState.params.id )
+        .then(( state ) => {
+          return assoc(
+            'state',
+            state
+              ? omit(['id'], state )
+              : ( handlerState.commandHandler as Aggregate ).initialValue(),
+            handlerState
+          );
+        });
+    };
+
+export const domainModelCommit =
+  ( eventstore: EventStorePort ) =>
+    ( database: DatabasePort, collection: string ) =>
+      ( handlerState: CommandHandlerState ): Promise<CommandHandlerState> => {
+        return database.initTransaction( async ( getCollection ) => {
+          const { params, expectedVersion } = handlerState;
+          // console.log( 'EXPECTED VERSION AT COMMIT', expectedVersion );
+          const initialValue = (
+            handlerState.commandHandler as Aggregate
+          ).initialValue();
+          const eventsToCommit = await prepareEventsToCommit( handlerState );
+          if ( eventsToCommit.length === 0 ) {
+            return handlerState;
+          }
+          const { state, events } = reduceEventsIntoState(
+            handlerState.state || initialValue,
+            handlerState.commandHandler as Aggregate,
+            eventsToCommit
+          );
+
+          let lastCommittedVersion = 0;
+          if ( eventstore._adapter._adapter() === database ) {
+            const state = await ( commitEvents( eventstore )( handlerState, { getCollection }));
+            lastCommittedVersion = state.committedEvents?.at( -1 )?.version || 1;
+          } else {
+            // TODO: Determine how to get the lastCommittedVersion in the outbox scenario
+            await getCollection( `${collection}_outbox` ).createMany(
+              events.map(( e ) => assoc( 'id', randomUUID(), e ))
+            );
+          }
+          if ( expectedVersion )
+            await getCollection( collection ).updateMany(
+              [
+                { field: 'id', op: 'eq', value: params.id },
+                { field: 'version', op: 'eq', value: expectedVersion },
+              ],
+              { ...state, version: lastCommittedVersion }
+            );
+          else {
+            if ( state !== null ) {
+              await getCollection( collection ).upsert( handlerState.params.id, { ...state, version: lastCommittedVersion });
+            } else {
+              await getCollection( collection ).destroyById( handlerState.params.id );
+            }
+          }
+          return {
+            ...handlerState,
+            state,
+          } as CommandHandlerState;
+        });
+      };
+
+export const defaultHandler =
+  ( eventsProducedByCommand: string[]): CommandHandlerFunction =>
+    ( _, data ) => {
+      return Promise.all(
+        ( eventsProducedByCommand || []).map(( e ) => () => ({
+          name: e,
+          data,
+        }))
+      );
+    };
+
+export const defaultCommit =
+  ( eventstore: EventStorePort ) => ( state: CommandHandlerState ) =>
+    commitEvents( eventstore )( state );
+
+export const reduceEventsIntoState = (
+  initialState: any,
+  commandHandler: Aggregate,
+  events: EventToCommit[]
+) => {
+  const reducer = getEventReducers( commandHandler as Aggregate, {
+    state: initialState,
+  });
+  const _state = events.reduce(
+    ( _, event ) => reducer( event ),
+    {} as AggregateReducedState
+  );
+  return { events, state: _state.state };
+};
+
+export const formatDomainModelCommandResponse = (
+  handlerState: CommandHandlerState
+): Promise<CommandExecutionResponse> => {
+  return Promise.resolve({
+    state: handlerState.state,
+  } as CommandExecutionResponse );
+};
+
+export const formatEventSourcedCommandResponse = async (
+  handlerState: CommandHandlerState
+): Promise<CommandExecutionResponse> => {
+  const { committedEvents, commandHandler, state } = handlerState;
+  if ( !committedEvents || !committedEvents.length )
+    return Promise.resolve({ state } as CommandExecutionResponse );
+  if ( !commandHandler.isAggregate ) {
+    return Promise.resolve({ events: committedEvents });
+  }
+  return reduceEventsIntoState(
+    state,
+    commandHandler as Aggregate,
+    committedEvents
+  ) as CommandExecutionResponse;
+};
+
+export const validateInvariants =
+  ( invariants: InvariantType[]) => ( state: CommandHandlerState ) => {
+    return invariants.reduce(( success, invariant ) => {
+      return success
+        .then(( state ) => invariant.check( state ))
+        .then(( resultState ) => resultState || state );
+    }, Promise.resolve( state ));
+  };
+
+export const defaultEventsourcingLoad =
+  ( eventstore: EventStorePort ) =>
+    (
+      handlerState: CommandHandlerState,
+      options?: ReadStreamOptions,
+      state?: any
+    ) => {
+      return loadAggregateState( eventstore )(
+        handlerState.commandHandler as Aggregate,
+        handlerState.stream,
+        options,
+        state ||
+        handlerState.state ||
+        ( handlerState.commandHandler as Aggregate ).initialValue()
+      ).then(
+        ( reducedState ) =>
+          ({
+            ...handlerState,
+            state: reducedState?.state,
+            expectedVersion: reducedState?.lastEvent?.version,
+          } as CommandHandlerState )
+      );
+    };
+
+export const handleCommand =
+  ( handler: CommandHandlerFunction ) =>
+    async ( handlerState: CommandHandlerState ): Promise<CommandHandlerState> => {
+      const { state, data } = handlerState;
+      handlerState.events = await Promise.resolve()
+        .then(() =>
+          ( handler as CommandHandlerFunction )(
+            state ? clone( state ) : null,
+            clone( data ),
+            handlerState
+          )
+        )
+        .then(( events ) => {
+          return [ ...handlerState.events, ...events ];
+        });
+      return handlerState;
+    };
+
+export function createCommandHandlers(
+  logger: LoggerType,
+  endpoint: EndpointsPort,
+  eventstore: EventStorePort
+): EventSourcingCommandHandlers {
+  const internalExecuteCommand =
+    <SYSTEM extends System, COMMAND extends keyof SYSTEM['commands']>(
+      commandHandler: SYSTEM,
+      commandName: COMMAND
+    ) =>
+      async (
+        actionParams: EndpointActionParams
+      ): Promise<
+      CommandExecutionResponse | Record<string, CommandExecutionResponse>
+      > => {
+        const command: Command = ( commandHandler.commands[commandName] as Builder )
+          .build
+          ? commandHandler.commands[commandName].build()
+          : commandHandler.commands[commandName];
+        command.name = commandName as string;
+        logger.log(
+          'Processing Command',
+          commandName,
+          'in',
+          commandHandler.isAggregate ? 'Aggregate' : 'External System',
+          commandHandler.name
+        );
+        logger.debug(
+          'with payload:',
+          pick([ 'body', 'params', 'query' ], actionParams )
+        );
+        const { body, params, query, context } = actionParams;
+        const id = command.dataPropertyId
+          ? path( command.dataPropertyId.split( '.' ), body )
+          : params.id;
+        const stream = formatStream( commandHandler.name, id );
+        const handlerState = {
+          command,
+          data: body,
+          query,
+          params,
+          context,
+          stream,
+          events: [],
+          commandHandler,
+          expectedVersion: query?.expectedVersion,
+          state: undefined,
+          metadata: {
+            correlationId: query?.correlationId || randomUUID(),
+            ...( query?.causationId ? { causationId: query?.causationId } : {}),
+          },
+        } as CommandHandlerState;
+
+        const loadFunction =
+        command.load ||
+        ( commandHandler.isEventsourced
+          ? defaultEventsourcingLoad( eventstore )
+          : domainModelLoad(
+            ( commandHandler as any ).outboxDatabase,
+            ( commandHandler as any ).outboxCollection
+          ));
+        const commitFunction =
+        command.commit ||
+        ( commandHandler.isEventsourced
+          ? defaultCommit( eventstore )
+          : domainModelCommit( eventstore )(
+            ( commandHandler as any ).outboxDatabase,
+            ( commandHandler as any ).outboxCollection
+          ));
+        const formatFunction =
+        command.format ||
+        ( commandHandler.isEventsourced
+          ? formatEventSourcedCommandResponse
+          : formatDomainModelCommandResponse );
+
+        return Promise.resolve( handlerState )
+          .then( loadFunction )
+          .then( validateInvariants( command.invariants || []))
+          .then(
+            handleCommand(
+              command.handler || defaultHandler( command.events as string[])
+            )
+          )
+          .then( commitFunction )
+          .then( formatFunction );
+      };
+
+  const executeCommand =
+    <SYSTEM extends System, COMMAND extends keyof SYSTEM['commands']>(
+      commandHandler: SYSTEM,
+      commandName: COMMAND,
+      schemas?: EndpointSchemas<any, any, any>
+    ) =>
+      async (
+        actionParams: EndpointActionParams
+      ): Promise<
+      CommandExecutionResponse | Record<string, CommandExecutionResponse>
+      > => {
+        const command: Command = ( commandHandler.commands[commandName] as Builder )
+          .build
+          ? commandHandler.commands[commandName].build()
+          : commandHandler.commands[commandName];
+        schemas = schemas || getCommandSchemas( commandHandler, command );
+        command.name = commandName as string;
+        return Promise.resolve( actionParams )
+          .then( validateEndpoint( validateSchema, schemas ))
+          .then( internalExecuteCommand( commandHandler, commandName ))
+          .catch(( err ) => {
+            if ( command.onErrorHandler )
+              return command.onErrorHandler( err, actionParams.body );
+            return Promise.reject( err );
+          });
+      };
+
+  const getCommandSchemas = ( commandHandler: System, command: Command ) => {
+    const eventsSchemas: Record<string, ObjectSchema> = command.events?.reduce(
+      ( schemas, eventName ) => {
+        if ( !!commandHandler.events[eventName])
+          schemas[eventName] = commandHandler.events[eventName]().schema;
+        if ( schemas[eventName])
+          schemas[eventName] = schemas[eventName].id( eventName );
+        return schemas;
+      },
+      {} as Record<string, ObjectSchema>
+    );
+    const responses =
+      !eventsSchemas || Object.keys( eventsSchemas ).length === 0
+        ? {
+          200: [
+            {
+              schema: S.shape({
+                state: ( commandHandler as Aggregate ).schema.id(
+                  `${commandHandler.name}State`
+                ),
+              }),
+              name: 'OK',
+            },
+          ],
+        }
+        : {
+          200: [
+            {
+              schema: commandHandler.isAggregate
+                ? S.shape({
+                  state: ( commandHandler as Aggregate ).schema.id(
+                    `${commandHandler.name}State`
+                  ),
+                  events: CommittedEventSchema(
+                    S.anyOf(
+                      ...Object.values( eventsSchemas )
+                    ) as ObjectSchema,
+                    Object.keys( eventsSchemas )
+                  ),
+                })
+                : S.shape({
+                  events: CommittedEventSchema(
+                    S.anyOf(
+                      ...Object.values( eventsSchemas )
+                    ) as ObjectSchema,
+                    Object.keys( eventsSchemas )
+                  ),
+                }),
+              name: 'OK',
+            },
+          ],
+        };
+    return {
+      query: CommandEndpointQuerySchema,
+      body: command.schema?.copyWith({ plain: { $id: command.name }}),
+      responses,
+      ...( commandHandler.isStreamable && !command.dataPropertyId
+        ? { params: SystemEndpointParamsSchema }
+        : {}),
+    };
+  };
+
+  const formatCommandRoute = (
+    commandName: string,
+    transformFn: ( x: string ) => string
+  ) => {
+    return `${commandName.startsWith( '_' ) ? '_' : ''}${transformFn(
+      commandName
+    )}`;
+  };
+
+  const registerCommandHandlerGetEndpoints = (
+    commandHandler: System,
+    name = commandHandler.name
+  ): string[] => {
+    const isStreamable =
+      !!( commandHandler as Aggregate ).eventReducers ||
+      ( commandHandler as System ).isStreamable;
+    const idRoute = `/${formatCommandRoute( name, paramCase )}/:id/state`;
+    const streamRoute = isStreamable
+      ? `/${formatCommandRoute( name, paramCase )}/:id/stream`
+      : `/${formatCommandRoute( name, paramCase )}/stream`;
+    if (
+      !commandHandler.isEventsourced &&
+      !( commandHandler as Aggregate ).outboxDatabase
+    )
+      throw Error(
+        'Aggregate declared as Not Eventsourced without Outbox database.'
+      );
+    isStreamable &&
+      endpoint.registerEndpoint({
+        name: `Get ${name} state by Id`,
+        description: `Get current reduced ${name} state by Id`,
+        method: 'GET',
+        module: name,
+        route: idRoute,
+        schemas: {
+          params: SystemEndpointParamsSchema,
+          query: SystemGetQuerySchema,
+        },
+        action: ({ params, query }) =>
+          loadAggregateState( eventstore )(
+            commandHandler as Aggregate,
+            formatStream( commandHandler.name, params?.id ),
+            formatAggregateGetQueryParams( query )
+          ).then(( response ) => response && Object.values( response )[0]),
+      });
+    endpoint.registerEndpoint({
+      name: formatCommandRoute( name, pascalCase ),
+      description: `Get the stream of events for ${name} by Id`,
+      method: 'GET',
+      module: name,
+      route: streamRoute,
+      schemas: {
+        params: isStreamable ? SystemEndpointParamsSchema : undefined,
+        query: SystemGetQuerySchema,
+      },
+      action: ({ params, query }) =>
+        ( isStreamable
+          ? loadStream( eventstore )(
+            formatStream( commandHandler.name, params?.id ),
+            query
+          )
+          : loadStream( eventstore )( name, formatAggregateGetQueryParams( query ))
+        ).then(( response ) => ( Array.isArray( response ) ? response : [])),
+    });
+
+    return [ idRoute, streamRoute ];
+  };
+
+  const registerCommandHandlerPostEndpoints = (
+    commandHandler: System
+  ): Record<string, string> => {
+    const commandHandlerName: string = commandHandler.name;
+    const isStreamable = commandHandler.isStreamable;
+    return !commandHandler.commands
+      ? {}
+      : reduce(
+        ( result, name ) => {
+          const command: Command = commandHandler.commands[name]?.build
+            ? commandHandler.commands[name]?.build()
+            : commandHandler.commands[name];
+          const route =
+              !isStreamable || !!command.dataPropertyId === true
+                ? `/${paramCase( commandHandlerName )}/${formatCommandRoute(
+                  name,
+                  paramCase
+                )}`
+                : `/${paramCase( commandHandlerName )}/:id/${formatCommandRoute(
+                  name,
+                  paramCase
+                )}`;
+          const schemas = getCommandSchemas( commandHandler, command );
+          endpoint.registerEndpoint({
+            module: commandHandlerName,
+            name: formatCommandRoute( name, pascalCase ),
+            description: command.description,
+            multipartProperties: command.multipartProperties,
+            route,
+            tags: commandHandler.isAggregate ? ['aggregate'] : ['system'],
+            schemas,
+            shouldValidate: false,
+            method: 'POST',
+            action: executeCommand(
+              commandHandler as Aggregate,
+              name,
+              schemas
+            ),
+          });
+          result[name] = route;
+          return result;
+        },
+        {},
+        Object.keys( commandHandler.commands )
+      );
+  };
+
+  return {
+    loadStream: loadStream( eventstore ),
+    loadAggregateState: loadAggregateState( eventstore ),
+    executeCommand,
+    registerCommandHandlerGetEndpoints,
+    registerCommandHandlerPostEndpoints,
+  };
+}

package/src/ports/eventsourcing/commandTemplates/index.ts

@@ -0,0 +1,2 @@
+export * from './multiStream';
+export * from './snapshot';

package/src/ports/eventsourcing/commandTemplates/multiStream.ts

@@ -0,0 +1,70 @@
+import { map } from '@bett3r-dev/bett3r-utils';
+import { Ports, Aggregate, Command, CommandExecutionResponse, CommandHandlerState, CommittedEvent } from '@bett3r-dev/pv3-types';
+import { InternalServerError, createError } from '../../../utils';
+import { objOf, path, pick, prop } from 'ramda';
+import { formatStream } from '..';
+
+const getStreams = ( dataPropertyId: string, data: any, formatStream: ( id: string ) => string ): any[] => {
+  const pathParts = dataPropertyId.split( '.' );
+
+  const recursiveExtractor = ( currentObj: any, currentPath: string[]): any[] => {
+    if ( !currentObj || currentPath.length === 0 ) return [];
+    const part = currentPath[0];
+    if ( Array.isArray( currentObj )) {
+      return currentObj.flatMap( childObj => recursiveExtractor( childObj, currentPath ));
+    }
+    if ( currentPath.length === 1 ) {
+      return [formatStream( currentObj[part])];
+    }
+    return recursiveExtractor( currentObj[part], currentPath.slice( 1 ));
+  };
+
+  return recursiveExtractor( data, pathParts );
+};
+
+export const getMultipleEventReducers = ( aggregate: Aggregate, reducedState = {}) => ( event: CommittedEvent ): any => {
+  reducedState[event.stream] = {
+    lastEvent: pick([ 'id', 'version' ], event ),
+    state: aggregate.eventReducers[event.name as string](( reducedState && reducedState[event.stream]?.state ) || aggregate.initialValue(), event.data, event.metadata )
+  };
+  return reducedState;
+};
+
+export const multiStream = ( ports: Pick<Ports, 'eventstore'>, dataPropertyId: string, ): Command => {
+  return {
+    dataPropertyId,
+    load: async <Model, Payload>( commandHandlerState: CommandHandlerState<Model,Payload> ): Promise<CommandHandlerState<Model, Payload>> => {
+      if ( !ports.eventstore.readMultipleStream ) throw createError( InternalServerError(), { details: { command: commandHandlerState.command.name }, description: 'MultiStream Command: The Eventstore in use does not Support Multiple Streams' });
+      const streams = getStreams( dataPropertyId, commandHandlerState.data, formatStream( commandHandlerState.commandHandler.name ));
+      return ports.eventstore.readMultipleStream({ streams }, getMultipleEventReducers( commandHandlerState.commandHandler as Aggregate ))
+        .then( state => {
+          return {
+            ...commandHandlerState,
+            state: !state || !Object.keys( state ).length ? undefined : map( prop( 'state' ), state ),
+            expectedVersion: !state || !Object.keys( state ).length ? undefined : map( path([ 'lastEvent', 'version' ]), state ) as any,
+          };
+        });
+    },
+    commit: async <Model, Payload>( commandHandlerState: CommandHandlerState<Model,Payload> ): Promise<CommandHandlerState<Model, Payload>> => {
+      if ( !ports.eventstore.appendToMultipleStreams ) throw createError( InternalServerError(), { details: { command: commandHandlerState.command.name }, description: 'MultiStream Command: The Eventstore in use does not Support Multiple Streams' });
+      const eventsToCommit = commandHandlerState.events.reduce(( streams, e: any ) => {
+        streams[e().stream] ||= { events:[], expectedVersion: commandHandlerState.expectedVersion![e().stream] };
+        streams[e().stream].events.push( e());
+        return streams;
+      }, {} as Record<string, {events: any[], expectedVersion?: number}> );
+      const events = await ports.eventstore.appendToMultipleStreams( eventsToCommit );
+      const formatedState = map( objOf( 'state' ), commandHandlerState.state );
+      const state = events.reduce(( _, event ) => {
+        return getMultipleEventReducers( commandHandlerState.commandHandler as Aggregate, formatedState )( event );
+      }, {});
+      return {
+        ...commandHandlerState,
+        state: map( prop( 'state' ), state ),
+        events
+      } as any;
+    },
+    format: async <Model, Payload>( state: CommandHandlerState<Model,Payload> ): Promise<CommandExecutionResponse<Model>> => {
+      return pick([ 'state', 'events' ], state ) as CommandExecutionResponse<Model>;
+    }
+  } as Command;
+};