event_base

event_base is a Dart package that provides a foundational protocol for time-series event recording. It leverages ULIDs for unique, chronologically sortable event identifiers and uses json_serializable for easy and reliable serialization.

This package is designed to be a building block for systems that need to log, transmit, or store sequences of events in a structured and verifiable manner.

Features

• Extensible Event Structure: Defines a clear base class IEvt for creating custom event types.
• Time-Sortable IDs: Uses ULIDs to ensure that events are unique and can be sorted chronologically.
• JSON Serialization: Built-in support for converting events to and from JSON using json_serializable.
• Core Event Types: Includes common event types out-of-the-box:
  • RawEvt: For general-purpose events with arbitrary JSON data.
  • AnchorEvt: For creating cryptographic anchors in an event stream, enabling verification.
  • HeartEvt: A simple event for heartbeat or keep-alive signals.

Getting started

Add event_base to your pubspec.yaml dependencies:

dependencies:
  event_base: ^0.0.1 # Replace with the latest version

Then, run flutter pub get or dart pub get.

Usage

Here is a simple example of how to create a RawEvt, serialize it to JSON, and deserialize it back into an object.

import 'dart:convert';
import 'package:event_base/event_base.dart';
import 'package:ulid/ulid.dart';

void main() {
  // 1. Create a raw event with a custom type and data payload.
  final rawEvt = RawEvt(
    id: Ulid(),
    tp: 'USER_LOGIN',
    data: RawData(raw: {'userId': 'user-123', 'method': 'email'}),
  );

  // 2. Serialize the event to a JSON string.
  final jsonString = jsonEncode(rawEvt.toJson());
  print('Serialized Event: $jsonString');
  // Output: Serialized Event: {"id":"01HXX...","tp":"USER_LOGIN","data":{"userId":"user-123","method":"email"}}

  // 3. Deserialize the JSON string back into an IEvt object.
  // The generic factory IEvt.fromJson handles dispatching to the correct data type based on the 'tp' field.
  final decodedEvt = IEvt.fromJson(jsonDecode(jsonString));

  // Verify the data is intact.
  print('Decoded Event ID: ${decodedEvt.id}');
  print('Decoded Event Type: ${decodedEvt.tp}');
  
  // Accessing nested data
  if (decodedEvt.data is RawData) {
    final rawData = decodedEvt.data as RawData;
    print('Decoded Data: ${rawData.raw}');
    // Output: Decoded Data: {userId: user-123, method: email}
  }
}

Additional information

For more information, to file issues, or to contribute, please visit the GitHub repository. We appreciate your feedback and contributions!