Full documentation: docs/00-README.md — envelope contract, the two env-var families, the consumer, why OutboxHandler is not a transactional outbox, and why NATS replaced Kafka.

@nebulae/tpiv2-event-store

Librería CommonJS de Nebula Engineering para eventos de dominio de TPI V2. Usa NATS JetStream para transporte y MongoDB 8 para outbox, dead-letter y reproceso.

Instalación

npm install @nebulae/tpiv2-event-store

Configuración

Variables principales:

| Variable | Propósito | Valor por defecto | | --- | --- | --- | | EVENTSTORE_ENABLED | Habilita productor y consumidor | true | | EVENTSTORE_SERVERS | Servidores NATS separados por coma | nats://localhost:4222 | | EVENTSTORE_CLIENT_ID | Identificador del cliente | definido por el µService | | EVENTSTORE_STREAM_NAME | Stream de JetStream | TPIV2_EVENTS | | EVENTSTORE_SUBJECT_PREFIX | Prefijo de subjects | evt | | EVENTSTORE_DURABLE_NAME | Identidad durable del consumidor | EVENTSTORE_CLIENT_ID | | EVENTSTORE_ENSURE_TOPICS_MODE | create, verify o skip | create | | EVENT_STORE_MONGODB_URL | URI de MongoDB; activa outbox y dead-letter | desactivado | | EVENT_STORE_MONGODB_DATABASE | Base de datos operacional | event-store | | EVENT_STORE_OUTBOX_CONTAINER | Coleccion de outbox | outbox | | EVENT_STORE_DEAD_LETTER_CONTAINER | Coleccion dead-letter | dead-letters |

En GKE, el stream y sus políticas deben aprovisionarse por IaC. Las credenciales se suministran mediante Kubernetes Secret sincronizado con Secret Manager.

Uso

const { EventStore, Event } = require("@nebulae/tpiv2-event-store");

const store = new EventStore({
  clientId: "organization-mng",
  groupId: "organization-mng",
  prod: { mse: "organization", mbe: "organization-mng" },
});

store.emit$(new Event({
  eventType: "OrganizationUpdated",
  aggregateType: "Organization",
  aggregateId: "org-1",
  organizationId: "nebulae",
  data: { name: "Nebula Engineering" },
}));

store.configAggregateEventMap({
  Organization: {
    OrganizationUpdated: { autoAck: false },
  },
});

aggregateVersion is always derived from timestamp as Unix epoch seconds. Callers cannot override it with a database revision.

Las claves de aggregate del mapa se instalan como filtros JetStream del durable (evt.Organization.*). El servicio no recibe aggregates que no declaró. Esta topología no usa particiones: hay un stream ordenado y un solo mensaje pendiente de ack por durable. El envelope no incluye claves de partición del broker.

La API conserva productor/consumidor reactivos, circuit breaker, reintentos, mapeo de subjects, outbox, dead-letter y reproceso. Consulte test/ para ejemplos ejecutables y playground/ para el entorno local con MongoDB 8 y NATS JetStream.

Publicación

GitLab CI valida y publica el paquete público en npmjs mediante trusted publishing con OIDC. El nombre del paquete es @nebulae/tpiv2-event-store.

Propiedad

• Empresa: Nebula Engineering
• Proyecto: TPI (Transporte Publico Individual) V2

Licencia

MIT. Consulte LICENSE. El aviso de copyright y la licencia deben conservarse en las copias o porciones sustanciales del software.