Instructions on how to use burrow.js with node deprecated/misleading

[multimedial]

Describe the Bug

[UPDATE]: the old @monax/burrow library, although everywhere being marked as being deprecated, seems to work fine though. So it is not the documentation itself which is faulty, but more the confusing situation that one is actively being encouraged to use a new lib instead which is not behaving as the old library.

Burrow.js is being described as a library to interacti with a burrow blockchain server and to be installed with

npm install -g "@monax/burrow"

To be used then:

const monax = require('@monax/burrow');
var burrowURL = "<IP address>:<PORT>"; // localhost:10997 if running locally on default port
var account = 'ABCDEF01234567890123'; // address of the account to use for signing, hex string representation 
var options = {objectReturn: true};
var burrow = monax.createInstance(burrowURL, account, options);

Two issues here:

1. the @monax/burrow lib is clearly marked as being deprecated - one is encouraged to use @hyperledger/burrow instead. Ok, can happen, installed it.

2. when replacing @monax/burrow with @hyperledger/burrow in the code snipped above, the last line of code fails, saying that "createInstance" is no function of @hyperledger/burrow. So one is left with no way to instantiate the library. I also looked for additional documentation on how to use the @hyperledger/burrow library, but to no avail.

To Reproduce
Follow along the steps on
https://hyperledger.github.io/burrow/#/js-api and install @hyperledger/burrow instead the deprecated @monax/burrow

Adapt the code snippet from above accordingly:

const monax = require('@hyperledger/burrow');
var burrowURL = "192.168.178.61:10997";
var account = 'B660F446FFC5BED8110246510CA32B55E3D3D6A1';
var options = {objectReturn: true};
var burrow = monax.createInstance(burrowURL, account, options);

Expected Behavior
I would expect the new @hyperledger/burrow lib to work just as the burrow one. OR I would expect additional documentation or any hint on how to use the new @hyperledger/burrow lib instead.

Technical Details
n/a

Additional Context

Here is what happens in node:

Welcome to Node.js v13.14.0.
Type ".help" for more information.
> const monax = require('@hyperledger/burrow');
undefined
> monax
{
  __esModule: true,
  Burrow: [Function: Burrow],
  Contract: [Function: Contract],
  transformToFullName: [Function: transformToFullName],
  extractDisplayName: [Function: extractDisplayName],
  extractTypeName: [Function: extractTypeName],
  isFunction: [Function: isFunction],
  TxInput: [Function (anonymous)] {
    superClass_: {
      getJsPbMessageId: [Function (anonymous)],
      syncMapFields_: [Function (anonymous)],
      toArray: [Function (anonymous)],
      toString: [Function (anonymous)],
      getExtension: [Function (anonymous)],
      setExtension: [Function (anonymous)],
      cloneMessage: [Function (anonymous)],
      clone: [Function (anonymous)]
    },
    base: [Function (anonymous)],
    toObject: [Function (anonymous)],
    deserializeBinary: [Function (anonymous)],
    deserializeBinaryFromReader: [Function (anonymous)],
    serializeBinaryToWriter: [Function (anonymous)]
  },
  CallTx: [Function (anonymous)] {
    superClass_: {
      getJsPbMessageId: [Function (anonymous)],
      syncMapFields_: [Function (anonymous)],
      toArray: [Function (anonymous)],
      toString: [Function (anonymous)],
      getExtension: [Function (anonymous)],
      setExtension: [Function (anonymous)],
      cloneMessage: [Function (anonymous)],
      clone: [Function (anonymous)]
    },
    base: [Function (anonymous)],
    repeatedFields_: [ 7 ],
    toObject: [Function (anonymous)],
    deserializeBinary: [Function (anonymous)],
    deserializeBinaryFromReader: [Function (anonymous)],
    serializeBinaryToWriter: [Function (anonymous)]
  },
  TxExecution: [Function (anonymous)] {
    superClass_: {
      getJsPbMessageId: [Function (anonymous)],
      syncMapFields_: [Function (anonymous)],
      toArray: [Function (anonymous)],
      toString: [Function (anonymous)],
      getExtension: [Function (anonymous)],
      setExtension: [Function (anonymous)],
      cloneMessage: [Function (anonymous)],
      clone: [Function (anonymous)]
    },
    base: [Function (anonymous)],
    repeatedFields_: [ 7, 11 ],
    toObject: [Function (anonymous)],
    deserializeBinary: [Function (anonymous)],
    deserializeBinaryFromReader: [Function (anonymous)],
    serializeBinaryToWriter: [Function (anonymous)]
  }
}
> var burrowURL = "192.168.178.61:10997";
undefined
> var account = 'B660F446FFC5BED8110246510CA32B55E3D3D6A1';
undefined
> var options = {objectReturn: true};
undefined
> options
{ objectReturn: true }
> var burrow = monax.createInstance(burrowURL, account, options);
Uncaught TypeError: monax.createInstance is not a function

I am a newbie to burrow, it might well be that I am missing something here? I would just need a working code snippet on how to use the new @hyperledger/burrow library instead of the old @monax/burrow one.

And again, i am under a tight deadline for my thesis and this is completely throwing me off. I understand that this is none of anyone's business, but I specifically opted for burrow as it was being described as to be relatively easy to learn and to be in productive use...

[silasdavis]

Yes those docs should have been updated when createInstance was replaced with new Burrow. Much of it should be similar.

The code should be:

import { Burrow } from '@hyperledger/burrow';

const client = new Burrow(burrowURL, account);

or

const burrow = require('@hyperledger/burrow');

const client = new burrow.Burrow(burrowURL, account);

For source code usage see the JS tests, e.g.: https://github.com/hyperledger/burrow/blob/master/js/src/test/get-set.test.ts

Or the Blackstone project, start here: https://github.com/agreements-network/blackstone/blob/master/src/lib/client.ts

If you are able to make an pull requests to fix the docs it is very welcome.

[slavitch]

I have the same issue with other function calls such as

var.contract = client.contracts.new(abi, null, contractAddress);

[slavitch]

We need a mapping of old API calls to new.

[silasdavis]

This is not something I have time or inclination to do. I note we are still a breaking changes project.