gh-as-db 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tommy Hansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# gh-as-db
+
+[![NPM Version](https://img.shields.io/npm/v/gh-as-db.svg)](https://www.npmjs.com/package/gh-as-db)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Use a private GitHub repository as a database for your application. `gh-as-db` provides a familiar database-like interface (CRUD, filtering, sorting, pagination) while leveraging GitHub's infrastructure for versioned data storage.
+
+## Features
+
+- 📂 **GitHub-Backed**: Your data lives in JSON files within a GitHub repository.
+- 🔐 **Secure**: Designed for private repositories using Personal Access Tokens (PAT).
+- 🚀 **Performance**: Built-in in-memory caching and auto-indexing for fast local queries.
+- 🛡️ **Concurrency**: Optimistic locking using Git SHAs to prevent data loss.
+- 🧩 **Middleware**: Extensible hooks for data validation or transformation.
+- ⌨️ **CLI Tool**: Initialize and manage your "database" from the terminal.
+- 📦 **TypeScript**: Fully typed for a great developer experience.
+
+## Installation
+
+```bash
+npm install gh-as-db
+```
+
+## Quick Start
+
+```typescript
+import { GitHubDB } from 'gh-as-db';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+const db = new GitHubDB({
+  accessToken: process.env.GITHUB_TOKEN,
+  owner: 'your-username',
+  repo: 'my-data-repo',
+});
+
+// Access the 'users' collection
+const users = db.collection<User>('users');
+
+// Create a new user
+await users.create({
+  id: '1',
+  name: 'John Doe',
+  email: 'john@example.com'
+});
+
+// Find a user by ID
+const user = await users.findById('1');
+console.log(user?.name); // 'John Doe'
+
+// Query with filters
+const results = await users.find({
+  filters: [
+    { field: 'name', operator: 'eq', value: 'John Doe' }
+  ]
+});
+```
+
+## API Reference
+
+### `GitHubDB`
+
+The entry point for linking to your GitHub repository.
+
+```typescript
+const db = new GitHubDB({
+  accessToken: string; // GitHub PAT with 'repo' scope
+  owner: string;       // Repository owner
+  repo: string;        // Repository name
+  branch?: string;     // Optional: branch to use (defaults to 'main')
+});
+```
+
+### `Collection<T>`
+
+Methods for interacting with your data collections (JSON files).
+
+#### `create(item: T): Promise<T>`
+Inserts a new item. If the file doesn't exist, it creates it.
+
+#### `find(options?: QueryOptions<T> | ((item: T) => boolean)): Promise<T[]>`
+Fetches items based on a query object or a predicate function.
+
+#### `findById(id: string): Promise<T | null>`
+Helper to find a single item by its `id` field.
+
+#### `update(id: string, updates: Partial<T>): Promise<T>`
+Updates an existing item. Throws if the item is not found.
+
+#### `delete(id: string): Promise<void>`
+Removes an item by its ID.
+
+### Querying
+
+`gh-as-db` supports advanced querying including filtering, sorting, and pagination.
+
+```typescript
+const items = await users.find({
+  filters: [
+    { field: 'age', operator: 'gte', value: 18 },
+    { field: 'status', operator: 'eq', value: 'active' }
+  ],
+  sort: [
+    { field: 'name', order: 'asc' }
+  ],
+  pagination: {
+    limit: 10,
+    offset: 0
+  }
+});
+```
+
+**Supported Operators**: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `in`.
+
+### Middleware
+
+You can attach middleware to intercept operations.
+
+```typescript
+const users = db.collection<User>('users', {
+  middleware: [{
+    beforeSave: async (item, context) => {
+      console.log(`Saving to ${context.collection}...`);
+      return { ...item, updatedAt: new Date().toISOString() };
+    }
+  }]
+});
+```
+
+## CLI Usage
+
+`gh-as-db` comes with a CLI tool to help you manage your repository.
+
+```bash
+# Initialize a new repository
+npx gh-as-db init
+
+# List all collections
+npx gh-as-db list
+
+# Inspect a specific collection
+npx gh-as-db inspect <collection-name>
+```
+
+## Why gh-as-db?
+
+For small projects, side-projects, or internal tools, setting up a database server (PostgreSQL, MongoDB) is often overkill. `gh-as-db` gives you:
+1. **Zero Cost**: GitHub's free tier for private repos is enough for many use cases.
+2. **Versioned Data**: Every change is a commit. You can see history and revert easily.
+3. **Collaboration**: Use GitHub's own UI to edit data in a pinch.
+
+## Performance
+
+- **Caching**: Data is fetched once and cached in memory. Subsequent reads are near-instant.
+- **Indexing**: Automatic in-memory indexing on all fields makes querying fast even as data grows.
+- **Optimistic Concurrency**: Uses Git SHAs to ensure that you don't overwrite changes made by another client.
+
+## License
+
+MIT

package/dist/core/indexer.d.ts

@@ -0,0 +1,11 @@
+import { Schema } from "./types.js";
+export declare class Indexer<T extends Schema> {
+    private indexes;
+    build(items: T[], fields: (keyof T)[]): void;
+    query(field: keyof T, value: any): T[] | null;
+    add(item: T): void;
+    remove(item: T): void;
+    update(oldItem: T, newItem: T): void;
+    clear(): void;
+    hasIndex(field: keyof T): boolean;
+}

package/dist/core/indexer.js

@@ -0,0 +1,52 @@
+export class Indexer {
+    indexes = new Map();
+    build(items, fields) {
+        this.indexes.clear();
+        for (const field of fields) {
+            const fieldIndex = new Map();
+            for (const item of items) {
+                const val = item[field];
+                if (!fieldIndex.has(val)) {
+                    fieldIndex.set(val, new Set());
+                }
+                fieldIndex.get(val).add(item);
+            }
+            this.indexes.set(field, fieldIndex);
+        }
+    }
+    query(field, value) {
+        const fieldIndex = this.indexes.get(field);
+        if (!fieldIndex)
+            return null;
+        const matches = fieldIndex.get(value);
+        return matches ? Array.from(matches) : [];
+    }
+    add(item) {
+        for (const [field, fieldIndex] of this.indexes) {
+            const val = item[field];
+            if (!fieldIndex.has(val)) {
+                fieldIndex.set(val, new Set());
+            }
+            fieldIndex.get(val).add(item);
+        }
+    }
+    remove(item) {
+        for (const [field, fieldIndex] of this.indexes) {
+            const val = item[field];
+            const matches = fieldIndex.get(val);
+            if (matches) {
+                matches.delete(item);
+            }
+        }
+    }
+    update(oldItem, newItem) {
+        this.remove(oldItem);
+        this.add(newItem);
+    }
+    clear() {
+        this.indexes.clear();
+    }
+    hasIndex(field) {
+        return this.indexes.has(field);
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,49 @@
+export interface GitHubDBConfig {
+    accessToken: string;
+    owner: string;
+    repo: string;
+}
+export type Schema = Record<string, any>;
+export type MiddlewareOperation = "create" | "update" | "read" | "delete";
+export interface MiddlewareContext {
+    collection: string;
+    operation: MiddlewareOperation;
+}
+export interface Middleware<T extends Schema> {
+    beforeSave?: (item: T, context: MiddlewareContext) => Promise<T> | T;
+    afterRead?: (item: T, context: MiddlewareContext) => Promise<T> | T;
+}
+export type FilterOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "contains" | "in";
+export interface FilterPredicate<T> {
+    field: keyof T;
+    operator: FilterOperator;
+    value: any;
+}
+export type SortOrder = "asc" | "desc";
+export interface SortOptions<T> {
+    field: keyof T;
+    order: SortOrder;
+}
+export interface PaginationOptions {
+    limit?: number;
+    offset?: number;
+}
+export interface QueryOptions<T> {
+    filters?: FilterPredicate<T>[];
+    sort?: SortOptions<T>[];
+    pagination?: PaginationOptions;
+}
+export declare class ConcurrencyError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+export interface StorageResponse<T> {
+    data: T;
+    sha: string;
+}
+export interface IStorageProvider {
+    testConnection(): Promise<boolean>;
+    exists(path: string): Promise<boolean>;
+    readJson<T>(path: string): Promise<StorageResponse<T>>;
+    writeJson<T>(path: string, content: T, message: string, sha?: string): Promise<string>;
+}

package/dist/core/types.js

@@ -0,0 +1,8 @@
+export class ConcurrencyError extends Error {
+    path;
+    constructor(path) {
+        super(`Concurrency conflict at ${path}. The remote data has changed.`);
+        this.path = path;
+        this.name = "ConcurrencyError";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export declare const version = "0.1.0";

package/dist/index.js

@@ -0,0 +1 @@
+export const version = "0.1.0";

package/dist/infrastructure/cache-provider.d.ts

@@ -0,0 +1,17 @@
+export interface CacheEntry<T> {
+    data: T;
+    sha: string;
+}
+export interface ICacheProvider {
+    get<T>(key: string): CacheEntry<T> | null;
+    set<T>(key: string, value: CacheEntry<T>, ttl?: number): void;
+    delete(key: string): void;
+    clear(): void;
+}
+export declare class MemoryCacheProvider implements ICacheProvider {
+    private cache;
+    get<T>(key: string): CacheEntry<T> | null;
+    set<T>(key: string, value: CacheEntry<T>, ttl?: number): void;
+    delete(key: string): void;
+    clear(): void;
+}

package/dist/infrastructure/cache-provider.js

@@ -0,0 +1,23 @@
+export class MemoryCacheProvider {
+    cache = new Map();
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        if (entry.expiry !== null && Date.now() > entry.expiry) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.data;
+    }
+    set(key, value, ttl) {
+        const expiry = ttl ? Date.now() + ttl : null;
+        this.cache.set(key, { data: value, expiry });
+    }
+    delete(key) {
+        this.cache.delete(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+}

package/dist/infrastructure/github-storage.d.ts

@@ -0,0 +1,12 @@
+import { GitHubDBConfig, IStorageProvider, StorageResponse } from "../core/types.js";
+import { ICacheProvider } from "./cache-provider.js";
+export declare class GitHubStorageProvider implements IStorageProvider {
+    private config;
+    private octokit;
+    private cache;
+    constructor(config: GitHubDBConfig, cache?: ICacheProvider);
+    testConnection(): Promise<boolean>;
+    exists(path: string): Promise<boolean>;
+    readJson<T>(path: string): Promise<StorageResponse<T>>;
+    writeJson<T>(path: string, content: T, message: string, sha?: string): Promise<string>;
+}

package/dist/infrastructure/github-storage.js

@@ -0,0 +1,106 @@
+import { Octokit } from "@octokit/rest";
+import { ConcurrencyError, } from "../core/types.js";
+import { MemoryCacheProvider } from "./cache-provider.js";
+export class GitHubStorageProvider {
+    config;
+    octokit;
+    cache;
+    constructor(config, cache) {
+        this.config = config;
+        this.octokit = new Octokit({
+            auth: config.accessToken,
+        });
+        this.cache = cache || new MemoryCacheProvider();
+    }
+    async testConnection() {
+        try {
+            await this.octokit.repos.get({
+                owner: this.config.owner,
+                repo: this.config.repo,
+            });
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    async exists(path) {
+        try {
+            await this.octokit.repos.getContent({
+                owner: this.config.owner,
+                repo: this.config.repo,
+                path,
+            });
+            return true;
+        }
+        catch (error) {
+            if (error.status === 404) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    async readJson(path) {
+        const cached = this.cache.get(path);
+        if (cached) {
+            return cached;
+        }
+        const response = await this.octokit.repos.getContent({
+            owner: this.config.owner,
+            repo: this.config.repo,
+            path,
+        });
+        if (Array.isArray(response.data)) {
+            throw new Error("Path is a directory, not a file");
+        }
+        if (!("content" in response.data) || !("sha" in response.data)) {
+            throw new Error("No content or SHA in response");
+        }
+        const content = Buffer.from(response.data.content, "base64").toString("utf-8");
+        const result = {
+            data: JSON.parse(content),
+            sha: response.data.sha,
+        };
+        this.cache.set(path, result);
+        return result;
+    }
+    async writeJson(path, content, message, sha) {
+        let internalSha = sha;
+        if (!internalSha) {
+            try {
+                const existing = await this.octokit.repos.getContent({
+                    owner: this.config.owner,
+                    repo: this.config.repo,
+                    path,
+                });
+                if (!Array.isArray(existing.data) && "sha" in existing.data) {
+                    internalSha = existing.data.sha;
+                }
+            }
+            catch (error) {
+                if (error.status !== 404) {
+                    throw error;
+                }
+            }
+        }
+        try {
+            const response = await this.octokit.repos.createOrUpdateFileContents({
+                owner: this.config.owner,
+                repo: this.config.repo,
+                path,
+                message,
+                content: Buffer.from(JSON.stringify(content, null, 2)).toString("base64"),
+                sha: internalSha,
+            });
+            const newSha = response.data.content?.sha || "";
+            this.cache.delete(path);
+            return newSha;
+        }
+        catch (error) {
+            if (error.status === 409) {
+                throw new ConcurrencyError(path);
+            }
+            throw error;
+        }
+    }
+}

package/dist/ui/cli/commands.d.ts

@@ -0,0 +1,3 @@
+export declare function initCommand(): Promise<void>;
+export declare function listCollectionsCommand(): Promise<void>;
+export declare function inspectCollectionCommand(name: string): Promise<void>;

package/dist/ui/cli/commands.js

@@ -0,0 +1,108 @@
+import enquirer from "enquirer";
+import chalk from "chalk";
+import { Octokit } from "@octokit/rest";
+import { GitHubStorageProvider } from "../../infrastructure/github-storage.js";
+export async function initCommand() {
+    console.log(chalk.yellow("\n--- Database Initialization ---\n"));
+    try {
+        const questions = [
+            {
+                type: "input",
+                name: "owner",
+                message: "GitHub Repository Owner:",
+            },
+            {
+                type: "input",
+                name: "repo",
+                message: "GitHub Repository Name:",
+            },
+            {
+                type: "password",
+                name: "accessToken",
+                message: "GitHub Personal Access Token:",
+            },
+        ];
+        const answers = await enquirer.prompt(questions);
+        const storage = new GitHubStorageProvider({
+            owner: answers.owner,
+            repo: answers.repo,
+            accessToken: answers.accessToken,
+        });
+        process.stdout.write(chalk.blue("Verifying connection... "));
+        const success = await storage.testConnection();
+        if (success) {
+            console.log(chalk.green("Success!"));
+            console.log(chalk.dim("\nYou can now use these credentials in your application configuration."));
+        }
+        else {
+            console.log(chalk.red("Failed."));
+            console.log(chalk.red("Please check your token permissions and repository details."));
+        }
+    }
+    catch (error) {
+        console.error(chalk.red("\nInitialization cancelled or failed."));
+    }
+}
+export async function listCollectionsCommand() {
+    console.log(chalk.yellow("\n--- Collections List ---\n"));
+    const owner = process.env.GH_DB_OWNER;
+    const repo = process.env.GH_DB_REPO;
+    const auth = process.env.GH_DB_TOKEN;
+    if (!owner || !repo || !auth) {
+        console.log(chalk.red("Error: Environment variables GH_DB_OWNER, GH_DB_REPO, and GH_DB_TOKEN must be set."));
+        return;
+    }
+    const octokit = new Octokit({ auth });
+    try {
+        const { data } = await octokit.repos.getContent({
+            owner,
+            repo,
+            path: "",
+        });
+        if (Array.isArray(data)) {
+            const collections = data
+                .filter((item) => item.name.endsWith(".json"))
+                .map((item) => item.name.replace(".json", ""));
+            if (collections.length === 0) {
+                console.log(chalk.dim("No collections found in the repository."));
+            }
+            else {
+                collections.forEach((name) => {
+                    console.log(chalk.cyan(` • ${name}`));
+                });
+            }
+        }
+    }
+    catch (error) {
+        console.error(chalk.red(`Error fetching collections: ${error.message}`));
+    }
+}
+export async function inspectCollectionCommand(name) {
+    console.log(chalk.yellow(`\n--- Inspecting Collection: ${name} ---\n`));
+    const owner = process.env.GH_DB_OWNER;
+    const repo = process.env.GH_DB_REPO;
+    const auth = process.env.GH_DB_TOKEN;
+    if (!owner || !repo || !auth) {
+        console.log(chalk.red("Error: Environment variables GH_DB_OWNER, GH_DB_REPO, and GH_DB_TOKEN must be set."));
+        return;
+    }
+    const storage = new GitHubStorageProvider({
+        owner,
+        repo,
+        accessToken: auth,
+    });
+    try {
+        const path = `${name}.json`;
+        if (!(await storage.exists(path))) {
+            console.log(chalk.red(`Collection "${name}" does not exist.`));
+            return;
+        }
+        const response = await storage.readJson(path);
+        console.log(JSON.stringify(response.data, null, 2));
+        console.log(chalk.dim(`\nTotal records: ${response.data.length}`));
+        console.log(chalk.dim(`Current SHA: ${response.sha}`));
+    }
+    catch (error) {
+        console.error(chalk.red(`Error inspecting collection: ${error.message}`));
+    }
+}

package/dist/ui/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/ui/cli/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import chalk from "chalk";
+import boxen from "boxen";
+import { initCommand, listCollectionsCommand, inspectCollectionCommand, } from "./commands.js";
+const program = new Command();
+console.log(boxen(chalk.bold.blue("gh-as-db CLI"), {
+    padding: 1,
+    margin: 1,
+    borderStyle: "double",
+    borderColor: "blue",
+}));
+program
+    .name("gh-as-db")
+    .description("CLI to manage your GitHub-based database")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("Initialize connection and verify repository")
+    .action(initCommand);
+program
+    .command("list")
+    .alias("ls")
+    .description("List all collections in the database")
+    .action(listCollectionsCommand);
+program
+    .command("inspect <collection>")
+    .description("Inspect the contents of a collection")
+    .action(inspectCollectionCommand);
+program.parse();

package/dist/ui/collection.d.ts

@@ -0,0 +1,18 @@
+import { IStorageProvider, Middleware, QueryOptions, Schema } from "../core/types.js";
+export declare class Collection<T extends Schema> {
+    readonly name: string;
+    private readonly storage;
+    private readonly middleware;
+    private lastSha;
+    private indexer;
+    private items;
+    private dataLoaded;
+    constructor(name: string, storage: IStorageProvider, middleware?: Middleware<T>[]);
+    private get path();
+    create(item: T): Promise<T>;
+    find(queryOrPredicate?: ((item: T) => boolean) | QueryOptions<T>): Promise<T[]>;
+    private applyQueryOptions;
+    findById(id: string): Promise<T | null>;
+    update(id: string, updates: Partial<T>): Promise<T>;
+    delete(id: string): Promise<void>;
+}

package/dist/ui/collection.js

@@ -0,0 +1,236 @@
+import { ConcurrencyError, } from "../core/types.js";
+import { Indexer } from "../core/indexer.js";
+export class Collection {
+    name;
+    storage;
+    middleware;
+    lastSha;
+    indexer = new Indexer();
+    items = [];
+    dataLoaded = false;
+    constructor(name, storage, middleware = []) {
+        this.name = name;
+        this.storage = storage;
+        this.middleware = middleware;
+    }
+    get path() {
+        return `${this.name}.json`;
+    }
+    async create(item) {
+        let finalItem = item;
+        const context = {
+            collection: this.name,
+            operation: "create",
+        };
+        for (const mw of this.middleware) {
+            if (mw.beforeSave) {
+                finalItem = await mw.beforeSave(finalItem, context);
+            }
+        }
+        let items = [];
+        if (this.dataLoaded) {
+            items = [...this.items];
+        }
+        else {
+            try {
+                if (await this.storage.exists(this.path)) {
+                    const response = await this.storage.readJson(this.path);
+                    items = response.data;
+                    this.lastSha = response.sha;
+                }
+            }
+            catch (error) {
+                // If file doesn't exist, start with empty array
+            }
+        }
+        items.push(finalItem);
+        try {
+            this.lastSha = await this.storage.writeJson(this.path, items, `Add item to ${this.name}`, this.lastSha);
+        }
+        catch (error) {
+            if (error instanceof ConcurrencyError) {
+                this.dataLoaded = false;
+            }
+            throw error;
+        }
+        // Update in-memory state if already loaded
+        if (this.dataLoaded) {
+            this.items = items;
+            this.indexer.add(finalItem);
+        }
+        return finalItem;
+    }
+    async find(queryOrPredicate) {
+        if (!(await this.storage.exists(this.path))) {
+            return [];
+        }
+        let items;
+        const context = {
+            collection: this.name,
+            operation: "read",
+        };
+        // Use cached/indexed data if available
+        if (this.dataLoaded) {
+            // If it's an 'eq' filter we can potentially use index directly
+            if (typeof queryOrPredicate !== "function" &&
+                queryOrPredicate?.filters &&
+                queryOrPredicate.filters.length === 1 &&
+                queryOrPredicate.filters[0].operator === "eq" &&
+                this.indexer.hasIndex(queryOrPredicate.filters[0].field)) {
+                const filter = queryOrPredicate.filters[0];
+                const results = this.indexer.query(filter.field, filter.value);
+                if (results !== null) {
+                    return results;
+                }
+            }
+            // Fallback to full scan of current in-memory items
+            if (typeof queryOrPredicate === "function") {
+                return this.items.filter(queryOrPredicate);
+            }
+            if (queryOrPredicate) {
+                return this.applyQueryOptions(this.items, queryOrPredicate);
+            }
+            return this.items;
+        }
+        const response = await this.storage.readJson(this.path);
+        this.lastSha = response.sha;
+        items = response.data;
+        items = await Promise.all(items.map(async (item) => {
+            let currentItem = item;
+            for (const mw of this.middleware) {
+                if (mw.afterRead) {
+                    currentItem = await mw.afterRead(currentItem, context);
+                }
+            }
+            return currentItem;
+        }));
+        // Build index and store in-memory items
+        if (!this.dataLoaded) {
+            this.items = items;
+            this.indexer.build(items, items.length > 0 ? Object.keys(items[0]) : []);
+            this.dataLoaded = true;
+        }
+        if (typeof queryOrPredicate === "function") {
+            return items.filter(queryOrPredicate);
+        }
+        if (queryOrPredicate) {
+            return this.applyQueryOptions(items, queryOrPredicate);
+        }
+        return items;
+    }
+    applyQueryOptions(items, options) {
+        let result = [...items];
+        // Apply filters
+        if (options.filters) {
+            for (const filter of options.filters) {
+                result = result.filter((item) => {
+                    const val = item[filter.field];
+                    switch (filter.operator) {
+                        case "eq":
+                            return val === filter.value;
+                        case "neq":
+                            return val !== filter.value;
+                        case "gt":
+                            return val > filter.value;
+                        case "gte":
+                            return val >= filter.value;
+                        case "lt":
+                            return val < filter.value;
+                        case "lte":
+                            return val <= filter.value;
+                        case "contains":
+                            return (typeof val === "string" && val.includes(filter.value));
+                        case "in":
+                            return Array.isArray(filter.value) && filter.value.includes(val);
+                        default:
+                            return true;
+                    }
+                });
+            }
+        }
+        // Apply sorting
+        if (options.sort) {
+            for (const sort of options.sort) {
+                result.sort((a, b) => {
+                    const aVal = a[sort.field];
+                    const bVal = b[sort.field];
+                    if (aVal < bVal)
+                        return sort.order === "asc" ? -1 : 1;
+                    if (aVal > bVal)
+                        return sort.order === "asc" ? 1 : -1;
+                    return 0;
+                });
+            }
+        }
+        // Apply pagination
+        if (options.pagination) {
+            const { limit, offset = 0 } = options.pagination;
+            result = result.slice(offset, limit ? offset + limit : undefined);
+        }
+        return result;
+    }
+    async findById(id) {
+        if (this.dataLoaded && this.indexer.hasIndex("id")) {
+            const results = this.indexer.query("id", id);
+            return results && results.length > 0 ? results[0] : null;
+        }
+        const items = await this.find();
+        return items.find((item) => item.id === id) || null;
+    }
+    async update(id, updates) {
+        const items = await this.find();
+        const index = items.findIndex((item) => item.id === id);
+        if (index === -1) {
+            throw new Error(`Item with id ${id} not found in ${this.name}`);
+        }
+        const originalItem = items[index];
+        items[index] = { ...items[index], ...updates };
+        let finalItem = items[index];
+        const context = {
+            collection: this.name,
+            operation: "update",
+        };
+        for (const mw of this.middleware) {
+            if (mw.beforeSave) {
+                finalItem = await mw.beforeSave(finalItem, context);
+            }
+        }
+        items[index] = finalItem;
+        try {
+            this.lastSha = await this.storage.writeJson(this.path, items, `Update item ${id} in ${this.name}`, this.lastSha);
+        }
+        catch (error) {
+            if (error instanceof ConcurrencyError) {
+                this.dataLoaded = false;
+            }
+            throw error;
+        }
+        if (this.dataLoaded) {
+            this.items = items;
+            this.indexer.update(originalItem, finalItem);
+        }
+        return items[index];
+    }
+    async delete(id) {
+        const items = await this.find();
+        const index = items.findIndex((item) => item.id === id);
+        if (index === -1) {
+            return;
+        }
+        const itemToDelete = items[index];
+        const filtered = items.filter((_, i) => i !== index);
+        try {
+            this.lastSha = await this.storage.writeJson(this.path, filtered, `Delete item ${id} from ${this.name}`, this.lastSha);
+        }
+        catch (error) {
+            if (error instanceof ConcurrencyError) {
+                this.dataLoaded = false;
+            }
+            throw error;
+        }
+        if (this.dataLoaded) {
+            this.items = filtered;
+            this.indexer.remove(itemToDelete);
+        }
+    }
+}

package/dist/ui/github-db.d.ts

@@ -0,0 +1,11 @@
+import { GitHubDBConfig, IStorageProvider, Middleware, Schema } from "../core/types.js";
+import { Collection } from "./collection.js";
+export declare class GitHubDB {
+    readonly config: GitHubDBConfig;
+    readonly storage: IStorageProvider;
+    constructor(config: GitHubDBConfig);
+    connect(): Promise<boolean>;
+    collection<T extends Schema>(name: string, options?: {
+        middleware?: Middleware<T>[];
+    }): Collection<T>;
+}

package/dist/ui/github-db.js

@@ -0,0 +1,25 @@
+import { GitHubStorageProvider } from "../infrastructure/github-storage.js";
+import { Collection } from "./collection.js";
+export class GitHubDB {
+    config;
+    storage;
+    constructor(config) {
+        this.config = config;
+        if (!config.accessToken) {
+            throw new Error("accessToken is required");
+        }
+        if (!config.owner) {
+            throw new Error("owner is required");
+        }
+        if (!config.repo) {
+            throw new Error("repo is required");
+        }
+        this.storage = new GitHubStorageProvider(config);
+    }
+    async connect() {
+        return this.storage.testConnection();
+    }
+    collection(name, options = {}) {
+        return new Collection(name, this.storage, options.middleware);
+    }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "gh-as-db",
+  "version": "1.0.0",
+  "description": "Use a private GitHub repository as a database for your application.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "gh-as-db": "./dist/ui/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run",
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "github",
+    "database",
+    "storage",
+    "orm",
+    "json",
+    "collection"
+  ],
+  "author": "Tommy Hansen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/almyk/gh-as-db.git"
+  },
+  "bugs": {
+    "url": "https://github.com/almyk/gh-as-db/issues"
+  },
+  "homepage": "https://github.com/almyk/gh-as-db#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "@vitest/coverage-v8": "^4.0.17",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "dependencies": {
+    "@octokit/rest": "^22.0.1",
+    "boxen": "^8.0.1",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "enquirer": "^2.4.1"
+  }
+}