Actions enhancers

Note

Many actions enhancers 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

context

Merge the given context into the action's current context. The context is not deeply merged.

This is the most basic context enhancer. It is used by a lot of Foscia enhancers.

Example

import { context } from 'foscia/core';

action().use(context({ /* additional context */ }));

Arguments

• {{}} contextToMerge a context object to merge into the action's current context

target

provides: Model

Only target the given model.

In most cases, you should use (model, find or any other model's enhancers instead of target.

Example

import { target } from 'foscia/core';

action().use(target(Post));

Arguments

• {M extends Model} model the model class to use

forModel

provides: Model

Target the given model.

Use its type and other applicable model's context.

Example

import { forModel } from 'foscia/core';

action().use(forModel(Post));

Arguments

• {M extends Model} model the model class to use

forInstance

provides: Model, Instance, ID

Target the given model.

Use its type and other applicable model's context.

Example

import { forInstance } from 'foscia/core';

action().use(forInstance(post));

Arguments

• {I extends ModelInstance} instance the instance to use

forRelation

provides: Model, Instance, ID, Relation

Target the given instance's relation.

Use its type and other applicable model/relation context.

Example

import { forRelation } from 'foscia/core';

action().use(forRelation(post, 'comments'));

Arguments

• {I extends ModelInstance} instance the instance to use
• {ModelRelationKey<I>} relationKey the relation to use

forId

provides: ID

Target the given ID.

Example

import { forId } from 'foscia/core';

action().use(forId('123'));

Arguments

• {ModelId | undefined} id the ID to use

find

provides: Model, ID

Target a given model record using its ID.

Example

import { find } from 'foscia/core';

action().use(find(Post, '123'));

Arguments

• {M extends Model} model the model class to use
• {ModelId} id the ID to use

create

requires: Serializerprovides: Model, Instance, ID

Prepare context for an instance creation.

Example

import { create } from 'foscia/core';

const post = new Post();
action().use(create(post));

Arguments

• {I extends ModelInstance}instance an instance of model to create

update

requires: Serializerprovides: Model, Instance, ID

Prepare context for an instance update.

Example

import { update } from 'foscia/core';

action().use(update(post));

Arguments

• {I extends ModelInstance}instance an instance of model to update

save

requires: Serializerprovides: Model, Instance, ID

Prepare context for an instance creation or update depending on its existence state. Calls update if the instance exists, otherwise call create.

Example

import { save } from 'foscia/core';

action().use(save(post));

Arguments

• {I extends ModelInstance}instance an instance of model to save

destroy

provides: Model, Instance, ID

Prepare context for an instance deletion.

Example

import { destroy } from 'foscia/core';

action().use(destroy(post));

Arguments

• {I extends ModelInstance}instance an instance of model to delete

instanceData

requires: Serializer

Serialize the given instance as the context's data.

Example

import { instanceData } from 'foscia/core';

action().use(instanceData(post));

Arguments

• {I extends ModelInstance}instance an instance of model to serialize

include

requires: Model

Eager load the given relations for the current model definition. It accepts deep relations through dot notation. The new relations will be merged with the previous ones.

Example

import { include } from 'foscia/core';

action().use(include('author'));
action().use(include('author', 'comments', 'comments.reactions'));
action().use(include(['author', 'comments', 'comments.reactions']));

Arguments

• {ArrayableVariadic<ModelRelationDotKey<M>>}...relations a relation or a set of relation to eager load

HTTP

makeGet

only: HTTP

HTTP GET method shortcut for the makeRequest function.

Example

import { makeGet } from 'foscia/http';

action().use(makeGet('https://example.com', { /* config */ }));

Arguments

• {string} pathOrBaseURL a path or base URL for the request
• {HttpRequestConfig | undefined} config a request configuration object

makePost

only: HTTP

HTTP POST method shortcut for the makeRequest function.

Example

import { makePost } from 'foscia/http';

action().use(makePost('https://example.com', { data: 'foobar' }, { /* config */ }));

Arguments

• {string} pathOrBaseURL a path or base URL for the request
• {HttpRequestConfig['body'] | undefined} body a request body
• {HttpRequestConfig | undefined} config a request configuration object

makePut

only: HTTP

HTTP PUT method shortcut for the makeRequest function.

Example

import { makePut } from 'foscia/http';

action().use(makePut('https://example.com', { data: 'foobar' }, { /* config */ }));

Arguments

• {string} pathOrBaseURL a path or base URL for the request
• {HttpRequestConfig['body'] | undefined} body a request body
• {HttpRequestConfig | undefined} config a request configuration object

makePatch

only: HTTP

HTTP PATCH method shortcut for the makeRequest function.

Example

import { makePatch } from 'foscia/http';

action().use(makePatch('https://example.com', { data: 'foobar' }, { /* config */ }));

Arguments

• {string} pathOrBaseURL a path or base URL for the request
• {HttpRequestConfig['body'] | undefined} body a request body
• {HttpRequestConfig | undefined} config a request configuration object

makeDelete

only: HTTP

HTTP DELETE method shortcut for the makeRequest function.

Example

import { makeDelete } from 'foscia/http';

action().use(makeDelete('https://example.com', { data: 'foobar' }, { /* config */ }));

Arguments

• {string} pathOrBaseURL a path or base URL for the request
• {HttpRequestConfig['body'] | undefined} body a request body
• {HttpRequestConfig | undefined} config a request configuration object

makeRequest

only: HTTP

Prepare a generic HTTP request. If given path starts with scheme (HTTPS, etc.), it will be used as the base URL of action, otherwise it will only be used as path.

Example

import { makeRequest } from 'foscia/http';

action().use(makeRequest('https://example.com', { /* config */ }));

Arguments

• {string} pathOrBaseURL a path or base URL for the request
• {HttpRequestConfig | undefined} config a request configuration object

param

only: HTTP

Set the given query param on the request. The new params will be merged with the previous ones.

Example

import { param } from 'foscia/http';

action().use(param('foo', 'foo'));   // Key and value.
action().use(param({ bar: 'bar' })); // Object.

Arguments

• {string | Dictionary} key a key for the param or a params object
• {unknown | undefined} value a value for the param

abortSignal

only: HTTP

Configure an abort signal on the request to make it abortable.

Example

import { abortSignal } from 'foscia/http';

const abortController = new AbortController();

action().use(abortSignal(abortController));

Arguments

• {Optional<AbortController | AbortSignal>} controllerOrSignal an abort controller or signal instance to configure (or undefined/null to cancel a previous configuration)

JSON:API

fields

only: JSON:APIrequires: Model

Select the given JSON:API fieldsets for the current context's model. The new fieldsets will be merged with the previous ones.

Example

import { fields } from 'foscia/jsonapi';

action().use(fields('title'));
action().use(fields('title', 'description'));
action().use(fields(['title', 'description']));

Arguments

• {ArrayableVariadic<ModelKey<M>>} ...fieldset a field or a set of field to select for the current context's model

fieldsFor

only: JSON:API

Select the given JSON:API fieldsets for the given model. The new fieldsets will be merged with the previous ones.

Example

import { fieldsFor } from 'foscia/jsonapi';


action().use(fieldsFor(Post, 'title'));
action().use(fieldsFor(Post, 'title', 'description'));
action().use(fieldsFor(Post, ['title', 'description']));

Arguments

• {M extends ModelClass<D>} model the model to select the fieldsets for
• {ArrayableVariadic<ModelKey<M>>} ...fieldset a field or a set of field to select for the given model

filterBy

only: JSON:API

Filter the JSON:API resource by the given key and value. When key is an object, it will spread the object as a filter values map. The new filter will be merged with the previous ones.

Example

import { filterBy } from 'foscia/jsonapi';


action().use(filterBy('isPublished', true));

Arguments

• {string | Dictionary} key a key for the filter or a filter object
• {unknown | undefined} value a value for the filter

sortBy

only: JSON:API

Sort the JSON:API resource by the given keys and directions. The new sort will be merged with the previous ones. Sorts priority are kept.

Example

import { sortBy } from 'foscia/jsonapi';

action().use(sortBy('createdAt'));
action().use(sortBy('createdAt', 'desc'));
action().use(sortBy(['name', 'createdAt'], ['asc', 'asc']));
action().use(sortBy({ name: 'asc', createdAt: 'asc'}));

Arguments

• {Arrayable<string> | Dictionary<SortDirection>} key the key(s) for the sort
• {Arrayable<'asc' | 'desc'> = 'asc'} direction the direction(s) for the sort

sortByAsc

only: JSON:API

Shortcut for the sortBy function with an asc direction.

Example

import { sortByAsc } from 'foscia/jsonapi';

action().use(sortByAsc('createdAt'));

Arguments

• {ArrayableVariadic<string>} ...keys the key(s) for the sort

sortByDesc

only: JSON:API

Shortcut for the sortBy function with a desc direction.

Example

import { sortByDesc } from 'foscia/jsonapi';

action().use(sortByDesc('createdAt'));

Arguments

• {ArrayableVariadic<string>} ...keys the key(s) for the sort

paginate

only: JSON:API

Paginate the JSON:API resource by the given params. JSON:API specification on pagination is agnostic, so page params may be anything used by your implementation.

Example

import { paginate } from 'foscia/jsonapi';


action().use(paginate({ number: 1, size: 10 }));

Arguments

• {unknown} page a pagination value which match your implementation

Hooks

onRunning

Register a running hook callback on action. Callback may be async.

Example

import { onRunning } from 'foscia/jsonapi';


action().use(onRunning((event) => {
  /* Do something */
}));

Arguments

• {(event: { context: {}; runner: Function }) => Awaitable<void>} callback callback to run on event

onSuccess

Register a success hook callback on action. Callback may be async.

Example

import { onSuccess } from 'foscia/jsonapi';


action().use(onSuccess((event) => {
  /* Do something */
}));

Arguments

• {(event: { context: {}; result: unknown }) => Awaitable<void>} callback callback to run on event

onError

Register a error hook callback on action. Callback may be async.

Example

import { onError } from 'foscia/jsonapi';


action().use(onError((event) => {
  /* Do something */
}));

Arguments

• {(event: { context: {}; error: unknown }) => Awaitable<void>} callback callback to run on event

onFinally

Register a finally hook callback on action. Callback may be async.

Example

import { onFinally } from 'foscia/jsonapi';


action().use(onFinally((event) => {
  /* Do something */
}));

Arguments

• {(event: { context: {} }) => Awaitable<void>} callback callback to run on event