Tramway Connection is a simple connection library for the tramway framework. It includes:
- An adaptive Connection system
- Repositories and Entities which are separate but when used together with Providers can speed up workflow.
- Introduces async/await support to replace callbacks
npm install tramway-core-connection
https://gitlab.com/tramwayjs/tramway-example
- config
- providers
- entities
- repositories
- factories
Here is where you can put all the parameters for your connection.
Providers are your way to access data sets from a data source, be it a database or API
To create a provider, import the class and implement a derived class with the abstracted stubs to get the most out of it.
import {Provider} from 'tramway-core-connection';
Function | Usage |
---|---|
constructor() |
Handles database configuration |
getOne(id: any, collection: string) |
Returns item from the connection |
getMany(ids: any[], collection: string) |
Passes an array of items for an array of ids. |
find(conditions: string/Object, collection: string) |
Returns an array of items for a query on specific conditions. This may be done by object or query string depending on your implementation |
has(id: any, collection: string) |
Checks if item exists |
hasThese(ids : any[], collection: string) |
Checks if a set of items exists |
count(conditions: any, collection: string) |
Gets a count of items that meet the conditions. |
create(item: Entity, collection: string): Entity |
Creates an object in the database from an Entity or standard object |
update(id: any, item: Entity, collection: string): Entity |
Updates the item found with the given id |
delete(id: any, collection: string) |
Removes an item from the datastore and returns it |
deleteMany(ids : any[], collection: string) |
Removes items from the datastore and returns them |
query(query: string/Object, values: Object, collection: string) |
Meant as an override based on your datastore because we can't always rely on simple CRUD |
createCollection(collection: string) |
A method encompassing the steps to create a collection programatically |
Repositories allow you to interact with a given connection specifically for the purposes of handling a given entity. This usually implies persisting to a database but with the flexibility of Tramway, it can also mean local storage or via an API connection. The default Repository
already links to a connection and utilizes the existing methods that were implemented when the Provider
was implemented or imported. The following demonstrates how a Repository could be used with a Provider and Entity. It is recommended, however, to instantiate providers and repositories using tramway-core-dependency-injector
such to make more efficient use of memory and simplify usage, in this case, no class would be required unless it was overriding default connection logic.
import {Repository} from 'tramway-core-connection';
import TestConnection from '../connections/TestConnection';
import TestEntity from '../entities/TestEntity';
export default class SampleRepository extends Repository {
constructor(item, factory) {
super(new TestConnection(), factory);
}
Note, using dependency injection negates the need for the above code.
Function | Usage |
---|---|
constructor(Provider, Factory, collection) |
Constructor takes a Provider, Factory, and the name of the collection |
All of these methods rely on the Provider's implementation and will just interact with the Provider.
Function | Usage |
---|---|
exists(id: string/int): boolean |
Calls Provider's exist function |
getOne(id: string/int): Entity |
Gets entity with id |
get(): Collection |
Gets collection of all objects from the entity's set |
create(entity: Entity) |
Sends the entity to the provider to be created and returns the persisted result. |
update(entity: Entity) |
Updates the entity via the provider and returns the persisted result. |
delete(id: string/int) |
Deletes the item with the Model's set id. |
find(condtions: string/Object): Collection |
Finds a collection of objects in the entity's set with given conditions |
getMany(ids: any[]): Collection |
Gets objects tied to a list of ids |
count(conditions): number |
Gets a count of objects for given conditons |
setup() |
Handles programatic initialization of the data source |
The factory facilitates the creation of standardized Entity
and Collection
objects and is primarily used by the Repository
. Based on different use cases, it can be extended to support common formats like HATEAOS and decorate entities.
To create a factory, extend the class.
import {Factory} from 'tramway-core-connection';
Function | Usage |
---|---|
create(item: Object): Entity |
Creates entity from object |
createCollection(items: Object[]): Collection |
Returns collection of entities from array of objects. |
An entity is a simple class that contains the getters and setters for its properties. It also comes with validation and serialization.
Function | Usage |
---|---|
constructor(obj: Object) |
Converts a passed object into the proper attributes |
hasAttribute(attribute: string): boolean |
Checks if attribute is in the Entity |
serialize(): string |
Returns stringified JSON |
unserialize(item): Entity |
Sets own attributes based on serialized string |
To create an entity, extend the class.
import {Entity} from 'tramway-core-connection';
A collection stores a group of entities in a Map to facilitate bulk operations and validation.
Function | Type | Usage |
---|---|---|
from(entities: Entity[]) |
static | Creates a collection from an array of entities. let collection = Collection.from(entities) |
add(entity: Entity) |
instance | Adds entity to collection at its id as key |
has(id) |
instance | Checks if entity with given id exists |
get(id) |
instance | Gets entity with given id |
forEach(cb: function(value: Entity, key: number/string, map: Map)) |
instance | Iterates collection of entities |
getSize(): number |
instance | Returns size of collection |
isEmpty(): boolean |
instance | Checks if collection is empty |
getEntities(): Iterator |
instance | Gets entities as an Iterator |
getFirst(): Entity |
instance | Gets first entity of collection |
getLast(): Entity |
instance | Gets last entity of collection |
getIds(): [] |
instance | Gets ordered array of ids of the collection |
To create an collection, extend the class.
import {Collection} from 'tramway-core-connection';