feat(test): add lib.test unit-testing framework

.github/workflows/release.yml

@@ -3,15 +3,15 @@ name: Create release
 on:
   push:
     tags:
-      - 'v*.*.*'
+      - "v*.*.*"
 
 permissions:
   id-token: write # Required for OIDC
   contents: write
 
 jobs:
   create-release:
-    if: github.actor_id != 210085057
+    if: github.actor_id != 278903378
     runs-on: ubuntu-latest
     steps:
       - name: Install zip
@@ -22,7 +22,6 @@ jobs:
         with:
           bun-version: latest
 
-
       - name: Generate GitHub App token
         id: app_token
         uses: tibdex/github-app-token@v2
@@ -37,6 +36,10 @@ jobs:
           ref: ${{ github.event.repository.default_branch }}
           token: ${{ steps.app_token.outputs.token }}
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
 
       - name: Bump package version
         run: bun run .github/actions/bump-package-version.js
@@ -54,8 +57,7 @@ jobs:
           add: '["fxmanifest.lua", "package/package.json"]'
           push: true
           default_author: github_actions
-          message: 'chore: bump version to ${{ github.ref_name }}'
-
+          message: "chore: bump version to ${{ github.ref_name }}"
 
       - name: Install package dependencies
         run: bun install --frozen-lockfile
@@ -69,7 +71,6 @@ jobs:
         run: bun run build
         working-directory: web
 
-
       - name: Bundle files
         run: |
           mkdir -p ./temp/ox_lib/web
@@ -78,8 +79,12 @@ jobs:
           cp -r ./web/build ./temp/ox_lib/web/
           cd ./temp && zip -r ../ox_lib.zip ./ox_lib
 
+      - name: Publish package to npm registry
+        run: npm publish --access public
+        working-directory: package
+
       - name: Create release
-        uses: 'marvinpinto/action-automatic-releases@v1.2.1'
+        uses: "marvinpinto/action-automatic-releases@v1.2.1"
         with:
           repo_token: ${{ secrets.GITHUB_TOKEN }}
           prerelease: false
@@ -89,13 +94,3 @@ jobs:
         uses: EndBug/latest-tag@v1
         with:
           ref: ${{ github.ref_name }}
-
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '24'
-
-      - name: Publish package to npm registry
-        run: npm publish --access public
-        working-directory: package

CONTRIBUTING.md

@@ -6,7 +6,7 @@ We welcome you to contribute to our projects, whether reporting a bug, suggestin
 
 ### Search for existing issues
 
-Before creating a new issue, please search existing [issues](https://github.com/communityox/ox_lib/issues) to see if it has already been reported.
+Before creating a new issue, please search existing [issues](https://github.com/overextended/ox_lib/issues) to see if it has already been reported.
 
 ### Add details to existing issues
 
@@ -51,7 +51,7 @@ Pull requests that do not contribute meaningful improvements to the project's st
 - Fork the repository and, optionally, create a new branch for your changes.
 - If applicable, include example code to demonstrate your changes.
 - Ensure your code's style is consistent with the project, e.g. uses the same indentation and string quotations.
-- If you have modified or introduced new APIs, open a pull request to our [documentation](https://github.com/communityox/docs). We will not accept undocumented code.
+- If you have modified or introduced new APIs, open a pull request to our [documentation](https://github.com/overextended/docs). We will not accept undocumented code.
 
 ## Contributor License Agreement
 

README.md

@@ -2,10 +2,10 @@
 
 A FiveM library and resource implementing reusable modules, methods, and UI elements.
 
-![](https://img.shields.io/github/downloads/communityox/ox_lib/total?logo=github)
-![](https://img.shields.io/github/downloads/communityox/ox_lib/latest/total?logo=github)
-![](https://img.shields.io/github/contributors/communityox/ox_lib?logo=github)
-![](https://img.shields.io/github/v/release/communityox/ox_lib?logo=github)
+![](https://img.shields.io/github/downloads/overextended/ox_lib/total?logo=github)
+![](https://img.shields.io/github/downloads/overextended/ox_lib/latest/total?logo=github)
+![](https://img.shields.io/github/contributors/overextended/ox_lib?logo=github)
+![](https://img.shields.io/github/v/release/overextended/ox_lib?logo=github)
 
 For guidelines to contributing to the project, and to see our Contributor License Agreement, see [CONTRIBUTING.md](./CONTRIBUTING.md)
 
@@ -14,19 +14,19 @@ For additional legal notices, refer to [NOTICE.md](./NOTICE.md).
 
 ## 📚 Documentation
 
-https://coxdocs.dev/ox_lib
+https://overextended.dev/ox_lib
 
 ## 💾 Download
 
-https://github.com/communityox/ox_lib/releases/latest/download/ox_lib.zip
+https://github.com/overextended/ox_lib/releases/latest/download/ox_lib.zip
 
 ## 📦 npm package
 
-https://www.npmjs.com/package/@communityox/ox_lib
+https://www.npmjs.com/package/@overextended/ox_lib
 
 ## 🖥️ Lua Language Server
 
 - Install [Lua Language Server](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) to ease development with annotations, type checking, diagnostics, and more.
-- Install [CfxLua IntelliSense](https://marketplace.visualstudio.com/items?itemName=communityox.cfxlua-vscode-cox) to add natives and cfxlua runtime declarations to LLS.
+- Install [CfxLua IntelliSense](https://marketplace.visualstudio.com/items?itemName=overextended.cfxlua-vscode-cox) to add natives and cfxlua runtime declarations to LLS.
 - You can load ox_lib into your global development environment by modifying workspace/user settings "Lua.workspace.library" with the resource path.
   - e.g. "c:/fxserver/resources/ox_lib"

fxmanifest.lua

@@ -6,9 +6,9 @@ rdr3_warning 'I acknowledge that this is a prerelease build of RedM, and I am aw
 
 name 'ox_lib'
 author 'Overextended'
-version '3.32.3'
+version '3.32.6'
 license 'LGPL-3.0-or-later'
-repository 'https://github.com/communityox/ox_lib'
+repository 'https://github.com/overextended/ox_lib'
 description 'A library of shared functions to utilise in other resources.'
 
 dependencies {
@@ -43,6 +43,7 @@ client_scripts {
 server_scripts {
     'imports/callback/server.lua',
     'imports/getFilesInDirectory/server.lua',
+    'imports/test/server.lua',
     'resource/**/server.lua',
     'resource/**/server/*.lua',
 }

imports/getFilesInDirectory/server.lua

@@ -6,40 +6,74 @@
     Copyright © 2025 Linden <https://github.com/thelindat>
 ]]
 
----@param path string
----@param pattern string
----@return table string[]
+---List files in a directory inside a resource. Returns paths relative to
+---`path` so each entry can be appended back to it for further use.
+---
+---@param path string  resource-relative path, optionally `@resource/subdir` for cross-resource
+---@param pattern string  Lua pattern matched against each returned path
+---@param recursive? boolean  walk subdirectories (default false)
+---@return string[] files
 ---@return integer fileCount
-function lib.getFilesInDirectory(path, pattern)
+function lib.getFilesInDirectory(path, pattern, recursive)
     local resource = cache.resource
 
     if path:find('^@') then
         resource = path:gsub('^@(.-)/.+', '%1')
         path = path:sub(#resource + 3)
     end
 
+    -- os.getenv('OS') isn't reliable across all FXServer environments. The
+    -- resource path itself tells us: drive letter or backslash means Windows.
+    local rawPath = GetResourcePath(resource)
+    local windows = rawPath:find('\\', 1, true) ~= nil or rawPath:match('^%a:') ~= nil
+    local resourcePath = rawPath:gsub('\\', '/'):gsub('//', '/')
+    local relRoot = path:gsub('\\', '/'):gsub('/$', ''):gsub('^/', '')
+    local fullDir = ('%s/%s'):format(resourcePath, relRoot):gsub('//', '/'):gsub('/$', '')
+
+    local cmd
+    if recursive then
+        if windows then
+            cmd = ('dir "%s" /b /s /a-d 2>&1'):format(fullDir:gsub('/', '\\'))
+        else
+            cmd = ('find "%s" -type f 2>&1'):format(fullDir)
+        end
+    else
+        if windows then
+            cmd = ('dir "%s" /b 2>&1'):format(fullDir:gsub('/', '\\'))
+        else
+            cmd = ('ls "%s" 2>&1'):format(fullDir)
+        end
+    end
+
+    local pipe = io.popen(cmd)
+    if not pipe then return {}, 0 end
+
     local files = {}
     local fileCount = 0
-    local windows = string.match(os.getenv('OS') or '', 'Windows')
-    local command = ('%s%s%s'):format(
-        windows and 'dir "' or 'ls "',
-        (GetResourcePath(resource):gsub('//', '/') .. '/' .. path):gsub('\\', '/'),
-        windows and '/" /b' or '/"'
-    )
-
-    local dir = io.popen(command)
-
-    if dir then
-        for line in dir:lines() do
-            if line:match(pattern) then
-                fileCount += 1
-                files[fileCount] = line
+    local prefix = fullDir .. '/'
+
+    for line in pipe:lines() do
+        -- Windows io.popen leaves trailing \r, which breaks end-of-string patterns.
+        line = line:gsub('[\r\n]+$', '')
+        if line ~= '' and line ~= '.' and line ~= '..' then
+            local normalized = line:gsub('\\', '/')
+            -- Some shells return full paths (Windows `dir /s`, unix `find`),
+            -- others return bare filenames. Slash presence tells us which.
+            local rel
+            if normalized:find('/', 1, true) then
+                rel = normalized:sub(#prefix + 1)
+                if rel:sub(1, 1) == '/' then rel = rel:sub(2) end
+            else
+                rel = normalized
+            end
+            if rel ~= '' and rel:match(pattern) then
+                fileCount = fileCount + 1
+                files[fileCount] = rel
             end
         end
-
-        dir:close()
     end
 
+    pipe:close()
     return files, fileCount
 end
 

imports/locale/shared.lua

@@ -59,7 +59,7 @@ end
 
 local table = lib.table
 
----Loads the ox_lib locale module. Prefer using fxmanifest instead (see [docs](https://coxdocs.dev/ox_lib#usage)).
+---Loads the ox_lib locale module. Prefer using fxmanifest instead (see [docs](https://overextended.dev/ox_lib#usage)).
 ---@param key? string
 function lib.locale(key)
     local lang = key or lib.getLocaleKey()