@open-core/framework 0.1.0-alpha.1

package/dist/server/database/adapters/oxmysql.adapter.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * OxMySQL Adapter
+ *
+ * Default database adapter using oxmysql resource for FiveM.
+ * Requires oxmysql to be installed and running on the server.
+ *
+ * @see https://github.com/overextended/oxmysql
+ * @see https://coxdocs.dev/oxmysql/Functions/transaction
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxMySQLAdapter = void 0;
+const database_contract_1 = require("../database.contract");
+/**
+ * Get the oxmysql export from FiveM
+ */
+function getOxMySQL() {
+    const ox = exports['oxmysql'];
+    if (!ox) {
+        throw new Error('[OpenCore] oxmysql is not available. Make sure oxmysql resource is started before your resource.');
+    }
+    return ox;
+}
+/**
+ * Normalize transaction input to oxmysql format
+ */
+function normalizeQueries(queries) {
+    if (queries.length === 0)
+        return [];
+    const first = queries[0];
+    // String array - used with shared params
+    if (typeof first === 'string') {
+        return queries;
+    }
+    // Tuple format: [query, values]
+    if (Array.isArray(first)) {
+        return queries.map(([query, values]) => ({
+            query,
+            values,
+        }));
+    }
+    // Already in TransactionQuery format
+    return queries;
+}
+/**
+ * OxMySQL Database Adapter
+ *
+ * Implements DatabaseContract using oxmysql exports.
+ *
+ * @example
+ * ```typescript
+ * import { OxMySQLAdapter } from '@open-core/framework/server'
+ *
+ * // Usually you don't need to instantiate directly,
+ * // use DatabaseService instead
+ * const adapter = new OxMySQLAdapter()
+ * const users = await adapter.query('SELECT * FROM users')
+ * ```
+ */
+class OxMySQLAdapter extends database_contract_1.DatabaseContract {
+    constructor() {
+        super();
+        this.ox = getOxMySQL();
+    }
+    /**
+     * Execute a query and return all matching rows
+     */
+    async query(sql, params) {
+        const result = await this.ox.query_async(sql, params);
+        return result !== null && result !== void 0 ? result : [];
+    }
+    /**
+     * Execute a query and return a single row
+     */
+    async single(sql, params) {
+        const result = await this.ox.single_async(sql, params);
+        return result !== null && result !== void 0 ? result : null;
+    }
+    /**
+     * Execute a query and return a single scalar value
+     */
+    async scalar(sql, params) {
+        const result = await this.ox.scalar_async(sql, params);
+        return result !== null && result !== void 0 ? result : null;
+    }
+    /**
+     * Execute an UPDATE or DELETE statement
+     */
+    async execute(sql, params) {
+        const affectedRows = await this.ox.update_async(sql, params);
+        return { affectedRows: affectedRows !== null && affectedRows !== void 0 ? affectedRows : 0 };
+    }
+    /**
+     * Execute an INSERT statement
+     */
+    async insert(sql, params) {
+        const insertId = await this.ox.insert_async(sql, params);
+        return { insertId: insertId !== null && insertId !== void 0 ? insertId : 0 };
+    }
+    /**
+     * Execute multiple queries within a transaction.
+     *
+     * Supports three formats:
+     *
+     * **1. Specific format (object)**
+     * ```typescript
+     * await db.transaction([
+     *   { query: 'INSERT INTO test (id) VALUES (?)', values: [1] },
+     *   { query: 'INSERT INTO test (id, name) VALUES (?, ?)', values: [2, 'bob'] },
+     * ])
+     * ```
+     *
+     * **2. Specific format (tuple)**
+     * ```typescript
+     * await db.transaction([
+     *   ['INSERT INTO test (id) VALUES (?)', [1]],
+     *   ['INSERT INTO test (id, name) VALUES (?, ?)', [2, 'bob']],
+     * ])
+     * ```
+     *
+     * **3. Shared format (named parameters)**
+     * ```typescript
+     * await db.transaction(
+     *   [
+     *     'INSERT INTO test (id, name) VALUES (@someid, @somename)',
+     *     'UPDATE test SET name = @newname WHERE id = @someid',
+     *   ],
+     *   {
+     *     someid: 2,
+     *     somename: 'John Doe',
+     *     newname: 'John Notdoe',
+     *   }
+     * )
+     * ```
+     *
+     * @see https://coxdocs.dev/oxmysql/Functions/transaction
+     */
+    async transaction(queries, sharedParams) {
+        if (queries.length === 0)
+            return true;
+        const normalizedQueries = normalizeQueries(queries);
+        // Use shared params format if provided
+        if (sharedParams) {
+            return await this.ox.transaction_async(normalizedQueries, sharedParams);
+        }
+        return await this.ox.transaction_async(normalizedQueries);
+    }
+}
+exports.OxMySQLAdapter = OxMySQLAdapter;

package/dist/server/database/database.contract.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Database Contract
+ *
+ * Abstract base class that defines the interface for all database adapters.
+ * Implement this contract to create custom database adapters.
+ *
+ * @example
+ * ```typescript
+ * class MyDatabaseAdapter extends DatabaseContract {
+ *   async query<T>(sql: string, params?: any[]): Promise<T[]> {
+ *     // Implementation
+ *   }
+ *   // ... other methods
+ * }
+ * ```
+ */
+import type { ExecuteResult, InsertResult, TransactionInput, TransactionSharedParams } from './types';
+/**
+ * Abstract contract for database adapters.
+ *
+ * All database adapters must extend this class and implement
+ * all abstract methods to ensure consistent behavior across
+ * different database backends.
+ */
+export declare abstract class DatabaseContract {
+    /**
+     * Execute a query and return all matching rows.
+     *
+     * @param sql - The SQL query string
+     * @param params - Optional parameters for prepared statement
+     * @returns Array of results
+     *
+     * @example
+     * ```typescript
+     * const users = await db.query<User>('SELECT * FROM users WHERE active = ?', [true])
+     * ```
+     */
+    abstract query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+    /**
+     * Execute a query and return a single row.
+     *
+     * @param sql - The SQL query string
+     * @param params - Optional parameters for prepared statement
+     * @returns Single result or null if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await db.single<User>('SELECT * FROM users WHERE id = ?', [userId])
+     * if (user) {
+     *   console.log(user.name)
+     * }
+     * ```
+     */
+    abstract single<T = any>(sql: string, params?: any[]): Promise<T | null>;
+    /**
+     * Execute a query and return a single scalar value.
+     *
+     * @param sql - The SQL query string
+     * @param params - Optional parameters for prepared statement
+     * @returns Scalar value or null if not found
+     *
+     * @example
+     * ```typescript
+     * const count = await db.scalar<number>('SELECT COUNT(*) FROM users')
+     * const name = await db.scalar<string>('SELECT name FROM users WHERE id = ?', [userId])
+     * ```
+     */
+    abstract scalar<T = any>(sql: string, params?: any[]): Promise<T | null>;
+    /**
+     * Execute an UPDATE or DELETE statement.
+     *
+     * @param sql - The SQL statement
+     * @param params - Optional parameters for prepared statement
+     * @returns Object containing affected rows count
+     *
+     * @example
+     * ```typescript
+     * const result = await db.execute('UPDATE users SET active = ? WHERE id = ?', [false, userId])
+     * console.log(`Updated ${result.affectedRows} rows`)
+     * ```
+     */
+    abstract execute(sql: string, params?: any[]): Promise<ExecuteResult>;
+    /**
+     * Execute an INSERT statement.
+     *
+     * @param sql - The SQL insert statement
+     * @param params - Optional parameters for prepared statement
+     * @returns Object containing the inserted row ID
+     *
+     * @example
+     * ```typescript
+     * const result = await db.insert('INSERT INTO users (name, email) VALUES (?, ?)', ['John', 'john@example.com'])
+     * console.log(`Inserted user with ID: ${result.insertId}`)
+     * ```
+     */
+    abstract insert(sql: string, params?: any[]): Promise<InsertResult>;
+    /**
+     * Execute multiple queries within a transaction.
+     *
+     * All queries are committed together if all succeed, or rolled back if any fails.
+     *
+     * **Specific format** - Each query has its own parameters:
+     * ```typescript
+     * await db.transaction([
+     *   { query: 'INSERT INTO users (name) VALUES (?)', values: ['John'] },
+     *   { query: 'INSERT INTO logs (action) VALUES (?)', values: ['user_created'] },
+     * ])
+     * ```
+     *
+     * **Shared format** - All queries share named parameters:
+     * ```typescript
+     * await db.transaction(
+     *   [
+     *     'INSERT INTO users (id, name) VALUES (@userid, @username)',
+     *     'INSERT INTO profiles (user_id) VALUES (@userid)',
+     *   ],
+     *   { userid: 1, username: 'John' }
+     * )
+     * ```
+     *
+     * @param queries - Array of queries to execute
+     * @param sharedParams - Optional shared parameters for all queries (named params format)
+     * @returns true if transaction succeeded, false otherwise
+     *
+     * @see https://coxdocs.dev/oxmysql/Functions/transaction
+     */
+    abstract transaction(queries: TransactionInput, sharedParams?: TransactionSharedParams): Promise<boolean>;
+}

package/dist/server/database/database.contract.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Database Contract
+ *
+ * Abstract base class that defines the interface for all database adapters.
+ * Implement this contract to create custom database adapters.
+ *
+ * @example
+ * ```typescript
+ * class MyDatabaseAdapter extends DatabaseContract {
+ *   async query<T>(sql: string, params?: any[]): Promise<T[]> {
+ *     // Implementation
+ *   }
+ *   // ... other methods
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseContract = void 0;
+/**
+ * Abstract contract for database adapters.
+ *
+ * All database adapters must extend this class and implement
+ * all abstract methods to ensure consistent behavior across
+ * different database backends.
+ */
+class DatabaseContract {
+}
+exports.DatabaseContract = DatabaseContract;

package/dist/server/database/database.service.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Database Service
+ *
+ * Main entry point for database operations. Acts as a factory/wrapper
+ * that delegates to the registered database adapter.
+ *
+ * @example
+ * ```typescript
+ * import { DatabaseService } from '@open-core/framework/server'
+ * import { inject, injectable } from 'tsyringe'
+ *
+ * @injectable()
+ * class UserService {
+ *   constructor(@inject(DatabaseService) private db: DatabaseService) {}
+ *
+ *   async getUser(id: number) {
+ *     return this.db.single<User>('SELECT * FROM users WHERE id = ?', [id])
+ *   }
+ * }
+ * ```
+ */
+import { DatabaseContract } from './database.contract';
+import type { DatabaseConfig, ExecuteResult, InsertResult, TransactionInput, TransactionSharedParams } from './types';
+/**
+ * Database Service
+ *
+ * Singleton service that provides database operations through
+ * a pluggable adapter system. Uses oxmysql by default.
+ */
+export declare class DatabaseService extends DatabaseContract {
+    private adapter;
+    private config;
+    private isInitialized;
+    /**
+     * Initialize the database service with optional configuration
+     *
+     * @param config - Database configuration options
+     */
+    initialize(config?: DatabaseConfig): void;
+    /**
+     * Check if the service is initialized
+     */
+    get initialized(): boolean;
+    /**
+     * Register a custom database adapter
+     *
+     * @param adapter - Custom adapter implementing DatabaseContract
+     *
+     * @example
+     * ```typescript
+     * class CustomAdapter extends DatabaseContract {
+     *   // Implementation
+     * }
+     *
+     * db.setAdapter(new CustomAdapter())
+     * ```
+     */
+    setAdapter(adapter: DatabaseContract): void;
+    /**
+     * Get the current adapter
+     */
+    getAdapter(): DatabaseContract;
+    /**
+     * Ensure the service is initialized before operations
+     */
+    private ensureInitialized;
+    /**
+     * Execute a query and return all matching rows
+     */
+    query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+    /**
+     * Execute a query and return a single row
+     */
+    single<T = any>(sql: string, params?: any[]): Promise<T | null>;
+    /**
+     * Execute a query and return a single scalar value
+     */
+    scalar<T = any>(sql: string, params?: any[]): Promise<T | null>;
+    /**
+     * Execute an UPDATE or DELETE statement
+     */
+    execute(sql: string, params?: any[]): Promise<ExecuteResult>;
+    /**
+     * Execute an INSERT statement
+     */
+    insert(sql: string, params?: any[]): Promise<InsertResult>;
+    /**
+     * Execute multiple queries within a transaction
+     */
+    transaction(queries: TransactionInput, sharedParams?: TransactionSharedParams): Promise<boolean>;
+}
+/**
+ * Get the global DatabaseService instance
+ *
+ * @returns The singleton DatabaseService instance
+ *
+ * @example
+ * ```typescript
+ * import { getDatabaseService } from '@open-core/framework/server'
+ *
+ * const db = getDatabaseService()
+ * const users = await db.query('SELECT * FROM users')
+ * ```
+ */
+export declare function getDatabaseService(): DatabaseService;
+/**
+ * Initialize the database service
+ *
+ * @param config - Database configuration options
+ *
+ * @example
+ * ```typescript
+ * import { initDatabase } from '@open-core/framework/server'
+ *
+ * // Initialize with default oxmysql adapter
+ * initDatabase()
+ *
+ * // Or with custom config
+ * initDatabase({ debug: true })
+ * ```
+ */
+export declare function initDatabase(config?: DatabaseConfig): void;
+/**
+ * Standalone query function
+ *
+ * @example
+ * ```typescript
+ * import { query } from '@open-core/framework/server'
+ *
+ * const users = await query<User>('SELECT * FROM users WHERE active = ?', [true])
+ * ```
+ */
+export declare function query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+/**
+ * Standalone single function
+ *
+ * @example
+ * ```typescript
+ * import { single } from '@open-core/framework/server'
+ *
+ * const user = await single<User>('SELECT * FROM users WHERE id = ?', [userId])
+ * ```
+ */
+export declare function single<T = any>(sql: string, params?: any[]): Promise<T | null>;
+/**
+ * Standalone scalar function
+ *
+ * @example
+ * ```typescript
+ * import { scalar } from '@open-core/framework/server'
+ *
+ * const count = await scalar<number>('SELECT COUNT(*) FROM users')
+ * ```
+ */
+export declare function scalar<T = any>(sql: string, params?: any[]): Promise<T | null>;
+/**
+ * Standalone execute function
+ *
+ * @example
+ * ```typescript
+ * import { execute } from '@open-core/framework/server'
+ *
+ * const result = await execute('UPDATE users SET active = ? WHERE id = ?', [false, userId])
+ * console.log(`Updated ${result.affectedRows} rows`)
+ * ```
+ */
+export declare function execute(sql: string, params?: any[]): Promise<ExecuteResult>;
+/**
+ * Standalone insert function
+ *
+ * @example
+ * ```typescript
+ * import { insert } from '@open-core/framework/server'
+ *
+ * const result = await insert('INSERT INTO users (name) VALUES (?)', ['John'])
+ * console.log(`Inserted with ID: ${result.insertId}`)
+ * ```
+ */
+export declare function insert(sql: string, params?: any[]): Promise<InsertResult>;
+/**
+ * Standalone transaction function
+ *
+ * Execute multiple queries atomically. All succeed or all fail.
+ *
+ * @example Specific format (each query has its own params)
+ * ```typescript
+ * import { transaction } from '@open-core/framework/server'
+ *
+ * const success = await transaction([
+ *   { query: 'INSERT INTO users (name) VALUES (?)', values: ['John'] },
+ *   { query: 'INSERT INTO logs (action) VALUES (?)', values: ['user_created'] },
+ * ])
+ * ```
+ *
+ * @example Tuple format
+ * ```typescript
+ * const success = await transaction([
+ *   ['INSERT INTO users (name) VALUES (?)', ['John']],
+ *   ['INSERT INTO logs (action) VALUES (?)', ['user_created']],
+ * ])
+ * ```
+ *
+ * @example Shared format (named parameters)
+ * ```typescript
+ * const success = await transaction(
+ *   [
+ *     'INSERT INTO users (id, name) VALUES (@userid, @username)',
+ *     'INSERT INTO profiles (user_id) VALUES (@userid)',
+ *   ],
+ *   { userid: 1, username: 'John' }
+ * )
+ * ```
+ *
+ * @see https://coxdocs.dev/oxmysql/Functions/transaction
+ */
+export declare function transaction(queries: TransactionInput, sharedParams?: TransactionSharedParams): Promise<boolean>;