@gql-x/plugin-defradb-transport-http

A transport plugin for @gql-x/plugin-defradb (DefraDB GraphQL extensions) for live query execution against DefraDB: Source Network's open-source, peer-to-peer document database with native GraphQL and CRDT-based sync.

This package extends the DefraDB plugin DSL with an HTTP transport (via fetch(..)) for executing queries and managing transactions.

Relationship to @gql-x/composer

Both this plugin and @gql-x/plugin-defradb plugin are built on top of @gql-x/composer, the generic GraphQL query-string composer. Composer handles variable bookkeeping, dynamic composition, selection-set rendering, and the field/argument/root-level extension seams that this plugin uses to define its transport.

This plugin is another illustration of Composer's extensibility architecture in action. It demonstrates wrapping/decorating another plugin with additional capabilities -- in this case, specifying a transport for execution and transaction management to the underlying DefraDB plugin; see composer's EXTENSIBILITY.md for more info.

Why?

As this plugin works explicitly on top of @gql-x/plugin-defradb plugin, please see its Design explainer for motivation of the query building DSL at the core of this plugin.

Features

In addition to the DefraDB-specific features already defined by @gql-x/plugin-defradb, this plugin further adds:

• exec(..) for live query execution (with optional variables passed in)

• transaction management methods: hasActiveTransaction(), startTransaction(), commitTransaction(), and discardTransaction()

Getting Started

import { createHTTPTransportComposer, } from "@gql-x/plugin-defradb-transport-http";

var DQL = createHTTPTransportComposer({
    namePrefix: "Dev_",
});

await DQL.startTransaction();

try {
    let res = await (
        DQL.collection("User")
            .get(
                DQL.varArgs(DQL.$v("docID","[ID!]")),
                DQL.selectionSet("firstName","lastName")
            )
            .tap(query => console.log(query.text))
            // "query GetUser($docID:ID) { User: Dev_User(docID:$docID) { firstName lastName } }"
            .exec({ docID: "abcd-1234" })
    );

    if (!(res?.length > 0)) {
        throw new Error("DB query failed");
    }

    await DQL.commitTransaction();
}
catch (err) {
    await DQL.discardTransaction();
    console.error(err);
}

createHTTPTransportComposer() returns a plugin instance -- conventionally named DQL in these docs -- which exposes the entire DSL surface: helpers, builders, collection accessors, and transport-defined methods; all helpers are exposed per-instance.

Plugin API Overview

To construct an instance of this plugin for use in your application:

import { createHTTPTransportComposer, } from "@gql-x/plugin-defradb-transport-http";

var DQL = createHTTPTransportComposer({ namePrefix: "Dev_", });

DQL is the plugin instance -- the transport-extended DefraDB plugin instance.

createHTTPTransportComposer(opts)

Initializes an instance of the plugin.

Pass in an optional object with the following configurations to customize the instance:

• namePrefix (string, default: ""): sets the namespace prefix (e.g., "Dev_")

• maxOpTime (integer, default: 8000): sets the maximum time (ms) to wait for an operation to complete before it times out

• txnEndpoint (string, default: "http://localhost:9181/api/v0/tx"): sets the DefraDB HTTP endpoint for managing transactions

• gqlEndpoint (string, default: "http://localhost:9181/api/v0/graphql"): sets the DefraDB GraphQL endpoint

• fetch (function, default: env-native fetch()): sets the fetch()-compliant HTTP client

The return value of createHTTPTransportComposer(..) is a plugin instance.

Plugin Instance

In addition to the methods/helpers inherited from the DefraDB plugin, this plugin instance offers:

• exec(..): takes a query (Composer Query Result object, or GraphQL string) and optionally an object of variables to pass in, executes the query against the configured DefraDB instance (via HTTP); await the returned promise to receive the result of the query; throws exceptions on timeout or other HTTP request/response errors.

• hasActiveTransaction(): returns true / false if the plugin instance is managing an active transaction across its queries

• startTransaction(): starts a new transaction; await the result to ensure it has fully started before performing any further queries

• commitTransaction(): commits any changes made across queries during the transaction; await the result to ensure the transaction is fully committed

• discardTransaction(): discards any changes made across queries during the transaction; await the result to ensure the transaction is fully discarded

Composer Query Result

In addition to the properties and the tap() / map() methods included on the result object, this plugin adds an exec(..) method for executing the query.

Just like the plugin instance's exec(..), except that the query argument is not passed, but rather assumed to be the query result context object:

DQL.collection("User")
    .get( /* composer options */ )
    .exec({ /* .. optional variables .. */ })

Tests

A test suite is included in this repository, as well as the npm package distribution. The default test behavior runs the test suite using the files in src/.

To run the test suite:

npm test

License

All code and documentation are (c) 2026 Kyle Simpson and released under the MIT License. A copy of the MIT License is also included.