@compilacion/colleciones-clientos 2.0.2 → 2.0.4

package/README.md

@@ -38,16 +38,64 @@ const tracker = new CollecionesTracker([emitter], 'myTracker', 'myApp');
 
 You can construct events declaratively using a natural language-like DSL:
 
+Most simplistic use case
 ```js
 import collecionesDsl from './src/collecionesDsl.js';
 
 collecionesDsl
-  .the('red')
-  ._('button')
-  .has.been('clicked')
+  .the('button')              // Entity
+  .has.been('clicked')        // Verb
+  .then.track.with(emitter);  // Send
+```
+
+Adding adjectives (states etc) onto the entity
+```js
+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:
+```js
+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('jef@email.com')      // 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](./docs/dsl.md) for full DSL documentation.
 
 ### 4. Manually Create Events (Optional)

package/dist/collecionesClientos.iife.js

@@ -43,13 +43,34 @@
     };
 
     /**
-     * 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.
+     * CollecionesEvent
+     * -----------------
+     * Base class representing a semantically structured event object.
+     * Each event models a specific interaction with an entity, optionally performed by an actor,
+     * and may reference related entities or include contextual metadata.
+     *
+     * Key features:
+     * - Captures structured semantics: entity, action, actor, context, references
+     * - Supports multiple identifiers for both the main entity and the actor
+     * - Allows origin tagging for cross-context or cross-application references
+     * - Supports referencing collections of entities or grouped data
+     * - Includes timestamps and tracker/app metadata for auditability
+     * - Fully serializable and deserializable via toJSON/fromJSON
      */
     class CollecionesEvent {
 
         /**
-         * Constructs a new event with default metadata and timestamps.
+         * Constructs a new CollecionesEvent with default structure and timestamps.
+         * Initializes empty containers for semantic attributes such as:
+         * - entity: the subject of the event
+         * - adjectives: descriptors of the entity
+         * - identifiers: identifiers of the entity
+         * - action: what happened to the entity
+         * - actor: who or what triggered the event (with identifiers in actorIdentifiers)
+         * - context: environmental data related to the event
+         * - references: external entities involved, optionally scoped by origin
+         * - collections: groups of related entities
+         * - meta: tracking metadata and timestamps
          */
         constructor() {
             // initialize event properties
@@ -61,6 +82,7 @@
             this.actorIdentifiers = {};
             this.context = {};
             this.references = {};
+            this.collections = {};
             // set default values
             this.meta = {
                 eventFormat: 'CollecionesEvent',
@@ -164,6 +186,7 @@
 
         /**
          * Adds or updates an identifier for the primary entity.
+         * Identifiers allow multiple keys to uniquely identify the entity.
          * @param {string} name - The identifier key.
          * @param {*} identifier - The identifier value.
          */
@@ -176,7 +199,7 @@
 
         /**
          * Defines the name of the actor (who or what performed the action).
-         * @param {string} name - Actor name (e.g., 'user').
+         * @param {string} name - Actor name (e.g., 'user', 'system').
          */
         setActor = function(name) {
             if (typeof name !== 'string') {
@@ -187,7 +210,8 @@
 
         /**
          * Adds or updates an identifier for the actor.
-         * @param {string} name - Identifier name.
+         * Supports multiple identifiers to uniquely identify the actor.
+         * @param {string} name - Identifier key.
          * @param {*} identifier - Identifier value.
          */
         setActorIdentifier = function(name, identifier) {
@@ -199,6 +223,7 @@
 
         /**
          * Adds contextual information to the event.
+         * Context can include any additional environmental or situational data.
          * @param {string} context - The key of the context field.
          * @param {*} value - The value of the context field.
          */
@@ -209,39 +234,128 @@
             this.context[context] = value;
         }
 
+        /**
+         * Alias for `setReference` for compatibility.
+         * Declares an external entity referenced by this event.
+         * @param {string} entity - The referenced entity name.
+         * @param {string|null} origin - The origin application or context (optional).
+         */
+        setRefence = function(entity, origin=null) {
+            return this.setReference(entity, origin);
+        }
+
         /**
          * Declares an entity referenced by this event.
+         * References may include multiple identifiers and an optional origin to scope the reference.
          * @param {string} entity - The referenced entity name.
+         * @param {string|null} origin - The origin application or context (optional).
          */
-        setRefence = function(entity) {
+        setReference = function(entity, origin=null) {
             if (typeof entity !== 'string') {
                 throw new Error('Referenced entity must be a string');
             }
             if(this.references[entity] === undefined) {
-                this.references[entity] = {identifiers: {}};
+                this.references[entity] = {
+                    identifiers: {},
+                    origin
+                };
             }
         }
 
+        /**
+         * Adds or updates an identifier for a referenced entity.
+         * Ensures the reference is declared and sets the identifier under that reference.
+         * @param {string} entity - The referenced entity name.
+         * @param {string} name - The identifier key.
+         * @param {*} identifier - The identifier value.
+         * @param {string|null} origin - Optional origin context.
+         */
+        setRefenceIdentifier = function(entity, name, identifier, origin=null) {
+            return this.setReferenceIdentifier(entity, name, identifier, origin);
+        }
+
         /**
          * 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.
+         * @param {string|null} origin - Optional origin context.
          */
-        setRefenceIdentifier = function(entity, name, identifier) {
+        setReferenceIdentifier = function(entity, name, identifier, origin=null) {
             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.setRefence(entity, origin);
             this.references[entity].identifiers[name] = identifier;
         }
 
         /**
-         * Serializes the event to a plain object suitable for JSON.stringify().
-         * @returns {object}
+         * Declares a collection of related entities for this event.
+         * Collections group multiple related items and may include identifiers and origin metadata.
+         * @param {string} entity - The collection name.
+         * @param {string|null} origin - Optional origin identifier (e.g. system name).
+         */
+        setCollection = function(entity, origin=null) {
+            if(this.collections[entity] == undefined) {
+                this.collections[entity] = {
+                    items: [],
+                    identifiers: {},
+                    origin
+                };
+            }
+        }
+
+        /**
+         * Adds a new item to a collection and returns its index key.
+         * Items represent individual elements within the collection.
+         * @param {string} entity - The name of the collection.
+         * @returns {number} Index of the newly added item in the collection.
+         */
+        setCollectionItem = function(entity) {
+            this.setCollection(entity);
+            this.collections[entity].items.push({});
+            let itemKey = this.collections[entity].items.length - 1;
+            return itemKey;
+        }
+
+        /**
+         * Assigns a reference (identifier) to a specific item in a collection.
+         * Useful for tagging individual collection elements with identifiers.
+         * @param {string} entity - Collection name.
+         * @param {number} itemKey - The index of the item in the collection.
+         * @param {string} name - The identifier key.
+         * @param {*} identifier - The identifier value.
+         * @throws {Error} If the item does not exist at the given index.
+         */
+        setCollectionItemReference = function(entity, itemKey, name, identifier) {
+            this.setCollection(entity);
+            if(typeof this.collections[entity].items[itemKey] !== 'object') {
+                throw new Error('bad bad man, the collection key does not exists');
+            }
+            this.collections[entity].items[itemKey][name] = identifier;
+        }
+        
+        /**
+         * Sets a static identifier that applies to the entire collection.
+         * These identifiers describe the collection as a whole.
+         * @param {string} entity - Collection name.
+         * @param {string} name - Identifier key.
+         * @param {*} identifier - Identifier value.
+         */
+        setCollectionIdentifier = function(entity, name, identifier) {
+            if(this.collections[entity] == undefined) {
+                this.collections[entity] = {};
+            }
+            this.collections[entity].identifiers[name] = identifier;
+        }
+
+        /**
+         * Serializes the event instance to a plain object suitable for transport or storage.
+         * The output includes all semantic fields and metadata.
+         * @returns {object} A plain JavaScript object representing the event.
          */
         toJSON() {
             return {
@@ -255,14 +369,17 @@
                 actorIds: this.actorIds,
                 context: this.context,
                 references: this.references,
-                meta: this.meta
+                meta: this.meta,
+                collections: this.collections
             };
         }
 
         /**
-         * Recreates an instance of CollecionesEvent from a plain object.
-         * @param {object} obj
-         * @returns {CollecionesEvent}
+         * Recreates a CollecionesEvent instance from a plain object.
+         * Used when deserializing events from storage or network transport.
+         * @param {object} obj - The input object containing event data.
+         * @returns {CollecionesEvent} A rehydrated event instance.
+         * @throws {Error} If the class type is not 'CollecionesEvent'.
          */
         static fromJSON(obj) { 
             if (!obj || obj.class !== 'CollecionesEvent') {
@@ -279,6 +396,7 @@
             instance.context = obj.context || {};
             instance.references = obj.references || {};
             instance.meta = obj.meta || {};
+            instance.collections = obj.collections || {};
             return instance;
         }
         
@@ -544,9 +662,9 @@
             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)
+            let addCollection = () => {};
 
             // Adjective chaining: .and(...)._('entity')
             setEntityAfterAnd = (entity) => {
@@ -602,6 +720,9 @@
                     with: addContext,
                     conform: {to: conformingTo},
                     then: {track: {with: track}},
+                    including: {
+                        a: addCollection,
+                    },
                     helpers
                 }
             };
@@ -614,6 +735,9 @@
                         by: setActorIdentifier
                     },
                     with: addContext,
+                    including: {
+                        a: addCollection,
+                    },
                     helpers
                 }
             };
@@ -628,6 +752,9 @@
                             and: setActorIdentifier,
                             with: addContext,
                             referring: { to: addReference },
+                            including: {
+                                a: addCollection,
+                            },
                         }
                     },
                     helpers
@@ -645,6 +772,9 @@
                                 helpers,
                                 and: addContext,
                                 referring: { to: addReference },
+                                including: {
+                                    a: addCollection,
+                                },
                             }
                         }
                     }
@@ -660,6 +790,9 @@
                     },
                     conform: {to: conformingTo},
                     then: {track: {with: track}},
+                    including: {
+                        a: addCollection,
+                    },
                     helpers
                 }
             };
@@ -672,9 +805,12 @@
                             eventInstance.setRefenceIdentifier(entity, name, value);
                             return {
                                 helpers,
-                                and: addReferenceIdentifier,
+                                and: {by: getAddReference(entity) },
                                 conform: {to: conformingTo},
                                 then: {track: {with: track}},
+                                including: {
+                                    a: addCollection,
+                                },
                             }
                         },
                         helpers,
@@ -691,6 +827,61 @@
                 }
             };
 
+            addCollection = (entity) => {
+                const collection = () => {
+                    eventInstance.setCollection(entity);
+                    
+                    const addItem = (referenceName) => {
+                        const itemKey = eventInstance.setCollectionItem(entity);
+                        const addIdentifier = (referenceNameNewIdentifier) => {
+                            referenceName = referenceNameNewIdentifier;
+                            return {
+                                as: addItemReferenceValue,
+                            }
+                        };
+                        const addItemReferenceValue = (value) => {
+                            eventInstance.setCollectionItemReference(entity, itemKey, referenceName, value);
+                            return {
+                                and: {
+                                    helpers, 
+                                    by: addIdentifier,
+                                    item: { 
+                                        identified: { 
+                                            by: addItem
+                                        }
+                                    },
+                                    a: addCollection
+                                },
+                                conform: {
+                                    to: conformingTo,
+                                },  
+                                then: {track: {with: track}},
+                                helpers
+                            }
+                        };
+                        return {
+                            as: addItemReferenceValue
+                        }
+
+                    };
+
+                    return {
+                        helpers,
+                        with: {
+                            item: {
+                                identified: {
+                                    by: addItem
+                                }
+                            }
+                        },
+                        and: { a: addCollection }
+                    }
+                };
+                return {
+                    collection
+                }
+            };
+
             // Final dispatch: .then.track.with(tracker)
             track = (tracker) => {
                 if(!(tracker instanceof CollecionesTracker)){