Global

Methods

(async) _start()

Wait until the system is free to do a server side prerrender, and then set it to not-free

Source:

afterRefetch(path, hook)

Attach a handler for an express-like path, that will be executed after any refresh operation on the resources whose url match that path.
From inside the handler it is possible to add more parameters to the call to plugin.

Parameters:
Name Type Description
path string

express-like path to check in which resources execute the hook
hook afterRefetchHandler

Function to be called
Source:
See:
Example
<p>import { afterRefetch, refresh } from 'onget'</p>
<p>afterrefetch('/api/user/current', context =&gt; {<br>
const token = get('localStorage://token')<br>
context.options = {<br>
headers: { 'Authorization': <code>Bearer ${token}</code> }<br>
}<br>
})</p>
<p>refresh('/api/user/current')</p>

afterSet(path, hook)

Attach a handler for an express-like path, that will be executed after any set operation the the resources whose url match that path.
From inside the handler it is possible to prevent the next afterSet handlers to be executed.

Parameters:
Name Type Description
path string

Pattern to check in which resources execute the hook
hook afterSetHandler

Function to be called
Source:
See:

beforeRefetch(path, hook)

Attach a handler for an express-like path, that will be executed before any refresh operation on the resources whose url match that path.
From inside the handler it is possible to add more parameters to the call to plugin.

Parameters:
Name Type Description
path string

express-like path to check in which resources execute the hook
hook beforeRefetchHandler

Function to be called
Source:
See:
Example
<p>import { beforeRefetch, refresh } from 'onget'</p>
<p>beforerefetch('/api/user/current', context =&gt; {<br>
const token = get('localStorage://token')<br>
context.options = {<br>
headers: { 'Authorization': <code>Bearer ${token}</code> }<br>
}<br>
})</p>
<p>refresh('/api/user/current')</p>

beforeSet(path, hook)

Attach a handler for an express-like path, that will be executed before any set operation on the resources whose url match that path.
From inside the handler it is possible to modify the value to be set, prevent the next beforeSet and afterSet handlers to be executed, prevent the subscription callbacks to be executed, or prevent the whole to be set to take place.

Parameters:
Name Type Description
path string

express-like path to check in which resources execute the hook
hook BeforeSetHandler

Function to be called
Source:
See:
Example
<p>import { beforeSet, set } from 'onget'</p>
<p>beforeSet(<code>localStorage://username</code>, context =&gt; {<br>
context.value = context.value.trim().toLowerCase()<br>
})</p>
<p>beforeSet(<code>localStorage://email</code>, context =&gt; {<br>
if (context.value.match(/@/) === null) {<br>
context.preventSet = true<br>
set('dotted://errors.email', true)<br>
}<br>
})</p>

command(url, command, …paramsopt) → {any}

Executes a command defined in a plugin, for an url

Parameters:
Name Type Attributes Description
url string

the resource url
command string

the command name
params any <optional>
<repeatable>

the parameters to the command
Source:
See:
Example
<p>import { command } from 'onget'</p>
<p>command('history://contact-form', 'undo')</p>

end(cb)

Indicates that the prerrendering has finished and allows the next prerrendering to begin.
It is used in server-side prerrendering along with start

Parameters:
Name Type Description
cb
Source:
See:
  • start

get(url) → {any}

Returns the value of a resource
If the resource has not been used yet, so it has no value cached, the plugin that deals with its url could evaluate the value. This is only possible when the evaluation is synchronous and the plugins has the get method defined.

Parameters:
Name Type Description
url string

url of the resource
Source:
Example
<p>import { get } from 'onget'<br>
set('sessionStorage://foo', 42)<br>
get('sessionStorage://foo') // 42<br>
get('localStorage://foo') // undefined</p>

load(data)

Restores the state of the resources and plugins to a previous saved one.
It is intended to be used in universal applications, that prerender the html clientside, to make the client state reflects the prerendered state.

Parameters:
Name Type Description
data object

is an object representing the state in which the application will be, after loading it.
Source:
See:
Example
<p>import { load } from 'onget'</p>
<p>load(<strong>PRELOADED_STATE</strong>)</p>

once(url, handler) → {function}

Attach a handler, that will be executed at most once, to the eventual change the the value of resource.
The handler is attached to a resource, not to a path that could match several resources, and it will be called after the value changes.

If the value has changed because of a set operation, context.preventRefresh could prevent the handler to be executed if it were set to true by any beforeSet or afterSet handler.

Parameters:
Name Type Description
url string

The url of a single resource.
handler onceHandler

function that will be executed the first time the resource's value changes
Source:
See:
Example
<p>import { once, set } from 'onget'</p>
<p>once('dotted://hello', value =&gt; alert(<code>hello ${value}</code>))<br>
set('dotted://hello', 'world') // handler will be executed<br>
set('dotted://hello', 'cow') // handler will not be executed</p>

onGet(url, cb, optionsopt) → {function}

Set a handler to be called each time the value of a resource changes
The handler is attached to a resource, (not to a path that could match several resources), and it will be called after the value changes.
If the value has changed because of a set operation, context.preventRefresh could prevent the handler to be executed if it were set to true by any beforeSet or afterSet handler.

Parameters:
Name Type Attributes Default Description
url string

The resource to subscribe to
cb handler

handler to be called
options object <optional>
 {}

subscription's options

Properties
Name Type Description
first any

first value to initiate the resorce with
interval number

Some plugins, evaluates periodically the value of the resource. Tha actual amount of milliseconds will be the minimum options.interval of every option.intervals of every subscriptions on the resource
Source:
See:
Example
<p>import { onGet } from 'onget'<br>
onGet('/api/posts', value =&gt; {<br>
console.log(value)<br>
}, {<br>
interval: 5000<br>
})</p>

refetch(resource, beforeRefetch)

Do the actual fetch and set the new value to the resource

Parameters:
Name Type Description
resource object

The resource that is going to be refetched
beforeRefetch object

The result of executing the beforeRefetch hooks
Source:

(async) refresh(url, force) → {boolean}

Check if the value of a resource has changed, and execute the subscriptions if so.
It makes the plugin reevaluate the value of the resorce, in those plugins that make periodical evaluations, or that uses some source that could have been changed with a set operation on the resource, like localStorage or sessionStorage

Parameters:
Name Type Description
url string

of the resources to be refreshed
force boolean

Some plugins could include a debounce system te avoid reevaluate the value too much. Set force to true to ignore the threshold and force a check no matter how close it is from the previous one
Source:
Example
<p>import { afterSet, refresh } from 'onget'</p>
<p>afterSet('/api/cart/:item', async context =&gt; {<br>
await fetch(<code>/api/cart/${context.params.item}</code>, {<br>
method: 'POST',<br>
headers: {<br>
'Content-Type': 'application/json'<br>
},<br>
body: {<br>
amount: context.value<br>
}<br>
})<br>
refresh(<code>/api/stock/${context.params.item}</code>)<br>
})</p>

refreshRegExp(regex, force)

Refresh every resource that matches the regular expression.

Parameters:
Name Type Description
regex RegExp

to test against the resources' urls
force boolean

to pass to refresh
Source:
Example
<p>import { refreshRegExp } from 'onget'<br>
document.getElementById('reload').addEventListener('click', () =&gt; {<br>
refreshRegExp(/^/api//)<br>
})</p>

registerPlugin(plugin)

Registers a plugin
When it comes to decide which plugin deals with an URL, the last registered ones are checked first. In other words, the check order is the inverted order of registration.

Parameters:
Name Type Description
plugin Plugin

Plugin object to register
Source:

save() → {object}

Save the state of the resources and the plugins

It returns a serializable object that represents the current state of the resources and the plugins in a way that can be used eventually by load to restore the same state.

Source:

set(url, value, options)

set a new cached value for an resource, and call the handlers. If the resource does not exists, it creates it.

Parameters:
Name Type Description
url string

of the resource whose value set to.
value any

value to series.
options object

to determine the behaviour of the set, and to be passed to the hooks.

Properties
Name Type Description
preventPospone boolean

if true, it prevents to pospone the next check.
preventHooks boolean

if true, prevent the hooks to be executed.
preventRefresh boolean

if true, prevents the resource callbacks to be executed.
preventSet boolean

if true to prevent the whole set operation, except the beforeSetHooks
debounce number

amount of milliseconds to debounce consecutive sets to a resource. (beforeSetHooks are also debounced)
Source:

useOnGet(url, options)

React hook that reload the component when the resource's value change

Parameters:
Name Type Description
url string

the url to subscribe to
options object

options

Properties
Name Type Description
first any

The first value to be used. Useful with asynchronous resources, when there is no value cached yet.
firstIfUrlChanges boolean

When the url changes, the first value returned for the new url will be the last value of the last url, unless options.firstIfUrlChanges be truthy
Source:

waitUntil(url, condition) → {Promise}

Used with await, stops the execution of a function until the resorce value meets some condition that defaults to be truthy

Parameters:
Name Type Description
url *

the url of the resource
condition *

the condition that should be met
Source:

Type Definitions

afterRefetchHandler(conext)

Function to be called after a refresh operation. They are executed synchrony and they can prevent the refresh, prevent the next hook from being executed, and set the second parameter to plugin.refresh.

Parameters:
Name Type Description
conext object

context in which the hook is executed.
context.url string

url of the resource that has received the set
context.path string

path part of the url
context.search string

search part of the url
context.hash string

hash part of the url
context.params object

the params captured on the url by the path. Like in express
context.value any

The current value. It can be changed.
context.options any

The options that will be passed to plugin.refresh
context.preventHooks boolean

set this to true to prevent the next hooks to be executed.
context.preventRefresh boolean

set this to true to prevent the resource callbacks to be executed.
Source:
See:

afterSetHandler(context)

Function to be called after a set operation. They are executed synchrony and they cannot modify the set.

Parameters:
Name Type Description
context object

context in which the hook is executed

Properties
Name Type Description
url string

url of the resource that has received the set
path string

path part of the url
search string

search part of the url
hash string

hash part of the url
params object

the params captured on the url by the path. Like in express
oldValue any

The previous value
value any

The current value
preventHooks boolean

set this to true, to prevent the next hooks to be executed.
preventPospone boolean

Indicates the next periodical check has been posponed
Source:
See:

beforeRefetchHandler(conext)

Function to be called before a refresh operation. They are executed synchrony and they can prevent the refresh, prevent the next hook from being executed, and set the second parameter to plugin.refresh.

Parameters:
Name Type Description
conext object

context in which the hook is executed.
context.url string

url of the resource that has received the set
context.path string

path part of the url
context.search string

search part of the url
context.hash string

hash part of the url
context.params object

the params captured on the url by the path. Like in express
context.value any

The current value. It can be changed. So the real fetch will never take place.
context.options any

The options that will be passed to plugin.refresh
context.preventHooks boolean

set this to true to prevent the next hooks to be executed.
context.preventRefresh boolean

set this to true to prevent the resource callbacks to be executed.
Source:
See:

BeforeSetHandler(event)

Function to be called before a set operation. They are executed synchrony and they can modify, even prevent, the set.

Parameters:
Name Type Description
event object

context in which the hook is executed.

Properties
Name Type Description
url string

url of the resource that has received the set
context.path string

path part of the url
context.search string

search part of the url
context.hash string

hash part of the url
event.params object

the params captured on the url by the path. Like in express
event.value *

The current value. It can be changed.
event.preventHooks boolean

set this to true to prevent the next hooks to be executed.
event.preventRefresh boolean

set this to true to prevent the resource callbacks to be executed.
event.preventSet boolean

set this to true to prevent the whole set operation (except the next hooks, that can be prevented with preventHooks)
event.preventPospone boolean

set this to true to prevent the next periodical check to be posponed
Source:
See:

cleanPluginHandler(resource) → {boolean}

Cleans all the stuff related with the resource that will not be needed after the garbage collector cleans the resource.
It can prevent the garbage collector to clean the resource returning true

Parameters:
Name Type Description
resource Resource

The resource to be cleaned
Source:
See:

commandPlugin(url, …paramsopt) → {any}

Parameters:
Name Type Attributes Description
url string

The url of the resorce in which apply the command
params any <optional>
<repeatable>

Whatever params that are needed by the command
Source:
See:

getPluginHandler(resource) → {any}

Evaluates the value of the resource
The evaluation must be done synchronously

Parameters:
Name Type Description
resource Resource

The resource whose value is going to be evaluated
Source:
See:

getResourcePluginHandler(resource)

It should set things up for the plugin to deal with the resource.
The plugin is allowed to add or modify properties to the resource

Parameters:
Name Type Description
resource Resource

The resource that is being initialized
Source:
See:

handler(value)

Parameters:
Name Type Description
value any

The value of the resource
Source:

loadPluginHandler()

Restores the plugin state from a previous saved one

Source:
See:

loadResourcePluginHandler()

Restores a resource from a previous saved one
If the plugin add keys to the resource at ist initialization, it might use this to do it at its restoration.

Source:
See:

onceHandler(value, url)

Parameters:
Name Type Description
value any
url string

of the resource whose value has change
Source:

Plugin :object

Properties:
Name Type Attributes Description
name string

Name of the Plugin. It must be unique. Mandatory for load and save.
regex RegExp

Regex to match the resource's url
clean cleanPluginHandler <optional>

Cleans up everything that is no more needed. Called by the garbage collector when it wants to clean a resource.
get getPluginHandler <optional>

evaluates the value of the resource. Only synchronous evaluations.
getResource getResourcePluginHandler <optional>

handler to the hook getResource that is called to
load loadPluginHandler <optional>
loadResource loadResourcePluginHandler <optional>
save savePluginHandler <optional>
saveResource saveResourcePluginHandler <optional>

handler
set setPluginHandler <optional>

establishes a new value for the resource.
start startPluginHandler <optional>

Reset everything to get a fresh and clean state.
refresh refreshPluginHandler <optional>

It is called by refresh to reevaluate the value
commands object <optional>

Contains the commands. The keys are the name of the command, and the values the function that is called to execute the command.

Properties
Name Type Attributes Description
someCommandName commandPlugin <optional>
someOtherCommandName commandPlugin <optional>
etc commandPlugin <optional>
Source:
See:

(async) refreshPluginHandler(resource)

It should reevaluate the resource and return his new value.
It must not update the value itself. The value must be returned to be updated by onget, to check if is different and trigger the subscriptions and callbacks.

Parameters:
Name Type Description
resource Resource

The resource that needs to reevaluate
Source:
See:

savePluginHandler() → {any}

Allows to save the state of the plugin, to be eventually loaded and restored.

Source:
See:

saveResourcePluginHandler(url, saveResource)

Allows the plugin to save the state of a resource.
The save system stores the url and the value of the resource. If the plugin needs to store something else there in the object that represents the state of the resource in order to be able to restore it later, it needs to update this object with this handler.

Parameters:
Name Type Description
url string

The url of the resource
saveResource object

The object that represent the state of the resource.
Source:
See:

setPluginHandler(resource)

For instance, the localStorage plugin maps the urls with values stored at localStorage, so when a set operation is made, the plugin updates localstorage to the value of resource.value, using this handler.

Parameters:
Name Type Description
resource Resource
Source:
See:

startPluginHandler()

In universal applications, It is needed to reset the state each time a new html is prerrendered.

Source:
See: