!F add include_event_description option to log event descriptions and update related documentation

Author: yelmuratoff

CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented in this file.
 
 ## [0.1.6] - Unreleased
+ - Add `include_event_description` config option to optionally include an
+   event's `description` property inside the emitted `logger.logEvent`
+   parameters map. This flag defaults to `false` to preserve existing
+   behavior; enable it via `analytics_gen.yaml` (key: `include_event_description`).
+   - The code generator now inserts a `'description'` key for events that
+     have a non-empty description when the flag is enabled.
+   - The example config and `README.md` were updated to document this flag.
+   - Unit tests assert that descriptions are properly included when enabled
+     and omitted otherwise.
 - Support interpolated placeholders in custom `event_name` strings
   - You can now include parameter placeholders in `event_name` using
     `{parameter_name}` and the code generator will replace them with

README.md

@@ -199,6 +199,10 @@ analytics_gen:
   generate_json: true
   generate_sql: true
   generate_plan: true
+  # When true, event descriptions are included in the emitted
+  # `logger.logEvent` parameters under the key `description`. Defaults to
+  # `false`.
+  # include_event_description: false
 ```
 
 When `generate_docs` or any export flag is enabled in the config, the CLI will run those generators automatically (no need to pass `--docs` or `--exports`). Use `--no-docs` or `--no-exports` to temporarily override config.

example/analytics_gen.yaml

@@ -1,19 +1,22 @@
 analytics_gen:
   # Path to YAML event files (relative to project root)
   events_path: events
-  
+
   # Path where generated code will be written (relative to lib/)
   output_path: src/analytics/generated
-  
+
   # Path for documentation (optional)
   docs_path: docs/analytics_events.md
-  
+
   # Path for export files (optional)
   exports_path: assets/generated
-  
+
   # Enable/disable various generators
   generate_docs: true
   generate_csv: true
   generate_json: true
   generate_sql: true
   generate_plan: true
+  # If true, each generated logEvent call will include the event description
+  # under the 'description' key in the parameters map. Default: false
+  include_event_description: true

example/assets/generated/analytics_events.csv

@@ -2,6 +2,7 @@ Domain,Action,Event Name,Description,Parameters,Deprecated,Replacement
 auth,login,auth: login,User logs in to the application,"method (string): Login method (email, google, apple)",true,auth.login_v2
 auth,login_v2,auth: login_v2,User logs in to the application (v2),"method (string): Login method v2 (email, google, apple)",false,
 auth,logout,auth: logout,User logs out,,false,
+auth,phone_login,Auth: Phone,When user logs in via phone,user_exists (bool?): Whether the user exists or not,false,
 auth,signup,auth: signup,User creates a new account,method (string); referral_code (string?): Optional referral code used during signup,false,
 purchase,cancelled,purchase: cancelled,User cancelled a purchase,product_id (string); reason (string?): Reason for cancellation,false,
 purchase,completed,purchase: completed,User completed a purchase,currency (string); price (double); product_id (string); quantity (int): Number of items purchased,false,

example/assets/generated/analytics_events.db

@@ -1,15 +1,15 @@
 {
   "metadata": {
-    "fingerprint": "-16b6279a2f73b424",
+    "fingerprint": "-3889fe4dbbfad68f",
     "total_domains": 3,
-    "total_events": 7,
-    "total_parameters": 13
+    "total_events": 8,
+    "total_parameters": 14
   },
   "domains": [
     {
       "name": "auth",
-      "event_count": 4,
-      "parameter_count": 4,
+      "event_count": 5,
+      "parameter_count": 5,
       "events": [
         {
           "name": "login",
@@ -47,6 +47,20 @@
           "deprecated": false,
           "parameters": []
         },
+        {
+          "name": "phone_login",
+          "event_name": "Auth: Phone",
+          "description": "When user logs in via phone",
+          "deprecated": false,
+          "parameters": [
+            {
+              "name": "user_exists",
+              "type": "bool",
+              "nullable": true,
+              "description": "Whether the user exists or not"
+            }
+          ]
+        },
         {
           "name": "signup",
           "event_name": "auth: signup",

example/assets/generated/analytics_events.json

@@ -1 +1 @@
-{"metadata":{"fingerprint":"-16b6279a2f73b424","total_domains":3,"total_events":7,"total_parameters":13},"domains":[{"name":"auth","event_count":4,"parameter_count":4,"events":[{"name":"login","event_name":"auth: login","description":"User logs in to the application","deprecated":true,"replacement":"auth.login_v2","parameters":[{"name":"method","type":"string","nullable":false,"description":"Login method (email, google, apple)"}]},{"name":"login_v2","event_name":"auth: login_v2","description":"User logs in to the application (v2)","deprecated":false,"parameters":[{"name":"method","type":"string","nullable":false,"description":"Login method v2 (email, google, apple)"}]},{"name":"logout","event_name":"auth: logout","description":"User logs out","deprecated":false,"parameters":[]},{"name":"signup","event_name":"auth: signup","description":"User creates a new account","deprecated":false,"parameters":[{"name":"method","type":"string","nullable":false},{"name":"referral_code","type":"string","nullable":true,"description":"Optional referral code used during signup"}]}]},{"name":"purchase","event_count":2,"parameter_count":6,"events":[{"name":"cancelled","event_name":"purchase: cancelled","description":"User cancelled a purchase","deprecated":false,"parameters":[{"name":"product_id","type":"string","nullable":false},{"name":"reason","type":"string","nullable":true,"description":"Reason for cancellation"}]},{"name":"completed","event_name":"purchase: completed","description":"User completed a purchase","deprecated":false,"parameters":[{"name":"currency","type":"string","nullable":false},{"name":"price","type":"double","nullable":false},{"name":"product_id","type":"string","nullable":false},{"name":"quantity","type":"int","nullable":false,"description":"Number of items purchased"}]}]},{"name":"screen","event_count":1,"parameter_count":3,"events":[{"name":"view","event_name":"Screen: {screen_name}","description":"User views a screen","deprecated":false,"parameters":[{"name":"duration_ms","type":"int","nullable":true,"description":"Time spent on previous screen in milliseconds"},{"name":"previous_screen","type":"string","nullable":true,"description":"Name of the previous screen"},{"name":"screen_name","type":"string","nullable":false}]}]}]}
+{"metadata":{"fingerprint":"-3889fe4dbbfad68f","total_domains":3,"total_events":8,"total_parameters":14},"domains":[{"name":"auth","event_count":5,"parameter_count":5,"events":[{"name":"login","event_name":"auth: login","description":"User logs in to the application","deprecated":true,"replacement":"auth.login_v2","parameters":[{"name":"method","type":"string","nullable":false,"description":"Login method (email, google, apple)"}]},{"name":"login_v2","event_name":"auth: login_v2","description":"User logs in to the application (v2)","deprecated":false,"parameters":[{"name":"method","type":"string","nullable":false,"description":"Login method v2 (email, google, apple)"}]},{"name":"logout","event_name":"auth: logout","description":"User logs out","deprecated":false,"parameters":[]},{"name":"phone_login","event_name":"Auth: Phone","description":"When user logs in via phone","deprecated":false,"parameters":[{"name":"user_exists","type":"bool","nullable":true,"description":"Whether the user exists or not"}]},{"name":"signup","event_name":"auth: signup","description":"User creates a new account","deprecated":false,"parameters":[{"name":"method","type":"string","nullable":false},{"name":"referral_code","type":"string","nullable":true,"description":"Optional referral code used during signup"}]}]},{"name":"purchase","event_count":2,"parameter_count":6,"events":[{"name":"cancelled","event_name":"purchase: cancelled","description":"User cancelled a purchase","deprecated":false,"parameters":[{"name":"product_id","type":"string","nullable":false},{"name":"reason","type":"string","nullable":true,"description":"Reason for cancellation"}]},{"name":"completed","event_name":"purchase: completed","description":"User completed a purchase","deprecated":false,"parameters":[{"name":"currency","type":"string","nullable":false},{"name":"price","type":"double","nullable":false},{"name":"product_id","type":"string","nullable":false},{"name":"quantity","type":"int","nullable":false,"description":"Number of items purchased"}]}]},{"name":"screen","event_count":1,"parameter_count":3,"events":[{"name":"view","event_name":"Screen: {screen_name}","description":"User views a screen","deprecated":false,"parameters":[{"name":"duration_ms","type":"int","nullable":true,"description":"Time spent on previous screen in milliseconds"},{"name":"previous_screen","type":"string","nullable":true,"description":"Name of the previous screen"},{"name":"screen_name","type":"string","nullable":false}]}]}]}

example/assets/generated/analytics_events.min.json

@@ -1,5 +1,5 @@
 -- Analytics Events Database Schema
--- Fingerprint: -16b6279a2f73b424 (domains=3, events=7, parameters=13)
+-- Fingerprint: -3889fe4dbbfad68f (domains=3, events=8, parameters=14)
 
 -- Create domains table
 CREATE TABLE IF NOT EXISTS domains (
@@ -39,7 +39,7 @@ CREATE INDEX IF NOT EXISTS idx_events_domain ON events(domain_id);
 CREATE INDEX IF NOT EXISTS idx_parameters_event ON parameters(event_id);
 
 -- Insert domain data
-INSERT INTO domains (id, name, event_count, parameter_count) VALUES (1, 'auth', 4, 4);
+INSERT INTO domains (id, name, event_count, parameter_count) VALUES (1, 'auth', 5, 5);
 INSERT INTO domains (id, name, event_count, parameter_count) VALUES (2, 'purchase', 2, 6);
 INSERT INTO domains (id, name, event_count, parameter_count) VALUES (3, 'screen', 1, 3);
 
@@ -49,21 +49,23 @@ INSERT INTO parameters (event_id, name, type, nullable, description, allowed_val
 INSERT INTO events (id, domain_id, name, event_name, description, deprecated, replacement) VALUES (2, 1, 'login_v2', 'auth: login_v2', 'User logs in to the application (v2)', 0, NULL);
 INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (2, 'method', 'string', 0, 'Login method v2 (email, google, apple)', NULL);
 INSERT INTO events (id, domain_id, name, event_name, description, deprecated, replacement) VALUES (3, 1, 'logout', 'auth: logout', 'User logs out', 0, NULL);
-INSERT INTO events (id, domain_id, name, event_name, description, deprecated, replacement) VALUES (4, 1, 'signup', 'auth: signup', 'User creates a new account', 0, NULL);
-INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (4, 'method', 'string', 0, NULL, NULL);
-INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (4, 'referral_code', 'string', 1, 'Optional referral code used during signup', NULL);
-INSERT INTO events (id, domain_id, name, event_name, description, deprecated, replacement) VALUES (5, 2, 'cancelled', 'purchase: cancelled', 'User cancelled a purchase', 0, NULL);
-INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (5, 'product_id', 'string', 0, NULL, NULL);
-INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (5, 'reason', 'string', 1, 'Reason for cancellation', NULL);
-INSERT INTO events (id, domain_id, name, event_name, description, deprecated, replacement) VALUES (6, 2, 'completed', 'purchase: completed', 'User completed a purchase', 0, NULL);
-INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (6, 'currency', 'string', 0, NULL, NULL);
-INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (6, 'price', 'double', 0, NULL, NULL);
+INSERT INTO events (id, domain_id, name, event_name, description, deprecated, replacement) VALUES (4, 1, 'phone_login', 'Auth: Phone', 'When user logs in via phone', 0, NULL);
+INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (4, 'user_exists', 'bool', 1, 'Whether the user exists or not', NULL);
+INSERT INTO events (id, domain_id, name, event_name, description, deprecated, replacement) VALUES (5, 1, 'signup', 'auth: signup', 'User creates a new account', 0, NULL);
+INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (5, 'method', 'string', 0, NULL, NULL);
+INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (5, 'referral_code', 'string', 1, 'Optional referral code used during signup', NULL);
+INSERT INTO events (id, domain_id, name, event_name, description, deprecated, replacement) VALUES (6, 2, 'cancelled', 'purchase: cancelled', 'User cancelled a purchase', 0, NULL);
 INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (6, 'product_id', 'string', 0, NULL, NULL);
-INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (6, 'quantity', 'int', 0, 'Number of items purchased', NULL);
-INSERT INTO events (id, domain_id, name, event_name, description, deprecated, replacement) VALUES (7, 3, 'view', 'Screen: {screen_name}', 'User views a screen', 0, NULL);
-INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (7, 'duration_ms', 'int', 1, 'Time spent on previous screen in milliseconds', NULL);
-INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (7, 'previous_screen', 'string', 1, 'Name of the previous screen', NULL);
-INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (7, 'screen_name', 'string', 0, NULL, NULL);
+INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (6, 'reason', 'string', 1, 'Reason for cancellation', NULL);
+INSERT INTO events (id, domain_id, name, event_name, description, deprecated, replacement) VALUES (7, 2, 'completed', 'purchase: completed', 'User completed a purchase', 0, NULL);
+INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (7, 'currency', 'string', 0, NULL, NULL);
+INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (7, 'price', 'double', 0, NULL, NULL);
+INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (7, 'product_id', 'string', 0, NULL, NULL);
+INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (7, 'quantity', 'int', 0, 'Number of items purchased', NULL);
+INSERT INTO events (id, domain_id, name, event_name, description, deprecated, replacement) VALUES (8, 3, 'view', 'Screen: {screen_name}', 'User views a screen', 0, NULL);
+INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (8, 'duration_ms', 'int', 1, 'Time spent on previous screen in milliseconds', NULL);
+INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (8, 'previous_screen', 'string', 1, 'Name of the previous screen', NULL);
+INSERT INTO parameters (event_id, name, type, nullable, description, allowed_values) VALUES (8, 'screen_name', 'string', 0, NULL, NULL);
 
 -- Create useful views
 CREATE VIEW IF NOT EXISTS events_with_domain AS

example/assets/generated/create_database.sql

@@ -1,7 +1,7 @@
 # Analytics Events Documentation
 
-Fingerprint: `-16b6279a2f73b424`
-Domains: 3 | Events: 7 | Parameters: 13
+Fingerprint: `-3889fe4dbbfad68f`
+Domains: 3 | Events: 8 | Parameters: 14
 
 ## Table of Contents
 
@@ -12,18 +12,19 @@ Domains: 3 | Events: 7 | Parameters: 13
 ## Summary
 
 - **Total Domains**: 3
-- **Total Events**: 7
-- **Total Parameters**: 13
+- **Total Events**: 8
+- **Total Parameters**: 14
 
 ## auth
 
-Events: 4 | Parameters: 4
+Events: 5 | Parameters: 5
 
 | Event | Description | Status | Parameters |
 |-------|-------------|--------|------------|
 | auth: login | User logs in to the application | **Deprecated** -> `auth.login_v2` | `method` (string): Login method (email, google, apple) |
 | auth: login_v2 | User logs in to the application (v2) | Active | `method` (string): Login method v2 (email, google, apple) |
 | auth: logout | User logs out | Active | - |
+| Auth: Phone | When user logs in via phone | Active | `user_exists` (bool?): Whether the user exists or not |
 | auth: signup | User creates a new account | Active | `method` (string)<br>`referral_code` (string?): Optional referral code used during signup |
 
 ### Code Examples

example/docs/analytics_events.md

@@ -26,3 +26,11 @@ auth:
       referral_code:
         type: string?
         description: Optional referral code used during signup
+
+  phone_login:
+    description: When user logs in via phone
+    event_name: "Auth: Phone"
+    parameters:
+      user_exists:
+        bool?:
+        description: Whether the user exists or not