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

getOperation

Class Method

Returns a reference to an Operation

Parameters

Parameter Type Default Notes
id Required string

Unique Identifier

Returns

getOperations

Class Method

Returns reference to the operations array

Returns

getWorking

Class Method

Return an array of working operations

Returns

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

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 common/src/OperationStack.ts:47