commitspark/graphql-api
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.
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 ToolsREADME.md
OriginalIntroduction
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:
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-apiBy 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:
typeunionenum- the built-in scalars
String,Int,Float,BooleanandID
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
- Characters
- 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:
messagesummarizes the change in a single line. A message containing line breaks is rejected with error codeBAD_USER_INPUT. If omitted or empty, a message such asUpdate RocketFlight "VA256"is generated from the mutation, type and ID of the entry.bodyoptionally 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 ofString) of that type searchable. - On a field, the directive makes the field searchable. The field must be of type
Stringor a list ofString, 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_searchis 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).