Merge pull request #4 from AtomicGmod/develop

feat(mysql): add mysql support, update readme, add code style, etc

Author: smokingplaya

.gitignore

@@ -1,3 +1,4 @@
 changelog.md
 puff.yml
+docker-compose.yml
 .env

CODE_STYLE.md

@@ -0,0 +1,64 @@
+# Atomic Framework — Code Style Guide
+
+This document defines the official coding conventions for **Atomic Framework** and all packages built under it.
+The goal is simple — **clean, readable, and predictable Lua code**.
+
+---
+
+## 🧱 General Style
+
+- **Indentation:** 2 spaces (no tabs)
+- **Line length:** ~100 characters max
+- **Encoding:** UTF-8 (no BOM)
+- **Trailing whitespace:** none
+- **End of file:** one empty line
+- **Comments:** short, factual, no essays
+
+---
+
+## 📦 Naming Conventions
+
+| Type | Style | Example |
+|------|--------|---------|
+| Variables / locals | `camelCase` | `playerData`, `configTable` |
+| Functions | `camelCase` | `loadPackage`, `registerCommand` |
+| Classes / Objects | `PascalCase` | `Package`, `NetworkService` |
+| Constants | `ALL_CAPS` | `DEFAULT_TIMEOUT` |
+| Private internals | Prefix `_` | `_resolve_dependencies` |
+| Package namespaces | Lowercase, dot-separated | `atomic.config`, `atomic.command` |
+
+## 🧠 OOP Conventions
+
+- Use `:` for instance methods, `.` for static functions.
+- Avoid global variables — everything should live under a namespace (`Atomic.*`).
+- Keep internal state private whenever possible.
+- Don’t mutate other modules’ tables directly.
+- Favor composition over inheritance when possible.
+
+---
+
+## 🧩 Documentation & Comments
+
+- Use `--` for single-line comments and `--[[ ... ]]` for multi-line blocks.
+- Document **every public function** — parameters and return values.
+- Keep comment style consistent and concise.
+
+## 🚫 Don’ts
+
+- ❌ Do **not** use global variables unless absolutely necessary.
+- ❌ Do **not** rely on random metatable hacks or implicit magic.
+- ❌ Do **not** use inconsistent indentation or mixed styles.
+
+---
+
+## 🧩 Commits & Versioning
+
+Use clear and conventional commit prefixes:
+
+| Type | Description | Example |
+|------|------------|---------|
+| `feat:` | New feature | `feat(command): add argument parser` |
+| `fix:` | Bug fix | `fix(config): prevent nil index in mysql adapter` |
+| `refactor:` | Code improvement | `refactor(package): simplify dependency resolver` |
+| `docs:` | Documentation changes | `docs(readme): update installation guide` |
+| `chore:` | Non-code tasks | `chore: cleanup old debug prints` |

README.md

@@ -1,22 +1,48 @@
 # Atomic Framework
-No more magic
-
-## To Do
-### Packages
-- [x] Hooks system
-- [x] Commands system
-- [x] Package unloading
-- [ ] Config system (with value saving in database)
-
-### Libraries
-- [x] ``atomic.class``
-- [ ] ``atomic.database``
-- [ ] ``atomic.config``
-- [ ] ``atomic.net`` (autumnnet as base)
-- [ ] ``atomic.web``
-- [x] ``atomic.command``
-  - [ ] Command parser
-- [x] ``atomic.bind``
-
-### Misc
-- [ ] Normal documentation everywhere
+**No more magic.**
+
+Atomic is a flexible, OOP-driven framework for building Garry’s Mod addons and gamemodes with a clean, modular architecture.
+Each **package** is a self-contained unit — just like an addon — with built-in dependency management and powerful libraries for writing structured, maintainable Lua code.
+
+---
+
+## Features
+- Modular **package-based** architecture
+- Built-in **dependency resolution**
+- Flexible **OOP** utilities and core libraries
+- Expandable with **atomic.\*** modules (config, command, network, etc.)
+- Designed for both **addons** and **gamemodes**
+
+---
+
+## Documentation
+Full documentation, API references, and examples are available here:
+👉 **[Atomic Framework Wiki](https://github.com/AtomicGmod/atomic-framework/wiki)**
+
+---
+
+## Installation
+Optional dependencies:
+- For `atomic.mysql` → install [MySQLOO](https://github.com/FredyH/MySQLOO)
+- For `atomic.git` → install [gm_git](https://github.com/AtomicGmod/gm_git)
+
+Simply place the framework in your `addons/` folder.
+Atomic will automatically load and register available packages.
+
+---
+
+## Contributing
+We welcome all contributions — bug fixes, improvements, and new libraries are appreciated.
+Please follow the [project’s coding style](./CODE_STYLE.md) and submit a pull request through GitHub.
+Discussions and proposals are also encouraged in the issue tracker.
+
+---
+
+## Roadmap
+See [To Do](#) or the project’s issue tracker for current development progress.
+
+---
+
+## License
+This project is licensed under the **GNU General Public License v3.0**.
+See the [LICENSE](./LICENSE) file for more details.

lua/atomic/libraries/git.lua

@@ -1,33 +1,30 @@
-if (not util.IsBinaryModuleInstalled("atomic_git")) then
-  atomic.log:warn("Binary module `atomic_git` isn't installed!")
-
+if (not util.IsBinaryModuleInstalled("git")) then
   return
 end
 
 ---@class Atomic.Git.Folder
 ---@field folder string
 
-if (not atomic.git) then
-  require("atomic_git")
-
-  if (not atomic.git) then
-  	return
-  end
+if (not git) then
+  require("git")
 end
 
+atomic.git = atomic.git or {
+  logger = atomic.logger.new("git")
+}
 
 ---@type table<string, fun(name: string): Atomic.Git.Folder>
 local openers = {
   root = function()
-    return atomic.git.open("garrysmod")
+    return git.open("garrysmod")
   end,
 
   gamemode = function(name)
-    return atomic.git.open("garrysmod/gamemodes/" .. name)
+    return git.open("garrysmod/gamemodes/" .. name)
   end,
 
   addon = function(name)
-    return atomic.git.open("garrysmod/addons/" .. name)
+    return git.open("garrysmod/addons/" .. name)
   end
 }
 
@@ -58,7 +55,8 @@ function atomic.git.from(kind, name)
   local folder, err = opener(name)
 
   if (not folder) then
-    return atomic.git.logger:err("failed to open git repository: %s", tostring(err))
+    local who = name and kind .. " " .. name or kind
+    return atomic.git.logger:err("failed to open git repository for %s: %s", who, tostring(err))
   end
 
   atomic.git._storage[kind][name] = folder

lua/atomic/libraries/mysql.lua

@@ -0,0 +1,117 @@
+if (not util.IsBinaryModuleInstalled("mysqloo")) then
+	return
+end
+
+if (not mysqloo) then
+  require("mysqloo")
+end
+
+atomic.mysql = atomic.mysql or {
+  logger = atomic.logger.new("mysql")
+}
+
+local logger = atomic.mysql.logger
+
+file.CreateDir("atomic/mysql")
+
+if (file.Size("data/atomic/mysql/credentials.json", "GAME") <= 0) then
+  local defaultJson = [[{
+    "host": "127.0.0.1",
+    "user": "root",
+    "password": "root",
+    "table": "gmod",
+    "port": 3306
+}]];
+
+  file.Write("atomic/mysql/credentials.json", defaultJson)
+	logger:warn("The `credentials.json` file has just been created in `data/atomic/mysql/` folder. To work with MySQL, fill in the database connection credentials in this file.")
+end
+
+---@class Atomic.MySQL.Credentials
+---@field host string
+---@field user string
+---@field password string
+---@field table string
+---@field port? integer
+local credentials = util.JSONToTable(file.Read("atomic/mysql/credentials.json"))
+local autoconnect = CreateConVar("atomic_mysql_autoconnect", "1", {FCVAR_PROTECTED, FCVAR_ARCHIVE}, "Should the connection to MySQL be automatic?")
+
+if (autoconnect:GetBool() and not atomic.mysql._database) then
+  atomic.mysql._database = mysqloo.connect(
+    credentials.host,
+    credentials.user,
+    credentials.password,
+    credentials.table,
+    credentials.port or 3306
+  )
+
+  atomic.mysql._database.onConnected = function(_)
+    logger:info("Successfully connected to the MySQL database")
+  end
+
+  atomic.mysql._database.onConnectionFailed = function(_, err)
+    logger:err("Error while connecting to database: %s", err)
+  end
+
+  atomic.mysql._database.onError = function(_, err, sql)
+    logger:debug("Error executing query `%s`: %s", sql, err)
+  end
+
+  atomic.mysql._database:connect()
+end
+
+local prepareTypes = {
+  string = "setString",
+  boolean = "setBoolean",
+  number = "setNumber"
+}
+
+--- Returns a raw database object
+---@see https://github.com/FredyH/MySQLOO/
+function atomic.mysql.getDatabase()
+  return atomic.mysql._database
+end
+
+--- Checks whether the connection to the database is active.
+---@return boolean
+function atomic.mysql.isConnected()
+  return atomic.mysql._database and atomic.mysql._database:ping()
+end
+
+--- Executes a query to the database, and escaping the arguments
+---
+--- ```lua
+--- local data = atomic.mysqlo.query("SELECT * from users WHERE steamid=?;", Player(1):SteamID())
+--- ```
+---@async
+---@param query string
+---@vararg ...?
+---@return table, string?
+function atomic.mysql.query(query, ...)
+  local co = coroutine.get()
+
+  local result, error
+  local prepared = atomic.mysql._database:prepare(query)
+  prepared.onSuccess = function(_, data)
+    result = data
+
+    coroutine.resume(co)
+  end
+
+  prepared.onError = function(_, err)
+    error = err
+
+    coroutine.resume(co)
+  end
+
+  for index, value in ipairs({...}) do
+    local method = prepareTypes[type(value)] or prepareTypes.string
+    prepared[method](prepared, index, value)
+  end
+
+  prepared:start()
+
+  coroutine.yield()
+
+  return result, error
+end

lua/atomic/utils/coroutine.lua

@@ -2,4 +2,19 @@
 ---@return boolean
 function coroutine.start(fun)
   return coroutine.resume(coroutine.create(fun))
+end
+
+--- Checks whether the current function is within a coroutine or not, and if not, throws an error.
+---
+--- ```lua
+--- ```
+---@return thread
+function coroutine.get()
+  local co = coroutine.running()
+
+  if (not co) then
+    error("attempt to use an asynchronous function outside of a coroutine")
+  end
+
+  return co
 end

lua/autorun/atomic_autorun.lua

@@ -1,8 +1,8 @@
 atomic = {
   meta = {
     author = "smokingplaya",
-    version_name = "Feijoa",
-    version = "0.2.1",
+    version_name = "Ackee",
+    version = "0.3.0",
   }
 }
 
@@ -31,6 +31,7 @@ shared("atomic/utils/semver.lua")
 shared("atomic/libraries/bind.lua")
 client("atomic/libraries/web.lua")
 server("atomic/libraries/command.lua")
+server("atomic/libraries/mysql.lua")
 server("atomic/libraries/git.lua")
 -- package loading should be latest
 shared("atomic/libraries/package/class.lua")