Introduction
Firstly, welcome to the rewyre documentation, in this guide we shall build the basic to-do demo in the /test directory and in each stage I shall explain what, how and why to the whole process. Before we can do that we need to discuss some basic naming conventions and processes on how it works.
Throughout this demo all examples will be done in TypeScript as it is the suggested language to use, but you can use JavaScript as the library is compiled to JavaScript with the TypeScript definitions.
A controller is a class that defines a series of methods, each method can be a route or can just be a function, we suggest using providers for external functionality to make sure the controller class is clean and concise as this will essentially be your actual code for each route, but as well your routing.
You can have many classes and each class can be prefixed, so you can prefix a class with /api and then create a new route method inside with the path: /hello which means you can access it from the browser using http://localhost:3000/api/hello - this depends on your hostname and port settings, but that is the default.
Routing Notes: If you want to have no prefix for a certain controller, for example you're making a website, then you may want to use the
/<route>path, instead of/<prefix>/<route>so you can set either the prefix or the route path to/which will nullify it, so example to create an about us page, available at:/about-usthen you can set the controller's prefix to:/and the route path as/about-usand if you want to use the domain directly, you can also set the route path to/which means it will do://which rewyre rewrites as:/meaning you can get to the domain, useful if you are using rewyre to serve HTML. Last point regarding this is if you have an account section which you want to me:/accountand you want to make sure all code is together, you can set the controller prefix to:/accountand then set the route path to/which turns into:/account/or/account.
A model is a class that relates to a specific collection, the actual @Model decorator just augments the class adding a model definition and some other properties, then when you extend the AbstractModel, you then have access to all the pre-defined wrapper methods for inserting, updating and deleting, the insert functions actually validate the model design against the record being given before upload, this is to to enforce the structure and you can call the validate function manually as well.
A model can get injected to a controller or a service using the @Inject decorator, which you would apply the same name you give to the model, once you do this you then need to add a property to your class with the same name, that defines your model, this helps with type checking and hinting.
Naming Notes: When naming your models be aware that rewyre does not handle models and providers that share the same name, there is a plan to add this, but it does not exist yet, so when naming your models or providers (or any other injectable classes).
A provider is a helper class that can be instantiated for each instance or instantiated once and shared between each instance, this can contain a collection of useful helper functions, in time, the rewyre framework will come with various built-in providers that offer helpers for things like JWT (JSON web tokens), authentication, oAuth2, and there will be the availability to create a PR to add your own into the core framework, or just create your own local providers.
Naming Notes: Again, same issue as models, when naming providers and models, make sure that none share a unique name, otherwise injecting the same two classes with the same name will fail.
A service is a scheduled task that runs every X amount of seconds, you create a class and define the name and schedule, and then once registered it will run at an interval every X amount of seconds, there is no controls for CRON styled scheduling yet, but at the moment it works quite nicely, the idea is to create a service define a public execute function which gets called on the timer, allowing you to write custom code, you can then inject models or providers to help.
Schedule Notes: When creating a service, remember it will run a timer based on the time that the service was actually scheduled, meaning if you have a schedule for every hour, it will run an hour after the time you launched the application.
The state is a new feature of the rewyre framework, and is there to serve a specific purpose, that state uses a dot notation style lookup method for variables, and also allows you to create your own structures and state objects. The state is accessible in every controller, model, provider and service and is there to allow you some form of cross class storage throughout the application. There are two state types, one is temporary storage and the other is permanent storage, temporary uses simple in-memory, and the permanent uses database or file to store data. It's worth noting that the state (because it can get so big), is periodically flushed to the database, therefore this can account for times where data may get lost, you can define the time interval inside of the settings. Accessing the state is as simple as doing this.state.<method>() and the methods are all defined in the docs.
Flushing Notes: When flushing please be aware this could take a few seconds, this depends on the size of your state and the structure, you can also define an option to make changes as soon as they are applied, but again, this would be fairly intensive to the database and the application if you are a high traffic application.
