@cristaline/core

An immutable database engine based on log streams.

Requirements

• Node
• NPM

Installation

mkdir project
cd project
npm init --yes
npm install @cristaline/core zod tsx

[!WARNING] It is highly recommended to use a parsing library like Zod in order to ease the creation of robust and resilient schemas, but you can use any library of your choice.

touch index.ts

import type { EventShape } from "@cristaline/core";
import type { ZodSchema } from "zod";

import { MemoryEvent, MemoryState, createEventStore } from "@cristaline/core";
import { z } from "zod";

const eventSchema = z.object({
  id: z.string(),
  date: z.date({ coerce: true }),
  type: z.literal("TodoAdded"),
  version: z.literal(1),
  data: z.object({
    id: z.string(),
    title: z.string()
  })
}) satisfies ZodSchema<EventShape>

type Event = z.infer<typeof eventSchema>;

type Todo = {
  id: string,
  title: string
}

type State = {
  todos: Todo[]
}

const eventStore = createEventStore<State, Event>({
  event: MemoryEvent.for<Event>({
    events: [],
    parser: eventSchema.parse
  }),
  state: MemoryState.for<State>({
    state: {
      todos: []
    }
  }),
  replay: {
    TodoAdded: (state, event) => {
      return {
        ...state,
        todos: [
          ...state.todos,
          event.data
        ]
      }
    }
  }
});

await eventStore.initialize();

const state = await eventStore.getState();

console.log(state);

API

createEventStore

Create the shape of the event, and how to create a projection from those events.

Example

[!NOTE] We recommend using a parser library like Zod in order to validate the integrity of your events.

import { EventShape, createEventStore, MemoryState, MemoryEvent } from "@cristaline/core";
import { ZodSchema, z } from "zod";

const eventSchema = z.union([
  z.object({
    type: z.literal("UserCreated"),
    version: z.literal(1),
    identifier: z.string(),
    date: z.date({ coerce: true }),
    data: z.object({
      id: z.string(),
      email: z.string(),
    }),
  }) satisfies ZodSchema<EventShape>,
  z.object({
    type: z.literal("UserUpdated"),
    version: z.literal(1),
    identifier: z.string(),
    date: z.date({ coerce: true }),
    data: z.object({
      id: z.string(),
      email: z.string(),
    }),
  }) satisfies ZodSchema<EventShape>,
]);

type Event = z.infer<typeof eventSchema>

type User = {
  email: string
}

type State = {
  users: Array<User>
}

const eventStore = createEventStore<State, Event>({
  state: MemoryState.for<State>({
    state: {
      users: []
    }
  }),
  event: MemoryEvent.for<Event>({
    events: [],
    parser: eventSchema.parse,
  }),
  replay: {
    UserCreated: (state, event) => {
      return {
        ...state,
        users: [
          ...state.users,
          user,
        ],
      }
    },
    UserUpdated: (state, event) => {
      return {
        ...state,
        users: state.users.map(user => {
          if (user.id !== event.data.id) {
            return user;
          }

          return {
            ...user,
            ...event.data,
          };
        }),
      }
    }
  },
});

initialize

This function lets you initialize the state and events that are stored and retrieved from the storage system and mounts them in memory.

You'll need to run this method in order to get the initial state of your events.

If an error occurs, this typically means that the database has been altered from an outside source other than the script itself and does not respect the format expected when parsing the events.

Example

const error = await eventStore.initialize();

if (error instanceof Error) {
  console.error("Database corrupted.");
} else {
  console.log("Database initialized.");
}

getEvents

This is a simple getter for accessing the events log as an array.

Example

const events = await eventStore.getEvents();

for (const event of events) {
  console.log(event.type);
}

getState

This is also a getter method that will get you the actual state of your application computed from your events log.

const state = await eventStore.getState();

for (const user of state.users) {
  console.log(user.email);
}

saveEvent

This method will allow you to save an event directly to your storage system.

It also add this event to the list of events mounted in memory, as well as computing again the state of your application.

Note that saveEvent will request a lock on the database, this means that if there should be multiple writes at the same times, it will wait until all other waits in the queue are done before commiting the changes.

Example

const error = await eventStore.saveEvent({
  type: "USER_CREATED",
  version: 1,
  date: new Date(),
  identifier: crypto.randomUUID(),
  data: {
    id: crypto.randomUUID(),
    email: "[email protected]",
  },
});

if (error instanceof Error) {
  console.error("Failed to create a new user.");
} else {
  console.log("User created successfully");
}

transaction

For the times where you need to prevent write before finishing an action while operating on the database, it can be great to lock the database while performing an algorithm, this method has been designed specifically for that purpose, letting you commit or rollback changes as the algorithm run.

Using the saveEvent method in here is highly unrecommended since it is already called by the transaction function after the callback returns and it could lead to data inconsistencies.

The commit function exposed inside the transaction callback is used to save all wanted events, while the rollback function is used to discard all events that should be saved in case of an error for instance.

const usersToSave = [
  { email: "[email protected]" },
  { email: "[email protected]" },
  { email: "[email protected]" },
];

eventStore.transaction(async ({ commit, rollback }) => {
  try {
    const state = await eventStore.getState();

    for (const user of users) {
      const shouldBeSaved = state.users.every(user => {
        return usersToSave.every(userToSave => {
          return userToSave.email !== user.email;
        });
      });

      if (shouldBeSaved) {
        await saveEvent({
          type: "USER_CREATED",
          identifier: crypto.randomUUID(),
          version: 1,
          date: new Date(),
          data: {
            id: crypto.randomUUID(),
            email: user.email,
          },
        });
      }
    }

    await commit();
  } catch {
    rollback();
  }
});

subscribe

This method will help you react to any change in your event store whenever an event has been added.

eventStore.subscribe(() => {
  console.log("New event added.");
});

Changelog

Summary

• 3.0.0
• 2.0.0
• 1.0.0
• 0.1.0

3.0.0

Major Changes

• The replay property for the createEventStore function now accepted an object with the type of each defined events as its properties, instead of a function

Minor changes

None.

Bug & security fixes

None.

2.0.0

Major changes

• Renamed the StateAdapter interface to State and the EventAdapter interface to Event
• Added a new initial property in the State interface for setting the initial state
• Added a new reset method in the State interface for resetting the state

Minor changes

None.

Bug & security fixes

None.

1.0.0

Major changes

• The parser property is now removed from the createEventStore function's arguments
• The retrieve method of the EventAdapter interface now return a Promise<Event[]> instead of just returning Promise<unknown[]>

Minor changes

None.

Bug & security fixes

None.

0.1.0

Major changes

None.

Minor changes

None.

Bug & security fixes

None.

License

See LICENSE.