@compilacion/colleciones-clientos 1.0.12 → 2.0.0

package/dist/index.cjs

@@ -1,58 +1,7 @@
 'use strict';
 
 // helper 'private' functions
-/**
- * Converts a snake_case string to camelCase.
- * Removes non-ASCII characters.
- * @param {string} str
- * @returns {string}
- */
-const underscoreToCamelCase = function (str) {
-    str = str.replace(/[^\x00-\x7F_]/g, '');
-    return str
-        .split('_')
-        .map((word, index) => {
-            if (index === 0) {
-                return word;
-            }
-            return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
-        })
-        .join('');
-};
 
-/**
- * Formats adjectives by converting them to camelCase strings.
- * Accepts a single string or an array of strings.
- * @param {string|string[]|undefined} adjectiveParameter
- * @returns {string[]|undefined}
- */
-const formatAdjectives = function (adjectiveParameter) {
-    const errorMsg = new Error('Adjective must be a string, an array of strings, or undefined');
-    if (typeof adjectiveParameter === 'undefined') {
-        return undefined;
-    }
-    if (typeof adjectiveParameter === 'string') {
-        return [underscoreToCamelCase(adjectiveParameter)];
-    }
-    if (Array.isArray(adjectiveParameter) && adjectiveParameter.every(item => typeof item === 'string')) {
-        return adjectiveParameter.map(adjective => underscoreToCamelCase(adjective));
-    }
-    throw errorMsg;
-};
-
-/**
- * Converts an array of adjective strings to a dot-prefixed, dot-separated string.
- * Removes duplicates and sorts alphabetically.
- * @param {string[]} adjective
- * @returns {string|undefined}
- */
-const stringifyAdjectives = function (adjective) {
-    if (!Array.isArray(adjective) || adjective.length === 0) {
-        return undefined;
-    }
-    const uniqueSorted = [...new Set(adjective)].sort();
-    return '.' + uniqueSorted.join('.');
-};
 
 /**
  * Encodes a string to Base64.
@@ -94,171 +43,264 @@ const getBrowserContext = function() {
 
 /**
  * Base class representing a structured event with timestamp, identifiers, and data fields.
+ * This class is used to model events in a semantic and structured format for tracking purposes.
  */
-class CollecionesBaseEvent {
+class CollecionesEvent {
 
     /**
      * Constructs a new event with default metadata and timestamps.
      */
     constructor() {
-        this.eventName = '';
-        this.data = {};
-        this.data.meta = {
-            eventFormat: 'CollecionesBaseEvent',
+        // initialize event properties
+        this.entity = '';
+        this.adjevtives = [];
+        this.identifiers = {};
+        this.action = '';
+        this.actor = {
+            name:'', 
+            identifiers: []
+        };
+        this.context = {};
+        this.references = {};
+        // set default values
+        this.meta = {
+            eventFormat: 'CollecionesEvent',
             eventFormatVersion: '1'
         };
-        this.data.timestamps = {};
-        this.data.timestamps.clientDatetimeUtc = new Date().toISOString();
+        this.meta.tracker = '';
+        this.meta.app = '';
+        this.meta.timestamps = {};
+        this.meta.timestamps.clientDatetimeUtc = new Date().toISOString();
         if (typeof window !== 'undefined' && typeof navigator !== 'undefined' && navigator.language) {
-            this.data.timestamps.clientDatetimeLocal = new Date(Date.now() - new Date().getTimezoneOffset() * 60000).toISOString();
-            this.data.timestamps.timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
-            this.data.timestamps.timeZoneOffset = new Date().getTimezoneOffset();
+            this.meta.timestamps.clientDatetimeLocal = new Date(Date.now() - new Date().getTimezoneOffset() * 60000).toISOString();
+            this.meta.timestamps.timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+            this.meta.timestamps.timeZoneOffset = new Date().getTimezoneOffset();
         } else {
-            this.data.timestamps.clientDatetimeLocal = new Date().toISOString();
-            this.data.timestamps.timeZone = 'UTC';
+            this.meta.timestamps.clientDatetimeLocal = new Date().toISOString();
+            this.meta.timestamps.timeZone = 'UTC';
         }
     }
 
     /**
-     * Sets the event name.
-     * @param {string} name
+     * Returns the declared event format.
+     * @returns {string} The format name (e.g. 'CollecionesEvent').
      */
-    setEventName(name) {
-        this.eventName = name;
+    getEventFormat() {
+        let v = this.meta?.eventFormat;
+        return (typeof v !== 'undefined') ? v : '1';
     }
 
     /**
-     * Returns the event name.
-     * @returns {string}
+     * Returns the version of the event format.
+     * @returns {string} The format version string.
      */
-    getEventName() {
-        return this.eventName;
+    getEventFormatVersion() {
+        let v = this?.meta?.eventFormatVersion;
+        return (typeof v !== 'undefined') ? v : 'CollecionesEvent';
     }
 
     /**
-     * Gets the format of the event.
-     * @returns {string}
+     * Overrides or supplements the event's timestamp fields with custom values.
+     * @param {object} dateTimeObject - Key-value pairs to merge into the existing timestamp object.
      */
-    getEventFormat() {
-        let v = this.data?.meta?.eventFormat;
-        return (typeof v !== 'undefined') ? v : '1';
+    overrideDatetime(dateTimeObject = {}) {
+        for (const [key, value] of Object.entries(dateTimeObject)) {
+            this.meta.timestamps[key] = value;
+        }
     }
 
     /**
-     * Gets the version of the event format.
-     * @returns {string}
+     * Sets the name of the tracker responsible for generating this event.
+     * @param {string} name - Tracker name.
      */
-    getEventFormatVersion() {
-        let v = this.data?.meta?.eventFormatVersion;
-        return (typeof v !== 'undefined') ? v : 'CollecionesBaseEvent';
+    setTracker(name) {
+        this.meta.tracker = name;
     }
 
     /**
-     * Replaces the entire data object.
-     * @param {object} data
+     * Sets the name of the application that generated the event.
+     * @param {string} name - Application name.
      */
-    setData(data) {
-        this.data = data;
+    setAppName(name) {
+        this.meta.appName = name;
     }
 
     /**
-     * Adds a field to the event's custom fields section.
-     * @param {string} name
-     * @param {*} value
+     * Sets the expected schema name for this event.
+     * @param {string} schema - The name of the schema.
      */
-    addAttribute(name, value) {
-        return this.addField(name, value);
+    setSchema(schema) {
+        if (typeof schema !== 'string') {
+            throw new Error('Schema must be a string');
+        }
+        this.meta.schema = schema;
     }
 
     /**
-     * Adds a key-value pair to the custom fields.
-     * @param {string} name
-     * @param {*} value
+     * Sets the entity (subject) of the event.
+     * @param {string} entity - The entity name.
+     */
+    setEntity = function(entity) {
+        this.entity = entity;
+    }
+    
+    /**
+     * Defines the main action of the event (e.g., 'clicked').
+     * @param {string} action - The action string.
      */
-    addField(name, value) {
-        if (typeof this.data.fields !== 'object' || this.data.fields === null) {
-            this.data.fields = {};
+    setAction = function(action) {
+        this.action = action;
+    }
+
+    /**
+     * Adds an adjective that describes the entity in more detail.
+     * @param {string} adjective - An adjective string.
+     */
+    addAdjective = function(adjective) {
+        if (typeof adjective !== 'string') {
+            throw new Error('Adjective must be a string');
         }
-        this.data.fields[name] = value;
+        this.adjevtives.push(adjective);
     }
 
     /**
-     * Sets the name of the tracker used to generate the event.
-     * @param {string} name
+     * Adds or updates an identifier for the primary entity.
+     * @param {string} name - The identifier key.
+     * @param {*} identifier - The identifier value.
      */
-    setTracker(name) {
-        this.data.tracker = name;
+    setIdentifier = function(name, identifier) {
+        if (typeof name !== 'string') {
+            throw new Error('Identifier name must be a string');
+        }
+        this.identifiers[name] = identifier;
     }
 
     /**
-     * Sets the name of the application that created the event.
-     * @param {string} name
+     * Defines the name of the actor (who or what performed the action).
+     * @param {string} name - Actor name (e.g., 'user').
      */
-    setAppName(name) {
-        this.data.appName = name;
+    setActor = function(name) {
+        if (typeof name !== 'string') {
+            throw new Error('Actor name must be a string');
+        }
+        this.actor.name = name;
     }
 
     /**
-     * Adds multiple identifiers from an object.
-     * @param {object} param
+     * Adds or updates an identifier for the actor.
+     * @param {string} name - Identifier name.
+     * @param {*} identifier - Identifier value.
      */
-    convertParamIdentifiers(param) {
-        if (typeof param === 'object' && param !== null && !Array.isArray(param)) {
-            for (const [key, value] of Object.entries(param)) {
-                this.addIdentifier(key, value);
-            }
+    setActorIdentifier = function(name, identifier) {
+        if (typeof name !== 'string') {
+            throw new Error('Actor Identifier name must be a string');
         }
+        this.actor.identifiers[name] = identifier;
     }
 
     /**
-     * Adds a single identifier to the event.
-     * @param {string} name
-     * @param {*} value
+     * Adds contextual information to the event.
+     * @param {string} context - The key of the context field.
+     * @param {*} value - The value of the context field.
      */
-    addIdentifier(name, value) {
-        if (typeof this.data.identifiers !== 'object' || this.data.identifiers === null) {
-            this.data.identifiers = {};
+    setContext = function(context, value) {
+        if (typeof context !== 'string') {
+            throw new Error('Context must be a string');
         }
-        this.data.identifiers[name] = value;
+        this.context[context] = value;
     }
 
     /**
-     * Constructs the postable event object with metadata and encoded payload.
-     * @returns {object}
+     * Declares an entity referenced by this event.
+     * @param {string} entity - The referenced entity name.
      */
-    getPostObject() {
-        this.data.timestamps.sendDatetimeUtc = new Date().toISOString();
-        this.data.timestamps.sendDatetimeLocal = new Date(Date.now() - new Date().getTimezoneOffset() * 60000).toISOString();
-        return {
-            eventname: this.getEventName(),
-            eventFormat: this.getEventFormat(),
-            eventFormatVersion: this.getEventFormatVersion(),
-            payload: toBase64(this.getPayload())
-        };
+    setRefence = function(entity) {
+        if (typeof entity !== 'string') {
+            throw new Error('Referenced entity must be a string');
+        }
+        if(this.references[entity] === undefined) {
+            this.references[entity] = {identifiers: {}};
+        }
     }
 
     /**
-     * Overrides or extends the timestamp fields of the event.
-     * @param {object} dateTimeObject
+     * Adds or updates an identifier for a referenced entity.
+     * @param {string} entity - The referenced entity name.
+     * @param {string} name - The identifier key.
+     * @param {*} identifier - The identifier value.
      */
-    overrideDatetime(dateTimeObject = {}) {
-        for (const [key, value] of Object.entries(dateTimeObject)) {
-            this.data.timestamps[key] = value;
+    setRefenceIdentifier = function(entity, name, identifier) {
+        if (typeof entity !== 'string') {
+            throw new Error('Referenced entity name must be a string');
+        }
+        if (typeof name !== 'string') {
+            throw new Error('Actor Identifier name must be a string');
         }
+        this.setRefence(entity);
+        this.references[entity].identifiers[name] = identifier;
     }
 
     /**
-     * Serializes the event data to a JSON string.
-     * @returns {string}
+     * Serializes the event to a plain object suitable for JSON.stringify().
+     * @returns {object}
      */
-    getPayload() {
-        return JSON.stringify(this.data);
+    toJSON() {
+        return {
+            class: 'CollecionesEvent',
+            entity: this.entity,
+            adjectives: this.adjevtives,
+            identifiers: this.identifiers,
+            action: this.action,
+            actor: this.actor,
+            context: this.context,
+            references: this.references,
+            meta: this.meta
+        };
     }
 
+    /**
+     * Recreates an instance of CollecionesEvent from a plain object.
+     * @param {object} obj
+     * @returns {CollecionesEvent}
+     */
+    static fromJSON(obj) {
+        if (!obj || obj.class !== 'CollecionesEvent') {
+            throw new Error('Invalid or missing event class type');
+        }
+        const instance = new CollecionesEvent();
+        instance.entity = obj.entity;
+        instance.adjevtives = obj.adjectives || [];
+        instance.identifiers = obj.identifiers || {};
+        instance.action = obj.action;
+        instance.actor = obj.actor || { name: '', identifiers: {} };
+        instance.context = obj.context || {};
+        instance.references = obj.references || {};
+        instance.meta = obj.meta || {};
+        return instance;
+    }
+    
 }
 
 /**
- * Emitter class responsible for batching and sending events to a configured endpoint.
+ * CollecionesEmitter
+ * -------------------
+ * This class collects and sends event objects to a remote endpoint (e.g., an event collector API).
+ * It is used in both client- and server-side tracking scenarios, typically in combination with
+ * CollecionesEvent or subclasses like CollecionesBaseEvent.
+ *
+ * Behavior:
+ * - Events are buffered via `.track()` or `.trackAsync()`.
+ * - If the number of buffered events reaches `flushSize`, the buffer is automatically flushed.
+ * - If `flushInterval` is provided, the buffer is flushed at a fixed interval.
+ * - Flushing serializes each event using `.toJSON()`, encodes it with base64, and posts
+ *   the resulting array to the configured endpoint.
+ *
+ * Example usage:
+ *   const emitter = new CollecionesEmitter('/track', 5, 10000);
+ *   emitter.track(new CollecionesEvent());
+ *
+ * Note:
+ * This class is stateful. To stop periodic flushing, call `.stopTimer()` when the emitter is no longer in use.
  */
 class CollecionesEmitter {
 
@@ -278,6 +320,7 @@ class CollecionesEmitter {
 
     /**
      * Starts the flush timer if a valid interval is set.
+     * @returns {void}
      */
     startTimer() {
         this.stopTimer();
@@ -288,6 +331,7 @@ class CollecionesEmitter {
 
     /**
      * Starts the flush timer only if not already running.
+     * @returns {void}
      */
     startTimerIfStopped() {
         if (!this.timer) {
@@ -297,6 +341,7 @@ class CollecionesEmitter {
 
     /**
      * Stops the active flush timer.
+     * @returns {void}
      */
     stopTimer() {
         if (this.timer) {
@@ -307,23 +352,28 @@ class CollecionesEmitter {
 
     /**
      * Adds an event to the buffer and flushes if threshold is reached.
-     * @param {CollecionesBaseEvent} event
+     * Validates that the event is an instance of CollecionesEvent to ensure correct event type.
+     * @param {CollecionesEvent} event - Event instance to be tracked.
+     * @throws {Error} Throws if event is not a CollecionesEvent instance.
+     * @returns {void}
      */
     track(event) {
-        if (!(event instanceof CollecionesBaseEvent)) {
-            throw new Error('Event must be an instance of CollecionesBaseEvent');
+        if (!(event instanceof CollecionesEvent)) {
+            throw new Error('Event must be an instance of CollecionesEvent');
         }
         this.trackAsync(event);
     }
 
     /**
      * Asynchronously adds an event and flushes if the buffer size is exceeded.
-     * @param {CollecionesBaseEvent} event
-     * @returns {Promise<void>}
+     * Validates that the event is an instance of CollecionesEvent to ensure correct event type.
+     * @param {CollecionesEvent} event - Event instance to be tracked asynchronously.
+     * @throws {Error} Throws if event is not a CollecionesEvent instance.
+     * @returns {Promise<void>} Resolves when event is added and flush triggered if needed.
      */
     async trackAsync(event) {
-        if (!(event instanceof CollecionesBaseEvent)) {
-            throw new Error('Event must be an instance of CollecionesBaseEvent');
+        if (!(event instanceof CollecionesEvent)) {
+            throw new Error('Event must be an instance of CollecionesEvent');
         }
         this.startTimerIfStopped();
         this.buffer.push(event);
@@ -331,8 +381,11 @@ class CollecionesEmitter {
     }
 
     /**
-     * Sends the buffered events to the server and clears the buffer.
-     * @returns {Promise<boolean|undefined>}
+     * Sends all buffered events in a single POST request to the server.
+     * Each event is serialized via `.toJSON()` and encoded as a base64 string.
+     * Response status is checked for HTTP success; errors are logged but not thrown.
+     *
+     * @returns {Promise<boolean|undefined>} Resolves true if flush was triggered, or undefined if buffer was empty.
      */
     async flush() {
         if (this.buffer.length === 0) return;
@@ -340,7 +393,7 @@ class CollecionesEmitter {
         this.buffer = [];
         let postPayload = [];
         eventsToSend.forEach((e) => {
-            postPayload.push( e.getPostObject() );
+            postPayload.push( toBase64( JSON.stringify(e.toJSON())) );
         });
         this.stopTimer();
         try {
@@ -380,22 +433,13 @@ class CollecionesTracker {
         this.identifiers = {};
     }
 
-    /**
-     * Adds a global identifier to be included with every event.
-     * @param {string} name - Identifier key.
-     * @param {*} value - Identifier value.
-     */
-    addIdentifier(name, value) {
-        this.identifiers[name] = value;
-    }
-
     /**
      * Sends an event to all emitters after enriching it with identifiers and metadata.
-     * @param {CollecionesBaseEvent} collecionesEvent - The event to be sent.
-     * @throws {Error} If the input is not an instance of CollecionesBaseEvent.
+     * @param {CollecionesEvent} collecionesEvent - The event to be sent.
+     * @throws {Error} If the input is not an instance of CollecionesEvent.
      */
     track(collecionesEvent) {
-        if (!(collecionesEvent instanceof CollecionesBaseEvent)) {
+        if (!(collecionesEvent instanceof CollecionesEvent)) {
             throw new Error('Event must be of type CollecionesEvent');
         }
         for (const [key, value] of Object.entries(this.identifiers)) {
@@ -426,214 +470,253 @@ class CollecionesWebTracker extends CollecionesTracker {
 
     /**
      * Tracks an event, enriching it with browser context information.
-     * @param {CollecionesBaseEvent} collecionesEvent - The event object to track.
-     * @throws {Error} If the event is not an instance of CollecionesBaseEvent.
+     * @param {CollecionesEvent} collecionesEvent - The event object to track.
+     * @throws {Error} If the event is not an instance of CollecionesEvent.
      */
     track(collecionesEvent) {
-        if (!(collecionesEvent instanceof CollecionesBaseEvent)) {
+        if (!(collecionesEvent instanceof CollecionesEvent)) {
             throw new Error('Event must be of type CollecionesEvent');
         }
-        collecionesEvent.addField('browserContext', getBrowserContext());
+        collecionesEvent.setContext('browserContext', getBrowserContext());
         super.track(collecionesEvent);        
     }
 }
 
 /**
- * Represents a semantic event with a name, data payload, and identifiers.
- * Extends CollecionesBaseEvent.
+ * Colleciones DSL
+ * ---------------
+ * This module provides a fluent, human-readable DSL (domain-specific language) for constructing
+ * structured tracking events based on CollecionesBaseEvent. Each step in the chain represents
+ * a semantically meaningful piece of the event: the entity, the action, the actor, references, etc.
+ *
+ * Entry Point:
+ *   collecionesDsl.the('dark')
+ *
+ * Chaining:
+ *   - .and('...')                    : add additional adjectives
+ *   - ._('entity')                  : specify the entity being acted on
+ *   - .identified.by('field')      : declare primary identifier for the subject
+ *   - .has.been('action')          : declare what happened
+ *   - .by('actor')                 : describe the actor performing the action
+ *   - .identified.by('id')        : add identifiers for the actor
+ *   - .with('key').set.to('val')  : add contextual data fields
+ *   - .referring.to('entity')     : describe referenced/related entities
+ *   - .identified.by('refId')     : add identifiers for the reference
+ *   - .conform.to('SchemaName')   : attach schema metadata
+ *   - .then.track.with(emitter)   : finalize and emit the event
+ *
+ * Each function in the chain passes forward a scoped version of the CollecionesBaseEvent instance,
+ * and enforces semantic constraints (e.g. `.as()` is required after `.by()`).
+ *
+ * Internal:
+ *   - Uses setRefence / setRefenceIdentifier for references
+ *   - Uses helpers.getEvent() for test access
+ *   - Uses instanceof CollecionesEmitter for validation
+ *
+ * This file is designed for internal use by developers building with the Colleciones tracking model.
  */
-class CollecionesEvent extends CollecionesBaseEvent {
 
-    /**
-     * Constructs a new CollecionesEvent instance.
-     * @param {string} name - The name of the event.
-     * @param {object} data - The main data payload of the event.
-     * @param {object} identifiers - A set of identifiers to associate with the event.
-     */
-    constructor(name, data, identifiers) {
-        super();
-        this.setEventName(name);
-        Object.assign(this.data, data);
-        this.convertParamIdentifiers(identifiers);
-    }
 
-}
+let init = (entity) => {
+    return ((entity)=>{
+        let eventInstance = new CollecionesEvent(); // Core event object
+        eventInstance.setEntity(entity);
 
-const byteToHex = [];
-for (let i = 0; i < 256; ++i) {
-    byteToHex.push((i + 0x100).toString(16).slice(1));
-}
-function unsafeStringify(arr, offset = 0) {
-    return (byteToHex[arr[offset + 0]] +
-        byteToHex[arr[offset + 1]] +
-        byteToHex[arr[offset + 2]] +
-        byteToHex[arr[offset + 3]] +
-        '-' +
-        byteToHex[arr[offset + 4]] +
-        byteToHex[arr[offset + 5]] +
-        '-' +
-        byteToHex[arr[offset + 6]] +
-        byteToHex[arr[offset + 7]] +
-        '-' +
-        byteToHex[arr[offset + 8]] +
-        byteToHex[arr[offset + 9]] +
-        '-' +
-        byteToHex[arr[offset + 10]] +
-        byteToHex[arr[offset + 11]] +
-        byteToHex[arr[offset + 12]] +
-        byteToHex[arr[offset + 13]] +
-        byteToHex[arr[offset + 14]] +
-        byteToHex[arr[offset + 15]]).toLowerCase();
-}
+        let helpers = {
+            getEvent: () => {
+                return eventInstance;
+            },
+        };
 
-let getRandomValues;
-const rnds8 = new Uint8Array(16);
-function rng() {
-    if (!getRandomValues) {
-        if (typeof crypto === 'undefined' || !crypto.getRandomValues) {
-            throw new Error('crypto.getRandomValues() not supported. See https://github.com/uuidjs/uuid#getrandomvalues-not-supported');
-        }
-        getRandomValues = crypto.getRandomValues.bind(crypto);
-    }
-    return getRandomValues(rnds8);
-}
+        // DSL function groups
+        let andEntity = () => {}; // .and(...) chaining after the()
+        let setEntityAfterAnd = () => {}; // ._('entity') after .and
+        let setEntityIdentifiers = () => {}; // .identified.by(...) for main subject
+        let setAction = () => {}; // .has.been(...) for action
+        let setActor = () => {}; // .by('actor')
+        let setActorIdentifier = () => {}; // .identified.by(...) inside .by(...)
+        let addContext = () => {}; // .with(...).set.to(...)
+        let addReference = () => {}; // .referring.to(...)
+        let getAddReference = () => {}; // .identified.by().as() inside .referring
+        let addReferenceIdentifier = () => {}; // .and(...) after reference
+        let conformingTo = () => {}; // .conform.to('SchemaName')
+        let track = () => {}; // .then.track.with(emitter)
+
+        // Adjective chaining: .and(...)._('entity')
+        setEntityAfterAnd = (entity) => {
+            eventInstance.addAdjective(eventInstance.entity);
+            eventInstance.setEntity(entity);
+            return {
+                as: () => {
+                    return { helpers }
+                },
+                identified: {
+                    by: setEntityIdentifiers
+                },
+                has: { been: setAction },
+                helpers
+            };
+        };
 
-const randomUUID = typeof crypto !== 'undefined' && crypto.randomUUID && crypto.randomUUID.bind(crypto);
-var native = { randomUUID };
+        // Identifier setup: .identified.by().as()
+        setEntityIdentifiers = (name) => {
+            eventInstance.setIdentifier(name, null);
+            return {
+                as: (value) => {
+                    eventInstance.setIdentifier(name, value);
+                    return {
+                        helpers,
+                        and: {
+                            by: setEntityIdentifiers
+                        },
+                        has: { been: setAction },
+                    }
+                },
+                helpers
+            };
+        };
 
-function v4(options, buf, offset) {
-    if (native.randomUUID && true && !options) {
-        return native.randomUUID();
-    }
-    options = options || {};
-    const rnds = options.random ?? options.rng?.() ?? rng();
-    if (rnds.length < 16) {
-        throw new Error('Random bytes length must be >= 16');
-    }
-    rnds[6] = (rnds[6] & 0x0f) | 0x40;
-    rnds[8] = (rnds[8] & 0x3f) | 0x80;
-    return unsafeStringify(rnds);
-}
+        // Additional adjectives: .and('...')._()
+        andEntity = (entity) => {
+            eventInstance.addAdjective(eventInstance.entity);
+            eventInstance.setEntity(entity);
+            return {
+                and: andEntity,
+                _ : setEntityAfterAnd,
+                helpers
+            }
+        };
 
-/**
- * Represents a structured semantic event with entity, action, and optional adjective.
- * Includes automatic naming and identifier mapping.
- * Extends CollecionesBaseEvent.
- */
-class CollecionesSemanticEvent extends CollecionesBaseEvent {
+        // Action: .has.been('...')
+        setAction = (action) => {
+            eventInstance.setAction(action);
+            return {
+                by: setActor,
+                referring: { to: addReference },
+                with: addContext,
+                conform: {to: conformingTo},
+                then: {track: {with: track}},
+                helpers
+            }
+        };
 
-    /**
-     * Constructs a new semantic event.
-     * @param {string} entity - The entity involved in the event.
-     * @param {string} action - The action performed on the entity.
-     * @param {string|string[]|undefined} adjective - Optional adjective(s) modifying the event.
-     * @param {object} identifiers - Key-value pairs to be added as identifiers.
-     */
-    constructor(entity, action, adjective, identifiers) {
-        super();
-        this.entity = underscoreToCamelCase(entity);
-        this.action = underscoreToCamelCase(action);
-        this.adjective = formatAdjectives(adjective);
-        let adjectiveString = stringifyAdjectives(this.adjective);
-        this.eventName = `${this.entity}${(adjectiveString !== undefined) ? adjectiveString : ''}__${this.action}`;
-        this.convertParamIdentifiers(identifiers);
-        this.data.entityIdentifiers = {};
-        this.data.attributes = {};
-        this.data.clientEventId = v4();
-        this.data.meta = {
-            eventFormat: 'CollecionesSemanticEvent',
-            eventFormatVersion: '1'
+        // Actor: .by('user')
+        setActor = (name) => {
+            eventInstance.setActor(name);
+            return { 
+                identified: {
+                    by: setActorIdentifier
+                },
+                with: addContext,
+                helpers
+            }
         };
-    }
 
-    /**
-     * This method is deprecated in semantic events and will throw if called.
-     * @throws {Error}
-     */
-    setData() {
-        throw new Error('setData deprecated in semantic events');
-    }
+        // Actor identifier: .identified.by().as()
+        setActorIdentifier = (name) => {
+            return {
+                as: (value) => {
+                    eventInstance.setActorIdentifier(name, value);
+                    return {
+                        helpers,
+                        and: setActorIdentifier,
+                        with: addContext,
+                        referring: { to: addReference },
+                    }
+                },
+                helpers
+            }
+        };
 
-    /**
-     * Adds a key-value pair as an identifier for the semantic entity.
-     * @param {string} key - The identifier name.
-     * @param {string|number} value - The identifier value.
-     * @throws Will throw if key is not a string or value is not a string or number.
-     */
-    addEntityIdentifier(key, value) {
-        if (typeof key !== 'string') {
-            throw new Error('Entity identifier key must be a string');
-        }
-        if (typeof value !== 'string' && typeof value !== 'number') {
-            throw new Error('Entity identifier value must be a string or number');
-        }
-        this.data.entityIdentifiers[key] = value;
-    }
+        // Contextual field: .with('key').set.to('value')
+        addContext = (context) => {
+            return {
+                helpers,
+                set: {
+                    to: (value) => {
+                        eventInstance.setContext(context, value);
+                        return {
+                            helpers,
+                            and: addContext,
+                            referring: { to: addReference },
+                        }
+                    }
+                }
+            }
+        };
 
-}
+        // Reference: .referring.to('...')
+        addReference = (entity) => {
+            eventInstance.setRefence(entity);
+            return {
+                identified: {
+                    by: getAddReference(entity)
+                },
+                conform: {to: conformingTo},
+                then: {track: {with: track}},
+                helpers
+            }
+        };
 
-/**
- * Represents a semantic event related to a collection of entities.
- * Extends CollecionesSemanticEvent and adds item-level detail and identifiers.
- */
-class CollecionesSemanticCollectionEvent extends CollecionesSemanticEvent {
+        // Reference identifier setup: .identified.by().as()
+        getAddReference = (entity) => {
+            return (name) => {
+                return {
+                    as: (value) => {
+                        eventInstance.setRefenceIdentifier(entity, name, value);
+                        return {
+                            helpers,
+                            and: addReferenceIdentifier,
+                            conform: {to: conformingTo},
+                            then: {track: {with: track}},
+                        }
+                    },
+                    helpers,
+                };
+            };
+        };
 
-    /**
-     * Constructs a new CollecionesSemanticCollectionEvent.
-     * @param {string} itemEntity - The name of the item entity being acted on.
-     * @param {string} action - The action performed.
-     * @param {string|string[]|undefined} adjective - Optional adjective(s) describing the action.
-     * @param {object} identifiers - Identifiers associated with the event.
-     * @param {string} [collectionEntity] - Optional collection name, defaults to `${itemEntity}Collection`.
-     */
-    constructor(itemEntity, action, adjective, identifiers, collectionEntity) {
-        if (typeof collectionEntity == 'undefined') {
-            collectionEntity = `${itemEntity}Collection`;
-        }
-        super(collectionEntity, action, undefined, identifiers);
-        this.data.meta = {
-            eventFormat: 'CollecionesSemanticCollectionEvent',
-            eventFormatVersion: '1'
+        // Schema declaration: .conform.to('...')
+        conformingTo = (name) => {
+            eventInstance.setSchema(name);
+            return { 
+                then: {track: {with: track}},
+                helpers
+            }
         };
-        this.adjective = formatAdjectives(adjective);
-        let adjectiveString = stringifyAdjectives(this.adjective);
-        itemEntity = underscoreToCamelCase(itemEntity);
-        this.data.itemEntity = itemEntity;
-        this.data.itemEventName = `${itemEntity}${(adjectiveString !== undefined) ? adjectiveString : ''}__${this.action}`;
-        this.data.entityItemIdentifiers = {};
-    }
 
-    /**
-     * Adds an identifier value (or values) for a specific entity item key.
-     * @param {string} key - The identifier name.
-     * @param {string|number|Array<string|number>} value - The identifier value(s).
-     * @throws Will throw if key is not a string or value is of invalid type.
-     */
-    addEntityItemIdentifier(key, value) {
-        if (typeof key !== 'string') {
-            throw new Error('Entity identifier key must be a string');
-        }
-        if (typeof value !== 'string' && typeof value !== 'number' && !Array.isArray(value)) {
-            throw new Error('Entity identifier value must be a string or number');
-        }
-        if (typeof this.data.entityItemIdentifiers[key] == 'undefined') {
-            this.data.entityItemIdentifiers[key] = [];
-        }
-        if (Array.isArray(value)) {
-            value.forEach((v) => {
-                this.data.entityItemIdentifiers[key].push(v);
-            });
-        } else {
-            this.data.entityItemIdentifiers[key].push(value);
+        // Final dispatch: .then.track.with(emitter)
+        track = (emitter) => {
+            if(emitter instanceof CollecionesEmitter){
+                emitter.track(eventInstance);
+            }
+            return {
+                and: track,
+                helpers,
+            }
+        };
+
+        return {
+            and: andEntity,
+            _: setEntityAfterAnd,
+            identified: {
+                by: setEntityIdentifiers
+            },
+            has: { been: setAction},
+            node: '_base',
+            helpers
         }
-    }
 
-}
+    })(entity);
+};
+
+let collecionesDsl = {
+    the: init
+};
 
 exports.CollecionesEmitter = CollecionesEmitter;
 exports.CollecionesEvent = CollecionesEvent;
-exports.CollecionesSemanticCollectionEvent = CollecionesSemanticCollectionEvent;
-exports.CollecionesSemanticEvent = CollecionesSemanticEvent;
 exports.CollecionesTracker = CollecionesTracker;
 exports.CollecionesWebTracker = CollecionesWebTracker;
+exports.collecionesDsl = collecionesDsl;
 //# sourceMappingURL=index.cjs.map