simple-state-model-graphql-api

The GraphQL layer over a simple-state-model StateModel. It exposes states as queries, patch mutations, and live subscriptions, and tracks who is subscribed to each state.

Install

npm install simple-state-model-graphql-api graphql @graphql-tools/schema

graphql and @graphql-tools/schema are peer dependencies so the host application controls the versions. If you assemble the schema yourself, use stateGraphQLTypeDefs and stateGraphQLResolvers and skip @graphql-tools/schema entirely.

Usage

import { StateModel } from "simple-state-model";
import { StateSubscriptionModel, stateGraphQLSchema } from "simple-state-model-graphql-api";

const stateModel = new StateModel({ logger: console });

const stateSubscriptionModel = new StateSubscriptionModel({
    stateModel: stateModel,
    logger: console
});

const { schema } = stateGraphQLSchema(stateSubscriptionModel, console);

Serve schema with any transport that supports subscriptions — graphql-http-ws-server, for example. Subscription resolvers return an async iterator, so no pubsub is needed.

Composing the schema yourself

import { makeExecutableSchema } from "@graphql-tools/schema";
import { stateGraphQLTypeDefs, stateGraphQLResolvers } from "simple-state-model-graphql-api";

const schema = makeExecutableSchema({
    typeDefs: [stateGraphQLTypeDefs, myOtherTypeDefs],
    resolvers: [stateGraphQLResolvers(stateSubscriptionModel, console), myOtherResolvers]
});

The API

type Query {
    state(provider_id: ID, state_id: ID!): State
    state_subscribers(provider_id: ID, state_id: ID!, options: StateSubscribersOptionsInput): StateSubscribers
}

type Mutation {
    state_patch(provider_id: ID, state_id: ID!, patch: JSON!, options: StateMutationOptionsInput): StateMutation
    update_subscriber(subscriber_id: ID!, subscriber: StateSubscriberInput!): StateSubscriber
}

type Subscription {
    state_mutation(provider_id: ID, state_id: ID!, options: StateMutationSubscriptionOptionsInput): StateMutationUpdate
    state_subscribers(provider_id: ID, state_id: ID!, options: StateSubscribersOptionsInput): StateSubscribers
}

provider_id selects a provider registered on the StateModel; omitting it uses the model's default. patch is an RFC6902 patch array.

state_mutation sends the current value first, as a root replace patch with reset: true, then streams each subsequent patch. Set exclude_source to your own source ID so your own writes are not echoed back to you.

Subscribers

StateSubscriptionModel keeps a StateSubscriberManager per state. Each state_mutation subscription registers a StateSubscriber, which starts anonymous and can be named later with update_subscriber — that is how a presence list ("who is editing this element") is built.

Subscribers to state_subscribers are registered with count: false, so watching the presence list does not add you to it. A manager destroys itself when its last subscriber leaves.

Related packages

• simple-state-model — the core model
• simple-state-model-graphql-client — the matching client