Colleciones

Colleciones is a structured, semantic tracking framework that lets you describe and dispatch events with clarity and precision. It introduces a fluent event model that is both developer-friendly and analytics-ready.

Why Colleciones?

Most tracking systems suffer from inconsistent event naming and arbitrary structure. Colleciones solves this by building events around a shared semantic structure — entity, action, actor, context, and references — modeled as natural-language chains or structured code.

📖 See docs/concept.md for the full background.

How to Use It

1. Create an Emitter

An emitter is responsible for collecting and sending events to a server.

import { CollecionesEmitter } from './index.js';

const emitter = new CollecionesEmitter('/collect', 5, 10000);

2. Create a Tracker

A tracker enriches and routes events to one or more emitters.

import { CollecionesTracker } from './index.js';

const tracker = new CollecionesTracker([emitter], 'myTracker', 'myApp');

3. Build Events with the DSL

You can construct events declaratively using a natural language-like DSL:

Most simplistic use case

import collecionesDsl from './src/collecionesDsl.js';

collecionesDsl
  .the('button')              // Entity
  .has.been('clicked')        // Verb
  .then.track.with(emitter);  // Send

Adding adjectives (states etc) onto the entity

import collecionesDsl from './src/collecionesDsl.js';

collecionesDsl
  .the('red')               // So now this is the adjective
  ._('button')              // and this becomes the entity
  .has.been('clicked')      // still the verb
  .then.track.with(emitter);

Full syntax:

import collecionesDsl from './src/collecionesDsl.js';

collecionesDsl
  the('dark')               // adjective 1
  .and('green')             // adjective 2
  ._('button')              // the entity
    .identified.by('id')          // the identifier-name for the entity
    .as('button12')               // the identifier-value for the entity
    .and.by('externalReference')  // yet another reference
    .as ('ext-123')               // and it's idnetifier value     
  .has.been('clicked')      // the verb
  .by('user')               // the actor (a user or a system or ..)
    .identified.by('usrId')   // an id for a user
    .as('abc-123')            // the id value
    .and('email')             // another id for the user
    .as('[email protected]')      // the id value
  .with('sourcePage').set.to('homepage')  // context
  .and('ctaLabel').set.to('register-now') // context
  .including.a('property').collection()
    .with
      .item.identified.by('propertyId').as('1')
        .and.by('externalId').as('12')
      .and.item.identified.by('propertyId').as('2')
        .and.by('externalId').as('13')
  .and.a('suggest').collection()
    .with
      .item.identified.by('suggestionId').as('1')
      .and.item.identified.by('suggestionId').as('2')
  .referring.to('property') // to what entities this event refers
    .identified.by('id') // optional
    .as('123') // required when preceding with 'identified'
  .conform.to('UserInteractionEvent') // if applicable which schema it should follow
      .then.track.with(emitter);

📘 See docs/dsl.md for full DSL documentation.

4. Manually Create Events (Optional)

You can also build structured events directly via the event class. Below are examples for all main options supported by the DSL:

import { CollecionesEvent } from './index.js';

const event = new CollecionesEvent();
// Entity and Adjectives
event.setEntity('button');
event.addAdjective('dark');
event.addAdjective('green');

// Entity Identifiers
event.setIdentifier('id', 'button12');
event.setIdentifier('externalReference', 'ext-123');

// Action
event.setAction('clicked');

// Actor and Actor Identifiers
event.setActor('user');
event.setActorIdentifier('usrId', 'abc-123');
event.setActorIdentifier('email', '[email protected]');

// Context
event.setContext('sourcePage', 'homepage');
event.setContext('ctaLabel', 'register-now');

// Collections
// Property collection
// Add first property item
const propertyKey1 = event.setCollectionItem('property');
event.setCollectionItemReference('property', propertyKey1, 'propertyId', '1');
event.setCollectionItemReference('property', propertyKey1, 'externalId', '12');
// Add second property item
const propertyKey2 = event.setCollectionItem('property');
event.setCollectionItemReference('property', propertyKey2, 'propertyId', '2');
event.setCollectionItemReference('property', propertyKey2, 'externalId', '13');
// Suggest collection
const suggestKey1 = event.setCollectionItem('suggest');
event.setCollectionItemReference('suggest', suggestKey1, 'suggestionId', '1');
const suggestKey2 = event.setCollectionItem('suggest');
event.setCollectionItemReference('suggest', suggestKey2, 'suggestionId', '2');

// References
// Reference to property entity
event.setRefence('property');
event.setRefenceIdentifier('property', 'id', '123');

// Schema
event.setSchema('UserInteractionEvent');

// Send the event
tracker.track(event);

This example covers all main options: entity, adjectives, identifiers, action, actor, actor identifiers, context, collections, references, and schema.

---

## Learn More

- 🧠 [Concept](./docs/concept.md)
- 🏗️ [Architecture](./docs/architecture.md)
- 🔄 [Emitters & Trackers](./docs/emitterAndTracker.md)
- ✍️ [DSL Syntax](./docs/dsl.md)
- 📦 [Event Structure](./docs/events.md)

## one more thing
It is also available in gtm 
This is a real real pain 
All things gtm can be found here:
🤕 [Gtm](./docs/gtm/readme.md)