@open-core/framework 1.0.1-beta.1

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>;

package/dist/server/database/database.service.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * 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])
+ *   }
+ * }
+ * ```
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseService = void 0;
+exports.getDatabaseService = getDatabaseService;
+exports.initDatabase = initDatabase;
+exports.query = query;
+exports.single = single;
+exports.scalar = scalar;
+exports.execute = execute;
+exports.insert = insert;
+exports.transaction = transaction;
+const tsyringe_1 = require("tsyringe");
+const database_contract_1 = require("./database.contract");
+const oxmysql_adapter_1 = require("./adapters/oxmysql.adapter");
+/**
+ * Database Service
+ *
+ * Singleton service that provides database operations through
+ * a pluggable adapter system. Uses oxmysql by default.
+ */
+let DatabaseService = class DatabaseService extends database_contract_1.DatabaseContract {
+    constructor() {
+        super(...arguments);
+        this.adapter = null;
+        this.config = {};
+        this.isInitialized = false;
+    }
+    /**
+     * Initialize the database service with optional configuration
+     *
+     * @param config - Database configuration options
+     */
+    initialize(config = {}) {
+        if (this.isInitialized)
+            return;
+        this.config = config;
+        // Use oxmysql by default
+        if (!this.adapter) {
+            this.adapter = new oxmysql_adapter_1.OxMySQLAdapter();
+        }
+        this.isInitialized = true;
+    }
+    /**
+     * Check if the service is initialized
+     */
+    get initialized() {
+        return this.isInitialized;
+    }
+    /**
+     * Register a custom database adapter
+     *
+     * @param adapter - Custom adapter implementing DatabaseContract
+     *
+     * @example
+     * ```typescript
+     * class CustomAdapter extends DatabaseContract {
+     *   // Implementation
+     * }
+     *
+     * db.setAdapter(new CustomAdapter())
+     * ```
+     */
+    setAdapter(adapter) {
+        this.adapter = adapter;
+    }
+    /**
+     * Get the current adapter
+     */
+    getAdapter() {
+        this.ensureInitialized();
+        return this.adapter;
+    }
+    /**
+     * Ensure the service is initialized before operations
+     */
+    ensureInitialized() {
+        if (!this.adapter) {
+            // Auto-initialize with defaults if not initialized
+            this.initialize();
+        }
+    }
+    /**
+     * Execute a query and return all matching rows
+     */
+    async query(sql, params) {
+        this.ensureInitialized();
+        return this.adapter.query(sql, params);
+    }
+    /**
+     * Execute a query and return a single row
+     */
+    async single(sql, params) {
+        this.ensureInitialized();
+        return this.adapter.single(sql, params);
+    }
+    /**
+     * Execute a query and return a single scalar value
+     */
+    async scalar(sql, params) {
+        this.ensureInitialized();
+        return this.adapter.scalar(sql, params);
+    }
+    /**
+     * Execute an UPDATE or DELETE statement
+     */
+    async execute(sql, params) {
+        this.ensureInitialized();
+        return this.adapter.execute(sql, params);
+    }
+    /**
+     * Execute an INSERT statement
+     */
+    async insert(sql, params) {
+        this.ensureInitialized();
+        return this.adapter.insert(sql, params);
+    }
+    /**
+     * Execute multiple queries within a transaction
+     */
+    async transaction(queries, sharedParams) {
+        this.ensureInitialized();
+        return this.adapter.transaction(queries, sharedParams);
+    }
+};
+exports.DatabaseService = DatabaseService;
+exports.DatabaseService = DatabaseService = __decorate([
+    (0, tsyringe_1.injectable)()
+], DatabaseService);
+// Singleton instance for standalone usage
+let databaseServiceInstance = null;
+/**
+ * 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')
+ * ```
+ */
+function getDatabaseService() {
+    if (!databaseServiceInstance) {
+        databaseServiceInstance = new DatabaseService();
+    }
+    return databaseServiceInstance;
+}
+/**
+ * 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 })
+ * ```
+ */
+function initDatabase(config = {}) {
+    getDatabaseService().initialize(config);
+}
+/**
+ * Standalone query function
+ *
+ * @example
+ * ```typescript
+ * import { query } from '@open-core/framework/server'
+ *
+ * const users = await query<User>('SELECT * FROM users WHERE active = ?', [true])
+ * ```
+ */
+async function query(sql, params) {
+    return getDatabaseService().query(sql, params);
+}
+/**
+ * Standalone single function
+ *
+ * @example
+ * ```typescript
+ * import { single } from '@open-core/framework/server'
+ *
+ * const user = await single<User>('SELECT * FROM users WHERE id = ?', [userId])
+ * ```
+ */
+async function single(sql, params) {
+    return getDatabaseService().single(sql, params);
+}
+/**
+ * Standalone scalar function
+ *
+ * @example
+ * ```typescript
+ * import { scalar } from '@open-core/framework/server'
+ *
+ * const count = await scalar<number>('SELECT COUNT(*) FROM users')
+ * ```
+ */
+async function scalar(sql, params) {
+    return getDatabaseService().scalar(sql, params);
+}
+/**
+ * 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`)
+ * ```
+ */
+async function execute(sql, params) {
+    return getDatabaseService().execute(sql, params);
+}
+/**
+ * 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}`)
+ * ```
+ */
+async function insert(sql, params) {
+    return getDatabaseService().insert(sql, params);
+}
+/**
+ * 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
+ */
+async function transaction(queries, sharedParams) {
+    return getDatabaseService().transaction(queries, sharedParams);
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Database Module
+ *
+ * Provides a flexible database abstraction layer with pluggable adapters.
+ * Uses oxmysql by default for FiveM environments.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   DatabaseService,
+ *   initDatabase,
+ *   query,
+ *   single,
+ *   transaction,
+ * } from '@open-core/framework/server'
+ *
+ * // Option 1: Use standalone functions
+ * initDatabase()
+ * const users = await query<User>('SELECT * FROM users')
+ *
+ * // Option 2: Use DI
+ * @injectable()
+ * class UserService {
+ *   constructor(@inject(DatabaseService) private db: DatabaseService) {}
+ *
+ *   async findUser(id: number) {
+ *     return this.db.single<User>('SELECT * FROM users WHERE id = ?', [id])
+ *   }
+ * }
+ *
+ * // Option 3: Use transactions (specific format)
+ * const success = await transaction([
+ *   { query: 'INSERT INTO orders (user_id) VALUES (?)', values: [userId] },
+ *   { query: 'INSERT INTO order_items (order_id, product_id) VALUES (?, ?)', values: [orderId, productId] },
+ * ])
+ *
+ * // Option 4: Use transactions (shared params format)
+ * const success = await transaction(
+ *   [
+ *     'INSERT INTO orders (user_id) VALUES (@userid)',
+ *     'UPDATE users SET order_count = order_count + 1 WHERE id = @userid',
+ *   ],
+ *   { userid: userId }
+ * )
+ * ```
+ *
+ * @see https://coxdocs.dev/oxmysql/Functions/transaction
+ */
+export type { DatabaseConfig, ExecuteResult, InsertResult, TransactionQuery, TransactionQueryTuple, TransactionSharedParams, TransactionInput, DatabaseAdapterFactory, } from './types';
+export { DatabaseContract } from './database.contract';
+export { DatabaseService } from './database.service';
+export { getDatabaseService, initDatabase, query, single, scalar, execute, insert, transaction, } from './database.service';
+export { OxMySQLAdapter } from './adapters/oxmysql.adapter';

package/dist/server/database/index.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Database Module
+ *
+ * Provides a flexible database abstraction layer with pluggable adapters.
+ * Uses oxmysql by default for FiveM environments.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   DatabaseService,
+ *   initDatabase,
+ *   query,
+ *   single,
+ *   transaction,
+ * } from '@open-core/framework/server'
+ *
+ * // Option 1: Use standalone functions
+ * initDatabase()
+ * const users = await query<User>('SELECT * FROM users')
+ *
+ * // Option 2: Use DI
+ * @injectable()
+ * class UserService {
+ *   constructor(@inject(DatabaseService) private db: DatabaseService) {}
+ *
+ *   async findUser(id: number) {
+ *     return this.db.single<User>('SELECT * FROM users WHERE id = ?', [id])
+ *   }
+ * }
+ *
+ * // Option 3: Use transactions (specific format)
+ * const success = await transaction([
+ *   { query: 'INSERT INTO orders (user_id) VALUES (?)', values: [userId] },
+ *   { query: 'INSERT INTO order_items (order_id, product_id) VALUES (?, ?)', values: [orderId, productId] },
+ * ])
+ *
+ * // Option 4: Use transactions (shared params format)
+ * const success = await transaction(
+ *   [
+ *     'INSERT INTO orders (user_id) VALUES (@userid)',
+ *     'UPDATE users SET order_count = order_count + 1 WHERE id = @userid',
+ *   ],
+ *   { userid: userId }
+ * )
+ * ```
+ *
+ * @see https://coxdocs.dev/oxmysql/Functions/transaction
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxMySQLAdapter = exports.transaction = exports.insert = exports.execute = exports.scalar = exports.single = exports.query = exports.initDatabase = exports.getDatabaseService = exports.DatabaseService = exports.DatabaseContract = void 0;
+// Contract
+var database_contract_1 = require("./database.contract");
+Object.defineProperty(exports, "DatabaseContract", { enumerable: true, get: function () { return database_contract_1.DatabaseContract; } });
+// Service
+var database_service_1 = require("./database.service");
+Object.defineProperty(exports, "DatabaseService", { enumerable: true, get: function () { return database_service_1.DatabaseService; } });
+// Standalone functions
+var database_service_2 = require("./database.service");
+Object.defineProperty(exports, "getDatabaseService", { enumerable: true, get: function () { return database_service_2.getDatabaseService; } });
+Object.defineProperty(exports, "initDatabase", { enumerable: true, get: function () { return database_service_2.initDatabase; } });
+Object.defineProperty(exports, "query", { enumerable: true, get: function () { return database_service_2.query; } });
+Object.defineProperty(exports, "single", { enumerable: true, get: function () { return database_service_2.single; } });
+Object.defineProperty(exports, "scalar", { enumerable: true, get: function () { return database_service_2.scalar; } });
+Object.defineProperty(exports, "execute", { enumerable: true, get: function () { return database_service_2.execute; } });
+Object.defineProperty(exports, "insert", { enumerable: true, get: function () { return database_service_2.insert; } });
+Object.defineProperty(exports, "transaction", { enumerable: true, get: function () { return database_service_2.transaction; } });
+// Adapters
+var oxmysql_adapter_1 = require("./adapters/oxmysql.adapter");
+Object.defineProperty(exports, "OxMySQLAdapter", { enumerable: true, get: function () { return oxmysql_adapter_1.OxMySQLAdapter; } });

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

@@ -0,0 +1,67 @@
+/**
+ * Database Module Types
+ *
+ * Core types for the database abstraction layer.
+ */
+/**
+ * Result of an execute/update operation
+ */
+export interface ExecuteResult {
+    /** Number of rows affected by the operation */
+    affectedRows: number;
+}
+/**
+ * Result of an insert operation
+ */
+export interface InsertResult {
+    /** The auto-generated ID of the inserted row */
+    insertId: number;
+}
+/**
+ * Configuration for database adapters
+ */
+export interface DatabaseConfig {
+    /** Adapter identifier (e.g., 'oxmysql', 'mysql-async') */
+    adapter?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Connection timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Transaction query definition for oxmysql (specific format)
+ *
+ * @see https://coxdocs.dev/oxmysql/Functions/transaction
+ */
+export interface TransactionQuery {
+    query: string;
+    /** Parameter values for the query (oxmysql uses 'values') */
+    values?: any[];
+}
+/**
+ * Transaction query as tuple format [query, values]
+ */
+export type TransactionQueryTuple = [string, any[]?];
+/**
+ * Shared parameters for transaction queries (named parameters format)
+ *
+ * @example
+ * ```typescript
+ * const params: TransactionSharedParams = {
+ *   someid: 2,
+ *   somename: 'John Doe',
+ *   newname: 'John Notdoe'
+ * }
+ * ```
+ */
+export interface TransactionSharedParams {
+    [key: string]: any;
+}
+/**
+ * Transaction input - can be specific format, tuple format, or just strings
+ */
+export type TransactionInput = TransactionQuery[] | TransactionQueryTuple[] | string[];
+/**
+ * Database adapter factory function type
+ */
+export type DatabaseAdapterFactory = () => import('./database.contract').DatabaseContract;