API Reference

API Reference

This page documents the public surface of LibCodex-1.0. For the higher-level "what is this" view, see Architecture. For the full module list, see Module Reference.

Entry point

local LC = LibStub("LibCodex-1.0")

The returned table is the library object. All library-level methods are members of this table and are called with the colon syntax (LC:NPCs(), LC:LoadModule("Quests"), etc.).

Library methods

Module access

LC:GetModule(name) -> collection | nil Look up a module by its registered name. Returns nil if not registered. Most consumers prefer the typed accessors below.

LC:NPCs(), LC:Items(), LC:Quests(), ... etc. One-line typed accessors, one per module. LC:NPCs() is just LC:GetModule("NPCs"). See Module Reference for the full list.

LC:Reputations() (deprecated) Alias for LC:Factions(). Reputations were merged into the unified Factions module. Filter the result with the kind field if you only want the rep-faction subset.

LoadOnDemand control

LC:LoadModule(moduleName) -> bool Force-load the LoadOnDemand sibling addon for a module (LibCodex-1.0-<moduleName>). Returns true if the addon is now available, false if it's missing or disabled. Idempotent: subsequent calls hit a cache.

You usually don't need to call this — collection :Get and :Search auto-load on first miss. Use it when you want to pre-warm a module before opening a UI panel.

LC:IsModuleLoaded(moduleName) -> bool Returns true if the LoD sibling addon for that module has loaded.

Adapters

LC:RegisterAdapter(name, fn) Register a runtime adapter. fn is called once at PLAYER_LOGIN with the library object as its argument: fn(LC). Adapters that need ongoing data capture should register their own event hooks from inside fn.

LC:RegisterAdapter("MyAddon.Quests", function(LC)
    -- runs once at PLAYER_LOGIN
    LC:Quests():Add({ id = 12345, label = "Custom quest", sources = {"MyAddon"} })
end)

LC:RunAdapters() Run every adapter that hasn't run yet. Called automatically at PLAYER_LOGIN. Adapters that error are logged and not retried.

Diagnostics

LC:CountAll() -> { [moduleName] = count } Returns a map of module name to entry count for every registered module.

LC:VersionString() -> string Returns a one-line human-readable version string: LibCodex-1.0 v7 (modules:73 adapters:1).

Collection API

Every typed accessor returns a collection object. All collections share the same shape (built by Modules/Common.lua).

Lookup

collection:Get(key) -> entry | nil Look up by exact key. The default keyField is "id". On a miss, this triggers a one-shot load of the LoD sibling addon for this module if available.

local npc = LC:NPCs():Get(207516)
if npc then print(npc.label) end

collection:Search(query, opts) -> array<entry> Substring search across the module's configured search fields. Multi-token queries split on whitespace and AND together ("rune cloth" matches entries containing both substrings).

The opts table accepts:

• filter = function(entry) -> bool — custom predicate run on every candidate.
• Any other key is treated as an exact field-equality filter: { side = "A", mapID = 2248 }.

for _, hit in ipairs(LC:Items():Search("rune", { quality = 4 })) do
    print(hit.id, hit.label)
end

:Search walks lazy bundled rows without materializing non-matches, so even on a 400k-row module the cost is a substring test per row, not a full table allocation.

Iteration

collection:All() -> iterator Returns a coroutine iterator yielding (key, entry) pairs for keyed entries and (nil, entry) for keyless extras. Materializes pending lazy chunks first.

for key, entry in LC:Quests():All() do
    -- key may be nil for keyless extras
end

collection:AllArray() -> array<entry> Same data as :All but returned as a flat array. Useful when you don't want a coroutine.

collection:AllRaw() -> { [key] = entry } Returns the raw key->entry map. Used by SavedVariables persistence; consumers usually want :AllArray or :All.

Mutation

**collection:Add(entry) -> entry** Add an entry, or merge into an existing one if its key already exists. Returns the resulting entry. Entries with no key field are stored in a keyless extras list (still discoverable via :Searchand:All`).

Merge rules (see Architecture: Source provenance and locked fields):

• Existing truthy fields stick unless incoming._overwrite[fieldName] = true.
• Missing fields are filled from the incoming entry.
• sources arrays are unioned.
• Fields locked by _handcrafted = true or listed in _locked are never overwritten.

collection:Remove(key) -> bool Remove an entry by key. Returns true if something was removed.

collection:Clear() Remove all entries from the collection. Does not affect SavedVariables until PLAYER_LOGOUT.

Counting and metadata

collection:Count() -> integer Total entries including unmaterialized lazy chunks. This forces materialization of any lazy chunks. If you want a cheap "approximate count" without paying that cost, call it before any :Get / :Search / :All.

collection:Name() -> string The module's registered name (e.g., "NPCs", "Items").

collection:ExpandAll() -> integer Force-materialize every lazy-backed entry into the dict store. Returns the number of entries materialized. Use when a consumer needs full iteration in non-:All form, or before passing the collection to code that doesn't understand lazy indexes.

Entry shape

Catalog entries are plain Lua tables. Common fields:

Field	Type	Notes
id	number	Default key field. Unique within a module.
label	string	Display name. The default search field.
sources	array of string	Provenance tags: "bundled", "savedvars", custom adapter names.
_handcrafted	bool	Marks every field as locked against future merges.
_locked	array of string	List of field names locked against future merges.
_overwrite	table	On the incoming entry only: { fieldName = true } forces overwrite of a specific field (unless locked).

Module-specific fields vary. Check Modules/Catalog/<Module>.lua or Modules/Enums/<Module>.lua for the searchFields and normalize configuration that defines what each module stores.

Globals

The library exposes a _G.LibCodex handle for legacy callsites, but LibStub("LibCodex-1.0") is the supported entry point. Don't depend on the global.

LibCodexDB is the SavedVariables table. Treat it as read-only from consumer code; the library owns it.