@openland/spacex

Scalable and typesafe GraphQL client for JS, React and React Native.

Usage no npm install needed!

<script type="module">
  import openlandSpacex from 'https://cdn.skypack.dev/@openland/spacex';
</script>

README

SpaceX GraphQL

Scalable and typesafe GraphQL client for JS, React and React Native.

Features

  • 🦺Simple codegeneration with full type safety at runtime and in typescript
  • 🚀~50% reduction in RAM usage and up to x20 performance in persistence (comparing to Apollo)
  • 🏎Does not block main thread
  • 🍰Layered design that allows replace transport, socket or graphql core implementations

Install

yarn add @openland/spacex @openland/spacex-web
yarn add -D @openland/spacex-cli get-graphql-schema

Generate Client

Requirements

Generate Client

SpaceX Compiler generates three files:

  • spacex.definitions.json: Descriptors of all fragments and operations for GraphQL Engines
  • spacex.types.ts: Typescript fragments and operations files
  • spacex.ts: Client itself
get-graphql-schema https://api.example.com/graphql --json > schema.json
yarn spacex-cli compile \
    --path "./src/api/definitions/*.graphql" \
    --schema ./schema.json \
    --output ./src/api/ \
    --name ExampleClient

Create Client


// Engine
const engine = /* Create Engine */

// Client
const client = new ExampleClient(engine)

Using client

Queries

For each query in definitions there are generated functions on client:

// Simple Promise-based api
const me = await client.queryUser({ username: 'steve' }) // returns: Promise<User>

// Provide fetchPolicy - bypass cache and fetch from network
const me = await client.queryUser(
  { username: 'steve' },
  { fetchPolicy: 'network-only' }
)

// Refetch method - sugar for fetchPolicy: 'network-only'
const me = await client.refetchUser({ username: 'steve' })

// Hook with suspence
const me = client.useUser({ username: 'steve' }) // returns: User

// Hook with fetchPolicy
const me = client.useUser(
  { username: 'steve' },
  { fetchPolicy: 'network-only' }
) // returns: User

// Hook without suspence
const me = client.useUser({ username: 'steve' }, { suspence: false }) // returns: User | null

Mutations

For each defined mutation there this generated function:

// Simple Promise-based api
const result = await client.mutateSendMessage({
  chat: 'steve',
  message: 'Hello, SpaceX!'
})

Subscriptions

For each defined mutation there this generated function:


// Subscription
const subscription = client.subscribeNewMessages({ chat: 'steve', from: Date.now() }, handler: (e) => {
    if (e.type === 'stopped') {
        // Subscription stopped
        // No more updates in this handler
    } else if (e.type === 'message') {
        // Received message
        const message = e.message;
    }
});

// Destroy subscription
subscription.destroy();

Reading and Writing to Store

If you want to edit store you are able to update queries in the store via update* functions:

await client.updateUser({username: 'stever'}, updated: (src) => {
    return {
        ...src,
        friends: src.friends + 1
    };
});

License

MIT