Rest Offline uses your existing RESTful APIs to synchronize client/server data allowing your application to run even when it goes offline.
Synchronize client/server data using your existing RESTful APIs.
clientOnly mode, RESToff automatically provides a complete RESTful offline service for your app.primaryKey field.Examples:
// Create a restoff service instance.
var roff = restoff({
rootUri : "http://api.example.com/" // Required Option
});
roff.get("users").then(function(user) {
console.log(rest.dbRepo.read("users")); // Access repository directly
});
roff.delete("users/301378d5").then(function(deletedUserId) {
console.log("User " + deletedUserId + " deleted");
});
var aUser = {
"id" : "ffa454",
"first_name": "Happy",
"last_name": "User"
}
roff.post("users", aUser).then(function(user){
console.log("Posted user %O.", user);
});
aUser.last_name = "put";
roff.put("users/ffa454", aUser).then(function(user){
console.log("Put user %O.", user);
});
Let's synchronize subsets of resources on the backend service using the user id:
var roff = restoff({
"rootUri" : "http://api.example.com/"
});
function synchronize(roff, userId) {
roff.get("users/" + userId);
roff.get("books?ownedby="+userId);
roff.get("addresses?userid="+userId);
...
roff.forcedOffline = true; // Let's go offline or unplug from the internet
roff.get("users/" + userId).then(function(user) {
// Yep! We can work offline.
});
}
| Row | Action | 1) Server Only Change | 2) Client Only Change | 3) Changes in Both |
|---|---|---|---|---|
| A | Insert (Post) | Get and Overwrite on Client | Post and Overwrite on Server | Same Primary Key. Apply B3. |
| B | Update (Post/Put) | Get and Overwrite on Client | Post and Overwrite on Server | Brent Reconciliation |
| C | Delete | Delete from Client | Delete on Server | Nothing to Do: Both deleted |
| D | Delete with Update on client | Honor Delete: ignore client update |
generateId function.rootUri is appended to RESTful calls when an incomplete uri is provided. rootUri is also used, under the hood, to determine the name of the repository.
Examples:
var roff = restoff({
"rootUri" : "http://api.example.com/",
});
// uri becomes http://api.example.com/users
// repository name is users
roff.get("users").then(function(result){
// use the result here
}
// uri is http://another.example.com/users
// repository name is users
roff.get("http://another.example.com/users").then(function(result){
// use the result here
}
When true, storage of RESTful results on the client are disabled.
Example configuration:
var roff = restoff({
rootUri : "http://api.example.com/",
persistenceDisabled : true
});
Creates a backend RESTful service on your client.
pending repository runs in clientOnly mode meaning the pending RESTful endpoint never hits the backend service.var rest = restoff({
"rootUri" : "http://api.example.com/",
"clientOnly" : true
});
rest.put("users", { Name : "Happy User"}).then(function(result) {
rest.get("users").then(function(result)) {
// never hit a backend RESTful service
});
});
onCallPending is the function called by RESToff before a pending call is executed. Provided is all information about the pending action and the uri record.
// TODO: Provide the json format for pendingAction and the uri record.
var rest = restoff({
rootUri: "http://api.example.com/",
onCallPending: function(pendingAction, uri) {
console.log("Pending will execute %O %O", pendingAction, uri);
}
});
primaryKeyName is the name of the primary key field for a given repository.
You can globally set the primaryKeyName or on a per RESTful call basis:
var roff = restlib.restoff({
rootUri: "api.example.com",
dbService: {
primaryKeyName : "ID",
},
});
roff.get("users").then(function(result) {
console.log("Primary key name used was ID.");
});
roff.get("users", {primaryKeyName:"USER_ID"}).then(function(result) {
console.log("Primary key name used was USER_ID.");
});
Forces the application to run in offline mode.
isOnline will return false when forcedOffline is true.var roff = restoff({
rootUri: "http://api.example.com/"
});
synchronize(roff, "user456");
roff.forceOffline();
if (!roff.isOnline) {
console.log ("We are offline!");
}
NOTE: There is a slight difference between clientOnly mode and forcedoffline mode.
forcedOffline mode, RESToff will store any put/post/delete actions in the pending repository.clientOnly mode, Retsoff will not store any put/post/delete actions in the pending repository.generateId is the function called by RESToff to generate a primary key. Bey default, restOff uses RestOff.prototype._guidGenerate() but you can define your own.
var rest = restoff({
rootUri: "http://api.example.com/",
generateId: function() { return Math.floor((1 + Math.random()) * 0x10000); } // not a great unique key generator
});
onReconciliation is the function called by RESToff after reconciliation of a given resource is complete.
var rest = restoff({
rootUri: "http://api.example.com/",
onReconciliation: function(completedAction) {
console.log("The following completed action was reconciled and saved to the server %O.", completedAction);
}
});
Note: Placed features will provide a more robust reconciliation process allowing the developer to provide their own custom reconciliation process. Currently, RESToff always applies Brent Reconciliation.
The concurrency option defaults to null and conflicts are resolved through Brent reconciliation (keep both versions)
Setting concurrency = 'overwrite' will result in conflicts resolved by being overwritten by the local version
When offline, RESToff places any put/post/delete RESTful operations in a pending repository. RESToff uses it's own persistence engine meaning it calls itself using get/post/delete.
Use pendingUri and pendingRepoName to configure the URI and repository name of the pending repository.
clientOnly mode, no changes are recorded in the pending repository.A parameter of name with value will be added/appended to EVERY RESTful api call. Useful for adding parameters such as an access token.
Example usage:
var roff = restoff({
rootUri : "http://api.example.com/"
});
roff.autoQueryParamSet("access_token", "rj5aabcea");
// uri becomes http://api.example.com/users?access_token=rj5aabcea
roff.get("users").then(function(user)) {
...
}
Returns the value of the query parameter with the provided name.
Example usage:
var roff = restoff({
rootUri : "http://api.example.com/"
});
roff.autoQueryParamSet("access_token", "rj5aabcea");
var paramValue = roff.autoQueryParamGet("access_token");
TODO: Add autoQueryParameters as an option.
A header of name with value will be added to the header of every RESTful api call. Useful for adding parameters such as an access token.
Example usage:
var roff = restoff({
rootUri : "http://api.example.com/"
});
roff.autoHeaderParamSet("access_token", "rj5aabcea");
Returns the value of the header parameter with the provided name.
Example usage:
var roff = restoff({
rootUri : "http://api.example.com/"
});
roff.autoHeaderParamSet("access_token", "rj5aabcea");
var headerValue = roff.autoHeaderParamGet("access_token");
TODO: Add autoHeaderParams as an option.
Clears the cache of the given repository name if the repository exists.
forced - Pass a value of true to force clearing a repository even if it has pending changes.repoName to the repository if it doesn't exist.Example:
var roff = restoff({
rootUri : "http://api.example.com/"
});
roff.clear("users", true);
console.log("User repository, even if it had pending, was cleared ")
Clears the cache of all repositories.
forced - Pass a value of true to force clearing all repositories even if there are any pending changes.Example:
var roff = restoff({
rootUri : "http://api.example.com/"
});
roff.clearAll(true);
console.log("User repository, even if it had pending, was cleared ");
delete(uri, [options]) asynchronously deletes a resource from a remote server and in the local repository.deleteRepo(uri, [options]) synchronously deletes a resource from in the local repository.Note:
delete is called on a non-existent repository, an empty repository is created.Example usage:
var roff = restoff();
return roff.delete("http://test.development.com:4050/users/553fdf")
.then(function(result){
// user was deleted
});
roff.forcedOffline = true;
var result = roff.deleteRepo("http://test.development.com:4050/users/553fdf");
get(uri, [options]) asynchronously retrieves a resource from a remote server. Uses the local repository when offline.getRepo(uri, [options]) synchronously retrieves a resource from the local repository.Example usage:
var roff = restoff();
return roff.get("http://test.development.com:4050/testsweb/testdata/users")
.then(function(result){
// use the result here
});
roff.forcedOffline = true;
var result = roff.getRepo("http://test.development.com:4050/testsweb/testdata/users");
post(uri, resource, [options]) asynchronously posts a resource to a remote server and in the local repository adding the resource if it doesn't exist or overwriting the existing resource.
postRepo(uri, resource, [options]) synchronously posts a resource in the local repository adding the resource if it doesn't exist or overwriting the existing resource.
When online, post(...) calls will happen immediately.
With postRepo(...), updates will happen when a get(...) is executed on that resource.
Example usage:
var roff = restoff();
var newUser = {
"id" : "ffa454",
"first_name": "Happy",
"last_name": "User"
}
return roff.post("http://test.development.com:4050/users", newUser)
.then(function(result){
// use the result here
});
roff.forcedOffline = true;
var result = roff.postRepo("http://test.development.com:4050/users", newUser)
put(uri, resource, [options]) asynchronously puts a known resource on a remote server and in the local repository updating the resource id provided in the uri.putRepo(uri, resource, [options]) synchronously puts a known resource in the local repository updating the resource id provided in the uri.Example usage:
var roff = restoff({
"rootUri" : "http://test.development.com:4050/"
});
var existingUser = {
"id" : "ffa454",
"first_name": "Happy",
"last_name": "User"
}
return roff.post("users/ffa454", existingUser)
.then(function(result){
// use the result here
});
roff.forcedOffline = true;
var result = roff.postRepo("users/ffa454", existingUser)
restOff may add additional query parameters when restOff.get(uri) is called. Use this method to see the final uri sent to the backend server.
Example usage:
var roff = restoff().autoQueryParamSet("access_token", "rj5aabcea");
var actualUri = roff.uriFromClient("http://test.development.com:4050/emailaddresses");
expect(actualUri)).to.equal("http://test.development.com:4050/emailaddresses?access_token=rj5aabcea");
offlineOnly and forcedOffline?
forcedOffline will line up any pending changes that are then synchronized when the client comes back online.offlineOnly does not log any "pending changes" because the repository will never be synchronzied with a backend service.Want to help out? Here is what you need to do to get started.
// TODO: Finish this part of documentation
Change directory to your node project.
$ npm install --save restoff
$ npm install
$ npm install -g json-server // for testing
$ npm outdated
See ./dist for files we build.
$ gulp
$ gulp webtests
Read documentation in gulpfile.js to see how to setup automated web testing.
$ gulp webserver
First time?
$ npm adduser # Need to do one time
Verifty package.json version is newer than one in npm (visit https://www.npmjs.com/package/restoff)
Verify no pending changes
$ git status
$ npm publish ./
$ git tag -a 0.1.4 -m "v0.1.4" // 0.1.4 is an example
$ git push origin --tags
Add to your /etc/hosts file:
127.0.0.1 test.development.com
$ npm install
(NPM install stuff ommitted)
$ mocha tests
3 passing (or something like this)
$ gulp
(gulp stuff happens, look for this line...)
Server started http://test.development.com:4050
... then open the test suite in your browser http://test.development.com:4050
RESToff is wraped in an angular provider.
Example Usage:
angular.module("fakeRoot", ["restoff"])
.config(["restoffProvider", function (restoffProvider) {
restoffProvider.setConfig({
rootUri:"http://localhost/"
});
}]);
Note that we "hard code" the configuration, but you could also get the configuration from another service.
chrome://extensions/ then find the LiveReload extension and check Allow access to file URLs.FAQs
Rest Offline uses your existing RESTful APIs to synchronize client/server data allowing your application to run even when it goes offline.
We found that restoff demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh discusses open source security challenges, including zero-day attacks and supply chain risks, on the Cyber Security Council podcast.
Security News
Research
Socket researchers uncover how threat actors weaponize Out-of-Band Application Security Testing (OAST) techniques across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.
Security News
Research
A malicious npm campaign is targeting Ethereum developers by impersonating Hardhat plugins and the Nomic Foundation, stealing sensitive data like private keys.