Event Processor (@zeeshan60/event-processor)

Shared event-sourcing core for MoneyRabbit. Provides the domain event/model classes, store interfaces, the EventProcessorSDK singleton, Firestore event converters, and shared utilities used by both the mobile app and gcloud-functions.

What this package is (and is not)

This package is a pure domain library: events, models, store interfaces, and utilities. It contains no projection/event handlers and no controllers.

Where handlers live now:

• Mobile (SQLite projections): mobile/src/app/shared/event-handlers/
• Backend (Firestore projections): gcloud-functions/src/backend-events/

The old residence.isClient dual-context mechanism has been removed; each consumer now wires its own stores and handlers. Historical design doc: ../docs/archive/DUAL_CONTEXT_FLOW.md.

Installation

Published to npm as @zeeshan60/event-processor:

{
  "dependencies": {
    "@zeeshan60/event-processor": "^1.0.238"
  }
}

Public API surface

Everything is exported from the package root (src/index.ts, which also re-exports src/events.ts).

| Area | Exports | |------|---------| | Base types | Event, Model/ModelProps, EventStore<T>, ModelStore (interfaces) | | Domain events + models | Per-domain classes, e.g. TransactionCreated, TransactionModel, UserCreated, FriendConnected, GroupTransactionCreated, ExpenseCreated, SubscriptionCreated, ... (see src/events.ts) | | SDK | initializeSDK, EventProcessorSDK, StoreConfig, getCurrencyStore, getModelChangeObservable, eventToFirestore, firestoreToEvent | | Change stream | ModelChange, ModelChangeEmitter | | Event type maps | EventMainType, EventType (+ EventMainTypeValue, EventTypeValue) | | Store interfaces | TransactionModelStore, UserEventStore, ... one pair per domain, plus CurrencyStore, MetadataStore | | Admin ops | AdminModelStoreOperations, AdminEventStoreOperations | | Utilities | GroupUtil builders (generatePerspectiveEvents, buildYouPaidSplitEquallyEvent, processGroupTransactionEventForPerspectives, ...), BalanceUtil, UserNameUtil, SortUtil, fuzzySearch, convertCurrency, splitTypeUtils (reverseSplitType, ...), generateActivityLogEvent, isDueToday, TestDataUtil | | Logging | Logger, defaultLogger | | Contracts | Request/response DTOs consumed by mobile controllers and gcloud-functions (see src/contracts/) | | Testing | __resetSDKForTesting (from src/EventProcessorSDK.ts; see SDK_USAGE.md) |

Notes:

• InMemoryEventStore/InMemoryModelStore are not exported. Internal in-memory test helpers (IM* classes) live under src/__tests__/test-helpers/ and are for this package's own tests only.
• Event classes live in per-domain files at the src/ root (e.g. src/TransactionEvents.ts, src/UserEvents.ts) — there is no src/events/ directory. src/events.ts is the curated re-export list.

Base interfaces

export interface Event {
  eventId: string;
  userId: string;
  streamId: string;
  version: number;
  createdAt: number;      // epoch millis
  createdBy: string;
  systemGenerated: boolean;
  skipNotify?: boolean;
  batchId?: string;
  eventMainType: EventMainTypeValue;
  eventType: EventTypeValue;
  apply(existing?: Model): Model;
  activityLog?(existingModel?: Model, actorName?: string): ActivityLogCreatedProps | undefined;
}

export interface ModelProps {
  userId: string;
  streamId: string;
  version: number;
  deleted: boolean;
  updatedAt: number;      // epoch millis
  synced: boolean;
}

Event main types

22 domains (EventMainType in src/common/EventTypes.ts):

transaction, user, friend, group, groupTransaction, activityLog, expenseAccount, expense, recurringExpense, recurringTransaction, recurringGroupTransaction, category, tag, notification, budget, attachmentProcess, importProcess, suggestion, reminder, appMetadata, currencyRate, subscription.

Consumers

event-processor (npm: @zeeshan60/event-processor)
    ↑
    ├── mobile            (SQLite stores + event handlers in the app)
    └── gcloud-functions  (Firestore stores + backend-events handlers)

Scripts

npm run build   # tsc
npm test        # jest
npm publish     # prepublishOnly runs the build automatically

Documentation

• SDK_USAGE.md — SDK initialization, full StoreConfig, testing
• QUICK_REFERENCE.md — cheat sheet: events, paths, utils
• Historical: ../docs/archive/DUAL_CONTEXT_FLOW.md (describes the removed dual-context architecture)