@hotmeshio/hotmesh 0.0.57 → 0.0.59

package/build/services/store/index.js

@@ -77,6 +77,7 @@ class StoreService {
         return result > 0 || result === 'OK' || result === true;
     }
     async zAdd(key, score, value, redisMulti) {
+        //default call signature uses 'ioredis' NPM Package format
         return await (redisMulti || this.redisClient)[this.commands.zadd](key, score, value);
     }
     async zRangeByScoreWithScores(key, score, value) {
@@ -101,6 +102,11 @@ class StoreService {
     invalidateCache() {
         this.cache.invalidate();
     }
+    /**
+     * At any given time only a single engine will
+     * check for and process work items in the
+     * time and signal task queues.
+     */
     async reserveScoutRole(scoutType, delay = enums_1.HMSH_SCOUT_INTERVAL_SECONDS) {
         const key = this.mintKey(key_1.KeyType.WORK_ITEMS, { appId: this.appId, scoutType });
         const success = await this.exec('SET', key, `${scoutType}:${(0, utils_1.formatISODate)(new Date())}`, 'NX', 'EX', `${delay - 1}`);
@@ -128,6 +134,7 @@ class StoreService {
         throw new Error('settings not found');
     }
     async setSettings(manifest) {
+        //HotMesh heartbeat. If a connection is made, the version will be set
         const params = {};
         const key = this.mintKey(key_1.KeyType.HOTMESH, params);
         return await this.redisClient[this.commands.hset](key, manifest);
@@ -135,8 +142,10 @@ class StoreService {
     async reserveSymbolRange(target, size, type) {
         const rangeKey = this.mintKey(key_1.KeyType.SYMKEYS, { appId: this.appId });
         const symbolKey = this.mintKey(key_1.KeyType.SYMKEYS, { activityId: target, appId: this.appId });
+        //reserve the slot in a `pending` state (range will be established in the next step)
         const response = await this.redisClient[this.commands.hsetnx](rangeKey, target, '?:?');
         if (response) {
+            //if the key didn't exist, set the inclusive range and seed metadata fields
             const upperLimit = await this.redisClient[this.commands.hincrby](rangeKey, ':cursor', size);
             const lowerLimit = upperLimit - size;
             const inclusiveRange = `${lowerLimit}:${upperLimit - 1}`;
@@ -146,6 +155,7 @@ class StoreService {
             return [lowerLimit + serializer_1.MDATA_SYMBOLS.SLOTS, upperLimit - 1, {}];
         }
         else {
+            //if the key already existed, get the lower limit and add the number of symbols
             const range = await this.redisClient[this.commands.hget](rangeKey, target);
             const [lowerLimitString] = range.split(':');
             const lowerLimit = parseInt(lowerLimitString, 10);
@@ -157,6 +167,7 @@ class StoreService {
         }
     }
     async getAllSymbols() {
+        //get hash with all reserved symbol ranges
         const rangeKey = this.mintKey(key_1.KeyType.SYMKEYS, { appId: this.appId });
         const ranges = await this.redisClient[this.commands.hgetall](rangeKey);
         const rangeKeys = Object.keys(ranges).sort();
@@ -329,6 +340,11 @@ class StoreService {
         };
         return await this.redisClient[this.commands.hset](key, payload);
     }
+    /**
+     * Registers the job, `jobId`, with `originJobId`. In the future,
+     * when `originJobId` is interrupted/expired, the items in the
+     * list (added via RPUSH) will be interrupted/expired (removed via LPOPed).
+     */
     async registerJobDependency(depType, originJobId, topic, jobId, gId, pd = '', multi) {
         const privateMulti = multi || this.getMulti();
         const dependencyParams = {
@@ -348,10 +364,15 @@ class StoreService {
             return await privateMulti.exec();
         }
     }
+    /**
+     * Ensures a `hook signal` is delisted when its parent activity/job
+     * is interrupted/expired.
+     */
     async registerSignalDependency(jobId, signalKey, dad, multi) {
         const privateMulti = multi || this.getMulti();
         const dependencyParams = { appId: this.appId, jobId };
         const dependencyKey = this.mintKey(key_1.KeyType.JOB_DEPENDENTS, dependencyParams);
+        //persiste dependency tasks as multi-segment composite keys
         const delistTask = [
             'delist',
             'signal',
@@ -388,6 +409,7 @@ class StoreService {
         }
     }
     hGetAllResult(result) {
+        //default response signature uses 'redis' NPM Package format
         return result;
     }
     async getJobStats(jobKeys) {
@@ -416,12 +438,13 @@ class StoreService {
     async getJobIds(indexKeys, idRange) {
         const multi = this.getMulti();
         for (const idsKey of indexKeys) {
-            multi[this.commands.lrange](idsKey, idRange[0], idRange[1]);
+            multi[this.commands.lrange](idsKey, idRange[0], idRange[1]); //0,-1 returns all ids
         }
         const results = await multi.exec();
         const output = {};
         for (const [index, result] of results.entries()) {
             const key = indexKeys[index];
+            //todo: resolve this discrepancy between redis/ioredis
             const idsList = result[1] || result;
             if (idsList && idsList.length > 0) {
                 output[key] = idsList;
@@ -460,6 +483,10 @@ class StoreService {
         await (multi || this.redisClient)[this.commands.hset](hashKey, hashData);
         return jobId;
     }
+    /**
+     * Returns custom search fields and values.
+     * NOTE: The `fields` param should NOT prefix items with an underscore.
+     */
     async getQueryState(jobId, fields) {
         const key = this.mintKey(key_1.KeyType.JOB_STATE, { appId: this.appId, jobId });
         const _fields = fields.map(field => `_${field}`);
@@ -471,6 +498,7 @@ class StoreService {
         return jobData;
     }
     async getState(jobId, consumes, dIds) {
+        //get abbreviated field list (the symbols for the paths)
         const key = this.mintKey(key_1.KeyType.JOB_STATE, { appId: this.appId, jobId });
         const symbolNames = Object.keys(consumes);
         const symKeys = await this.getSymbolKeys(symbolNames);
@@ -478,7 +506,7 @@ class StoreService {
         const fields = this.serializer.abbreviate(consumes, symbolNames, [':']);
         const jobDataArray = await this.redisClient[this.commands.hmget](key, fields);
         const jobData = {};
-        let atLeast1 = false;
+        let atLeast1 = false; //if status field (':') isn't present assume 404
         fields.forEach((field, index) => {
             if (jobDataArray[index]) {
                 atLeast1 = true;
@@ -509,9 +537,13 @@ class StoreService {
         }
         return job;
     }
+    /**
+     * collate is a generic method for incrementing a value in a hash
+     * in order to track their progress during processing.
+     */
     async collate(jobId, activityId, amount, dIds, multi) {
         const jobKey = this.mintKey(key_1.KeyType.JOB_STATE, { appId: this.appId, jobId });
-        const collationKey = `${activityId}/output/metadata/as`;
+        const collationKey = `${activityId}/output/metadata/as`; //activity state
         const symbolNames = [activityId];
         const symKeys = await this.getSymbolKeys(symbolNames);
         const symVals = await this.getSymbolValues();
@@ -521,6 +553,12 @@ class StoreService {
         const targetId = Object.keys(hashData)[0];
         return await (multi || this.redisClient)[this.commands.hincrbyfloat](jobKey, targetId, amount);
     }
+    /**
+     * synthentic collation affects those activities in the graph
+     * that represent the synthetic DAG that was materialized during compilation;
+     * Synthetic targeting ensures that re-entry due to failure can be distinguished from
+     * purposeful re-entry.
+     */
     async collateSynthetic(jobId, guid, amount, multi) {
         const jobKey = this.mintKey(key_1.KeyType.JOB_STATE, { appId: this.appId, jobId });
         return await (multi || this.redisClient)[this.commands.hincrbyfloat](jobKey, guid, amount);
@@ -659,10 +697,12 @@ class StoreService {
     }
     async setHookSignal(hook, multi) {
         const key = this.mintKey(key_1.KeyType.SIGNALS, { appId: this.appId });
+        //destructure the hook key
         const { topic, resolved, jobId } = hook;
         const signalKey = `${topic}:${resolved}`;
         const payload = { [signalKey]: jobId };
         await (multi || this.redisClient)[this.commands.hset](key, payload);
+        //jobId needs even more destructuring
         const [_aid, dad, _gid, jid] = jobId.split(key_1.VALSEP);
         return await this.registerSignalDependency(jid, signalKey, dad, multi);
     }
@@ -701,6 +741,7 @@ class StoreService {
         const didRemove = await this.redisClient[this.commands.zrem](zsetKey, workItemKey);
         if (didRemove) {
             if (scrub) {
+                //indexes can be designed to be self-cleaning; `engine.hookAll` exposes this option
                 this.redisClient[this.commands.expire](processedKey, 0);
                 this.redisClient[this.commands.expire](key.split(":").slice(0, 5).join(":"), 0);
             }
@@ -719,6 +760,11 @@ class StoreService {
             await this.redisClient[this.commands.expire](jobKey, inSeconds);
         }
     }
+    /**
+     * register the descendants of an expired origin flow to be
+     * expired at a future date; options indicate whether this
+     * is a standard `expire` or an `interrupt`
+     */
     async registerDependenciesForCleanup(jobId, deletionTime, options) {
         const depParams = { appId: this.appId, jobId };
         const depKey = this.mintKey(key_1.KeyType.JOB_DEPENDENTS, depParams);
@@ -732,8 +778,15 @@ class StoreService {
         const depKey = this.mintKey(key_1.KeyType.JOB_DEPENDENTS, depParams);
         return this.redisClient[this.commands.lrange](depKey, 0, -1);
     }
+    /**
+     * registers a hook activity to be awakened (uses ZSET to
+     * store the 'sleep group' and LIST to store the events
+     * for the given sleep group. Sleep groups are
+     * organized into 'n'-second blocks (LISTS))
+     */
     async registerTimeHook(jobId, gId, activityId, type, deletionTime, dad, multi) {
         const listKey = this.mintKey(key_1.KeyType.TIME_RANGE, { appId: this.appId, timeValue: deletionTime });
+        //construct the composite key (the key has enough info to signal the hook)
         const timeEvent = [
             type,
             activityId,
@@ -754,6 +807,7 @@ class StoreService {
             let [pType, pKey] = this.resolveTaskKeyContext(listKey);
             const timeEvent = await this.redisClient[this.commands.lpop](pKey);
             if (timeEvent) {
+                //deconstruct composite key
                 let [type, activityId, gId, _pd, ...jobId] = timeEvent.split(key_1.VALSEP);
                 const jid = jobId.join(key_1.VALSEP);
                 if (type === 'delist') {
@@ -772,6 +826,14 @@ class StoreService {
         }
         return false;
     }
+    /**
+     * when processing time jobs, the target LIST ID returned
+     * from the ZSET query can be prefixed to denote what to
+     * do with the work list. (not everything is known in advance,
+     * so the ZSET key defines HOW to approach the work in the
+     * generic LIST (lists typically contain target job ids)
+     * @param {string} listKey - composite key
+     */
     resolveTaskKeyContext(listKey) {
         if (listKey.startsWith(`${key_1.TYPSEP}INTERRUPT`)) {
             return ['interrupt', listKey.split(key_1.TYPSEP)[2]];
@@ -783,24 +845,38 @@ class StoreService {
             return ['sleep', listKey];
         }
     }
+    /**
+     * Interrupts a job and sets sets a job error (410), if 'throw'!=false.
+     * This method is called by the engine and not by an activity and is
+     * followed by a call to execute job completion/cleanup tasks
+     * associated with a job completion event.
+     *
+     * Todo: move most of this logic to the engine (too much logic for the store)
+     */
     async interrupt(topic, jobId, options = {}) {
         try {
+            //verify job exists
             const status = await this.getStatus(jobId, this.appId);
             if (status <= 0) {
+                //verify still active; job already completed
                 throw new Error(`Job ${jobId} already completed`);
             }
+            //decrement job status (:) by 1bil
             const amount = -1000000000;
             const jobKey = this.mintKey(key_1.KeyType.JOB_STATE, { appId: this.appId, jobId });
             const result = await this.redisClient[this.commands.hincrbyfloat](jobKey, ':', amount);
             if (result <= amount) {
+                //verify active state; job already interrupted
                 throw new Error(`Job ${jobId} already completed`);
             }
+            //persist the error unless specifically told not to
             if (options.throw !== false) {
-                const errKey = `metadata/err`;
-                const symbolNames = [`$${topic}`];
+                const errKey = `metadata/err`; //job errors are stored at the path `metadata/err`
+                const symbolNames = [`$${topic}`]; //the symbol for `metadata/err` is in redis and stored using the job topic
                 const symKeys = await this.getSymbolKeys(symbolNames);
                 const symVals = await this.getSymbolValues();
                 this.serializer.resetSymbols(symKeys, symVals, {});
+                //persists the standard 410 error (job is `gone`)
                 const err = JSON.stringify({
                     code: options.code ?? enums_1.HMSH_CODE_INTERRUPT,
                     message: options.reason ?? `job [${jobId}] interrupted`,

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

@@ -51,7 +51,10 @@ class IORedisStreamService extends index_1.StreamService {
     }
     async xreadgroup(command, groupName, consumerName, blockOption, blockTime, streamsOption, streamName, id) {
         try {
-            return await this.redisClient.xreadgroup(command, groupName, consumerName, blockOption, blockTime, streamsOption, streamName, id);
+            //@ts-ignore
+            return await this.redisClient.xreadgroup(command, groupName, consumerName, 
+            // @ts-ignore
+            blockOption, blockTime, streamsOption, streamName, id);
         }
         catch (error) {
             this.logger.error(`Error reading stream data [Stream ${streamName}] [Group ${groupName}]`, { ...error });

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

@@ -16,7 +16,16 @@ declare class TaskService {
     enqueueWorkItems(keys: string[]): Promise<void>;
     registerJobForCleanup(jobId: string, inSeconds: number, options: JobCompletionOptions): Promise<void>;
     registerTimeHook(jobId: string, gId: string, activityId: string, type: WorkListTaskType, inSeconds: number, dad: string, multi?: RedisMulti): Promise<void>;
+    /**
+     * Should this engine instance play the role of 'scout' on behalf
+     * of the entire quorum? The scout role is responsible for processing
+     * task lists on behalf of the collective.
+     */
     shouldScout(): Promise<boolean>;
+    /**
+     * Callback handler that takes an item from a work list and
+     * processes according to its type
+     */
     processTimeHooks(timeEventCallback: (jobId: string, gId: string, activityId: string, type: WorkListTaskType) => Promise<void>, listKey?: string): Promise<void>;
     cancelCleanup(): void;
     getHookRule(topic: string): Promise<HookRule | undefined>;

package/build/services/task/index.js

@@ -22,6 +22,7 @@ class TaskService {
             const destinationKey = `${sourceKey}:processed`;
             const jobId = await this.store.processTaskQueue(sourceKey, destinationKey);
             if (jobId) {
+                //todo: don't use 'id', make configurable using hook rule
                 await hookEventCallback(topic, { ...data, id: jobId });
             }
             else {
@@ -48,6 +49,11 @@ class TaskService {
         const awakenTimeSlot = Math.floor(fromNow / fidelityMS) * fidelityMS;
         await this.store.registerTimeHook(jobId, gId, activityId, type, awakenTimeSlot, dad, multi);
     }
+    /**
+     * Should this engine instance play the role of 'scout' on behalf
+     * of the entire quorum? The scout role is responsible for processing
+     * task lists on behalf of the collective.
+     */
     async shouldScout() {
         const wasScout = this.isScout;
         const isScout = wasScout || (this.isScout = await this.store.reserveScoutRole('time'));
@@ -61,6 +67,10 @@ class TaskService {
         }
         return false;
     }
+    /**
+     * Callback handler that takes an item from a work list and
+     * processes according to its type
+     */
     async processTimeHooks(timeEventCallback, listKey) {
         if (await this.shouldScout()) {
             try {
@@ -68,12 +78,16 @@ class TaskService {
                 if (Array.isArray(workListTask)) {
                     const [listKey, target, gId, activityId, type] = workListTask;
                     if (type === 'child') {
+                        //continue; this child is listed here for convenience, but
+                        //  will be expired by an origin ancestor and is listed there
                     }
                     else if (type === 'delist') {
+                        //delist the signalKey (target)
                         const key = this.store.mintKey(hotmesh_1.KeyType.SIGNALS, { appId: this.store.appId });
                         await this.store.redisClient[this.store.commands.hdel](key, target);
                     }
                     else {
+                        //awaken/expire/interrupt
                         await timeEventCallback(target, gId, activityId, type);
                     }
                     await (0, utils_1.sleepFor)(0);
@@ -81,11 +95,13 @@ class TaskService {
                     this.processTimeHooks(timeEventCallback, listKey);
                 }
                 else if (workListTask) {
+                    //a worklist was just emptied; try again immediately
                     await (0, utils_1.sleepFor)(0);
                     this.errorCount = 0;
                     this.processTimeHooks(timeEventCallback);
                 }
                 else {
+                    //no worklists exist; sleep before checking
                     let sleep = (0, utils_1.XSleepFor)(enums_1.HMSH_FIDELITY_SECONDS * 1000);
                     this.cleanupTimeout = sleep.timerId;
                     await sleep.promise;
@@ -94,6 +110,8 @@ class TaskService {
                 }
             }
             catch (err) {
+                //most common reasons: deleted job not found; container stopping; test stopping
+                //less common: redis/cluster down; retry with fallback (5s max main reassignment)
                 this.logger.warn('task-process-timehooks-error', err);
                 await (0, utils_1.sleepFor)(1000 * this.errorCount++);
                 if (this.errorCount < 5) {
@@ -102,6 +120,7 @@ class TaskService {
             }
         }
         else {
+            //didn't get the scout role; try again in 'one-ish' minutes
             let sleep = (0, utils_1.XSleepFor)(enums_1.HMSH_SCOUT_INTERVAL_SECONDS * 1000 * 2 * Math.random());
             this.cleanupTimeout = sleep.timerId;
             await sleep.promise;
@@ -126,6 +145,7 @@ class TaskService {
             const jobId = context.metadata.jid;
             const gId = context.metadata.gid;
             const activityId = hookRule.to;
+            //composite keys are used to fully describe the task target
             const compositeJobKey = [
                 activityId,
                 dad,
@@ -147,13 +167,22 @@ class TaskService {
     async processWebHookSignal(topic, data) {
         const hookRule = await this.getHookRule(topic);
         if (hookRule) {
+            //NOTE: both formats are supported by the mapping engine:
+            //      `$self.hook.data` OR `$hook.data`
             const context = { $self: { hook: { data } }, $hook: { data } };
             const mapExpression = hookRule.conditions.match[0].actual;
             const resolved = pipe_1.Pipe.resolve(mapExpression, context);
             const hookSignalId = await this.store.getHookSignal(topic, resolved);
             if (!hookSignalId) {
+                //messages can be double-processed; not an issue; return `undefined`
+                //users can also provide a bogus topic; not an issue; return `undefined`
                 return undefined;
             }
+            //`aid` is part of composite key, but the hook `topic` is its public interface;
+            // this means that a new version of the graph can be deployed and the
+            // topic can be re-mapped to a different activity id. Outside callers
+            // can adhere to the unchanged contract (calling the same topic),
+            // while the internal system can be updated in real-time as necessary.
             const [_aid, dad, gid, ...jid] = hookSignalId.split(key_1.WEBSEP);
             return [jid.join(key_1.WEBSEP), hookRule.to, dad, gid];
         }
@@ -164,6 +193,8 @@ class TaskService {
     async deleteWebHookSignal(topic, data) {
         const hookRule = await this.getHookRule(topic);
         if (hookRule) {
+            //NOTE: both formats are supported by the mapping engine:
+            //      `$self.hook.data` OR `$hook.data`
             const context = { $self: { hook: { data } }, $hook: { data } };
             const mapExpression = hookRule.conditions.match[0].actual;
             const resolved = pipe_1.Pipe.resolve(mapExpression, context);

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

@@ -35,6 +35,13 @@ declare class TelemetryService {
     setTelemetryContext(span: Span, leg: number): void;
     setActivityError(message: string): void;
     setStreamError(message: string): void;
+    /**
+     * Adds the paths (HGET) necessary to restore telemetry state for an activity
+     * @param consumes
+     * @param config
+     * @param metadata
+     * @param leg
+     */
     static addTargetTelemetryPaths(consumes: Consumes, config: ActivityType, metadata: ActivityMetadata, leg: number): void;
     static bindJobTelemetryToState(state: StringStringType, config: ActivityType, context: JobState): void;
     static bindActivityTelemetryToState(state: StringAnyType, config: ActivityType, metadata: ActivityMetadata, context: JobState, leg: number): void;

package/build/services/telemetry/index.js

@@ -13,6 +13,7 @@ class TelemetryService {
     constructor(appId, config, metadata, context) {
         this.leg = 1;
         this.appId = appId;
+        //these are REQUIRED for job and activity spans
         this.config = config;
         this.metadata = metadata;
         this.context = context;
@@ -81,6 +82,7 @@ class TelemetryService {
         return span;
     }
     mapActivityAttributes() {
+        //export user-defined span attributes (app.activity.data.*)
         if (this.config.telemetry) {
             const telemetryAtts = new mapper_1.MapperService(this.config.telemetry, this.context).mapRules();
             const namespacedAtts = {
@@ -121,7 +123,7 @@ class TelemetryService {
                 traceId: this.traceId,
                 spanId: this.spanId,
                 isRemote: true,
-                traceFlags: 1,
+                traceFlags: 1, // (todo: revisit sampling strategy/config)
             };
             const parentContext = telemetry_1.trace.setSpanContext(telemetry_1.context.active(), restoredSpanContext);
             return parentContext;
@@ -177,6 +179,13 @@ class TelemetryService {
     setStreamError(message) {
         this.span?.setStatus({ code: telemetry_1.SpanStatusCode.ERROR, message });
     }
+    /**
+     * Adds the paths (HGET) necessary to restore telemetry state for an activity
+     * @param consumes
+     * @param config
+     * @param metadata
+     * @param leg
+     */
     static addTargetTelemetryPaths(consumes, config, metadata, leg) {
         if (leg === 1) {
             if (!(config.parent in consumes)) {
@@ -198,14 +207,17 @@ class TelemetryService {
     }
     static bindActivityTelemetryToState(state, config, metadata, context, leg) {
         if (config.type === 'trigger') {
+            //trigger activities run non-duplexed and only have a single leg (2)
             state[`${metadata.aid}/output/metadata/l1s`] = context['$self'].output.metadata.l1s;
             state[`${metadata.aid}/output/metadata/l2s`] = context['$self'].output.metadata.l2s;
         }
         else if (utils_1.polyfill.resolveActivityType(config.type) === 'hook' && leg === 1) {
+            //hook activities run non-duplexed and only have a single leg (1)
             state[`${metadata.aid}/output/metadata/l1s`] = context['$self'].output.metadata.l1s;
             state[`${metadata.aid}/output/metadata/l2s`] = context['$self'].output.metadata.l1s;
         }
         else if (config.type === 'signal' && leg === 1) {
+            //signal activities run non-duplexed and only have a single leg (1)
             state[`${metadata.aid}/output/metadata/l1s`] = context['$self'].output.metadata.l1s;
             state[`${metadata.aid}/output/metadata/l2s`] = context['$self'].output.metadata.l1s;
         }

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

@@ -30,6 +30,10 @@ declare class WorkerService {
     initStreamChannel(service: WorkerService, stream: RedisClient): Promise<void>;
     initRouter(worker: HotMeshWorker, logger: ILogger): Router;
     subscriptionHandler(): SubscriptionCallback;
+    /**
+     * A quorum-wide command to broadcaset system details.
+     *
+     */
     doRollCall(message: RollCallMessage): Promise<void>;
     cancelRollCall(): void;
     stop(): void;

package/build/services/worker/index.js

@@ -97,7 +97,7 @@ class WorkerService {
         return async (topic, message) => {
             self.logger.debug('worker-event-received', { topic, type: message.type });
             if (message.type === 'throttle') {
-                if (message.topic !== null) {
+                if (message.topic !== null) { //undefined allows passthrough
                     self.throttle(message.throttle);
                 }
             }
@@ -105,12 +105,16 @@ class WorkerService {
                 self.sayPong(self.appId, self.guid, message.originator, message.details);
             }
             else if (message.type === 'rollcall') {
-                if (message.topic !== null) {
+                if (message.topic !== null) { //undefined allows passthrough
                     self.doRollCall(message);
                 }
             }
         };
     }
+    /**
+     * A quorum-wide command to broadcaset system details.
+     *
+     */
     async doRollCall(message) {
         let iteration = 0;
         let max = !isNaN(message.max) ? message.max : enums_1.HMSH_QUORUM_ROLLCALL_CYCLES;

package/build/types/activity.d.ts

@@ -32,7 +32,18 @@ interface Measure {
     target: string;
 }
 interface TriggerActivityStats {
+    /**
+     * dependent parent job id; including this allows the parent's
+     * expiration/interruption events to cascade; set
+     * `expire` in the YAML for the dependent graph
+     * to 0 and provide the parent for dependent,
+     * cascading interruption and cleanup
+     */
     parent?: string;
+    /**
+     * adjacent parent job id; this is the actual adjacent
+     * parent in the graph, but it is not used for cascading expiration
+     */
     adjacent?: string;
     id?: {
         [key: string]: unknown;
@@ -40,7 +51,19 @@ interface TriggerActivityStats {
     key?: {
         [key: string]: unknown;
     } | string;
+    /**
+     * @deprecated
+     * return 'infinity' to disable; default behavior
+     * is to always segment keys by time to ensure
+     * indexes (Redis LIST) never grow unbounded
+     * as a default behavior; for now, 5m is default
+     * and infinity can be set to override
+     */
     granularity?: string;
+    /**
+     * @deprecated
+     * what to capture
+     */
     measures?: Measure[];
 }
 interface TriggerActivity extends BaseActivity {
@@ -79,26 +102,84 @@ interface SignalActivity extends BaseActivity {
 }
 interface InterruptActivity extends BaseActivity {
     type: 'interrupt';
+    /**
+     * Optional Reason; will be used as the error `message` when thrown
+     * @default 'Job Interrupted'
+     */
     reason?: string;
+    /**
+     * throw JobInterrupted error upon interrupting
+     * @default true
+     */
     throw?: boolean;
+    /**
+     * Interrupt child/descendant jobs
+     * @default false
+     */
     descend?: boolean;
+    /**
+     * Target job id (if not present the current job will be targeted)
+     */
     target?: string;
+    /**
+     * Optional topic to publish the interrupt message (if not present the current job topic will be used
+     */
     topic?: string;
+    /**
+     * Optional Error Code; will be used as the error `code` when thrown
+     * @default 410
+     */
     code?: number;
+    /**
+     * Optional stack trace
+     */
     stack?: string;
 }
 type ActivityType = BaseActivity | TriggerActivity | AwaitActivity | WorkerActivity | InterruptActivity | HookActivity | SignalActivity | CycleActivity;
 type ActivityData = Record<string, any>;
+/**
+ * Type definition for activity metadata.
+ */
 type ActivityMetadata = {
+    /**
+     * Unique identifier for the activity.
+     */
     aid: string;
+    /**
+     * Type of the activity.
+     */
     atp: string;
+    /**
+     * Subtype of the activity.
+     */
     stp: string;
+    /**
+     * Timestamp when the activity was created, in GMT.
+     */
     ac: string;
+    /**
+     * Timestamp when the activity was last updated, in GMT.
+     */
     au: string;
+    /**
+     * Optional stringified JSON containing error details such as message, code, and an optional error object.
+     */
     err?: string;
+    /**
+     * OpenTelemetry span context for the first leg of the activity.
+     */
     l1s?: string;
+    /**
+     * OpenTelemetry span context for the second leg of the activity.
+     */
     l2s?: string;
+    /**
+     * Dimensional address, used for additional metadata.
+     */
     dad?: string;
+    /**
+     * Status of the activity, could be codes representing different states.
+     */
     as?: string;
 };
 type ActivityContext = {