Skip to main content

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​

requires: Adapter

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​

requires: Adapter

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​

requires: Adapter, Deserializer, Model

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​

requires: Adapter, Deserializer, Model

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​

requires: Adapter, Deserializer, Model

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​

requires: Adapter, Deserializer, Model, Instance

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​

requires: Adapter, Deserializer, Model

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​

requires: Cache, Model, Id

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​

requires: Cache, Model, Id

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​

requires: Cache, Model, Id

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​

only: JSON:API

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.