@borsawy/types NPM

Borsawy Types

Borsawy Types is a library of common classes that are used almost everywhere in all other Borsawy components. Here we include things such as access to the Database or the Elasticsearch domain. Since almost everyone writing code in any Borsawy component will need to access the Database some way or another, we write the Database logic here where other repositories can depend on it and use it.

Usage

To use this package, simply npm install @borsawy/types in your node project, then import { WhateverYouWant } from '@borsawy/types'; in your javascript/typescript.

Example Use Cases

To create a Market object, see the specification is constructable from objects or is constructable from json in src/market.spec.ts
To save a Market object to DynamoDb, see the specification is persistable to dynamo in src/market.spec.ts
To save a Market object to ElasticSearch, see the specification is persistable to elasticsearch in src/market.spec.ts
To find a Market in DynamoDb, see the specification is queryable from dynamo in src/market.spec.ts
To search for a Market in ElasticSearch, see the specification is searchable from elasticsearch in src/market.spec.ts
To search in ElasticSearch for an Exchange that belongs to a market that has a certain UUID, see the specification is searchable from elasticsearch by the UUID of a market in exchange.spec.ts

Validation

Besides being a place for common classed, Borsawy Types also includes most of our validation logic. For example, we know that the price of a stock can never be less than or equal to Zero. In order to make sure that we never receive a price variable that is less than zero, we create a class called Price. In the constructor of that class, we make sure to validate that the parameter is greater than Zero. See price.ts. Any other place in the code that needs a price input should then use the Price class instead of a simple price variable. This way, the developer can be sure that the value of this price is greater than zero, because the constructor of the Price class would have thrown an exception otherwise long before it was passed to us.

For example, in tick.ts, the Tick class is defined like this... constructor(price: Price) instead of... constructor(price: number) This is because number can be anything, but Price is guaranteed to be valid.

Ontology

Some classes in the Borsawy types library represent entities in the Borsawy ontology. See https://en.wikipedia.org/wiki/Ontology_(information_science)! By understanding the Borsawy ontology, you understand how objects interact with each other and how you can use them. Some of the most important entities in the ontology are Market, Exchange, Ticker, Tick, and TickerPrediction. Each entity is defined in its own source file and includes a docblock that explain the role of the entity in the ontology. Try src/market.ts for example.

Every entity has two main properties: the UUID, and the time. UUID is unique in the entire system. You can not have two objects with the same UUID. If you know the UUID of an object, you can query it directly without needing to know anything else about it. The UUID is a key to the object.

To understand why we have time in every object, you need to understand that it is not safe to edit existing items in the system. The reason why it is not safe is beyond the scope of this introduction. Since updates are not safe, we need a way to add new objects to the system and deprecate the old ones without editing the old ones. This is how we use time. For example, if you have two Exchange objects in the system with name XCAI, one of them is at time 5 and the other is at time 10, use the exchange at time 10. This means that for some reason we needed to update the data in the XCAI exchange so we added a new Exchange with the updated data at time 10 so that everyone would know this is an update. Most of the time, you will need the latest version of the item. To do that while querying ElasticSearch for example, you sort the results by time descending-ly and take the first item.

DynamoDB

Some classes in the Borsawy types library represent objects that we need to persist to DynamoDB. For example, exchange.ts, market.ts, and ticker.ts. These are called entities. We also have a special class called DynamoTable defined in dynamo-table.ts that is responsible for communicating with DynamoDB and storing the entities. Each entity has its own fields. Thus each entity must tell DynamoTable how it wants to be stored in DynamoDB. If an entity wants to define this, it needs to implement the DynamoObject interface. Read the comments in dynamo-object.ts and the spec about dynamo in each entities spec file (e.g. market.spec.ts) for examples on how this works.

ElasticSearch

Just like DynamoDB, some entities need to be stored in ElasticSearch. A special class called ElasticDomain knows how to communicate with ELasticSearch. In order to store an entity, the entity must implement the ElasticDocument interface in order to tell ElasticDomain how to store it. See elastic-document.ts and elastic-domain.spec.ts for more details on how this works.

Deployment

To deploy the types package to npmjs.com, you need an authentication token. The authentication token is written in a GitHub Actions secret called NPM_TOKEN. This token is obtained from npmjs.com using the Borsawy account. Thus, only the production Borsawy repository can publish a new version of the types library. See .github/workflows/tags.yml for more info on how this token is used.