Skip to content

l0.DependencyControl.ConfigHandler

ConfigHandler = require "l0.DependencyControl.ConfigHandler"

local ConfigHandler = require("l0.DependencyControl.ConfigHandler")

ConfigHandler

JSON-backed configuration manager with cooperative cross-script locking. Manages one JSON file per instance. Use ConfigView (via getView or ConfigView.get) to access specific hives (nested sections) of the config.

Constructor 

configHandler = ConfigHandler filePath, logger, schemaOpts

local configHandler = ConfigHandler(filePath, logger, schemaOpts)

Creates a ConfigHandler for the given file. Does not load from disk.

param type description
filePath? string
logger? Logger
schemaOpts? { schemaId: string, migrate: fun(config: table, current?: string, target: string): boolean } The $schema this handler targets and the migration callback invoked on load when a file's $schema differs.

Instance methods

getHive 

configHandler\getHive path

configHandler:getHive(path)

Returns the config table at the given hive path, creating it if missing.

param type description
path string[]

Returns:

  • hive table?
  • err string?

load 

configHandler\load views, waitLockTime

configHandler:load(views, waitLockTime)

Reads the config file and refreshes the in-memory config and all (or specified) views.

param type description
views? ConfigView|ConfigView[] Views to refresh (default: all registered views).
waitLockTime? number Seconds to wait for the config lock.

Returns:

  • success boolean?
  • err string?

save 

configHandler\save views, waitLockTime

configHandler:save(views, waitLockTime)

Writes the config file, merging only the specified views (or the full config if nil).

param type description
views? ConfigView|ConfigView[] Views to merge (default: the whole config).
waitLockTime? number Seconds to wait for the config lock.

Returns:

  • success boolean?
  • err string?

purgeHive 

configHandler\purgeHive hive

configHandler:purgeHive(hive)

Removes a view's hive from the in-memory config and returns the fresh (empty) hive.

param type description
hive ConfigView

Returns:

  • hive table?
  • err string?

Class methods

get 

ConfigHandler\get filePath, logger, noLoad, schemaOpts

ConfigHandler:get(filePath, logger, noLoad, schemaOpts)

Returns an existing handler for filePath, or creates and optionally loads one.

param type description
filePath string
logger? Logger
noLoad? boolean Don't load the file immediately (default false).
schemaOpts? { schemaId: string, migrate: fun(config: table, current?: string, target: string): boolean } Schema id this handler targets and the migration callback run when a loaded file's $schema differs. Applied on first creation; a cached handler keeps the opts it was created with.

Returns:

getView 

ConfigHandler\getView filePath, hivePath, defaults, logger

ConfigHandler:getView(filePath, hivePath, defaults, logger)

Returns a ConfigView for the given file and hive path, creating a handler if needed.

param type description
filePath string
hivePath string|string[]
defaults? table Default values for the hive.
logger? Logger

Returns:

getSerializableCopy 

ConfigHandler\getSerializableCopy val

ConfigHandler:getSerializableCopy(val)

Deep-copies a value while skipping private keys prefixed with "_".

param type description
val any

Returns:

  • copy any

Fields

field type description
handlers table