@galaxis/core v0.2.2

Galaxis Core

Apollo-inspired backend-agnostic fetching library with full SSR support.

This package contains core Galaxis functionality, which is dependency-free, framework-agnostic and as unopinionated as possible.

Installation

yarn add @galaxis/core

Note that you should use a framework-specific wrapper (such as Galaxis React) and not install Fecther Core directly.

The library is compiled to modern JS, but it should work in all reasonable browsers with the help of properly configured Babel.

Your client environment has to have AbortController. You might need to polyfill it.

Features

Queries

Queries are requests that do not change the system state. They are described as Query objects. Note that some options are ignored in the contexts where they are not applicable. For instance, the lazy option only works for managed queries.

You can work with queries manually via client.query(), client.fetchQuery() and client.readQuery(), or you can create a managed query via client.manageQuery(). Note that managed queries should be hidden behind some framework-specific wrapper. The library provides useQuery for React.

A query execution may or may not result in returning the state (data and error) from the cache and/or performing a network request, depending on the fetchPolicy and the cache state.

A query can also be (re)fetched from the network, which always leads to a network request.

Mutations

Mutations are requests that do change the system state. They are described as Mutation objects.

You can work with mutations manually via client.mutate(), or you can create a managed mutation via client.manageMutation(). Note that managed mutations should be hidden behind some framework-specific wrapper. The library provides useMutation for React.

A mutation execution always leads to a network request.

Shared Cache

Queries and mutations work with the same shared Cache. That means that a query can use the data (and/or error!) that was fetched by another query, and query data can be indirectly updated by a mutation. The library provides InMemoryCache as a recommended cache.

For queries, cache usage is specified by fetchPolicy option. Note that if fetchPolicy is not 'no-cache', you also need to specify toCache() and fromCache() options, or the caching will appear broken. Query errors are automatically cached by the network request id depending on fetchPolicy. You can opt-out of caching by using fetchPolicy: 'no-cache'.

For mutations, cache usage is specified by existense of toCache() option. Mutation errors are never cached. You can opt-out of caching by omitting this option (or setting it to undefined).

Optimistic Responses

You can specify optimisticData for mutations. During mutation execution, the cache will immediately be updated with this data, and then with the real data when it arrives. Note that you also have to specify the removeOptimisticData() and toCache() functions, so the library knows how to remove the optimistic data from the cache, and how to put the real data in.

Query Merging

The library encourages executing queries at arbitrary parts of code and points in time. This way, any component of the application can express its data requirements in isolation from other components.

That would lead to duplicate network requests to the same resources. To prevent that, the library uses query merging.

Query merging means that if a query execution (or fetching) results in performing a network request, the library will reuse an ongoing network request with the same id, if there is one. Network request id is calculated by the getRequestId function of BaseRequest.

The cache will also be updated just once, using the first cacheable query that created or reused the network request. A query is cacheable if its fetchPolicy is not no-cache.

This means that queries with the same network request id must update the cache in the same way. It shouldn't be an issue, as the opposite makes no sense.

You can't really opt-out of query merging, but you can use the forceRequestOnMerge option of Query to force a new network request (essentially re-run the existing one) if this query is being merged with another. This means that a promise representing a network request may hide more than one actual network request behind it.

Request Queueing

Since queries (and mutations!) are executed at arbitrary points in time, there must be a way to prevent overwriting newer data by the older one. This is done by request queueing.

Request queueing ensures that all queries, which were started before some mutation, are finished before that mutation is started (in no particular order). It also ensures that the next mutation will be started only after the previous one was finished.

A typical queue may look like this:

[a bunch of queries] -> [mutation] -> [mutation] -> [a bunch of queries]

Note that request queueing means that a promise representing a network request may hide an actual network request that wasn't started yet. Such a request can still be aborted at any time, regardless of its position in the queue.

Race Conditions Handling

Query merging and request queueing, alongside other techniques, make sure that there are no race conditions, as long as data from queries with different network request ids does not overlap. Even if it does, you are still fine, if you only change the system state by mutations, since you don't really care in which order the same data arrives.

Otherwise, beware that you have a razor-thin chance of overwriting an up-to-date data with an outdated one, if you execute such queries simultaneously. In the future, the library may provide means for relative queueing of such queries.

Full Server-Side Rendering Support

The library is built with SSR in mind. Managed queries can be executed on the server side, and, assuming they are wrapped in a framework-specific wrapper, there is no SSR-specific code in the application components, so they are SSR-ready by default. Note that you can disable fetching on the server by the disableSsr option of Query.

The server uses an instance of SsrPromisesManager to wait until all managed queries network requests are finished and the cache is filled with data and errors, then renders the app based on the cache, and sends resulting HTML with embedded cache to the client.

The exact server rendering logic and means of providing a SsrPromisesManager instance to managed queries are framework-specific. The library provides getDataFromTree for React.

Hydrate Stage Optimization

If you're doing SSR, you're going to have a hydrate stage on the client, which is the initial render with cached data. By default, queries with fetchPolicy: 'cache-and-network' will be fetched during the hydrate stage. This is likely undesirable because these requests were just performed on the server.

It can be fixed by setting optimizeOnHydrate: true for all queries by default. In general, you should always do that, unless your cache is not coming from just-performed requests (e.g. you are not doing SSR, but persist the cache to local storage).

Note that you have to indicate that the hydrate stage is complete by calling client.onHydrateComplete().

High Customizability

The library is completely unopinionated about the network level. You can use fetch, axios, XMLHttpRequest, or any other solution. You can add network requests logging, retries, or timeouts. The library doesn't care in which format your data arrives. Just provide a getRequestFactory option of BaseRequest that will abstract it all away. The library provides Fetch as a recommended network interface.

The library is also unopinionated about Cache internals. You can add cache persistence, partial or complete. You even should be able to integrate the cache with your own state management solution, should you need so. The library provides InMemoryCache as a recommended cache.

Note that almost everything is configurable on a per-request level. For instance, you can use different network interfaces for different queries!

Public API

⚠ Anything that is not documented here is not considered a part of public API and may change at any time.

Client

Client is the heart of the library that does all the heavy-lifting.

const client = new Client({
    cache: new MyCache(),
    merge,
    hash,
    defaultRequest,
    defaultQuery,
    defaultMutation,
});

Arguments

ClientOptions

⚠ Note that defaults are static for the given client instance. Dynamic defaults would add too much complexity. If you really need dynamic defaults, such as a user-specific header that is common for all requests, you should do it on the network level, somewhere inside the getRequestFactory option of the BaseRequest. Ideally, if we're talking about authorization, you should rely on a HttpOnly cookie set by the server.

client.manageQuery()

Starts managing of the given query. If the query is not lazy, it is executed immediately.

Note that this method is supposed to be wrapped in some framework-specific wrapper. You should use client.query(), client.fetchQuery() and client.readQuery() to work with queries manually.

const [result, dispose] = client.manageQuery(query, onChange, ssrPromisesManager);

Arguments

Return value

Related types

QueryManagerResult

client.manageMutation()

Starts managing of the given mutation.

Note that this method is supposed to be wrapped in some framework-specific wrapper. You should use client.mutate() to work with mutations manually.

const [result, dispose] = client.manageMutation(mutation, onChange);

Arguments

Return value

Related types

MutationManagerResult

⚠ Note that mutation manager only tracks the latest mutation execution.

client.query()

Execute the query and optionally subscribe to the changes in its state.

const result = client.query(query, onChange);

Arguments

Return value

QueryResult

Extends QueryState.

client.fetchQuery()

Fetch the query. This method will always lead to a network request. Note that this method respects the forceRequestOnMerge option of Query.

const result = client.fetchQuery(query);

Arguments

Return value

Promise<D>

client.readQuery()

Get state of the given query and optionally subscribe to its changes.

const queryState = client.readQuery(query, onChange);

Arguments

Return value

QueryState

client.mutate()

Execute the mutation.

const mutationResult = client.mutate(mutation);

Arguments

Return value

Promise<D>

client.purge()

Reset the client. Specifically, abort all requests, clear the cache, execute all executed managed queries and reset all managed mutations.

You should call this method on logout.

client.purge();

client.getCache()

Get cache that was passed to the constructor.

const cache = client.getCache();

Return value

CACHE

client.onHydrateComplete()

Report to the client that the hydrate stage is complete. The client always starts in the hydrate stage, and it's a one-way operation.

client.onHydrateComplete();

client.hash()

Get hash of the given value using the hash function that was passed to the constructor.

const hash = client.hash(value);

Arguments

Return value

string

SsrPromisesManager

SsrPromisesManager is a small helper for dealing with promises on the server side.

The exact algorithm is up to you, but this seems to be the most robust way:

1. Render the app, adding promises from QueryResult as they appear.
2. Check for added promises. If there are any, wait for them, then go to 1. Otherwise, go to 3.
3. The cache is now filled with data and errors.

const ssrPromisesManager = new SsrPromisesManager();

ssrPromisesManager.addPromise()

Add a promise to the manager.

ssrPromisesManager.addPromise(promise);

Arguments

ssrPromisesManager.awaitPromises()

Returns a promise that resolves when all added promises are resolved or rejected. Note that you can't use the manager while this promise is pending.

await ssrPromisesManager.awaitPromises();

Return value

Promise<void>

ssrPromisesManager.hasPromises()

Checks if there are added promises.

const hasPromises = ssrPromisesManager.hasPromises();

Return value

boolean

Important Types

User-defined types

NonUndefined

Anything but undefined.

BaseRequest

This type describes base network request.

Query

Extends BaseRequest.

Mutation

Extends BaseRequest.

RequestOptions

CacheOptions

CacheAndDataOptions

Extends CacheOptions

FetchPolicy

Cache

UpdateOptions