@esri/hub.js
@esri/hub.js

OperationStack

Class

Allows an application to track a series of operations, storing information about the arguments passes in and the results returned

import { OperationStack } from '@esri/solution-common';

const stack = new OperationStack();

// start an operation by type
const id = stack.start('getItem');
//.. work happens...
stack.finish(id);

// start an operation with an Operation object
stack.start({
  id: 'createItem_1',
  type: 'createItem',
  inputs: {
   item: {...truncated...},
   portal: 'https://www.arcgis.com',
   username: 'jsmith'
  },
});
// make the call
stack.finish('createItem_1', {newItemId: '00cf213'});

// later you can get that information back out of the stack
const prevOp = stack.getOperation('createItem_1);

// and if you need to roll back you can use the
// .cleanup and .output properties to help orchestrate

Can be used to implement "atomic" operations in an environment that does not have this as a core feature

Constructors

Constructor Parameters

Parameter Type Default Notes

Methods

Method Returns Notes
  • finish(id: string, options: Record<stringunknown>)
void

Inform the stack that an operation has finished.

This will append in a duration property, and mark the state as 'completed'.
IOperation[]

Get a list of the completed operations
IOperation

Returns a reference to an Operation
IOperation[]

Returns reference to the operations array
IOperation[]

Return an array of working operations
void

Merge a serialized operation stack into a stack instance

   import { OperationStack } from '@esri/solution-common';
   function someFunction() {
     const stack = new OperationStack();
     stack.start('getItem', {id: 'get-bc3'});
     // do some work...
     stack.finish('get-bc3');

     const itm = {title: 'Fake Item', type: 'Web Map'};
     // create an entry for the function we are about to call...
     stack.start('createItem', {id: 'createItem_01', inputs: {item: itm}});
     // call a function that does work, and has it's own stack
     // and returns a serialized version as part of it's results
     return createItem(itm)
     .then((result) => {
       // tell the stack the last operation finished...
       stack.finish('createItem_01');
       // merge in the stack from the function we called
       stack.merge(result.stack);
       // > stack.getCompleted().length === 3
     });
   }

   function createItem (itm) {
     const otherStack = new OperationStack();
     const id = otherStack.start('createItem');
     // make calls to create item etc
     otherStack.finish(id, {itemId: newItem.id});
     otherStack.start('protectItem', {id: 'protect-00c'});
     // make call to protect item...
     otherStack.finish('protect-00c');
     // all done... return a result with a stack
     return Promise.resolve({
       success:true,
       stack: otherStack.serialize()
     });
   }

Typically used to create a comprehensive list of operations when a function returns a SerializedOperationStack as part of it's response
ISerializedOperationStack

Serialize the stack into simple objects
  • start(type: string, params: Record<stringunknown>)
string

Start an operation without requiring a full operation

const opId = stack.start('getItems');
//...work happens
stack.finish(opId);
void

Start an Operation

const stack = new OperationStack();
stack.startOperation({
 id: 'get-bc3',
 type: 'getItem',
 cleanup: 'n/a',
 inputs: {
   id: 'bc3',
   owner: 'vader'
 }
});
// do work
stack.finish('get-bc3');
string

Serialize the completed operations into a set of human readable messages, sorted by the startedAt timestamp

finish

Class Method

Inform the stack that an operation has finished.

  • finish(id: string, options: Record<stringunknown>) : void

Parameters

Parameter Type Default Notes
id Required string

Unique identifier of the Operation
options Optional Record<stringunknown>

Returns

void

This will append in a duration property, and mark the state as 'completed'.

getCompleted

Class Method

Get a list of the completed operations

Returns

IOperation[]

getOperation

Class Method

Returns a reference to an Operation

Parameters

Parameter Type Default Notes
id Required string

Unique Identifier

Returns

IOperation

getOperations

Class Method

Returns reference to the operations array

Returns

IOperation[]

getWorking

Class Method

Return an array of working operations

Returns

IOperation[]

merge

Class Method

Merge a serialized operation stack into a stack instance

Parameters

Parameter Type Default Notes
stack Required ISerializedOperationStack

Returns

void 
   import { OperationStack } from '@esri/solution-common';
   function someFunction() {
     const stack = new OperationStack();
     stack.start('getItem', {id: 'get-bc3'});
     // do some work...
     stack.finish('get-bc3');

     const itm = {title: 'Fake Item', type: 'Web Map'};
     // create an entry for the function we are about to call...
     stack.start('createItem', {id: 'createItem_01', inputs: {item: itm}});
     // call a function that does work, and has it's own stack
     // and returns a serialized version as part of it's results
     return createItem(itm)
     .then((result) => {
       // tell the stack the last operation finished...
       stack.finish('createItem_01');
       // merge in the stack from the function we called
       stack.merge(result.stack);
       // > stack.getCompleted().length === 3
     });
   }

   function createItem (itm) {
     const otherStack = new OperationStack();
     const id = otherStack.start('createItem');
     // make calls to create item etc
     otherStack.finish(id, {itemId: newItem.id});
     otherStack.start('protectItem', {id: 'protect-00c'});
     // make call to protect item...
     otherStack.finish('protect-00c');
     // all done... return a result with a stack
     return Promise.resolve({
       success:true,
       stack: otherStack.serialize()
     });
   }

Typically used to create a comprehensive list of operations when a function returns a SerializedOperationStack as part of it's response

serialize

Class Method

Serialize the stack into simple objects

Returns

ISerializedOperationStack

start

Class Method

Start an operation without requiring a full operation

  • start(type: string, params: Record<stringunknown>) : string

Parameters

Parameter Type Default Notes
type Required string

Type of the operation. i.e. getItem
params Optional Record<stringunknown>

Returns

Identifier of the new stack entry

string 
const opId = stack.start('getItems');
//...work happens
stack.finish(opId);

startOperation

Class Method

Start an Operation

Parameters

Parameter Type Default Notes
operation Required IOperation

Returns

void 
const stack = new OperationStack();
stack.startOperation({
 id: 'get-bc3',
 type: 'getItem',
 cleanup: 'n/a',
 inputs: {
   id: 'bc3',
   owner: 'vader'
 }
});
// do work
stack.finish('get-bc3');

toString

Class Method

Serialize the completed operations into a set of human readable messages, sorted by the startedAt timestamp

  • toString() : string

Returns

string
Class defined in packages/common/src/OperationStack.ts:47