{"id":31039975,"url":"https://github.com/sure-development/sure_lib","last_synced_at":"2026-05-29T22:00:38.890Z","repository":{"id":313271703,"uuid":"1050765885","full_name":"Sure-Development/sure_lib","owner":"Sure-Development","description":"Open Source - Library that will help your manage your resource or handle your script as a controller","archived":false,"fork":false,"pushed_at":"2026-05-29T19:04:03.000Z","size":480,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T19:17:46.433Z","etag":null,"topics":["esx","fivem","lua","overextended"],"latest_commit_sha":null,"homepage":"https://docs.sure-developer.com","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sure-Development.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-04T22:53:10.000Z","updated_at":"2026-05-29T19:03:56.000Z","dependencies_parsed_at":"2025-09-05T00:25:57.949Z","dependency_job_id":"4066c9fa-ef1d-434e-b077-3b0c1be1bce3","html_url":"https://github.com/Sure-Development/sure_lib","commit_stats":null,"previous_names":["sure-development/sure_lib"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/Sure-Development/sure_lib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sure-Development%2Fsure_lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sure-Development%2Fsure_lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sure-Development%2Fsure_lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sure-Development%2Fsure_lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sure-Development","download_url":"https://codeload.github.com/Sure-Development/sure_lib/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sure-Development%2Fsure_lib/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33672125,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esx","fivem","lua","overextended"],"created_at":"2025-09-14T08:02:08.317Z","updated_at":"2026-05-29T22:00:38.883Z","avatar_url":"https://github.com/Sure-Development.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sure_lib\n\nModern-first Lua 5.4 utility library for FiveM resources.\n\n## Features\n\n- ESX client/server helpers\n- Shared cooldown state — by position **or** by identifier\n- Runtime schema validation\n- Reactive state tracking (`state`, `effect` with disposers, `computed`)\n- Hook pipeline: validated event handlers with composable middleware\n- Namespaced logger with configurable levels\n- ox_lib keybind wrapper with idempotent registration\n- Lua-driven NUI rendering with `lui`, hybrid declarative node trees, motion, shadcn-like components, theme overrides, and runtime utility styles\n- Text and Iconify-powered LUI icons through ergonomic Lua props\n- Database module with `count`, `select`, `orderBy`, `limit/offset`, `upsert`, `bulkInsert`, `transaction`, and ALTER-aware `db push`\n- Console diagnostics via `\u003cresource\u003e:doctor`\n- Drop-in Language Server type stubs in `library/`\n\n## Dependencies\n\n- [ox_lib](https://github.com/overextended/ox_lib)\n- [es_extended](https://github.com/esx-framework/esx_core)\n\n## Loading\n\nAdd the shared loader to resources that use this library:\n\n```lua\nshared_script '@sure_lib/init.lua'\n```\n\nModules are loaded through `sure.getModule(moduleName)`.\n\nAvailable modules: `esx`, `player`, `cooldown`, `validator`, `track`, `hook`, `log`, `slice`, `config`, `spawn`, `keybind`, `db`, `lui`.\n\n\u003e `listener` was renamed to `hook` and now supports a `use(middleware)` pipeline and explicit `dispatch` / `dispatchClient` / `dispatchServer` verbs.\n\nOther resources can inject middleware into a hook through exports:\n\n```lua\n-- from another resource that depends on sure_lib\nlocal hook = sure.getModule('hook')\n\nhook:injectResource('resourceWithHook', 'hookName', function(ctx)\n  ctx.args[1] = ctx.args[1]:upper() -- mutate\n  -- ctx.cancelled = true            -- short-circuit\nend)\n```\n\nThe target resource must be started before `injectResource` runs.\n\n## Slice — declarative feature bundle\n\n`slice` packages state, actions, event handlers, and lifecycle hooks for a feature in one declarative spec. Every name is auto-prefixed with the slice name so events, commands, and logs stay consistent across resources.\n\n```lua\nlocal slice = sure.getModule('slice')\n\nreturn slice 'duty' {\n  state = {\n    onDuty = false,\n    streak = 0,\n  },\n\n  actions = {\n    toggle = function(s)\n      s.state.onDuty = not s.state.onDuty\n    end,\n  },\n\n  net = {\n    sync = function(s, value)\n      s.state.onDuty = value\n    end,\n  },\n\n  watch = {\n    onDuty = function(s, value)\n      s.log.info('changed to ' .. tostring(value))\n      s:emit('changed', value)\n    end,\n  },\n\n  commands = {\n    print = function(s)\n      print(json.encode(s:snapshot()))\n    end,\n  },\n\n  onLoad = function(s)\n    s.log.info('ready')\n  end,\n}\n```\n\n- `state` becomes a reactive proxy; writing triggers `watch` and `subscribe` handlers.\n- `actions` are pure mutators exposed as `slice.actions.\u003cname\u003e(...)`.\n- `on` / `net` register listeners against `'\u003csliceName\u003e:\u003ceventName\u003e'`.\n- `emit` / `emitClient` / `emitServer` auto-prefix the same way.\n- `commands` registers `\u003csliceName\u003e:\u003ccommandName\u003e` console commands.\n- `onLoad` / `onUnload` only fire for the current resource.\n- `every` spawns a single scheduling thread per slice that fires each interval handler when its window elapses, sleeping only until the next due interval.\n- Auto-generates a `setX` action for every state key. Custom actions with the same name take precedence.\n- `slice:transaction(fn)` batches mutations so each watcher fires once with the net change.\n- `netSync = { stateKey = 'sender' | 'receiver' | { direction, scope, diff } }` mirrors state across server/client. Scopes are managed through `slice:scope(name)` with `add` / `remove` / `list` / `contains` accepting both player ids and ESX identifiers. Setting `diff = true` switches the wire format to a keyed-array patch (`{ added, removed, changed }`) and skips emits that produce an empty patch. Removing a player from a scope emits `{ cleared = true }` to that player for every diff field, which clears the receiver's mirror and lets `ref` cleanup tear down world entities.\n\n### Keyed reactive list with `slice:ref`\n\n`slice:ref(stateKey, fn)` watches an array of items, calls `fn(item, index)` for every new item, and re-runs only when an individual item's content changes (deep equal). Removed items run their cleanup function; unchanged items are left alone. Duplicate `key` values raise an error.\n\n```lua\nreturn slice 'world' {\n  state = {\n    entities = {\n      { key = 'guard-1', entity = 0, coords = vector3(0, 0, 0) },\n    },\n  },\n\n  onLoad = function(s)\n    s:ref('entities', function(item)\n      local ped = createGuard(item.coords)\n\n      return function()\n        DeleteEntity(ped)\n      end\n    end)\n  end,\n}\n```\n\n- Each item must expose a `key` field (`string` or `number`).\n- Return a function from `fn` to register a cleanup; omit the return for no-op cleanup.\n- `ref` returns a `dispose` function that unmounts every active item and stops watching. Every active ref also auto-disposes on `onResourceStop` for the current resource, after `spec.onUnload` runs.\n- Array mutation helpers `slice:push(stateKey, item)`, `slice:patch(stateKey, itemKey, partial)`, and `slice:removeBy(stateKey, predicate)` filter + reassign the array so watchers and netSync diffs fire correctly without hand-written loops.\n- `slice:interact(stateKey, spec)` (client only) bundles `slice:ref` with `sure.spawn` and `lib.points.new`: spawns the world entity from `spec.spawn`, creates a proximity point, wires `onEnter` / `onExit` / `nearby` callbacks with `(slice, item, ctx)`, and cleans up the entity + point on unmount. Prompts/UI are left to the user.\n- The watcher fires when the array reference changes — assign a new table to `state.\u003ckey\u003e` to trigger reconciliation.\n\nFor Lua UI, point your resource NUI page at the bundled renderer:\n\n```lua\nui_page 'https://cfx-nui-sure_lib/web/lui/index.html'\n```\n\nEnable LUI debug traces with `?luiDebug=1` or `localStorage.setItem('sure:lui:debug', '1')` in NUI Devtools.\n\n`lui` supports both nested callback builders and declarative node factories, so larger interfaces can be split into small Lua component functions.\n\n## Language Server types\n\nThe repo ships LLS stubs in `library/`. Add the folder to your `.luarc.json`:\n\n```json\n{\n  \"runtime.version\": \"Lua 5.4\",\n  \"workspace.library\": [\"../sure_lib/library\"],\n  \"diagnostics.globals\": [\"sure\", \"lib\", \"cache\", \"exports\"]\n}\n```\n\nSee `library/README.md` for details.\n\n## Console commands\n\n- `\u003cresource\u003e:db push \u003cschemaName\u003e` — `CREATE TABLE IF NOT EXISTS` or `ALTER TABLE ... ADD COLUMN` for new fields.\n- `\u003cresource\u003e:db pull \u003ctableName\u003e` — write a schema file from a live table.\n- `sure_lib:doctor` — verifies that `ox_lib`, `es_extended`, `oxmysql`, and the required `lib.*` helpers are reachable.\n\nDocumentation: https://docs.sure-developer.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsure-development%2Fsure_lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsure-development%2Fsure_lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsure-development%2Fsure_lib/lists"}