nGitDB

Getting Started

This guide shows the smallest useful nGitDB setup: one JSON resource type, one repository root, field ownership, validation, a session, a patch, a commit, and a pull request.

Install

npm install @nuanst-one/ngitdb

For local development from this repository:

npm install
npm run build
npm test

Repository Shape

nGitDB resolves resource paths by convention. A resource path has this shape:

<collection>/<id>

By default, that maps to:

data/<collection>/<id>/<fileName>

Example:

companies/acme-gmbh -> data/companies/acme-gmbh/company.json

Example JSON Document

{
  "legalName": "ACME GmbH",
  "machine": {
    "summary": "Legacy summary",
    "lastEnrichedAt": "2026-04-20"
  }
}

Create a Database Client

import { createGitDB } from "@nuanst-one/ngitdb";

const db = createGitDB({
  repositoryRoot: process.cwd(),
  backend: { type: "github" },
  baseBranch: "main",
  resources: {
    companies: {
      fileName: "company.json",
      ownership: {
        legalName: "human-owned",
        machine: "machine-owned",
      },
      validate: (document) => {
        const issues: string[] = [];

        if (typeof document.legalName !== "string" || document.legalName.length === 0) {
          issues.push("legalName must be a non-empty string");
        }

        if (
          document.machine === null ||
          typeof document.machine !== "object" ||
          Array.isArray(document.machine)
        ) {
          issues.push("machine must be an object");
        }

        return issues;
      },
    },
  },
});

In GitHub Actions, backend: { type: "github" } uses GITHUB_REPOSITORY and GITHUB_TOKEN unless you pass owner, repo, and token explicitly.

For the full CI recipe, including install path, token permissions, reusable workflow notes, and existing-resource limits, see GitHub Actions.

Read a Resource

const company = await db.read("companies/acme-gmbh");

Patch a Machine-Owned Field

Writes require an active session.

await db.startSession("acme-gmbh");

await db.patch("companies/acme-gmbh", {
  "machine.summary": "Industrial supplier with operations in Berlin",
  "machine.lastEnrichedAt": "2026-04-21",
});

Commit and Create a Pull Request

const commit = await db.commit("Enrich company profile for acme-gmbh");

const pullRequest = await db.createPullRequest({
  title: "Enrich acme-gmbh company profile",
});

With the GitHub backend, this creates a commit on the session branch and creates or updates a pull request. With the default local backend, nGitDB writes session commit artifacts under .ngitdb/sessions/<branch-name>/ and returns pull request draft metadata.