@godprotocol/repositories

@godprotocol/repositories

A unified interface for managing local and remote repositories.

This module provides a common abstraction for file operations across storage layers like the filesystem, GitHub, and other distributed repositories, forming the backbone of the God Protocol’s decentralized data infrastructure.

Features

• Unified Repository Interface: Seamless read/write access to multiple repository types.
• Extensible Architecture: Define custom repository types using the base Repository class.
• Multi-Source Sync: Integrates local and remote repositories under one logical layer.
• Dynamic Loader: The Repos manager dynamically instantiates repositories from definitions.
• Optimized I/O Operations: Supports safe read/write, conflict resolution, and async synchronization.
• Built for God Protocol: Core dependency for Oracle and GDS decentralized systems.

Installation

Install the module using npm:

npm install @godprotocol/repositories

Quick Start

Set up and use a repository with the following example:

import Repos from "@godprotocol/repositories/index.js";

const repoDef = {
  type: "github",
  options: {
    key: "ghp_XXXXX",
    username: "user-name",
    repo: "godprotocol-repos",
    branch: "main",
  },
};

const repositories = new Repos();
const repo = await repositories.cloth_repo(repoDef);

// Write file
await repo.write("docs/readme.md", "# Hello World");

// Read file
const content = await repo.read("docs/readme.md");
console.log(content); // "# Hello World"

// Sync repository
await repo.sync();

Core API Reference

Class: Repository

Method	Description
constructor(type)	Initializes a repository instance with its type (e.g., fs, github).
sync()	Synchronizes repository state.
write(path, content)	Writes data to the repository at the given path.
read(path)	Reads content from the repository.
objectify()	Returns an object representation of the repository configuration.
get_id()	Returns the unique identifier of the repository.
match()	Checks if the repository matches a given query or condition.

Class: Repos

Method	Description
cloth_repo(repoDef)	Dynamically instantiates a repository based on its type and options.

Example:

const repos = new Repos();
const repo = await repos.cloth_repo({
  type: "fs",
  options: { root: "./data" },
});

Example Repository Type: GitHub

Implements file operations over the GitHub REST API using fetch.

import Repository from "@godprotocol/repositories/Repository.js";

class Github extends Repository {
  constructor({ key, username, repo, branch }) {
    super("github");
    this.auth_token = key;
    this.owner = username;
    this.repo = repo;
    this.branch = branch || "main";
  }

  async write_file(file_path, content) {
    // Handles create/update file logic with SHA conflict resolution
  }

  async read_file(file_path) {
    // Reads and decodes Base64 content from GitHub
  }

  async delete_file(file_path) {
    // Deletes file via GitHub API
  }

  repo_id = () => `string`;
}

Supported Repository Types

Type	Description	Example Configuration
fs	Local filesystem repository	{ type: "fs", options: { root: "./data" } }
github	Remote GitHub-based repository	{ type: "github", options: { key, username, repo } }

To add a custom repository type, extend the Repository class and implement the required I/O methods (write_file, read_file, etc.).

Integration with God Protocol

This package is natively integrated into the God Protocol ecosystem:

Module	Purpose
@godprotocol/oracle	Uses repositories as data mirrors and sync points.
generalised-datastore	Leverages repositories for distributed CRUD storage.
godprotocol	Core orchestrator for repository coordination and transactions.

Extending the System

Create a custom repository driver by extending the Repository class:

import Repository from "@godprotocol/repositories/Repository.js";

class MyCustomRepo extends Repository {
  constructor(options) {
    super("custom");
    this.options = options;
  }

  async write_file(path, content) {
    // Implement custom write logic
  }

  async read_file(path) {
    // Implement custom read logic
  }
}

Register the custom repository dynamically:

const repos = new Repos();
const myRepo = await repos.cloth_repo({ type: "custom", options: { ... } });

License

MIT © Savvy