- Brings to the application ability to build full offline experience.
- Shows stored results before getting response from the server.
- Stores results of the http requests on the browser side by using flexible localForage for future usage even after application was reloaded.
- Provides TypeScript friendly interface based on decorators
- Independent from any frameworks. Can be used with Angular, React, Vue etc.
- Sending date with POST, PUT or DELETE methods in case if service is unreachable to queue for future invocation event if application is reloaded.
Define resource using decorators.
;/*** Single instance of the resource*//*** Array of the resources*/;
Since this package does not depend onto any certain framework there are no difficulties to use it as, for example, Angular provider
Class decorator. Declares new resource over the decorated class based on the given ResourceMetadata.
Resource.common - default resource configuration
Resource.common.networkStateAdapter = new CustomNetworkStateAdapter;Resource.common.driver = CustomLocalForage._driver;
Property decorator. Declares resource action over the decorated method based on a given ActionMetadata.
This metadata contains configuration information for the resource.
ResourceMetadata#url: StringUrl patters for the http. Action params will be passed to the url according to this pattern. Segments prefixed with
:(colon) will be replaced with action params, other will be passed to the query string params.
bookIdin this example is optional.
See url-pattern for extra information.
ResourceMetadata#params: ObjectBounding params pattern. This params used to map resource instance to url params and also as a key in the local data storage. Params prefixed with
@(at) will be picked from resource instance according to names.// Book resource with following structure:// Using params pattern:// Will be mapped to the action params:
ResourceMetadata#http: AxiosInstanceAxios instance used as http framework. Can be easily replaced with custom instance of the axios. For example to mock http in testing purposes.
ResourceMetadata#httpOnly: BooleanDo not perform any actions over storage. Note: if true
localOnlyfield on action decorators will be ignored. Default is false
ResourceMetadata#name: StringName of the LocalForage database. If name is not specified class name will be used.
ResourceMetadata#driver: String | LocalForageDriver | LocalForageDriverLocalForage driver.
ResourceMetadata#bootstrap: PromiseDefer initialization of resource.Resource.common.bootstrap = new Promise$document.readyresolve;
Whether to perform auto compaction after each array response is handled. Process is similar to garbage collection.
It is not recommended to use auto compaction if it is expected to have large amount of array responses cached, e.g pagination. Use Resource defined
$compactfunction on the instance of the decorated class to perform compaction manually e.g. on application start.await new ArticlesResource.$compact
Network state adapter. Used to determine network availability state of the application. Also notify resource about application is getting online/offline
navigator.onlineproperty and 'online'/'offline' events on the window.
ResourceMetadata#reattemptInterval: numberHow often to attempt to perform actions over http if server is unavailable (receives 5** codes)
60000- every minute
This metadata contains configuration information for the resource action.
ActionMetadata#method: 'get' | 'post' | 'put' | 'delete'Action method.
putmethods also create temporary instances so those instances will be added to the array.
Deletemethod also removes instance from the local array.
ActionMetadata#isArray: BooleanThreat response as array.
ActionMetadata#url: StringOverride resource url.
ActionMetadata#params: ObjectOverrides resource bounding params.
ActionMetadata#localOnly: BooleanDo not perform any actions over http.
ActionMetadata#httpOnly: BooleanDo not perform any actions over the local data storage.
ActionMetadata#configAdditional http action config
Resource instance and indicators to determine whether it was resolved either by http or from cache. Extend your instance model interfaces from this abstraction.
Whether the resource is newly created and not submitted to the server yet. Once resource is submitted this field will be deleted from the object.
Whether the resource is removed or waiting for its removal due to server is unavailable.
Resolution of performing operations over the local data storage. Once resolved this field will be deleted from the object.
Resolution of performing operations over the http. Once resolved this field will be deleted from the object.
Whether the resource is from the local data storage. Once resolved over the http this field will be set to
Represents an array of the resources and indicators to determine whether elements were resolved either by http or from cache. Extend your arrays model interfaces from this abstraction.
Resolution of performing operations over the local data storage.
Resolution of performing operations over the http.
Whether the resource is from the local data storage.
ResourceInstance#toJSON() => Object
Used to determine network availability state.
Indicates whether internet connection is available.
setOnlineHandler(handler: () => void) => void
Set handler to be called once application get online.
setOfflineHandler(handler: () => void) => void
Set handler to be called once application get offline.
Resource object resolution
Note that resource instances combines with results of the http requests by
Object.assign(...) like mechanism.
All the fields from response will be assigned to the resource instance due to server authority principle,
but fields which was already in the resource will not be removed from it.
Resource has "local only" fields. All the fields prefixed with
__(double underscore) will not be sent over http.
Such fields will be saved on the client side until they removed manually.
Thees fields are useful to store some kind of meta information such as references to another resource or timestamps of performed actions.
Clearing the cache
Use Resource defined
$clear function on the instance of the decorated class to perform clearing the resource data.
await new ArticlesResource.$clear
Resource instances and resource arrays use some fields for internal purposes.
Please do not override or delete or set them to avoid unexpected behavior.
$fromCache- Indicates whether array or instance is currently fetched from local data storage.
$new- Indicates whether the resource instance is newly created.
$removed- Indicates whether the resource instance is removed.
$query- Reference to itself in local data storage. Used to keep tracking of new object.
$storagePromise- Resolution of performing operations over the http.
$httpPromise- Resolution of performing operations over the http.
The MIT License (MIT)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.