@hotmeshio/hotmesh 0.1.14 → 0.1.16

package/build/services/activities/signal.d.ts

@@ -8,13 +8,7 @@ declare class Signal extends Activity {
     process(): Promise<string>;
     mapSignalData(): Record<string, any>;
     mapResolverData(): Record<string, any>;
-    /**
-     * The signal activity will hook one
-     */
     hookOne(): Promise<string>;
-    /**
-     * The signal activity will hook all paused jobs that share the same job key.
-     */
     hookAll(): Promise<string[]>;
 }
 export { Signal };

package/build/services/activities/signal.js

@@ -11,7 +11,6 @@ class Signal extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
         super(config, data, metadata, hook, engine, context);
     }
-    //********  LEG 1 ENTRY  ********//
     async process() {
         this.logger.debug('signal-process', {
             jid: this.context.metadata.jid,
@@ -23,7 +22,6 @@ class Signal extends activity_1.Activity {
             await this.verifyEntry();
             telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
             telemetry.startActivitySpan(this.leg);
-            //save state and notarize early completion (signals only run leg1)
             const multi = this.store.getMulti();
             this.adjacencyList = await this.filterAdjacent();
             this.mapOutputData();
@@ -32,14 +30,12 @@ class Signal extends activity_1.Activity {
             await collator_1.CollatorService.notarizeEarlyCompletion(this, multi);
             await this.setStatus(this.adjacencyList.length - 1, multi);
             const multiResponse = (await multi.exec());
-            //todo: this should execute BEFORE the status is decremented
             if (this.config.subtype === 'all') {
                 await this.hookAll();
             }
             else {
                 await this.hookOne();
             }
-            //transition to adjacent activities
             const jobStatus = this.resolveStatus(multiResponse);
             const attrs = { 'app.job.jss': jobStatus };
             const messageIds = await this.transition(this.adjacencyList, jobStatus);
@@ -90,9 +86,6 @@ class Signal extends activity_1.Activity {
             return mapper.mapRules();
         }
     }
-    /**
-     * The signal activity will hook one
-     */
     async hookOne() {
         const topic = pipe_1.Pipe.resolve(this.config.topic, this.context);
         const signalInputData = this.mapSignalData();
@@ -100,23 +93,15 @@ class Signal extends activity_1.Activity {
         const code = pipe_1.Pipe.resolve(this.config.code, this.context);
         return await this.engine.hook(topic, signalInputData, status, code);
     }
-    /**
-     * The signal activity will hook all paused jobs that share the same job key.
-     */
     async hookAll() {
-        //prep 1) generate `input signal data` (essentially the webhook payload)
         const signalInputData = this.mapSignalData();
-        //prep 2) generate data that resolves the job key (per the YAML config)
         const keyResolverData = this.mapResolverData();
         if (this.config.scrub) {
-            //self-clean the indexes upon use if configured
             keyResolverData.scrub = true;
         }
-        //prep 3) jobKeys can contain multiple indexes (per the YAML config)
         const key_name = pipe_1.Pipe.resolve(this.config.key_name, this.context);
         const key_value = pipe_1.Pipe.resolve(this.config.key_value, this.context);
         const indexQueryFacets = [`${key_name}:${key_value}`];
-        //execute: `hookAll` will now resume all paused jobs that share the same job key
         return await this.engine.hookAll(this.config.topic, signalInputData, keyResolverData, indexQueryFacets);
     }
 }

package/build/services/activities/trigger.d.ts

@@ -1,12 +1,15 @@
 import { EngineService } from '../engine';
 import { ActivityData, ActivityMetadata, ActivityType, TriggerActivity } from '../../types/activity';
-import { JobState, ExtensionType } from '../../types/job';
+import { JobState, ExtensionType, JobStatus } from '../../types/job';
 import { RedisMulti } from '../../types/redis';
+import { StringScalarType } from '../../types/serializer';
 import { Activity } from './activity';
 declare class Trigger extends Activity {
     config: TriggerActivity;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
     process(options?: ExtensionType): Promise<string>;
+    transitionAndLogAdjacent(options: ExtensionType, jobStatus: JobStatus, attrs: StringScalarType): Promise<void>;
+    initStatus(options: ExtensionType, count: number): number;
     setExpired(seconds: number, multi: RedisMulti): Promise<void>;
     safeKey(key: string): string;
     bindSearchData(options?: ExtensionType): void;
@@ -22,10 +25,6 @@ declare class Trigger extends Activity {
     resolveJobId(context: Partial<JobState>): string;
     resolveJobKey(context: Partial<JobState>): string;
     setStateNX(status?: number): Promise<void>;
-    /**
-     * Registers this job as a dependent of the parent job; when the
-     * parent job is interrupted, this job will be interrupted
-     */
     registerJobDependency(multi?: RedisMulti): Promise<void>;
     setStats(multi?: RedisMulti): Promise<void>;
 }

package/build/services/activities/trigger.js

@@ -25,9 +25,10 @@ class Trigger extends activity_1.Activity {
             telemetry.startJobSpan();
             telemetry.startActivitySpan(this.leg);
             this.mapJobData();
-            await this.setStateNX(options?.pending ? -1 : undefined);
             this.adjacencyList = await this.filterAdjacent();
-            await this.setStatus(options?.pending ? -1 : this.adjacencyList.length);
+            const initialStatus = this.initStatus(options, this.adjacencyList.length);
+            await this.setStateNX(initialStatus);
+            await this.setStatus(initialStatus);
             this.bindSearchData(options);
             this.bindMarkerData(options);
             const multi = this.store.getMulti();
@@ -40,20 +41,12 @@ class Trigger extends activity_1.Activity {
                 await this.registerJobDependency(multi);
             }
             await multi.exec();
-            //if the parent (spawner) chose not to await,
-            // emit the job_id as the data payload { job_id }
             this.execAdjacentParent();
             telemetry.mapActivityAttributes();
             const jobStatus = Number(this.context.metadata.js);
             telemetry.setJobAttributes({ 'app.job.jss': jobStatus });
             const attrs = { 'app.job.jss': jobStatus };
-            //todo: enable resume from pending state
-            if (jobStatus !== -1) {
-                const messageIds = await this.transition(this.adjacencyList, jobStatus);
-                if (messageIds.length) {
-                    attrs['app.activity.mids'] = messageIds.join(',');
-                }
-            }
+            await this.transitionAndLogAdjacent(options, jobStatus, attrs);
             telemetry.setActivityAttributes(attrs);
             return this.context.metadata.jid;
         }
@@ -77,6 +70,23 @@ class Trigger extends activity_1.Activity {
             });
         }
     }
+    async transitionAndLogAdjacent(options = {}, jobStatus, attrs) {
+        if (isNaN(options.pending)) {
+            const messageIds = await this.transition(this.adjacencyList, jobStatus);
+            if (messageIds.length) {
+                attrs['app.activity.mids'] = messageIds.join(',');
+            }
+        }
+    }
+    initStatus(options = {}, count) {
+        if (options.pending) {
+            return -1;
+        }
+        else if (options.statusThreshold) {
+            return 1000000 - options.statusThreshold + count;
+        }
+        return count;
+    }
     async setExpired(seconds, multi) {
         await this.store.expireJob(this.context.metadata.jid, seconds, multi);
     }
@@ -179,7 +189,7 @@ class Trigger extends activity_1.Activity {
             },
         };
         this.context['$self'] = this.context[this.metadata.aid];
-        this.context['$job'] = this.context; //NEVER call STRINGIFY! (circular)
+        this.context['$job'] = this.context;
     }
     bindJobMetadataPaths() {
         return serializer_1.MDATA_SYMBOLS.JOB.KEYS.map((key) => `metadata/${key}`);
@@ -207,10 +217,6 @@ class Trigger extends activity_1.Activity {
             throw new errors_1.DuplicateJobError(jobId);
         }
     }
-    /**
-     * Registers this job as a dependent of the parent job; when the
-     * parent job is interrupted, this job will be interrupted
-     */
     async registerJobDependency(multi) {
         const depKey = this.config.stats?.parent ?? this.context.metadata.pj;
         let resolvedDepKey = depKey ? pipe_1.Pipe.resolve(depKey, this.context) : '';

package/build/services/activities/worker.js

@@ -11,7 +11,6 @@ class Worker extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
         super(config, data, metadata, hook, engine, context);
     }
-    //********  INITIAL ENTRY POINT (A)  ********//
     async process() {
         this.logger.debug('worker-process', {
             jid: this.context.metadata.jid,
@@ -24,15 +23,12 @@ class Worker extends activity_1.Activity {
             telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
             telemetry.startActivitySpan(this.leg);
             this.mapInputData();
-            //save state and authorize reentry
             const multi = this.store.getMulti();
-            //todo: await this.registerTimeout();
             const messageId = await this.execActivity(multi);
             await collator_1.CollatorService.authorizeReentry(this, multi);
             await this.setState(multi);
             await this.setStatus(0, multi);
             const multiResponse = (await multi.exec());
-            //telemetry
             telemetry.mapActivityAttributes();
             const jobStatus = this.resolveStatus(multiResponse);
             telemetry.setActivityAttributes({

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

@@ -6,40 +6,13 @@ import { Activity } from '../activities/activity';
 import { Cycle } from '../activities/cycle';
 declare class CollatorService {
     static targetLength: number;
-    /**
-     * Upon re/entry, verify that the job status is active
-     */
     static assertJobActive(status: number, jobId: string, activityId: string, threshold?: number): void;
-    /**
-     * returns the dimensional address (dad) for the target; due
-     * to the nature of the notary system, the dad for leg 2 entry
-     * must target the `0` index while leg 2 exit must target the
-     * current index (0)
-     */
     static getDimensionalAddress(activity: Activity, isEntry?: boolean): Record<string, string>;
-    /**
-     * resolves the dimensional address for the
-     * ancestor in the graph to go back to. this address
-     * is determined by trimming the last digits from
-     * the `dad` (including the target).
-     * the target activity index is then set to `0`, so that
-     * the origin node can be queried for approval/entry.
-     */
     static resolveReentryDimension(activity: Cycle): string;
     static notarizeEntry(activity: Activity, multi?: RedisMulti): Promise<number>;
     static authorizeReentry(activity: Activity, multi?: RedisMulti): Promise<number>;
     static notarizeEarlyExit(activity: Activity, multi?: RedisMulti): Promise<number>;
     static notarizeEarlyCompletion(activity: Activity, multi?: RedisMulti): Promise<number>;
-    /**
-     * verifies both the concrete and synthetic keys for the activity; concrete keys
-     * exist in the original model and are effectively the 'real' keys. In reality,
-     * hook activities are atomized during compilation to create a synthetic DAG that
-     * is used to track the status of the graph in a distributed environment. The
-     * synthetic key represents different dimensional realities and is used to
-     * track re-entry overages (it distinguishes between the original and re-entry).
-     * The essential challenge is: is this a re-entry that is purposeful in
-     * order to induce cycles, or is the re-entry due to a failure in the system?
-     */
     static notarizeReentry(activity: Activity, guid: string, multi?: RedisMulti): Promise<number>;
     static notarizeContinuation(activity: Activity, multi?: RedisMulti): Promise<number>;
     static notarizeCompletion(activity: Activity, multi?: RedisMulti): Promise<number>;
@@ -48,56 +21,13 @@ declare class CollatorService {
     static isDuplicate(num: number, targetDigitIndex: number): boolean;
     static isInactive(num: number): boolean;
     static isPrimed(amount: number, leg: ActivityDuplex): boolean;
-    /**
-     * During compilation, the graphs are compiled into structures necessary
-     * for distributed processing; these are referred to as 'synthetic DAGs',
-     * because they are not part of the original graph, but are used to track
-     * the status of the graph in a distributed environment. This check ensures
-     * that the 'synthetic key' is not a duplicate. (which is different than
-     * saying the 'key' is not a duplicate)
-     */
     static verifySyntheticInteger(amount: number): void;
     static verifyInteger(amount: number, leg: ActivityDuplex, stage: CollationStage): void;
     static getDimensionsById(ancestors: string[], dad: string): Record<string, string>;
-    /**
-     * All non-trigger activities are assigned a status seed by their parent
-     */
     static getSeed(): string;
-    /**
-     * All trigger activities are assigned a status seed in a completed state
-     */
     static getTriggerSeed(): string;
-    /**
-     * entry point for compiler-type activities. This is called by the compiler
-     * to bind the sorted activity IDs to the trigger activity. These are then used
-     * at runtime by the activities to track job/activity status.
-     * @param graphs
-     */
     static compile(graphs: HotMeshGraph[]): void;
-    /**
-     * binds the ancestor array to each activity.
-     * Used in conjunction with the dimensional
-     *  address (dad). If dad is `,0,1,0,0` and the
-     * ancestor array is `['t1', 'a1', 'a2']` for
-     * activity 'a3', then the SAVED DAD
-     * will always have the trailing
-     * 0's removed. This ensures that the addressing
-     * remains consistent even if the graph changes.
-     *   id    DAD           SAVED DAD
-     * * t1 => ,0        =>  [empty]
-     * * a1 => ,0,1      =>  ,0,1
-     * * a2 => ,0,1,0    =>  ,0,1
-     * * a3 => ,0,1,0,0  =>  ,0,1
-     *
-     */
     static bindAncestorArray(graphs: HotMeshGraph[]): void;
-    /**
-     * All activities exist on a dimensional plane. Zero
-     * is the default. A value of
-     * `AxY,0,0,0,0,1,0,0` would reflect that
-     * an ancestor activity was dimensionalized beyond
-     * the default.
-     */
     static getDimensionalSeed(index?: number): string;
 }
 export { CollatorService };

package/build/services/collator/index.js

@@ -4,20 +4,11 @@ exports.CollatorService = void 0;
 const errors_1 = require("../../modules/errors");
 const collator_1 = require("../../types/collator");
 class CollatorService {
-    /**
-     * Upon re/entry, verify that the job status is active
-     */
     static assertJobActive(status, jobId, activityId, threshold = 0) {
         if (status <= threshold) {
             throw new errors_1.InactiveJobError(jobId, status, activityId);
         }
     }
-    /**
-     * returns the dimensional address (dad) for the target; due
-     * to the nature of the notary system, the dad for leg 2 entry
-     * must target the `0` index while leg 2 exit must target the
-     * current index (0)
-     */
     static getDimensionalAddress(activity, isEntry = false) {
         let dad = activity.context.metadata.dad || activity.metadata.dad;
         if (isEntry && dad && activity.leg === 2) {
@@ -25,61 +16,36 @@ class CollatorService {
         }
         return CollatorService.getDimensionsById([...activity.config.ancestors, activity.metadata.aid], dad);
     }
-    /**
-     * resolves the dimensional address for the
-     * ancestor in the graph to go back to. this address
-     * is determined by trimming the last digits from
-     * the `dad` (including the target).
-     * the target activity index is then set to `0`, so that
-     * the origin node can be queried for approval/entry.
-     */
     static resolveReentryDimension(activity) {
         const targetActivityId = activity.config.ancestor;
         const ancestors = activity.config.ancestors;
         const ancestorIndex = ancestors.indexOf(targetActivityId);
-        const dimensions = activity.metadata.dad.split(','); //e.g., `,0,0,1,0`
+        const dimensions = activity.metadata.dad.split(',');
         dimensions.length = ancestorIndex + 1;
         dimensions.push('0');
         return dimensions.join(',');
     }
     static async notarizeEntry(activity, multi) {
-        //decrement by -100_000_000_000_000
         const amount = await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, -100000000000000, this.getDimensionalAddress(activity), multi);
         this.verifyInteger(amount, 1, 'enter');
         return amount;
     }
     static async authorizeReentry(activity, multi) {
-        //set second digit to 8, allowing for re-entry
-        //decrement by -10_000_000_000_000
         const amount = await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, -10000000000000, this.getDimensionalAddress(activity), multi);
         return amount;
     }
     static async notarizeEarlyExit(activity, multi) {
-        //decrement the 2nd and 3rd digits to fully deactivate (`cycle` activities use this command to fully exit after leg 1) (should result in `888000000000000`)
         return await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, -11000000000000, this.getDimensionalAddress(activity), multi);
     }
     static async notarizeEarlyCompletion(activity, multi) {
-        //initialize both `possible` (1m) and `actualized` (1) zero dimension, while decrementing the 2nd
-        //3rd digit is optionally kept open if the activity might be used in a cycle
         const decrement = activity.config.cycle
             ? 10000000000000
             : 11000000000000;
         return await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, 1000001 - decrement, this.getDimensionalAddress(activity), multi);
     }
-    /**
-     * verifies both the concrete and synthetic keys for the activity; concrete keys
-     * exist in the original model and are effectively the 'real' keys. In reality,
-     * hook activities are atomized during compilation to create a synthetic DAG that
-     * is used to track the status of the graph in a distributed environment. The
-     * synthetic key represents different dimensional realities and is used to
-     * track re-entry overages (it distinguishes between the original and re-entry).
-     * The essential challenge is: is this a re-entry that is purposeful in
-     * order to induce cycles, or is the re-entry due to a failure in the system?
-     */
     static async notarizeReentry(activity, guid, multi) {
         const jid = activity.context.metadata.jid;
         const localMulti = multi || activity.store.getMulti();
-        //increment by 1_000_000 (indicates re-entry and is used to drive the 'dimensional address' for adjacent activities (minus 1))
         await activity.store.collate(jid, activity.metadata.aid, 1000000, this.getDimensionalAddress(activity, true), localMulti);
         await activity.store.collateSynthetic(jid, guid, 1000000, localMulti);
         const [_amountConcrete, _amountSynthetic] = await localMulti.exec();
@@ -94,12 +60,9 @@ class CollatorService {
         return amountConcrete;
     }
     static async notarizeContinuation(activity, multi) {
-        //keep open; actualize the leg2 dimension (+1)
         return await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, 1, this.getDimensionalAddress(activity), multi);
     }
     static async notarizeCompletion(activity, multi) {
-        //1) ALWAYS actualize leg2 dimension (+1)
-        //2) IF the activity is used in a cycle, don't close leg 2!
         const decrement = activity.config.cycle ? 0 : 1000000000000;
         return await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, 1 - decrement, this.getDimensionalAddress(activity), multi);
     }
@@ -127,7 +90,6 @@ class CollatorService {
         return this.getDigitAtIndex(num, 2) < 9;
     }
     static isPrimed(amount, leg) {
-        //activity entry is not allowed if paths not properly pre-set
         if (leg == 1) {
             return amount != -100000000000000;
         }
@@ -136,23 +98,13 @@ class CollatorService {
                 this.getDigitAtIndex(amount, 1) < 9);
         }
     }
-    /**
-     * During compilation, the graphs are compiled into structures necessary
-     * for distributed processing; these are referred to as 'synthetic DAGs',
-     * because they are not part of the original graph, but are used to track
-     * the status of the graph in a distributed environment. This check ensures
-     * that the 'synthetic key' is not a duplicate. (which is different than
-     * saying the 'key' is not a duplicate)
-     */
     static verifySyntheticInteger(amount) {
         const samount = amount.toString();
         const isCompletedValue = parseInt(samount[samount.length - 1], 10);
         if (isCompletedValue > 0) {
-            //already done error (ack/delete clearly failed; this is a duplicate)
             throw new errors_1.CollationError(amount, 2, 'enter', collator_1.CollationFaultType.INACTIVE);
         }
         else if (amount >= 2000000) {
-            //duplicate synthetic key (todo: need to resolve/fix this!!)
             throw new errors_1.CollationError(amount, 2, 'enter', collator_1.CollationFaultType.DUPLICATE);
         }
     }
@@ -190,11 +142,6 @@ class CollatorService {
         }
     }
     static getDimensionsById(ancestors, dad) {
-        //ancestors is an ordered list of all ancestors, starting with the trigger (['t1', 'a1', 'a2'])
-        //dad is the dimensional address of the ancestors list (',0,5,3')
-        //loop through the ancestors list and create a map of the ancestor to the dimensional address.
-        //return { 't1': ',0', 'a1': ',0,5', 'a1': ',0,5,3', $ADJACENT: ',0,5,3,0' };
-        // `adjacent` is a special key that is used to track the dimensional address of adjacent activities
         const map = { $ADJACENT: `${dad},0` };
         let dadStr = dad;
         ancestors.reverse().forEach((ancestor) => {
@@ -203,43 +150,15 @@ class CollatorService {
         });
         return map;
     }
-    /**
-     * All non-trigger activities are assigned a status seed by their parent
-     */
     static getSeed() {
         return '999000000000000';
     }
-    /**
-     * All trigger activities are assigned a status seed in a completed state
-     */
     static getTriggerSeed() {
         return '888000001000001';
     }
-    /**
-     * entry point for compiler-type activities. This is called by the compiler
-     * to bind the sorted activity IDs to the trigger activity. These are then used
-     * at runtime by the activities to track job/activity status.
-     * @param graphs
-     */
     static compile(graphs) {
         CollatorService.bindAncestorArray(graphs);
     }
-    /**
-     * binds the ancestor array to each activity.
-     * Used in conjunction with the dimensional
-     *  address (dad). If dad is `,0,1,0,0` and the
-     * ancestor array is `['t1', 'a1', 'a2']` for
-     * activity 'a3', then the SAVED DAD
-     * will always have the trailing
-     * 0's removed. This ensures that the addressing
-     * remains consistent even if the graph changes.
-     *   id    DAD           SAVED DAD
-     * * t1 => ,0        =>  [empty]
-     * * a1 => ,0,1      =>  ,0,1
-     * * a2 => ,0,1,0    =>  ,0,1
-     * * a3 => ,0,1,0,0  =>  ,0,1
-     *
-     */
     static bindAncestorArray(graphs) {
         graphs.forEach((graph) => {
             const ancestors = {};
@@ -255,21 +174,12 @@ class CollatorService {
                     dfs(transition.to, [...parentList, node]);
                 });
             };
-            // Start the DFS traversal
             dfs(startingNode, []);
         });
     }
-    /**
-     * All activities exist on a dimensional plane. Zero
-     * is the default. A value of
-     * `AxY,0,0,0,0,1,0,0` would reflect that
-     * an ancestor activity was dimensionalized beyond
-     * the default.
-     */
     static getDimensionalSeed(index = 0) {
         return `,${index}`;
     }
 }
 exports.CollatorService = CollatorService;
-//max int digit count that supports `hincrby`
 CollatorService.targetLength = 15;