The following is a brief sketch of the primary structures of the code in Arc.js.
Git repository is here.
User documentation is here.
Both code and automated tests are written in TypeScript.
Code standards are enforced by TsLint rules defined in tslint.json.
User documentation is generated using TypeDoc and MkDocs. Typedocs is configured and executed using typedoc.js. MkDocs is configured in mkdocs.yml.
While some scripts are available in package.json, all are defined in package-scripts.js. Package-script.js leverages nps and defers to several custom javascript node scripts contained here.
Code is located in the lib folder, tests under test.
Most of the code modules define either an Arc contract wrapper class or a service class.
Arc contract wrapper classes are all located under lib/wrappers.
Service classes are all located in lib (though there is a ticket to move them)
More on wrappers and services follows.
When you first clone the arc.js repo, run the script:
npm install
npm start migrateContracts.fetchContracts
This will install the Truffle artifact files from Arc and the migration.json file from DAOstack Migrations.
Every Arc contract wrapper class has as its root base the ContractWrapperBase class.
Several classes inherit from ContractWrapperBase, including:
Each wrapper can be instantiated and hydrated using the ContractWrapperFactory class. The word “hydrated” means to initialize a wrapper instance with information from the chain using .new, .at or .deployed.
Not all wrapper classes inherit directly from ContractWrapperBase. The two voting machine classes inherit from IntVoteInterfaceWrapper which in turn inherits from ContractWrapperBase.
utils.ts - provides miscellaneous functionality, including initializing web3, creating a truffle contract from a truffle contract artifact (json) file, and others.
utilsInternal.ts -- internal helper functions not exported to the client.
Dao.ts -- not a wrapper, nor defined as a service, more like an entity, it provides helper functions for DAOs, particularly DAO.new and DAO.at.
Arc.js typings are available to application via index.ts.
At runtime, applications must initialize Arc.js by calling InitializeArcJs which is defined in index.ts. This might be viewed as the entry-point to Arc.js.
Arc.js uses the DAOstack Migrations package to migrate contracts to Ganache, and as a source of Arc contract addresses as migrated to the various networks and to Ganache after running the migration script that Arc.js provides. These addresses are stored in "/migration.json".
!!! note As of this writing, the DAOstack Migration package only includes Ganache addresses.
Build the distributable code like this:
npm start build
Build the test code like this:
npm start test.build
Run lint on both library and test code like this:
npm start lint
!!! info
The above script runs npm start lint.code and npm start lint.test
To lint and fix:
npm start lint.andFix
!!! info
You can also fix code and test separately: npm start lint.code.andFix and npm start lint.test.andFix
To run the Arc.js tests, run the following script in the Arc.js root folder, assuming you have already run npm install, and are running a ganache with migrated Arc contracts (see "Getting Started" in the Arc.js Documentation):
npm start test
This script builds all of the code and runs all of the tests.
!!! info Both application and test code are written in TypeScript.
npm start test.bail
Sometimes you want to run just a single test module:
npm start "test.run test-build/test/[filename]"
To bail:
npm start "test.run --bail test-build/test/[filename]"
Unlike test, the script test.run does not build the code first, it assumes the code has already been built, which you can do like this:
npm start test.build
Build the documentation like this:
npm start docs.build
Preview the documentation:
npm start docs.build.andPreview
Publish the documentation:
npm start docs.build.andPublish