@hotmeshio/hotmesh 0.0.56 → 0.0.58

package/build/services/compiler/deployer.js

@@ -7,8 +7,8 @@ const collator_1 = require("../collator");
 const serializer_1 = require("../serializer");
 const pipe_1 = require("../pipe");
 const validator_1 = require("./validator");
-const DEFAULT_METADATA_RANGE_SIZE = 26;
-const DEFAULT_DATA_RANGE_SIZE = 260;
+const DEFAULT_METADATA_RANGE_SIZE = 26; //metadata is 26 slots ([a-z] * 1)
+const DEFAULT_DATA_RANGE_SIZE = 260; //data is 260 slots ([a-zA-Z] * 5)
 const DEFAULT_RANGE_SIZE = DEFAULT_METADATA_RANGE_SIZE + DEFAULT_DATA_RANGE_SIZE;
 class Deployer {
     constructor(manifest) {
@@ -41,19 +41,22 @@ class Deployer {
         };
     }
     async generateSymKeys() {
+        //note: symbol ranges are additive (per version); path assignments are immutable
         const appId = this.manifest.app.id;
         for (const graph of this.manifest.app.graphs) {
+            //generate JOB symbols
             const [, trigger] = this.findTrigger(graph);
             const topic = trigger.subscribes;
             const [lower, upper, symbols] = await this.store.reserveSymbolRange(`$${topic}`, DEFAULT_RANGE_SIZE, 'JOB');
-            const prefix = '';
+            const prefix = ''; //job meta/data is NOT namespaced
             const newSymbols = this.bindSymbols(lower, upper, symbols, prefix, trigger.PRODUCES);
             if (Object.keys(newSymbols).length) {
                 await this.store.addSymbols(`$${topic}`, newSymbols);
             }
+            //generate ACTIVITY symbols
             for (const [activityId, activity] of Object.entries(graph.activities)) {
                 const [lower, upper, symbols] = await this.store.reserveSymbolRange(activityId, DEFAULT_RANGE_SIZE, 'ACTIVITY');
-                const prefix = `${activityId}/`;
+                const prefix = `${activityId}/`; //activity meta/data is namespaced
                 this.bindSelf(activity.consumes, activity.produces, activityId);
                 const newSymbols = this.bindSymbols(lower, upper, symbols, prefix, activity.produces);
                 if (Object.keys(newSymbols).length) {
@@ -63,6 +66,7 @@ class Deployer {
         }
     }
     bindSelf(consumes, produces, activityId) {
+        //bind self-referential mappings
         for (const selfId of [activityId, '$self']) {
             const selfConsumes = consumes[selfId];
             if (selfConsumes) {
@@ -86,7 +90,7 @@ class Deployer {
                 const symbol = (0, utils_1.getSymKey)(startIndex);
                 startIndex++;
                 newSymbols[fullPath] = symbol;
-                currentSymbols[fullPath] = symbol;
+                currentSymbols[fullPath] = symbol; // update the currentSymbols to include this new symbol
             }
         }
         return newSymbols;
@@ -99,16 +103,20 @@ class Deployer {
             if (!jobSchema && !outputSchema)
                 continue;
             const activities = graph.activities;
+            // Find the trigger activity and bind the job schema to it
+            // at execution time, the trigger is a standin for the job
             for (const activityKey in activities) {
                 if (activities[activityKey].type === 'trigger') {
                     const trigger = activities[activityKey];
                     if (jobSchema) {
+                        //possible for trigger to have job mappings
                         if (!trigger.job) {
                             trigger.job = {};
                         }
                         trigger.job.schema = jobSchema;
                     }
                     if (outputSchema) {
+                        //impossible for trigger to have output mappings.
                         trigger.output = { schema: outputSchema };
                     }
                 }
@@ -129,6 +137,8 @@ class Deployer {
             }
         }
     }
+    //the cycle/goto activity includes and ancestor target;
+    //update with the cycle flag, so it can be rerun
     bindCycleTarget() {
         for (const graph of this.manifest.app.graphs) {
             const activities = graph.activities;
@@ -140,6 +150,8 @@ class Deployer {
             }
         }
     }
+    //it's more intuitive for SDK users to use 'topic',
+    //but the compiler is desiged to be generic and uses the attribute, 'subtypes'
     convertTopicsToTypes() {
         for (const graph of this.manifest.app.graphs) {
             const activities = graph.activities;
@@ -151,6 +163,7 @@ class Deployer {
             }
         }
     }
+    //legacy; remove at beta (assume no legacy refs to 'activity' at that point)
     convertActivitiesToHooks() {
         for (const graph of this.manifest.app.graphs) {
             const activities = graph.activities;
@@ -170,8 +183,11 @@ class Deployer {
                     const toTransitions = graph.transitions[fromActivity];
                     for (const transition of toTransitions) {
                         const to = transition.to;
+                        //DAGs have one parent; easy to optimize for
                         graph.activities[to].parent = fromActivity;
                     }
+                    //temporarily bind the transitions to the parent activity,
+                    // so the consumer/producer registrar picks up the bindings
                     graph.activities[fromActivity].transitions = toTransitions;
                 }
             }
@@ -229,6 +245,10 @@ class Deployer {
                         traverse(obj[key], newPath);
                     }
                     else {
+                        //wildcard mapping (e.g., 'friends[25]')
+                        //when this is resolved, it will be expanded to
+                        //`'friends/0', ..., 'friends/24'`, providing 25 dynamic
+                        //slots in the flow's output data
                         const pathName = [...path, key].join('/');
                         if (!pathName.includes('[')) {
                             const finalPath = `data/${pathName}`;
@@ -238,15 +258,17 @@ class Deployer {
                         }
                         else {
                             const [left, right] = pathName.split('[');
+                            //check if this variable isLiteralKeyType (#, -, or _)
                             const [amount, _] = right.split(']');
                             if (!isNaN(parseInt(amount))) {
+                                //loop to create all possible paths (0 to amount)
                                 for (let i = 0; i < parseInt(amount); i++) {
                                     const finalPath = `data/${left}/${i}`;
                                     if (!result.includes(finalPath)) {
                                         result.push(finalPath);
                                     }
                                 }
-                            }
+                            } //else ignore (amount might be '-' or '_')  `-` is marker data;   `_` is job data;
                         }
                     }
                 }
@@ -268,6 +290,7 @@ class Deployer {
     }
     resolveMappingDependencies() {
         const dynamicMappingRules = [];
+        //recursive function to descend into the object and find all dynamic mapping rules
         function traverse(obj, consumes) {
             for (const key in obj) {
                 if (typeof obj[key] === 'string') {
@@ -296,6 +319,7 @@ class Deployer {
             }
         }
         const groupedRules = this.groupMappingRules(dynamicMappingRules);
+        // Iterate through the graph and add 'produces' field to each activity
         for (const graph of graphs) {
             const activities = graph.activities;
             for (const activityId in activities) {
@@ -306,6 +330,7 @@ class Deployer {
     }
     groupMappingRules(rules) {
         rules = Array.from(new Set(rules)).sort();
+        // Group by the first symbol before the period (this is the activity name)
         const groupedRules = {};
         for (const rule of rules) {
             const [group, resolved] = this.resolveMappableValue(rule);
@@ -324,6 +349,7 @@ class Deployer {
             return [group, path.join('/')];
         }
         else {
+            //normalize paths to be relative to the activity
             const [group, type, subtype, ...path] = parts;
             const prefix = {
                 hook: 'hook/data',
@@ -340,6 +366,7 @@ class Deployer {
             const activities = graph.activities;
             for (const activityKey in activities) {
                 const target = activities[activityKey];
+                //remove transitions; no longer necessary for runtime
                 delete target.transitions;
                 activitySchemas[activityKey] = target;
             }
@@ -352,6 +379,7 @@ class Deployer {
         for (const graph of graphs) {
             const activities = graph.activities;
             const subscribesTopic = graph.subscribes;
+            // Find the activity ID associated with the subscribes topic
             for (const activityKey in activities) {
                 if (activities[activityKey].type === 'trigger') {
                     publicSubscriptions[subscribesTopic] = activityKey;
@@ -414,6 +442,7 @@ class Deployer {
                         if (!targetActivity.hook) {
                             targetActivity.hook = {};
                         }
+                        //create back-reference to the hook topic
                         targetActivity.hook.topic = topic;
                     }
                 }
@@ -422,6 +451,7 @@ class Deployer {
         await this.store.setHookRules(hookRules);
     }
     async deployConsumerGroups() {
+        //create one engine group
         const params = { appId: this.manifest.app.id };
         const key = this.store.mintKey(key_1.KeyType.STREAMS, params);
         await this.deployConsumerGroup(key, 'ENGINE');
@@ -429,9 +459,11 @@ class Deployer {
             const activities = graph.activities;
             for (const activityKey in activities) {
                 const activity = activities[activityKey];
+                //only precreate if the topic is concrete and not `mappable`
                 if (activity.type === 'worker' && pipe_1.Pipe.resolve(activity.subtype, {}) === activity.subtype) {
                     params.topic = activity.subtype;
                     const key = this.store.mintKey(key_1.KeyType.STREAMS, params);
+                    //create one worker group per unique activity subtype (the topic)
                     await this.deployConsumerGroup(key, 'WORKER');
                 }
             }

package/build/services/compiler/index.d.ts

@@ -2,13 +2,28 @@ import { ILogger } from '../logger';
 import { StoreService } from '../store';
 import { HotMeshManifest } from '../../types/hotmesh';
 import { RedisClient, RedisMulti } from '../../types/redis';
+/**
+ * The compiler service converts a graph into a executable program.
+ */
 declare class CompilerService {
     store: StoreService<RedisClient, RedisMulti> | null;
     logger: ILogger;
     constructor(store: StoreService<RedisClient, RedisMulti>, logger: ILogger);
+    /**
+     * verifies and plans the deployment of an app to Redis; the app is not deployed yet
+     * @param path
+     */
     plan(mySchemaOrPath: string): Promise<HotMeshManifest>;
     isPath(input: string): boolean;
+    /**
+     * deploys an app to Redis but does NOT activate it.
+     */
     deploy(mySchemaOrPath: string): Promise<HotMeshManifest>;
+    /**
+     * activates a deployed version of an app;
+     * @param appId
+     * @param appVersion
+     */
     activate(appId: string, appVersion: string): Promise<boolean>;
     saveAsJSON(originalPath: string, schema: HotMeshManifest): Promise<void>;
 }

package/build/services/compiler/index.js

@@ -33,11 +33,18 @@ const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
 const deployer_1 = require("./deployer");
 const validator_1 = require("./validator");
+/**
+ * The compiler service converts a graph into a executable program.
+ */
 class CompilerService {
     constructor(store, logger) {
         this.store = store;
         this.logger = logger;
     }
+    /**
+     * verifies and plans the deployment of an app to Redis; the app is not deployed yet
+     * @param path
+     */
     async plan(mySchemaOrPath) {
         try {
             let schema;
@@ -47,8 +54,10 @@ class CompilerService {
             else {
                 schema = js_yaml_1.default.load(mySchemaOrPath);
             }
+            // 1) validate the manifest file
             const validator = new validator_1.Validator(schema);
             validator.validate(this.store);
+            // 2) todo: add a PlannerService module that will plan the deployment (what might break, drift, etc)
             return schema;
         }
         catch (err) {
@@ -58,6 +67,9 @@ class CompilerService {
     isPath(input) {
         return !input.trim().startsWith('app:');
     }
+    /**
+     * deploys an app to Redis but does NOT activate it.
+     */
     async deploy(mySchemaOrPath) {
         try {
             let schema;
@@ -68,10 +80,13 @@ class CompilerService {
             else {
                 schema = js_yaml_1.default.load(mySchemaOrPath);
             }
+            // 2) validate the manifest file (synchronous operation...no callbacks)
             const validator = new validator_1.Validator(schema);
             validator.validate(this.store);
+            // 3) deploy the schema (segment, optimize, etc; save to Redis)
             const deployer = new deployer_1.Deployer(schema);
             await deployer.deploy(this.store);
+            // 4) save the app version to Redis (so it can be activated later)
             await this.store.setApp(schema.app.id, schema.app.version);
             return schema;
         }
@@ -79,6 +94,11 @@ class CompilerService {
             this.logger.error('compiler-deploy-error', err);
         }
     }
+    /**
+     * activates a deployed version of an app;
+     * @param appId
+     * @param appVersion
+     */
     async activate(appId, appVersion) {
         return await this.store.activateAppVersion(appId, appVersion);
     }

package/build/services/compiler/validator.d.ts

@@ -10,6 +10,9 @@ declare class Validator {
     static SYS_VARS: string[];
     static CONTEXT_VARS: string[];
     constructor(manifest: HotMeshManifest);
+    /**
+     * validate the manifest file
+     */
     validate(store: StoreService<RedisClient, RedisMulti>): Promise<void>;
     validateActivityIds(): void;
     isMappingStatement(value: string): boolean;

package/build/services/compiler/validator.js

@@ -10,6 +10,9 @@ class Validator {
         this.store = null;
         this.manifest = manifest;
     }
+    /**
+     * validate the manifest file
+     */
     async validate(store) {
         this.store = store;
         this.getMappingStatements();
@@ -25,10 +28,12 @@ class Validator {
         this.validateHooks();
         this.validateConditionalStatements();
     }
+    // 1.1) Validate the manifest file activity ids are unique (no duplicates)
     validateActivityIds() {
         const activityIdsSet = new Set();
         this.manifest.app.graphs.forEach((graph) => {
             const ids = Object.keys(graph.activities);
+            // Check for duplicates and add ids to the set
             ids.forEach((id) => {
                 if (activityIdsSet.has(id)) {
                     throw new Error(`Duplicate activity id found: ${id}`);
@@ -67,7 +72,9 @@ class Validator {
         });
         this.mappingStatements = mappingStatements;
     }
+    // 1.2) Validate no activity ids are referenced that don't exist
     validateReferencedActivityIds() {
+        // get list of all mapping statements and validate
         const mappingStatements = this.mappingStatements;
         const activityIds = this.activityIds;
         for (const activity in mappingStatements) {
@@ -89,23 +96,41 @@ class Validator {
     isContextVariable(value) {
         return ['{$input}', '{$output}', '{$item}', '{$key}', '{$index}'].includes(value);
     }
+    // 1.3) Validate the mapping/@pipe statements are valid
     validateMappingStatements() {
+        // Implement the method content
     }
+    // 1.4) Validate the transitions are valid
     validateTransitions() {
+        // Implement the method content
     }
+    // 1.5) Validate the transition conditions are valid
     validateTransitionConditions() {
+        // Implement the method content
     }
+    // 1.6) Validate the stats
     validateStats() {
+        // Implement the method content
     }
+    // 1.7) Validate the schemas
     validateSchemas() {
+        // Implement the method content
     }
+    // 1.8) Validate the topics are unique and handled
     validateUniqueHandledTopics() {
+        // Implement the method content
     }
+    // 1.9) Validate that every graph has publishes and subscribes
     validateGraphPublishSubscribe() {
+        // Implement the method content
     }
+    // 1.10) Validate hooks, including mapping statements
     validateHooks() {
+        // Implement the method content
     }
+    // 1.11) Validate conditional statements
     validateConditionalStatements() {
+        // Implement the method content
     }
 }
 exports.Validator = Validator;

package/build/services/connector/clients/ioredis.js

@@ -45,4 +45,6 @@ RedisConnection.instances = new Map();
 RedisConnection.clientOptions = {
     host: 'localhost',
     port: 6379,
+    //password: config.REDIS_PASSWORD,
+    //db: config.REDIS_DATABASE,
 };

package/build/services/connector/clients/redis.js

@@ -57,4 +57,6 @@ RedisConnection.clientOptions = {
         port: 6379,
         tls: false,
     },
+    //password: config.REDIS_PASSWORD,
+    //database: config.REDIS_DATABASE,
 };

package/build/services/connector/index.js

@@ -5,6 +5,8 @@ const utils_1 = require("../../modules/utils");
 const ioredis_1 = require("../connector/clients/ioredis");
 const redis_1 = require("../connector/clients/redis");
 class ConnectorService {
+    //1) Initialize `store`, `stream`, and `subscription` Redis clients.
+    //2) Bind to the target if not already present
     static async initRedisClients(Redis, options, target) {
         if (!target.store || !target.stream || !target.sub) {
             const instances = [];

package/build/services/durable/client.d.ts

@@ -8,12 +8,32 @@ export declare class ClientService {
     static instances: Map<string, HotMesh | Promise<HotMesh>>;
     constructor(config: ClientConfig);
     getHotMeshClient: (workflowTopic: string, namespace?: string) => Promise<HotMesh>;
+    /**
+     * Creates a stream (Redis `XGROUP.CREATE`) where events can be published (XADD).
+     * It is possible that the worker that will read from this stream channel
+     * has not yet been initialized, so this call ensures that the channel
+     * exists and is ready to serve as a container for events.
+     */
     static createStream: (hotMeshClient: HotMesh, workflowTopic: string, namespace?: string) => Promise<void>;
+    /**
+     * It is possible for a client to invoke a workflow without first
+     * creating the stream. This method will verify that the stream
+     * exists and if not, create it.
+     */
     static verifyStream: (workflowTopic: string, namespace?: string) => Promise<HotMesh>;
     search: (hotMeshClient: HotMesh, index: string, query: string[]) => Promise<string[]>;
     workflow: {
         start: (options: WorkflowOptions) => Promise<WorkflowHandleService>;
+        /**
+         * send a message to a running workflow that is paused and awaiting the signal
+         */
         signal: (signalId: string, data: Record<any, any>, namespace?: string) => Promise<string>;
+        /**
+         * send a message to spawn an parallel in-process thread of execution
+         * with the same job state as the main thread but bound to a different
+         * handler function. All job state will be journaled to the same hash
+         * as is used by the main thread.
+         */
         hook: (options: HookOptions) => Promise<string>;
         getHandle: (taskQueue: string, workflowName: string, workflowId: string, namespace?: string) => Promise<WorkflowHandleService>;
         search: (taskQueue: string, workflowName: string, namespace: null | string, index: string, ...query: string[]) => Promise<string[]>;

package/build/services/durable/client.js

@@ -27,6 +27,7 @@ class ClientService {
                 }
                 return hotMeshClient;
             }
+            //create and cache an instance
             const hotMeshClient = hotmesh_1.HotMeshService.init({
                 appId: targetNS,
                 logLevel: enums_1.HMSH_LOGLEVEL,
@@ -55,6 +56,8 @@ class ClientService {
                 const workflowName = options.entity ?? options.workflowName;
                 const trc = options.workflowTrace;
                 const spn = options.workflowSpan;
+                //NOTE: HotMesh 'workflowTopic' is a created by concatenating
+                //     the taskQueue and workflowName used by the Durable module
                 const workflowTopic = `${taskQueueName}-${workflowName}`;
                 const hotMeshClient = await this.getHotMeshClient(workflowTopic, options.namespace);
                 const payload = {
@@ -72,10 +75,19 @@ class ClientService {
                 const jobId = await hotMeshClient.pub(`${options.namespace ?? factory_1.APP_ID}.execute`, payload, context, { search: options?.search?.data, marker: options?.marker });
                 return new handle_1.WorkflowHandleService(hotMeshClient, workflowTopic, jobId);
             },
+            /**
+             * send a message to a running workflow that is paused and awaiting the signal
+             */
             signal: async (signalId, data, namespace) => {
                 const topic = `${namespace ?? factory_1.APP_ID}.wfs.signal`;
                 return await (await this.getHotMeshClient(topic, namespace)).hook(topic, { id: signalId, data });
             },
+            /**
+             * send a message to spawn an parallel in-process thread of execution
+             * with the same job state as the main thread but bound to a different
+             * handler function. All job state will be journaled to the same hash
+             * as is used by the main thread.
+             */
             hook: async (options) => {
                 const workflowTopic = `${options.taskQueue}-${options.workflowName}`;
                 const payload = {
@@ -86,6 +98,7 @@ class ClientService {
                     maximumAttempts: options.config?.maximumAttempts || enums_1.HMSH_DURABLE_MAX_ATTEMPTS,
                     maximumInterval: (0, ms_1.default)(options.config?.maximumInterval || enums_1.HMSH_DURABLE_MAX_INTERVAL) / 1000,
                 };
+                //seed search data if presentthe hook before entering
                 const hotMeshClient = await this.getHotMeshClient(workflowTopic, options.namespace);
                 const msgId = await hotMeshClient.hook(`${hotMeshClient.appId}.flow.signal`, payload, types_1.StreamStatus.PENDING, 202);
                 if (options.search?.data) {
@@ -159,6 +172,12 @@ class ClientService {
 _a = ClientService;
 ClientService.topics = [];
 ClientService.instances = new Map();
+/**
+ * Creates a stream (Redis `XGROUP.CREATE`) where events can be published (XADD).
+ * It is possible that the worker that will read from this stream channel
+ * has not yet been initialized, so this call ensures that the channel
+ * exists and is ready to serve as a container for events.
+ */
 ClientService.createStream = async (hotMeshClient, workflowTopic, namespace) => {
     const store = hotMeshClient.engine.store;
     const params = { appId: namespace ?? factory_1.APP_ID, topic: workflowTopic };
@@ -167,8 +186,14 @@ ClientService.createStream = async (hotMeshClient, workflowTopic, namespace) =>
         await store.xgroup('CREATE', streamKey, 'WORKER', '$', 'MKSTREAM');
     }
     catch (err) {
+        //ignore if already exists
     }
 };
+/**
+ * It is possible for a client to invoke a workflow without first
+ * creating the stream. This method will verify that the stream
+ * exists and if not, create it.
+ */
 ClientService.verifyStream = async (workflowTopic, namespace) => {
     const targetNS = namespace ?? factory_1.APP_ID;
     if (ClientService.instances.has(targetNS)) {

package/build/services/durable/exporter.d.ts

@@ -10,20 +10,42 @@ declare class ExporterService {
     symbols: Promise<Symbols> | Symbols;
     private static symbols;
     constructor(appId: string, store: StoreService<RedisClient, RedisMulti>, logger: ILogger);
+    /**
+     * Convert the job hash from its compiles format into a DurableJobExport object with
+     * facets that describe the workflow in terms relevant to narrative storytelling.
+     */
     export(jobId: string, options?: ExportOptions): Promise<DurableJobExport>;
+    /**
+     * Inflates the job data from Redis into a DurableJobExport object
+     * @param jobHash - the job data from Redis
+     * @param dependencyList - the list of dependencies for the job
+     * @returns - the inflated job data
+     */
     inflate(jobHash: StringStringType, options: ExportOptions): DurableJobExport;
     resolveValue(raw: string, withValues: boolean): Record<string, any> | string | number | null;
+    /**
+     * Inflates the key from Redis, 3-character symbol
+     * into a human-readable JSON path, reflecting the
+     * tree-like structure of the unidimensional Hash
+     * @private
+     */
     inflateKey(key: string): string;
     filterFields(fullObject: DurableJobExport, block?: ExportFields[], allow?: ExportFields[]): Partial<DurableJobExport>;
     inflateTransition(match: RegExpMatchArray, value: string, transitionsObject: Record<string, TransitionType>): void;
     sortEntriesByCreated(obj: {
         [key: string]: TransitionType;
     }): TransitionType[];
+    /**
+     * marker names are overloaded with details like sequence, type, etc
+     */
     keyToObject(key: string): {
         index: number;
         dimension?: string;
         secondary?: number;
     };
+    /**
+     * idem list has a complicated sort order based on indexes and dimensions
+     */
     sortParts(parts: TimelineType[]): TimelineType[];
 }
 export { ExporterService };

package/build/services/durable/exporter.js

@@ -9,6 +9,10 @@ class ExporterService {
         this.logger = logger;
         this.store = store;
     }
+    /**
+     * Convert the job hash from its compiles format into a DurableJobExport object with
+     * facets that describe the workflow in terms relevant to narrative storytelling.
+     */
     async export(jobId, options = {}) {
         if (!ExporterService.symbols.has(this.appId)) {
             const symbols = this.store.getAllSymbols();
@@ -18,6 +22,12 @@ class ExporterService {
         const jobExport = this.inflate(jobData, options);
         return jobExport;
     }
+    /**
+     * Inflates the job data from Redis into a DurableJobExport object
+     * @param jobHash - the job data from Redis
+     * @param dependencyList - the list of dependencies for the job
+     * @returns - the inflated job data
+     */
     inflate(jobHash, options) {
         const timeline = [];
         const state = {};
@@ -27,16 +37,20 @@ class ExporterService {
         Object.entries(jobHash).forEach(([key, value]) => {
             const match = key.match(regex);
             if (match) {
+                //transitions
                 this.inflateTransition(match, value, transitionsObject);
             }
             else if (key.length === 3) {
+                //state
                 state[this.inflateKey(key)] = serializer_1.SerializerService.fromString(value);
             }
             else if (key.startsWith('_')) {
+                //data
                 data[key.substring(1)] = value;
             }
             else if (key.startsWith('-')) {
-                const keyParts = this.keyToObject(key);
+                //timeline
+                const keyParts = this.keyToObject(key); //key parts have meaning
                 timeline.push({
                     ...keyParts,
                     key,
@@ -67,6 +81,12 @@ class ExporterService {
         }
         return resolved;
     }
+    /**
+     * Inflates the key from Redis, 3-character symbol
+     * into a human-readable JSON path, reflecting the
+     * tree-like structure of the unidimensional Hash
+     * @private
+     */
     inflateKey(key) {
         const symbols = ExporterService.symbols.get(this.appId);
         if (key in symbols) {
@@ -104,6 +124,7 @@ class ExporterService {
         const activity = parts[0];
         const isCreate = path.endsWith('/output/metadata/ac');
         const isUpdate = path.endsWith('/output/metadata/au');
+        //for now only export activity start/stop; activity data would also be interesting
         if (isCreate || isUpdate) {
             const targetName = `${activity},${dimensions}`;
             let target = transitionsObject[targetName];
@@ -127,6 +148,9 @@ class ExporterService {
         });
         return entriesArray;
     }
+    /**
+     * marker names are overloaded with details like sequence, type, etc
+     */
     keyToObject(key) {
         function extractDimension(label) {
             const parts = label.split(',');
@@ -137,12 +161,14 @@ class ExporterService {
         }
         const parts = key.split('-');
         if (parts.length === 4) {
+            //-proxy-5-     -search-1-1-
             return {
                 index: parseInt(parts[2], 10),
                 dimension: extractDimension(parts[1]),
             };
         }
         else {
+            //-search,0,0-1-1-    -proxy,0,0-1-
             return {
                 index: parseInt(parts[2], 10),
                 secondary: parseInt(parts[3], 10),
@@ -150,6 +176,9 @@ class ExporterService {
             };
         }
     }
+    /**
+     * idem list has a complicated sort order based on indexes and dimensions
+     */
     sortParts(parts) {
         return parts.sort((a, b) => {
             const { dimension: aDim, index: aIdx, secondary: aSec } = a;