Skip to content
Projects

commitspark/graphql-api has 31 GitHub stars and 4 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 00:50 UTC. Last push 2026-11-13.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

GraphQL API to manage structured data in a Git repository

Developer Tools

README.md

Original

Introduction

Commitspark is a set of tools to manage structured data with Git through a GraphQL API.

This library provides the GraphQL API that allows reading and writing structured data (entries) from and to a Git repository.

Queries and mutations offered by the API are determined by a standard GraphQL type definition file (schema) inside the Git repository.

Entries (data) are stored using plain YAML text files in the same Git repository. No other data store is needed.

Installation

There are two common ways to use this library:

  1. By making GraphQL calls directly to the library as a code dependency in your own JavaScript / TypeScript / Node.js application.

    To do this, simply install the library with

    npm i @commitspark/graphql-api
    
  2. By making GraphQL calls over HTTP to this library wrapped in a webserver or Lambda function.

    You can find an example Node.js Express web server implementation here.

Installing Git provider support

This library is agnostic to where a Git repository is stored and relies on separate adapters for repository access. To access a Git repository, use one of the pre-built adapters listed below or build your own using the interfaces in this repository.

Adapter Description Install with
GitHub Provides support for Git repositories hosted on github.com npm i @commitspark/git-adapter-github
GitLab (SaaS) Provides support for Git repositories hosted on gitlab.com npm i @commitspark/git-adapter-gitlab
Filesystem Provides support for Git repositories in the filesystem npm i @commitspark/git-adapter-filesystem

Installing search support

Searching entries (see Search) is optional and relies on a separate search adapter. To enable search, use the pre-built adapter listed below or build your own using the interfaces in this repository.

Adapter Description Install with
MiniSearch In-memory keyword search with prefix and misspelling support npm i @commitspark/search-adapter-minisearch

Building your GraphQL API

Commitspark builds a GraphQL data management API with create, read, update, and delete (CRUD) functionality that is solely driven by data types you define in a standard GraphQL schema file in your Git repository.

Commitspark achieves this by extending the types in your schema file at runtime with queries, mutations, and additional helper types.

Let's assume you want to manage information about rocket flights and have already defined the following simple GraphQL schema in your Git repository:

# commitspark/schema/schema.graphql

directive @Entry on OBJECT

type RocketFlight @Entry {
    id: ID!
    vehicleName: String!
    payloads: [Payload!]
}

type Payload {
    weight: Int!
}

At runtime, when sending a GraphQL request to Commitspark, these are the queries, mutations, and helper types that are added by Commitspark to your schema for the duration of request execution:

schema {
    query: Query
    mutation: Mutation
}

type Query {
    everyRocketFlight: [RocketFlight]
    RocketFlight(id: ID!): RocketFlight
    _typeName(id: ID!): String
}

type Mutation {
    createRocketFlight(id: ID!, data: RocketFlightInput!, commit: _CommitInput): RocketFlight
    updateRocketFlight(id: ID!, data: RocketFlightInput!, expectedVersion: String, commit: _CommitInput): RocketFlight
    deleteRocketFlight(id: ID!, expectedVersion: String, commit: _CommitInput): ID
}

input _CommitInput {
    message: String
    body: String
}

input RocketFlightIdInput {
    id: ID!
}

input RocketFlightInput {
    vehicleName: String!
    payloads: [PayloadInput!]
}

input PayloadInput {
    weight: Int!
}

extend type RocketFlight {
    _referencedBy: [ID!]
    _version: String!
}

Making GraphQL calls

Let's now assume your repository is located on GitHub and you want to query for a single rocket flight.

The code to do so could look like this:

import { createAdapter } from '@commitspark/git-adapter-github'
import { createClient } from '@commitspark/graphql-api'

const gitHubAdapter = createAdapter({
    repositoryOwner: process.env.GITHUB_REPOSITORY_OWNER,
    repositoryName: process.env.GITHUB_REPOSITORY_NAME,
    accessToken: process.env.GITHUB_ACCESS_TOKEN,
})

const client = await createClient(gitHubAdapter)

const response = await client.postGraphQL(
    process.env.GIT_BRANCH ?? 'main',
    {
        query: `query ($rocketFlightId: ID!) {
          rocketFlight: RocketFlight(id: $rocketFlightId) {
            vehicleName
            payloads {
              weight
            }
          }
        }`,
        variables: {
            rocketFlightId: 'VA256',
        }
    },
)

const rocketFlight = response.data.rocketFlight
// ...

Technical documentation

Schema

The schema (i.e. data model) is defined in a single GraphQL type definition text file using the GraphQL type system.

The schema file must be located at commitspark/schema/schema.graphql inside the Git repository (unless otherwise configured in your Git adapter).

Commitspark currently supports the following GraphQL types:

  • type
  • union
  • enum
  • the built-in scalars String, Int, Float, Boolean and ID

Directives can be declared and used freely, e.g. to annotate types and fields for other tools.

Data entries

To denote which data is to be given a unique identity for referencing, Commitspark expects type annotation with directive @Entry:

directive @Entry on OBJECT # Important: You must declare this for your schema to be valid

type MyType @Entry {
    id: ID! # Important: Any type annotated with `@Entry` must have such a field
    # ...
}

Note: As a general guideline, you should only apply @Entry to data types that meet one of the following conditions:

  • You want to independently create and query instances of this type
  • You want to reference or link to an instance of such a type from multiple other entries

This keeps the number of entries low and performance up.

Schema validation

Commitspark adds generated types and fields to the schema, e.g. input types, queries and mutations for every @Entry type, and it supports only a subset of GraphQL. To ensure predictable API behavior, Commitspark validates the schema on every request and rejects an invalid schema with error BAD_SCHEMA, listing all problems found. The schema can also be validated through the client together with all entries, e.g. in a CI pipeline.

A schema is invalid if it uses unsupported GraphQL constructs or if its names collide with names generated by Commitspark.

Changing the schema

A Commitspark schema can be changed by modifying the schema file stored in the repository.

It is recommended to update affected entries in the same commit as the schema and to check the repository with validate(), e.g. in CI before merging.

Data not matching the schema

Reading a value that does not match the schema fails with error BAD_REPOSITORY_DATA at the position of this value in the response, listing the problem under extensions.commitspark.violations (see Violations). As usual in GraphQL, the value becomes null if its type is nullable, otherwise the error propagates to the closest nullable parent. Values that are not queried do not lead to errors. Excess entry data stored under keys that are not fields in the schema is ignored and does not prevent reading an entry.

A null value in a response can therefore mean that no value is stored or that the stored value cannot be read. API callers should check the errors of a response to tell these apart, e.g. to avoid publishing incomplete content.

Known upstream issue with version 16 of graphql (graphql-js): reading data that does not match the schema can cause an unhandled promise rejection, which terminates Node.js by default. This happens for a list whose elements have a non-null type, e.g. [Item!], if an element fails while resolving a referenced entry and a later element fails as well. The issue is fixed in version 17 of graphql (graphql-js#4643). It is recommended to use graphql 17 or to keep data and schema consistent with validate().

Entry storage

Entries, i.e. instances of data types annotated with @Entry, are stored as .yaml YAML text files inside folder commitspark/entries/ in the given Git repository (unless otherwise configured in your Git adapter).

Entry files have the following structure:

metadata:
  type: MyType # type as defined in the schema that this entry file represents
data:
#   ... fields of the type as defined in the schema

Entry IDs

The path of an entry file relative to the entry folder excluding file extension constitutes the entry ID. Entry IDs can contain / to place entries in subfolders, however the entry type is always taken from the file's metadata.

Entry IDs are subject to the following rules:

  • Entry IDs are case-sensitive
  • Entry IDs must map to valid unique file paths within the entries folder
  • Never allowed:
    • Characters \ * " < > : | ?
    • Control characters
    • File or folder names that start with ., as such files and folders are ignored by Commitspark
  • Additionally rejected when creating an entry:
    • IDs not in composed Unicode form (NFC)
    • Folder names that end with . or a space

Commitspark does not limit the length of entry IDs and does not check whether IDs can be checked out on every operating system, e.g. IDs that only differ in case, which collide on case-insensitive filesystems, or reserved file names such as CON on Windows.

Serialization / Deserialization

References

References to types annotated with @Entry are serialized using a sub-field id.

For example, consider this variation of our rocket flight schema above:

directive @Entry on OBJECT

type RocketFlight @Entry {
    id: ID!
    operator: Operator
}

type Operator @Entry {
    id: ID!
    fullName: String!
}

An entry YAML file for a RocketFlight with ID VA256 referencing an Operator with ID Arianespace will look like this:

# commitspark/entries/VA256.yaml
metadata:
  type: RocketFlight
data:
  operator:
    id: Arianespace

The YAML file of referenced Operator with ID Arianespace will then look like this:

# commitspark/entries/Arianespace.yaml
metadata:
  type: Operator
data:
  fullName: Arianespace SA

When this data is deserialized, Commitspark transparently resolves references to other @Entry instances, allowing for retrieval of complex, linked data in a single query such as this one:

query {
    RocketFlight(id: "VA256") {
        id
        operator {
            fullName
        }
    }
}

This returns the following data:

{
  "id": "VA256",
  "operator": {
    "fullName": "Arianespace SA"
  }
}

Incoming references

Commitspark automatically determines incoming references to entries at runtime from the data of all entries of the requested commit.

These incoming references can be queried with the generated field _referencedBy that is added to all types annotated with @Entry. The query returns the IDs of all entries referencing an entry, sorted by ID.

Unions

In our rocket example, let's assume we want to store information about a rocket's stages. Assuming there are two different types of rocket motors for a rocket stage, a stage could be modeled as a GraphQL union type Stage, allowing different concrete types LiquidRocketMotor or SolidRocketMotor to be added to a rocket's stages list:

directive @Entry on OBJECT

type Rocket @Entry {
    id: ID!
    stages: [Stage!]!
}

union Stage =
    | LiquidRocketMotor
    | SolidRocketMotor

type LiquidRocketMotor {
    fuelTemperature: Int!
}

type SolidRocketMotor {
    fuelMass: Int!
}

During serialization, concrete type instances are represented through an additional nested level of data, using the concrete instance's type name as field name:

# commitspark/entries/VA256.yaml
metadata:
  type: Rocket
data:
  stages:
    - LiquidRocketMotor:
        fuelTemperature: 21
    - SolidRocketMotor:
        fuelMass: 200000

We can now query for a rocket and its stages like this:

query {
    Rocket(id: "VA256") {
        id
        stages {
            __typename
            ... on LiquidRocketMotor {
                fuelTemperature
            }
            ... on SolidRocketMotor {
                fuelMass
            }
        }
    }
}

This returns the following schema-conformant result data where the additional level of nesting has been transparently removed:

{
  "id": "VA256",
  "stages": [
    {
      "__typename": "LiquidRocketMotor",
      "fuelTemperature": 21
    },
    {
      "__typename": "SolidRocketMotor",
      "fuelMass": 200000
    }
  ]
}

Navigating the Git repository

As Commitspark is Git-based, postGraphQL(), getSchema() and validate() take a ref argument that selects the commit to work on. It can be a

  • branch name,
  • tag name (lightweight or annotated), or
  • commit hash, if supported by the Git adapter

Reading and writing data

Queries

The given ref is resolved to a commit when request processing starts. All queries in a request read data from this commit, which is returned as ref of the response.

If no entry exists for the ID given to a query by ID, i.e. <Type>(id) or _typeName(id), the query returns null together with error NOT_FOUND. For <Type>(id), this also applies if the entry with this ID has a different type.

Mutations

Mutations work on branch names only, as they create new commits.

Each successful mutation appends a new commit on HEAD of the given branch.

Before committing, Commitspark checks whether the entry as it would be written matches the schema. If the entry would not match the schema, no commit is made and the mutation fails with error BAD_USER_INPUT, listing the problems under extensions.commitspark.violations. This also applies to existing data of fields not included in an update, e.g. a stored value that no longer matches a changed field type; such a value can be fixed by including the field in the update. Data stored under keys that are not fields in the schema is retained by updates.

Multiple mutations in one request

To guarantee deterministic results, mutations in a request containing multiple mutations are processed sequentially (see the official GraphQL documentation for details). The commit internally resolved as branch HEAD for the duration of the request is updated after each successful mutation.

Mutations from multiple concurrent requests

When a repository is written to concurrently, whether through one or several Commitspark instances or from other sources, the following logic guards against race conditions and data loss:

Every @Entry type has a generated field _version that changes whenever the stored entry changes. Mutations update<Type> and delete<Type> accept an optional argument expectedVersion. If it is given and the entry has a different version, the mutation fails with error code CONFLICT instead of overwriting changes made in the meantime. Callers that let users edit entries are recommended to read _version together with the entry and pass it as expectedVersion when saving, e.g.:

mutation {
    updateMyEntry(id: "my-id", data: { name: "New name" }, expectedVersion: "<_version as read before>") {
        _version
    }
}

Each mutation is validated (expected version, references, etc.) against the latest commit of the branch and passed to the Git adapter together with this commit as expected parent. Git adapters must only add the new commit if the branch still points to that parent. If another commit was added to the branch in the meantime, the mutation is validated again against the new branch head and committed on top of it, up to three times in total, so that changes to unrelated entries do not lead to errors. If the attempts are exhausted, the mutation fails with error code CONFLICT.

How reliably a Git adapter detects a moved branch depends on its Git provider; see the documentation of the respective adapter for limitations.

Commit messages

Mutations accept an optional argument commit to describe the commit they create:

  • message summarizes the change in a single line. A message containing line breaks is rejected with error code BAD_USER_INPUT. If omitted or empty, a message such as Update RocketFlight "VA256" is generated from the mutation, type and ID of the entry.
  • body optionally holds details of the change and may span multiple lines.

Both are trimmed. How message and body are stored depends on the Git adapter, e.g. as commit headline and body.

Search

Entries can be searched by text using query _search once a search adapter is passed to createClient(). How a search is performed (e.g. keyword search, semantic search or a combination of both) depends on the search adapter (see Installing search support).

Marking fields as searchable

Only fields explicitly marked with directive @Searchable are searchable. The directive must be declared in the schema and can be used on types and fields:

directive @Entry on OBJECT
directive @Searchable on OBJECT | FIELD_DEFINITION

type Article @Entry {
    id: ID!
    title: String @Searchable
    url: String
    seo: Seo
    sections: [Section!]
}

type Seo {
    description: String @Searchable
}

type Section @Searchable {
    heading: String
    body: String
}

The following rules apply:

  • On a type, the directive makes all fields of type String (or a list of String) of that type searchable.
  • On a field, the directive makes the field searchable. The field must be of type String or a list of String, otherwise the schema is rejected as invalid.
  • The directive of a type does not extend to fields of other types used in it. Such types must be marked themselves.
  • References to other entries are never followed. Each entry is only searchable by its own data.

Search queries

query {
    hits: _search(query: "launch window", types: ["Article"], first: 10) {
        entryId
        entryType
        fieldPath
        score
        snippet
    }
}

Argument types optionally restricts hits to entries of the given entry types. Argument first limits the number of hits (default 10, maximum 100). Each hit identifies the entry by entryId and entryType and the matching field value by fieldPath (e.g. title, seo.description, tags[1] or sections[2].body). Hits are ordered by descending score, which is only meaningful for ordering hits of the same search.

For values within a union, the field path contains the name of the concrete union member type after the union field, e.g. blocks[2].TextBlock.body. The field path therefore matches the structure of the entry data as stored in the repository and as expected by mutations (see Unions).

Hits are based on the commit returned as ref of the search response. Where the Git adapter supports commit hashes as ref argument, entries of hits can therefore be retrieved from exactly the searched commit.

Error handling

This library catches known error cases and returns error information for GraphQL calls via the errors response field. The type of error is indicated in error field extensions.code, with additional information in error field extensions.commitspark (where available). This allows API callers to determine the cause of errors and take appropriate action.

Errors that prevent processing a call at all are thrown instead, with the same error fields: an invalid schema (BAD_SCHEMA) and errors of the Git adapter while resolving ref or loading the schema. This also applies to getSchema() and validate().

Example GraphQL response with error:

{
  "errors": [
    {
      "message": "No entry with ID \"SOME_UNKNOWN_ID\" exists.",
      "extensions": {
        "code": "NOT_FOUND",
        "commitspark": {
          "argumentName": "id",
          "argumentValue": "SOME_UNKNOWN_ID"
        }
      }
    }
  ]
}

Error codes

The following error codes are returned together with error codes of Git adapters as documented here and error codes of search adapters as documented here:

Error code Description
BAD_GRAPHQL_REQUEST Request cannot be executed, e.g. due to a syntax error or invalid variable values
BAD_USER_INPUT Invalid input data provided by the caller
NOT_FOUND Requested resource (entry, type, etc.) does not exist
BAD_REPOSITORY_DATA Data in the repository is malformed or invalid according to the schema
BAD_SCHEMA Schema definition is malformed or invalid
IN_USE Entry cannot be deleted because it is referenced by other entries
CONFLICT Entry or branch was changed concurrently (see "Mutations from multiple concurrent requests")
INTERNAL_ERROR Internal processing error

Errors for data not matching the schema

If data does not match the schema, the problems are listed under extensions.commitspark.violations, in the same format as returned by validate(). For example, reading an entry after field readingTime was changed from type String to Int, without updating the entry data to match, produces the following error:

{
  "errors": [
    {
      "message": "Entry \"welcome\" does not match the schema: readingTime: Int cannot represent non-integer value: \"5 min\"",
      "extensions": {
        "code": "BAD_REPOSITORY_DATA",
        "commitspark": {
          "typeName": "Article",
          "fieldValue": "welcome",
          "violations": [
            {
              "severity": "ERROR",
              "code": "INVALID_VALUE",
              "message": "Int cannot represent non-integer value: \"5 min\"",
              "path": ["readingTime"],
              "entryId": "welcome",
              "value": "5 min"
            }
          ]
        }
      }
    }
  ]
}

TypeScript API

createClient()

This function is used to create a Commitspark GraphQL API client instance.

Argument gitAdapter expects a Commitspark git adapter instance which is then used by the client to access the adapter's Git repository.

Optional argument options supports the following settings:

  • searchAdapter: A Commitspark search adapter instance. If set, query _search is added to the GraphQL API (see Search).

Client

postGraphQL()

This function is used to make GraphQL requests.

Argument ref expects a branch name, tag name or commit hash (see Navigating the Git repository).

Argument request expects a conventional GraphQL query and supports query variables as well as introspection. Errors are returned in field errors of the response (see Error handling).

getSchema()

This function allows retrieving the GraphQL schema extended by Commitspark as a string.

Compared to schema data obtained through GraphQL introspection, the schema returned by this function also includes directive declarations and annotations, allowing for development of additional tools that require this information.

Argument ref expects a branch name, tag name or commit hash (see Navigating the Git repository).

validate()

This function checks the schema and, if the schema is valid, all entries against the schema. All problems found are returned in a list.

Argument ref expects a branch name, tag name or commit hash (see Navigating the Git repository).

A validation result holds the commit hash that was checked in ref and a list of violations.

Violations

Each violation has a code, a severity, a message, the entryId of the affected entry (not set for problems of the schema) and the path of the affected value within the entry data, e.g. ['sections', 2, 'Hero', 'headline']. ERROR means that the affected data cannot be read or written, WARNING that it is ignored when reading and retained by updates.

Violations that concern a stored value hold it as value, exactly as stored, including null. If nothing is stored, value is not set.

Violation code Severity Description
INVALID_SCHEMA ERROR The schema is malformed or invalid
UNKNOWN_ENTRY_TYPE ERROR The type of an entry is not a type with directive @Entry in the schema
INVALID_VALUE ERROR A value does not match its field, e.g. a missing value of a non-null field
DANGLING_REFERENCE ERROR A reference points to an entry that does not exist
INCOMPATIBLE_REFERENCE ERROR A reference points to an entry of a type that the field does not permit
UNKNOWN_FIELD WARNING Data is stored under a key that is not a field in the schema

CI pipeline validation example

Example of a check that fails on errors and warnings:

const result = await client.validate('main')
for (const violation of result.violations) {
  console.log(violation.severity, violation.entryId ?? '', violation.path.join('.'), violation.message)
}
process.exitCode = result.violations.length > 0 ? 1 : 0

License

The code in this repository is licensed under the permissive ISC license (see LICENSE).