apollo-link-serialize
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.0 • Public • Published

    apollo-link-serialize

    npm version Build Status codecov

    An Apollo Link that serializes requests by key, making sure that they execute in the exact order in which they were submitted.

    Motivation

    When sending requests to the server using HTTP there are no guarantees in which order requests will reach the server. Worse yet, when using a RetryLink, it is very likely that requests will get reordered in case of transient network or server errors. For requests where the order matters, you can use apollo-link-serialize to guarantee that they are executed in the exact order in which they were submitted. If we have requests A and B, request B will not be forwarded by the serialization link until request A has completed or errored.

    Note: If combining apollo-link-serialize with apollo-link-retry, make sure the retry link is closer to the network stack than the serializing link. If it isn't, requests may get reordered before they reach the serializing link.

    Let's take a simple example: A page that lets the user input two values, their favorite color and their favorite number (yeah, I know, but it's just an example, so bear with me, okay!). When the user changes these values, they get sent to the server, and the server simply updates a database entry for that user with the new value. In this case, the order in which the updates reach the server is highly significant. If the user first sets the favorite color to "Red" and then to "Blue", the update setting it to "Blue" should arrive after the update setting it to "Red", otherwise the value that sticks will be "Red" instead of "Blue"! Same for the favorite number: The last update that the server sees has to be the last update the user made. apollo-link-serialize can help you make sure that that happens by not sending new requests until previous ones have completed.

    Note that in the example above, the ordering between requests for favorite color and favorite number don't matter, so ordering only needs to be preserved between requests of the same type. Preserving ordering between unrelated requests would be wasteful and increase latency, so apollo-link-serialize lets you specify which requests to serialize behind which other requests by specifying { context: { serializationKey: 'key here' } }. In the example above, we could use serializationKey: 'favoriteColor' and serializationKey: 'favoriteNumber'.

    Requests whose context does not contain serializationKey will be passed through to the next link and not serialized.

    Install

    npm install apollo-link-serialize

    or

    yarn add apollo-link-serialize
    

    Usage

    You can indicate requests that should be serialized by providing a serialization key. All requests with the same serialization key will be queued behind one another in the order they are executed.

    The key can be expressed via the @serialize(key: …) directive. The directive takes a key argument of type List.

    # The key can contain a literal string, number, boolean or enum…
    mutation favoriteIsRed @serialize(key: ["favoriteColor"]) {
        setFavoriteColor(color: "RED)
    }
    # …and it can contain variables…
    mutation upvotePost($id: ID!) @serialize(key: [$id]) {
        post(id: $id) {
            addVote
        }
    }
    # …and even all of the above mixed together (order matters)…
    mutation upvotePost($id: ID!) @serialize(key: [$id, "color", FOO, true, 17, 5.1]) {
        post(id: $id) {
            addVote
        }
    }

    If none of the above works for you, you can also pass an explicit serialization key in the operation's context:

    link.execute({
        query: gql`mutation { setFavoriteColor(color: "RED") }`,
        context: {
            serializationKey: 'favoriteColor',
        },
    });

    Requests without a serialization key are executed in parallel. Similarly, requests with differing keys are executed in parallel with one another.

    Example

    import { ApolloLink } from 'apollo-link';
    import { HttpLink } from 'apollo-link-http';
    import { RetryLink } from 'apollo-link-retry';
    import gql from 'graphql-tag';
    
    import SerializingLink from 'apollo-link-serialize';
    
    this.link = ApolloLink.from([
        new SerializingLink(),
        new HttpLink({ uri: URI_TO_YOUR_GRAPHQL_SERVER }),
    ]);
    
    // Assume the server/network delay for this request is 100ms
    const opColor = {
        query: gql`
            mutation favoriteIsRed @serialize(key: ["favoriteColor"]) {
                setFavoriteColor(color: "RED")
            }
        `,
    };
    
    // Assume the server/network delay for this request is 10ms
    const opColor2 = {
        query: gql`
            mutation favoriteIsBlue @serialize(key: ["favoriteColor"]) {
                setFavoriteColor(color: "BLUE")
            }
        `,
    };
    
    // Assume the server/network delay for this request is 50ms
    const opNumber = {
        query: gql`
            mutation favoriteIsSeven @serialize(key: ["favoriteNumber"]) {
                setFavoriteNumber(number: 7)
            }
        `,
    };
    
    link.execute(opColor).subscribe({
        next(response) { console.log(response.data.setFavoriteColor); },
    });
    link.execute(opColor2).subscribe({
        next(response) { console.log(response.data.setFavoriteColor); },
    });
    link.execute(opNumber).subscribe({
        next(response) { console.log(response.data.setFavoriteNumber); },
    });
    
    // Assuming the server/network delays mentioned above, this code will output:
    // 7 (after 50ms)
    // RED (after 100ms)
    // BLUE (after 110ms)

    Install

    npm i apollo-link-serialize

    DownloadsWeekly Downloads

    2,642

    Version

    4.0.0

    License

    MIT

    Unpacked Size

    78.6 kB

    Total Files

    27

    Last publish

    Collaborators

    • helfer