GSCB-DB Library

A database library for GitSense Chat Bridge (GSCB) that provides a clean and type-safe interface for database operations. Built on better-sqlite3 for high performance and concurrency.

Installation

npm install gscb-db

Usage

import { DatabaseClient, DatabaseConfig } from '@gitsense/gscb-db';

// Configure the database
const config: DatabaseConfig = {
    path: './data.db',
    verbose: false
};

// Create and initialize the client
const client = new DatabaseClient(config);
await client.initialize();

// Use the services
const groupId = await client.groups.createGroup({
    name: 'My Group',
    type: 'git-repo',
    meta: {
        type: 'repo',
        path: '/path/to/repo',
        bare: false,
        importedAt: new Date().toISOString()
    }
});

// Close the client when done
await client.close();

Features

• WAL Mode: Write-Ahead Logging enabled by default for improved concurrency and performance
• Synchronous Core: Built on better-sqlite3 for optimal performance with a backwards-compatible async API
• Full TypeScript support with strict typing
• Comprehensive error handling
• Transaction support
• Logging with Winston
• Schema migrations
• CRUD operations for all entities:
  • Groups
  • Chats
  • Messages
  • Prompts

API Documentation

DatabaseClient

The main client class that provides access to all services.

const client = new DatabaseClient(config);
await client.initialize();

// Access services
client.groups    // GroupService
client.chats     // ChatService
client.messages  // MessageService
client.prompts   // PromptService

constructor(config: DatabaseConfig)

Creates a new DatabaseClient instance.

• config: A DatabaseConfig object containing the database path and verbose settings.

async initialize(): Promise<void>

Initializes the database connection and runs migrations. Must be called before any other operations.

async close(): Promise<void>

Closes the database connection.

isInitialized(): boolean

Returns true if the database client has been initialized, false otherwise.

Direct Database Access

For advanced users, the database property provides direct access to the underlying database methods. Use this with caution, as it bypasses the service layer's validation and business logic.

Warning: Direct database access should only be used when the standard API methods are insufficient. Always handle validation and error checking manually.

database.transaction<T>(callback: () => T): Promise<T>

Executes a transaction with the provided callback.

• callback: The function to execute within the transaction. Note: While the method returns a Promise for compatibility, the callback itself is executed synchronously.
• Returns: The result of the callback.

database.run(sql: string, params?: any[]): void

Executes a SQL query.

• sql: The SQL query to execute.
• params: Optional parameters for the query.

database.get<T>(sql: string, params?: any[]): T | undefined

Executes a SQL query and returns a single row.

• sql: The SQL query to execute.
• params: Optional parameters for the query.
• Returns: The first row of the result set.

database.all<T>(sql: string, params?: any[]): T[]

Executes a SQL query and returns all rows.

• sql: The SQL query to execute.
• params: Optional parameters for the query.
• Returns: All rows of the result set.

Services

Each service provides CRUD operations for its respective entity:

• createX: Create a new entity
• getXById: Get an entity by ID
• updateX: Update an existing entity
• deleteX: Delete an entity
• Additional methods specific to each entity type

Error Handling

The library provides specific error types for different scenarios:

• GSCBError: Base error class
• DatabaseError: Database-related errors
• ConnectionError: Connection issues
• QueryError: SQL query errors
• ValidationError: Data validation errors
• NotFoundError: Resource not found

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

License

MIT