Actions runners
Note
Many actions runners are available. Each may:
- depend on a minimal package version
- only be available in a given use case (JSON:API, REST, HTTP, etc.)
- provide a given context to next enhancers or runners
- require a given context from previous enhancers or runners
Examples of this guide will omit imports of your action factories or models to provide shorter examples.
Common
none
Run the action and ignore the content of the result. Adapter errors are not caught and so may be thrown.
Example
import { none } from 'foscia/core';
await action().run(none());
Returns
{Promise<void>}
raw
Run the action and retrieve the raw adapter's data.
Example
import { raw } from 'foscia/core';
// When using HttpAdapter, raw result is a fetch Response object.
const response = await action().run(raw());
// You may also transform the data by passing a function.
const data = await action().run(raw((r) => r.json()));
Arguments
{Function | undefined}
transform
the callback to transform the data object
Returns
{Promise<AD>}
where AD
is your adapter's data (e.g. a fetch Response
object) or a transformed data if transform
callback was provided.
all
Run the action and deserialize an array of model's instance.
Example
import { all } from 'foscia/core';
const posts = await action().run(all());
Arguments
{Function | undefined}
transform
the callback to transform the data object
Returns
{Promise<I[]>}
where I
is an instance of the targeted model
or a transformed data if transform
callback was provided.
one
Run the action and deserialize one model's instance. Returns null when not found.
Example
import { one } from 'foscia/core';
const post = await action().run(one());
Arguments
{Function | undefined}
transform
the callback to transform the data object
Returns
{Promise<I | null>}
where I
is an instance of the targeted model
or a transformed data if transform
callback was provided.
oneOrFail
Run the action and deserialize one model's instance.
Throws an ExpectedRunFailureError
when not found or empty result.
Example
import { oneOrFail } from 'foscia/core';
const post = await action().run(oneOrFail());
Arguments
{Function | undefined}
transform
the callback to transform the data object
Returns
{Promise<I>}
where I
is an instance of the targeted model
or a transformed data if transform
callback was provided.
oneOrCurrent
Run the action and deserialize one model's instance. Returns current instance when not found or empty result.
Example
import { oneOrCurrent } from 'foscia/core';
const post = await action().run(oneOrCurrent());
Arguments
{Function | undefined}
transform
the callback to transform the data object
Returns
{Promise<I>}
where I
is an instance of the targeted model
or a transformed data if transform
callback was provided.
oneOr
Run the action and deserialize one model's instance.
Example
import { oneOr } from 'foscia/core';
const post = await action().run(oneOr(() => null));
Arguments
{Function}
nilRunner
the runner to use when one result is empty{Function | undefined}
transform
the callback to transform the data object
Returns
{Promise<I>}
where I
is an instance of the targeted model,
a transformed data if transform
callback was provided
or the nilRunner
result.
cached
Retrieve an instance from the cache. If the instance is not in cache or if the included relations are not loaded, returns null.
Example
import { cached } from 'foscia/core';
const post = await action().run(cached());
Arguments
{Function | undefined}
transform
the callback to transform the data object
Returns
{Promise<I | null>}
where I
is an instance of the targeted model
or a transformed data if transform
callback was provided.
cachedOrFail
Retrieve an instance from the cache.
If the instance is not in cache or if the included relations are not loaded,
throws an ExpectedRunFailureError
.
Example
import { cachedOrFail } from 'foscia/core';
const post = await action().run(cachedOrFail());
Arguments
{Function | undefined}
transform
the callback to transform the data object
Returns
{Promise<I>}
where I
is an instance of the targeted model
or a transformed data if transform
callback was provided.
cachedOr
Retrieve an instance from the cache. If the instance is not in cache or if the included relations are not loaded, runs the given runner.
Example
import { cachedOr } from 'foscia/core';
const post = await action().run(cachedOr(() => null));
Arguments
{Function}
nilRunner
the runner to use when cached result is empty{Function | undefined}
transform
the callback to transform the data object
Returns
{Promise<I>}
where I
is an instance of the targeted model,
a transformed data if transform
callback was provided
or the nilRunner
result.
catchIf
Run given runner and catch errors using catchCallback. If catchCallback is omitted, will return null on error. If catchCallback returns a function, will run it as an action's runner. Else, will ignore error and return null only if callback for error is truthy.
Example
import { catchIf, one } from 'foscia/core';
const postOrNull = await action().run(
catchIf(one(), (error) => error instanceof ErrorToCatch),
);
Arguments
{Function}
runner
the runner to run and catch errors from{Function | undefined}
catchCallback
the callback to use when an error is caught
Returns
{Promise<T>}
where T
is either the runner result, the catch runner result
or null.
JSON:API
usingDocument
Append the JSON:API document object to data object.
Use it as the parameter of all
and one
(and derivatives) runners.
Example
import { all } from 'foscia/core';
import { usingDocument } from 'foscia/jsonapi';
const data = await action().run(all(usingDocument));
data.instances; // Model instances.
data.document; // JSON:API document with meta, etc.