@open-core/framework 0.1.0-alpha.1

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;

package/dist/server/database/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Database Module Types
+ *
+ * Core types for the database abstraction layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/server/database.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Database Module Re-export
+ *
+ * This file re-exports the database module for backwards compatibility.
+ * Prefer importing directly from '@open-core/framework/server' or './database/index'
+ */
+export * from './database/index';

package/dist/server/database.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Database Module Re-export
+ *
+ * This file re-exports the database module for backwards compatibility.
+ * Prefer importing directly from '@open-core/framework/server' or './database/index'
+ */
+__exportStar(require("./database/index"), exports);

package/dist/server/decorators/bind.d.ts

@@ -0,0 +1,2 @@
+export type BindingScope = 'singleton' | 'transient';
+export declare function Bind(scope?: BindingScope): (target: any) => void;

package/dist/server/decorators/bind.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bind = Bind;
+const tsyringe_1 = require("tsyringe");
+function Bind(scope = 'singleton') {
+    return function (target) {
+        (0, tsyringe_1.injectable)()(target);
+        if (scope === 'singleton') {
+            (0, tsyringe_1.singleton)()(target);
+        }
+        else {
+            (0, tsyringe_1.scoped)(tsyringe_1.Lifecycle.ResolutionScoped)(target);
+        }
+    };
+}

package/dist/server/decorators/command.d.ts

@@ -0,0 +1,49 @@
+import type { ClassConstructor } from '../../system/class-constructor';
+import type z from 'zod';
+import type { Player } from '../entities/player';
+export interface CommandConfig {
+    /**
+     * The command name (e.g. "revive", "deposit"), used in chat "/revive"
+     */
+    command: string;
+    /**
+     * The command description, maybe "/help revive"
+     */
+    description?: string;
+    /**
+     * The command usage, maybe "/revive <player>"
+     */
+    usage?: string;
+    /**
+     * The command schema, used to validate the arguments, validated with zod
+     * @example
+     * ```ts
+     * Server.Command({
+     *   command: 'revive',
+     *   schema: z.object({
+     *     player: z.string(),
+     *   }),
+     * })
+     * ```
+     */
+    schema?: z.ZodType;
+}
+export interface CommandMetadata extends CommandConfig {
+    methodName: string;
+    target: ClassConstructor;
+    paramTypes?: any;
+}
+type ServerCommandHandler = (player: Player, ...args: any[]) => any;
+/**
+ * Decorator used to mark a controller method as a command.
+ * This method will be registered and then executed by the command service.
+ * It will depend on the chat you have implemented following the dependency conventions.
+ *
+ * @param configOrName - The command name (e.g. "revive", "deposit")
+ * @validation zod schema
+ * @handlerSignature ```ts
+ *  (player: Server.Player, args: any[]) => any
+ * ```
+ */
+export declare function Command(configOrName: string | CommandConfig): <T extends ServerCommandHandler>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;
+export {};

package/dist/server/decorators/command.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Command = Command;
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+/**
+ * Decorator used to mark a controller method as a command.
+ * This method will be registered and then executed by the command service.
+ * It will depend on the chat you have implemented following the dependency conventions.
+ *
+ * @param configOrName - The command name (e.g. "revive", "deposit")
+ * @validation zod schema
+ * @handlerSignature ```ts
+ *  (player: Server.Player, args: any[]) => any
+ * ```
+ */
+function Command(configOrName) {
+    return (target, propertyKey, descriptor) => {
+        const config = typeof configOrName === 'string' ? { command: configOrName } : configOrName;
+        const paramTypes = Reflect.getMetadata('design:paramtypes', target, propertyKey);
+        const metadata = Object.assign(Object.assign({}, config), { methodName: propertyKey, target: target.constructor, paramTypes });
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.COMMAND, metadata, target, propertyKey);
+    };
+}

package/dist/server/decorators/controller.d.ts

@@ -0,0 +1,25 @@
+import type { ClassConstructor } from '../../system/class-constructor';
+export declare const serverControllerRegistry: ClassConstructor[];
+/**
+ * Class decorator used to mark a class as a Server Controller.
+ *
+ * This decorator performs the following actions:
+ * 1. Marks the class as `@injectable` (via tsyringe) for dependency injection.
+ * 2. Defines metadata identifying the class as a 'server' type controller.
+ * 3. Automatically adds the class constructor to the `serverControllerRegistry`.
+ *
+ * @returns The decorator function to apply to the class.
+ *
+ * @example
+ * ```ts
+ * import { Controller } from '@core/server/decorators'
+ *
+ * @Server.Controller()
+ * export class PlayerController {
+ *   constructor(private playerService: PlayerService) {
+ *     // Dependency injection works automatically here
+ *   }
+ * }
+ * ```
+ */
+export declare function Controller(): (target: ClassConstructor) => void;

package/dist/server/decorators/controller.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serverControllerRegistry = void 0;
+exports.Controller = Controller;
+const tsyringe_1 = require("tsyringe");
+const metadata_server_keys_1 = require("../system/metadata-server.keys");
+exports.serverControllerRegistry = [];
+/**
+ * Class decorator used to mark a class as a Server Controller.
+ *
+ * This decorator performs the following actions:
+ * 1. Marks the class as `@injectable` (via tsyringe) for dependency injection.
+ * 2. Defines metadata identifying the class as a 'server' type controller.
+ * 3. Automatically adds the class constructor to the `serverControllerRegistry`.
+ *
+ * @returns The decorator function to apply to the class.
+ *
+ * @example
+ * ```ts
+ * import { Controller } from '@core/server/decorators'
+ *
+ * @Server.Controller()
+ * export class PlayerController {
+ *   constructor(private playerService: PlayerService) {
+ *     // Dependency injection works automatically here
+ *   }
+ * }
+ * ```
+ */
+function Controller() {
+    return function (target) {
+        (0, tsyringe_1.injectable)()(target);
+        Reflect.defineMetadata(metadata_server_keys_1.METADATA_KEYS.CONTROLLER, { type: 'server' }, target);
+        exports.serverControllerRegistry.push(target);
+    };
+}