Api client

An api client in Alette Signal is a router that takes request blueprint configuration and routes it to the core system for execution.

Configuring api client

To configure the api client, use the provided client() function:

api/client.ts

import { client } from "@alette/signal";

export const api = client();

By default, client() uses globalThis.location.origin as origin for all requests routed through it. To set origin manually, use the setOrigin() api client instruction.

api/client.ts

import { client } from "@alette/signal";

export const api = client(
    setOrigin('https://alette-os.com')
);

WARNING

A single application should have 1 api client.

Api client instruction

Api client instructions are events describing what the client() should do. They can be applied with .tell() or passed to client().

export const api = client(/* ... */);

api.tell(
    setOrigin('https://www.wikipedia.org/')
);

import { client } from "@alette/signal";

export const api = client(
    setOrigin('https://alette-os.com')
);

To send multiple instructions at once, pass them to the .tell() method or client():

api.tell(
    setOrigin('https://www.wikipedia.org/'),
    setContext({ hey: 'Alette Signal' })
)

import { client } from "@alette/signal";

export const api = client(
    setOrigin('https://alette-os.com'),
    setContext({ hey: 'Alette Signal' })
);

INFO

The api client configuration is done via instructions only. In comparison to class methods, instructions keep TypeScript types performant by not forcing IDEs to load everything at once.

Api client question

An api client question is an event asking for data from the api client config. Api client questions can be asked using the .ask() method:

api/client.ts

import { setOrigin, client } from '@alette/signal';

export const api = client(
    setOrigin('https://www.wikipedia.org/'),
);

test.ts

import { forOrigin } from '@alette/signal';

// returns 'https://www.wikipedia.org/'
const globalOrigin = await api.ask(forOrigin());

WARNING

Multiple api client questions cannot be put inside one .ask() method. Each api question requires a separate .ask() method call.

INFO

Each api question is prefixed with for for differentiation from api instructions.

Resetting api client

Resetting an api client refers to the process of wiping all api state and reapplying initial instructions passed to client().

To reset the api client, call the .reset() method:

api.reset()

DANGER

1. Only instructions passed to client() will be reapplied. Api instructions passed to the .tell() method will be ignored.
2. During .reset() all in-flight requests are interrupted.

TIP

1. The .reset() method can be used to wipe api state after each test:

vitest.setup.ts

import { api } from './src/api/base.ts'; // import the configured api

afterEach(() => {
    api.reset()
})

2. To learn more about api testing, refer to the Alette Signal testing guide.

Full api client configuration

api/base.ts

import { coreApiPlugin } from "@alette/signal";

export const core = coreApiPlugin();

const {
    query: baseQuery,
    mutation: baseMutation,
    custom: baseCustom,
} = core.use();

TIP

To learn more about plugins, refer to the Alette Signal api plugin documentation.

api/client.ts

import { client, activatePlugins, setOrigin } from "@alette/signal";
import { 
    core,
	baseQuery,
	baseMutation,
	baseCustom
} from "./base.ts";

export const api = client(
    activatePlugins(core.plugin)
);

export const query = baseQuery.toFactory();
export const mutation = baseMutation.toFactory();
export const custom = baseCustom.toFactory();

TIP

1. To learn more about .toFactory(), refer to the Alette Signal blueprint factory documentation.
2. To see more api client configuration examples, see Alette Signal middleware reuse guide.