@iamkirbki/database-handler-core 2.0.0

package/dist/Database.js

@@ -0,0 +1,130 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import Table from "./Table";
+import Query from "./Query";
+/**
+ * Main Database class for interacting with SQLite databases
+ *
+ * @example
+ * ```typescript
+ * import { Database } from 'kirbkis-bettersqlite3-handler';
+ *
+ * // Create or open a database
+ * const db = new Database('./myapp.db');
+ *
+ * // Access a table
+ * const users = db.Table('users');
+ *
+ * // Create a new table
+ * const posts = db.CreateTable('posts');
+ * ```
+ */
+export default class Database {
+    /**
+     * Creates a new Database instance
+     *
+     * @param dbPath - Path to the SQLite database file (absolute or relative to process.cwd())
+     *
+     * @example
+     * ```typescript
+     * // Relative path
+     * const db = new Database('./data/app.db');
+     *
+     * // Absolute path
+     * const db = new Database('/var/data/app.db');
+     *
+     * // In-memory database
+     * const db = new Database(':memory:');
+     * ```
+     */
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    /**
+     * Get a Table instance to interact with an existing table
+     *
+     * @param name - Name of the table
+     * @returns Table instance for querying and manipulating data
+     * @throws Error if the table does not exist
+     *
+     * @example
+     * ```typescript
+     * const users = await db.Table('users');
+     * const allUsers = await users.Records();
+     * ```
+     */
+    Table(name) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Validator.ValidateTableName(name);
+            return yield Table.create(name, this.adapter);
+        });
+    }
+    // TODO Make primary key required
+    /**
+     * Create a new table with specified columns
+     * Validates table name, column names, and column types before creation
+     * Uses CREATE TABLE IF NOT EXISTS to avoid errors if table already exists
+     *
+     * @param name - Name of the table to create
+     * @param columns - Object mapping column names to their type definitions
+     * @returns Table instance for the newly created table
+     * @throws Error if table name, column names, or column types are invalid
+     *
+     * @example
+     * ```typescript
+     * // Create a users table
+     * const users = await db.CreateTable('users', {
+     *   id: 'INTEGER PRIMARY KEY AUTOINCREMENT',
+     *   name: 'TEXT NOT NULL',
+     *   email: 'TEXT UNIQUE',
+     *   age: 'INTEGER',
+     *   created_at: 'DATETIME DEFAULT CURRENT_TIMESTAMP'
+     * });
+     *
+     * // Table is now ready to use
+     * await users.Insert({ name: 'John', email: 'john@example.com', age: 30 });
+     * ```
+     */
+    CreateTable(name, columns) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Validator.ValidateTableName(name);
+            const names = Object.keys(columns || {}).map((colName) => {
+                // Validator.ValidateColumnName(colName);
+                return colName;
+            });
+            const colsDef = names.map(colName => {
+                const colType = columns[colName];
+                // Validator.ValidateColumnType(colType);
+                return `"${colName}" ${colType}`;
+            }).join(", ");
+            const stmt = yield this.adapter.prepare(`CREATE TABLE IF NOT EXISTS "${name}" (${colsDef});`);
+            yield stmt.run();
+            return yield Table.create(name, this.adapter, true);
+        });
+    }
+    /**
+     * Create a Query object for executing custom SQL queries
+     *
+     * @param table - Table object for validation and context
+     * @param query - The SQL query string with ? placeholders
+     * @returns Query instance for executing the query
+     *
+     * @example
+     * ```typescript
+     * const users = db.Table('users');
+     * const query = db.Query(users, 'SELECT * FROM users WHERE age > ? AND status = ?');
+     * query.Parameters = { age: 18, status: 'active' };
+     * const results = query.All();
+     * ```
+     */
+    Query(table, query) {
+        return new Query(table, query, this.adapter);
+    }
+}

package/dist/Query.js

@@ -0,0 +1,186 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import Record from "@core/Record";
+/**
+ * Query class for executing custom SQL queries
+ *
+ * Features:
+ * - Supports named parameters using @fieldName syntax
+ * - Provides type-safe query execution (Run, All, Get)
+ * - Transaction support for atomic multi-insert/update operations
+ *
+ * @example
+ * ```typescript
+ * const users = db.Table('users');
+ *
+ * // SELECT query with parameters
+ * const query = db.Query(users, 'SELECT * FROM users WHERE age > @age AND status = @status');
+ * query.Parameters = { age: 18, status: 'active' };
+ * const results = query.All();
+ *
+ * // INSERT query
+ * const insert = db.Query(users, 'INSERT INTO users (name, email) VALUES (@name, @email)');
+ * insert.Parameters = { name: 'John', email: 'john@example.com' };
+ * insert.Run();
+ *
+ * // Transaction for multiple inserts
+ * insert.Transaction([
+ *   { name: 'John', email: 'john@example.com' },
+ *   { name: 'Jane', email: 'jane@example.com' }
+ * ]);
+ * ```
+ */
+export default class Query {
+    /**
+     * Creates a Query instance (usually called via db.Query() method)
+     *
+     * @param Table - Table instance for validation context
+     * @param Query - SQL query string with @fieldName placeholders for parameters
+     * @param DB - Database connection instance
+     *
+     * @example
+     * ```typescript
+     * // Direct instantiation (not recommended - use db.Query() instead)
+     * const query = new Query(
+     *   usersTable,
+     *   'SELECT * FROM users WHERE id = @id',
+     *   db
+     * );
+     * query.Parameters = { id: 1 };
+     *
+     * // Recommended approach
+     * const query = db.Query(usersTable, 'SELECT * FROM users WHERE id = @id');
+     * query.Parameters = { id: 1 };
+     * ```
+     */
+    constructor(Table, Query, adapter) {
+        this.query = "";
+        this.Parameters = {};
+        this.Table = Table;
+        this.query = Query;
+        this.adapter = adapter;
+    }
+    /**
+     * Execute a query that modifies data (INSERT, UPDATE, DELETE)
+     *
+     * @template Type - Expected return type (typically { lastInsertRowid: number, changes: number })
+     * @returns Result object with lastInsertRowid and changes count
+     *
+     * @example
+     * ```typescript
+     * // INSERT query
+     * const query = db.Query(users, 'INSERT INTO users (name, age) VALUES (@name, @age)');
+     * query.Parameters = { name: 'John', age: 30 };
+     * const result = query.Run<{ lastInsertRowid: number, changes: number }>();
+     * console.log(`Inserted ID: ${result.lastInsertRowid}`);
+     *
+     * // UPDATE query
+     * const update = db.Query(users, 'UPDATE users SET age = @age WHERE id = @id');
+     * update.Parameters = { age: 31, id: 1 };
+     * const updateResult = update.Run<{ changes: number }>();
+     * console.log(`Updated ${updateResult.changes} rows`);
+     * ```
+     */
+    Run() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const stmt = yield this.adapter.prepare(this.query);
+            return yield stmt.run(this.Parameters);
+        });
+    }
+    /**
+     * Execute a SELECT query and return all matching rows as Record objects
+     * Each row is wrapped in a Record instance for convenient updates/deletes
+     *
+     * @template Type - Expected row type
+     * @returns Array of Record objects containing the query results
+     *
+     * @example
+     * ```typescript
+     * interface User {
+     *   id: number;
+     *   name: string;
+     *   age: number;
+     * }
+     *
+     * const query = db.Query(users, 'SELECT * FROM users WHERE age > @age');
+     * query.Parameters = { age: 18 };
+     * const results = query.All<User>();
+     *
+     * // Each result is a Record object
+     * results.forEach(user => {
+     *   console.log(user.values); // { id: 1, name: 'John', age: 30 }
+     *   user.Update({ age: 31 }); // Can update directly
+     * });
+     * ```
+     */
+    All() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const stmt = yield this.adapter.prepare(this.query);
+            let results = yield stmt.all(this.Parameters);
+            // This is a fix for a bug where id's passed as numbers don't match string ids in the db
+            if (results.length === 0 && this.Parameters.id) {
+                this.Parameters.id = this.Parameters.id.toString();
+                results = (yield stmt.all(this.Parameters));
+            }
+            return results.map(res => new Record(res, this.adapter, this.Table));
+        });
+    }
+    /**
+     * Execute a SELECT query and return the first matching row as a Record object
+     * Returns undefined if no rows match the query
+     *
+     * @template Type - Expected row type
+     * @returns Single Record object or undefined if no match found
+     *
+     * @example
+     * ```typescript
+     * interface User {
+     *   id: number;
+     *   name: string;
+     *   email: string;
+     * }
+     *
+     * const query = db.Query(users, 'SELECT * FROM users WHERE id = @id');
+     * query.Parameters = { id: 1 };
+     * const user = query.Get<User>();
+     *
+     * if (user) {
+     *   console.log(user.values); // { id: 1, name: 'John', email: 'john@example.com' }
+     *   user.Update({ email: 'newemail@example.com' });
+     * }
+     * ```
+     */
+    Get() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const stmt = yield this.adapter.prepare(this.query);
+            const results = yield stmt.get(this.Parameters);
+            return results ? new Record(results, this.adapter, this.Table) : undefined;
+        });
+    }
+    Transaction(paramList) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const stmt = yield this.adapter.prepare(this.query);
+            const transactionFn = yield this.adapter.transaction((paramsArray) => {
+                for (const params of paramsArray) {
+                    // Use runSync for better-sqlite3 transactions (must be synchronous)
+                    // For other adapters, this method should be implemented appropriately
+                    if (stmt.runSync) {
+                        stmt.runSync(params);
+                    }
+                    else {
+                        // Fallback: call run without await (may not work for all adapters)
+                        stmt.run(params);
+                    }
+                }
+            });
+            transactionFn(paramList);
+        });
+    }
+}

package/dist/Record.js

@@ -0,0 +1,172 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { inspect } from "util";
+import Query from "@core/Query";
+/**
+ * Record class represents a single database row with methods for updates and deletion
+ * Automatically returned by Table.Records() and Table.Record() methods
+ *
+ * @example
+ * ```typescript
+ * const user = table.Record({ where: { id: 1 } });
+ *
+ * // Access values
+ * console.log(user?.values);
+ *
+ * // Update the record
+ * user?.Update({ name: 'John Doe', age: 31 });
+ *
+ * // Delete the record
+ * user?.Delete();
+ *
+ * // JSON serialization works automatically
+ * console.log(JSON.stringify(user)); // {"id": 1, "name": "John Doe", ...}
+ * ```
+ */
+export default class Record {
+    /**
+     * Creates a Record instance (typically called internally by Table methods)
+     *
+     * @param values - Object containing column names and their values
+     * @param db - Database connection instance
+     * @param tableName - Name of the table this record belongs to
+     */
+    constructor(values, adapter, table) {
+        this._values = {};
+        this._values = values;
+        this.adapter = adapter;
+        this._table = table;
+    }
+    /**
+     * Get the raw values object for this record
+     *
+     * @returns Object containing all column values
+     *
+     * @example
+     * ```typescript
+     * const user = table.Record({ where: { id: 1 } });
+     * console.log(user?.values); // { id: 1, name: 'John', email: 'john@example.com' }
+     * ```
+     */
+    get values() {
+        return this._values;
+    }
+    ;
+    /**
+     * Update this record in the database
+     * Updates both the database and the local values
+     *
+     * @template TEntity - Record type that must include an 'id' property (number or string)
+     * @param newValues - Object with column names and new values to update
+     * @throws Error if the record doesn't have an 'id' field
+     *
+     * @example
+     * ```typescript
+     * const user = table.Record({ where: { id: 1 } });
+     * user?.Update({ name: 'Jane Doe', age: 28 });
+     * // Database is updated and user.values reflects the changes
+     * ```
+     */
+    Update(newValues) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const setClauses = Object.keys(newValues)
+                .map(key => `${key} = @${key}`)
+                .join(", ");
+            // Use all current values as WHERE clause to identify the record
+            const originalValues = this._values;
+            const whereClauses = Object.keys(originalValues)
+                .map(key => `${key} = @where_${key}`)
+                .join(" AND ");
+            const query = `UPDATE "${this._table.Name}" SET ${setClauses} WHERE ${whereClauses};`;
+            const _query = new Query(this._table, query, this.adapter);
+            const params = Object.assign({}, newValues);
+            Object.entries(originalValues).forEach(([key, value]) => {
+                params[`where_${key}`] = value;
+            });
+            _query.Parameters = params;
+            yield _query.Run();
+            this._values = Object.assign(Object.assign({}, this._values), newValues);
+        });
+    }
+    /**
+     * Delete this record from the database
+     * Uses all current field values as WHERE clause conditions
+     *
+     * @example
+     * ```typescript
+     * const user = table.Record({ where: { id: 1 } });
+     * user?.Delete();
+     * // Record is permanently deleted from the database
+     * ```
+     */
+    Delete() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const whereClauses = Object.keys(this._values)
+                .map(key => `${key} = @${key}`)
+                .join(" AND ");
+            const _query = new Query(this._table, `DELETE FROM "${this._table.Name}" WHERE ${whereClauses};`, this.adapter);
+            _query.Parameters = Object.assign({}, this._values);
+            yield _query.Run();
+        });
+    }
+    /**
+     * Returns the values object when JSON.stringify() is called
+     * Allows seamless JSON serialization of Record objects
+     *
+     * @returns The values object
+     *
+     * @example
+     * ```typescript
+     * const user = table.Record({ where: { id: 1 } });
+     * console.log(JSON.stringify(user));
+     * // Output: {"id":1,"name":"John","email":"john@example.com"}
+     * ```
+     */
+    toJSON() {
+        return this._values;
+    }
+    /**
+     * Returns a formatted string representation of the record
+     *
+     * @returns Pretty-printed JSON string of the values
+     *
+     * @example
+     * ```typescript
+     * const user = table.Record({ where: { id: 1 } });
+     * console.log(user?.toString());
+     * // Output:
+     * // {
+     * //   "id": 1,
+     * //   "name": "John",
+     * //   "email": "john@example.com"
+     * // }
+     * ```
+     */
+    toString() {
+        return JSON.stringify(this._values, null, 2);
+    }
+    /**
+     * Custom inspect method for console.log() and Node.js REPL
+     * Makes Record objects display their values directly instead of the class structure
+     *
+     * @returns The values object for display
+     *
+     * @example
+     * ```typescript
+     * const user = table.Record({ where: { id: 1 } });
+     * console.log(user);
+     * // Output: { id: 1, name: 'John', email: 'john@example.com' }
+     * // Instead of: Record { _db: ..., _values: {...}, _tableName: '...' }
+     * ```
+     */
+    [inspect.custom]() {
+        return this._values;
+    }
+}

package/dist/Schema.js

@@ -0,0 +1,13 @@
+/**
+ * Schema module - placeholder for future schema definition and migration features
+ *
+ * Future capabilities:
+ * - Schema versioning and migrations
+ * - Schema validation and comparison
+ * - Automatic migration generation
+ * - Schema import/export
+ *
+ * @module Schema
+ * @packageDocumentation
+ */
+export {};