usm-api-graphql

Universal Schema Model — the GraphQL API layer for usm-core.

Turns a SearchSchema into a Hasura-style GraphQL interface:

• object types reflected from each collection,
• *_bool_exp / *_order_by / *_aggregate inputs and *_comparison_exp scalar comparison inputs,
• read queries: <table>, <type>_by_pk, <table>_aggregate,
• one live-query subscription per collection (driven by a usm-core SubscriptionManager).

It depends only on usm-core; it emits SDL strings + resolver maps and does not import graphql itself (except the bundled custom scalars). graphql is a peer dependency so your app supplies a single copy.

Install

npm install usm-api-graphql graphql @graphql-tools/schema

graphql is a peer dependency; @graphql-tools/schema is an optional peer used only by the buildExecutableSchema helper.

Usage

import { buildExecutableSchema } from "usm-api-graphql";
import { SubscriptionManager } from "usm-core";

// model.searchSchema comes from usm-adapter-postgres' knexSearchSchema(model)
const subscriptionManager = new SubscriptionManager(model.searchSchema, changeSource, {
    defaultPollInterval: 2000
});

const schema = await buildExecutableSchema(model.searchSchema, { subscriptionManager });
// -> GraphQLSchema with queries + aggregates + subscriptions, ready to serve

For finer control, use the builder directly:

import { SearchSchemaGraphQLBuilder, GraphQLISO8601TimestampType, GraphQLJSONType } from "usm-api-graphql";
import { makeExecutableSchema } from "@graphql-tools/schema";

const { typeDefs, resolvers } = new SearchSchemaGraphQLBuilder(model.searchSchema, {
    subscriptions: true,
    subscriptionManager,
    scalars: { ISO8601Timestamp: GraphQLISO8601TimestampType, JSON: GraphQLJSONType }
}).build();

const schema = makeExecutableSchema({ typeDefs, resolvers });

Query shape

query {
  authors(where: { name: { _ilike: "%a%" } }, order_by: [{ name: asc }], limit: 10) {
    id
    name
    books { id title }
  }
  authors_aggregate(where: { name: { _ilike: "%a%" } }) {
    aggregate { count }
  }
}

subscription {
  authors(where: { name: { _ilike: "%a%" } }, poll_interval: 5000) { id name }
}

Local development note

The inter-package dependency on usm-core is declared as file:../usm-core for in-repo development. When publishing, replace it with a version range (e.g. "usm-core": "^0.1.0"), or use a workspace / npm install --install-links.