datatable.lua

--[[
Lua Version Check
--]]

local supported_lua_versions <const> = {['Lua 5.4']=true}
if not supported_lua_versions[_VERSION] then
  warn("lua-datatable: detected unsupported lua version: " .. tostring(_VERSION))
end

--[[
Slot
--]]

local slot_metatable <const> = {}
local slot_private <const> = setmetatable({}, {__mode='k'})

-- implementation
local slot_internal_metatable <const> = {
  __name = 'Slot',
  __metatable = slot_metatable,
  __index = function (self, key)
    local private <const> = assert(slot_private[self], "Slot instance not recognized: " .. tostring(self))
    if key == 'validator' or key == 'formatter' then
      return private[key]
    end
  end,
  __newindex = function (_, _, _)
    error("Slot definition cannot be modified")
  end,
  __call = function (self, operation, value)
    local private <const> = assert(slot_private[self], "Slot instance not recognized: " .. tostring(self))
    if operation == 'validate' then
      local value, message = private.validator(value)

      if type(message) == 'string' then
        if value ~= nil then
          error("Slot validator returned a value and an error message")
        end
      elseif message ~= nil then
        error("Slot validator message must be a string or nil")
      end

      return value, message
    elseif operation == 'format' then
      local string_representation <const> = private.formatter(value)
      assert(type(string_representation) == 'string', "Slot formatter did not return a string")
      return string_representation
    else
      error("Slot unknown operation: " .. tostring(operation))
    end
  end,
  __gc = function (self)
    slot_private[self] = nil
  end
}

-- public interface
local Slot <const> = setmetatable({
  create = function (validator, formatter)
    if type(validator) ~= 'function' then
      error("Slot validator must be a function")
    end

    local formatter <const> = formatter or tostring
    if type(formatter) ~= 'function' then
      error("Slot formatter must be a function")
    end

    local instance <const> = {}
    slot_private[instance] = {
      validator=validator,
      formatter=formatter
    }

    return setmetatable(instance, slot_internal_metatable)
  end,
  is = function (value)
    return (getmetatable(value) == slot_metatable)
  end
}, {
  __call = function (self, ...)
    return self.create(...)
  end
})

--[[
Default Slots
--]]

local AnySlot <const> = Slot.create(function (value)
  if value == nil then
    return nil, "slot value must not be nil"
  end

  if type(value) == 'table' then
    return nil, "slot value must not be a table"
  end

  return value
end)

local BooleanSlot <const> = Slot.create(function (value)
  if type(value) == 'boolean' then
    return value
  else
    return nil, "slot value must be a boolean"
  end
end)

local StringSlot <const> = Slot.create(function (value)
  if type(value) == 'string' then
    return value
  else
    return nil, "slot value must be a string"
  end
end, function (value)
  return '"' .. tostring(value) .. '"'
end)

local NumberSlot <const> = Slot.create(function (value)
  if type(value) == 'number' then
    return value
  else
    return nil, "slot value must be a number"
  end
end)

local IntegerSlot <const> = Slot.create(function (value)
  if math.type(value) == 'integer' then
    return value
  else
    return nil, "slot value must be an integer"
  end
end)

local FloatSlot <const> = Slot.create(function (value)
  if math.type(value) == 'float' then
    return value
  else
    return nil, "slot value must be a float"
  end
end)

--[[
Slot Optional Wrapper
--]]

local function Optional(internal_slot)
  assert(Slot.is(internal_slot), "internal_slot value must be a Slot instance")

  return Slot.create(function (value)
    if value == nil then
      return nil
    end

    return internal_slot('validate', value)
  end, function (value)
    return internal_slot('format', value)
  end)
end

--[[
DataTable

A table with defined string keys pointing to corresponding slot values.
--]]

local datatable_type_metatable <const> = {}
local datatable_type_private <const> = setmetatable({}, {__mode='k'})

local datatable_instance_metatable <const> = {}
local datatable_instance_private <const> = setmetatable({}, {__mode='k'})

-- instance implementation
local datatable_instance_check <const> = function (value)
  local instance_private <const> = assert(
    datatable_instance_private[value],
    "DataTable instance not recognized: " .. tostring(value)
  )

  local datatable_private <const> = assert(
    datatable_type_private[instance_private.datatable],
    "DataTable type not recognized: " .. tostring(value)
  )

  return instance_private, datatable_private
end

local datatable_instance_internal_metatable <const> = {
  __name = 'DataTable',
  __metatable = datatable_instance_metatable,
  __index = function (self, key)
    local private <const>, datatable_private <const> = datatable_instance_check(self)
    local slot <const> = assert(datatable_private.slots[key], "DataTable slot not found: " .. tostring(key))

    return private.data[key]
  end,
  __newindex = function (self, key, value)
    local private <const>, datatable_private <const> = datatable_instance_check(self)
    local slot <const> = assert(datatable_private.slots[key], "DataTable slot not found: " .. tostring(key))
    assert(not private.frozen, "DataTable instance is frozen")

    local value, message = slot('validate', value)
    if message then
      error("DataTable slot '" .. key .. "': " .. message)
    end

    -- TODO: use a flag to toggle whether we should always run the datatable
    -- validator or not, we may want to delay that until later

    local previous_value <const> = private.data[key]
    private.data[key] = value

    local message = datatable_private.validator(private.data)
    if message ~= nil then
      private.data[key] = previous_value  -- XXX: is there a better way without a shallow copy of private.data?
      assert(type(message) == 'string', "DataTable validator function must return a string message")
      error("DataTable instance data is not valid: " .. message)
    end
  end,
  __pairs = function (self)
    local private <const>, datatable_private <const> = datatable_instance_check(self)

    -- note: lua table iteration is in arbitrary order whereas this always
    -- iterates in the same order which is technically backwards compatible
    -- for loops: https://www.lua.org/manual/5.4/manual.html#3.3.5
    local function iterate(keys, key) -- state variable, initial or previous control value
      -- note: not strictly necessary as table.remove({}, 1) and inner[nil]
      -- both return nil so the loop ends on it's own but this is safer
      if #keys == 0 then
        return
      end

      local key <const> = table.remove(keys, 1)
      local value <const> = private.data[key]
      return key, value -- control value, remaining loop values
    end

    local keys <const> = {}
    for name, _ in pairs(datatable_private.slots) do
      table.insert(keys, name)
    end

    -- iterator function, state variable, initial control value, closing variable
    return iterate, keys, keys[1], nil
  end,
  __gc = function (self)
    datatable_instance_private[self] = nil
  end
}

-- type implementation
local datatable_type_is <const> = function (self, value)
  if getmetatable(value) ~= datatable_instance_metatable then
    return false
  end

  local instance_private <const>, _ = datatable_instance_check(value)
  return (instance_private.datatable == self)
end

local datatable_type_is_frozen <const> = function (self, instance)
  local instance_private <const>, _ = datatable_instance_check(instance)
  assert(instance_private.datatable == self, "DataTable type method used with incompatible type")

  return instance_private.frozen
end

local datatable_type_class_methods <const> = {
  ['is']=datatable_type_is,
  ['is_frozen']=datatable_type_is_frozen,
}

local datatable_type_internal_metatable <const> = {
  __name = 'DataTableType',
  __metatable = datatable_type_metatable,
  __index = function (self, key)
    local private <const> = assert(
      datatable_type_private[self],
      "DataTable type not recognized: " .. tostring(self)
    )

    -- datatable type slots
    if key == 'slots' then
      -- shallow copy to prevent mutation
      local slots <const> = {}
      for name, slot in pairs(private.slots) do
        slots[name] = slot
      end

      return slots
    -- datatable frozen flag
    elseif key == 'freeze_instances' then
      return private.freeze_instances
    -- class methods
    elseif datatable_type_class_methods[key] ~= nil then
      return datatable_type_class_methods[key]
    -- unknown key
    else
      return nil
    end
  end,
  __newindex = function (_, _, _)
    error("DataTable definition cannot be modified")
  end,
  __call = function (self, value_data, flag_data)
    local private <const> = assert(
      datatable_type_private[self],
      "DataTable type not recognized: " .. tostring(self)
    )
  
    local initial_data <const> = {}
    for name, slot in pairs(private.slots) do
      local value, message = slot('validate', value_data[name])
      if message then
        error("DataTable slot '" .. name .. "': " .. message)
      end

      initial_data[name] = value
    end

    local message <const> = private.validator(initial_data)
    if message ~= nil then
      assert(type(message) == 'string', "DataTable validator function must return a string message")
      error("DataTable instance data is not valid: " .. message)
    end

    local flags <const> = flag_data or {}
    if type(flags) ~= 'table' then
      error("DataTable instance flags must be a table")
    end

    local frozen <const> = flags['frozen']
    if frozen ~= nil then
      if type(frozen) ~= 'boolean' then
        error("DataTable instance frozen flag must be a boolean")
      end

      if private.freeze_instances and not frozen then
        error("DataTable type freeze_instances requires instances to also be frozen")
      end
    end

    local instance_frozen <const> = (frozen or private.freeze_instances)
    local instance <const> = {}
    datatable_instance_private[instance] = {
      datatable=self,
      data=initial_data,
      frozen=instance_frozen
    }

    return setmetatable(instance, datatable_instance_internal_metatable)
  end,
  __gc = function (self)
    datatable_type_private[self] = nil
  end
}

-- public interface
local DataTable <const> = setmetatable({
  create = function (slot_data, flag_data)
    if type(slot_data) ~= 'table' or not next(slot_data) then
      error("DataTable slots must be a non-empty table")
    end

    local flag_data <const> = flag_data or {}
    if type(flag_data) ~= 'table' then
      error("DataTable flags must be a table")
    end

    local freeze_instances <const> = (flag_data['freeze_instances'] or false)
    if type(freeze_instances) ~= 'boolean' then
      error("DataTable freeze_instances flag must be a boolean")
    end

    local validator <const> = (flag_data['validator'] or (function (_) return end))
    if type(validator) ~= 'function' then
      error("DataTable validator flag must be a function")
    end

    local slots <const> = {}
    for name, value in pairs(slot_data) do
      -- XXX: can this ever happen?
      if slots[name] then
        error("DataTable duplicate slot name: " .. tostring(name))
      end

      if Slot.is(value) then
        slots[name] = value
      elseif type(value) == 'table' then
        slots[name] = Slot.create(table.unpack(value))
      else
        error("DataTable invalid slot value: " .. tostring(value))
      end
    end

    local instance <const> = {}
    datatable_type_private[instance] = {
      slots=slots,
      freeze_instances=freeze_instances,
      validator=validator
    }

    return setmetatable(instance, datatable_type_internal_metatable)
  end,
  is = function (value)
    return (getmetatable(value) == datatable_type_metatable)
  end
}, {
  __call = function (self, ...)
    return self.create(...)
  end
})

--[[
ArrayTable

A table with contiguous positive integer keys pointing to slot enforced values.
--]]

local arraytable_type_metatable <const> = {}
local arraytable_type_private <const> = setmetatable({}, {__mode='k'})

local arraytable_instance_metatable <const> = {}
local arraytable_instance_private <const> = setmetatable({}, {__mode='k'})

-- instance implementation
local arraytable_instance_check <const> = function (value)
  local instance_private <const> = assert(
    arraytable_instance_private[value],
    "ArrayTable instance not recognized: " .. tostring(value)
  )

  local arraytable_private <const> = assert(
    arraytable_type_private[instance_private.arraytable],
    "ArrayTable type not recognized: " .. tostring(value)
  )

  return instance_private, arraytable_private
end

local arraytable_instance_internal_metatable <const> = {
  __name = 'ArrayTable',
  __metatable = arraytable_instance_metatable,
  __len = function (self)
    local private <const>, _ = arraytable_instance_check(self)

    return #private.data
  end,
  __index = function (self, key)
    local private <const>, _ = arraytable_instance_check(self)

    if math.type(key) ~= 'integer' then
      error("ArrayTable index must be an integer: " .. tostring(key))
    end

    return private.data[key]
  end,
  __newindex = function (self, key, value)
    local private <const>, arraytable_private <const> = arraytable_instance_check(self)
    assert(not private.frozen, "ArrayTable instance is frozen")

    if math.type(key) ~= 'integer' then
      error("ArrayTable index must be an integer: " .. tostring(key))
    end

    if key <= 0 then
      error("ArrayTable index must be positive: " .. tostring(key))
    end

    if value ~= nil then
      local value, message = arraytable_private.value_slot('validate', value)
      if message then
        error("ArrayTable index " .. tostring(key) .. ": " .. message)
      end
    end

    -- TODO: use a flag to toggle whether we should always run the arraytable
    -- validator or not, we may want to delay that until later

    local previous_value <const> = private.data[key]
    private.data[key] = value

    -- validate array indices are contiguous
    local key_count = 0
    for _, _ in pairs(private.data) do
      key_count = key_count + 1
    end

    if key_count ~= #private.data then
      private.data[key] = previous_value
      error("ArrayTable indices must be contiguous")
    end

    -- validate new array data
    local message = arraytable_private.validator(private.data)
    if message ~= nil then
      private.data[key] = previous_value
      assert(type(message) == 'string', "ArrayTable validator function must return a string message")
      error("ArrayTable instance data is not valid: " .. message)
    end
  end,
  __pairs = function (self)
    local private <const>, _ = arraytable_instance_check(self)

    -- for loops: https://www.lua.org/manual/5.4/manual.html#3.3.5
    local function iterate(data, index) -- state variable, initial or previous control value
      index = index + 1
      local value <const> = data[index]

      if value == nil then
        return
      end

      return index, value -- control value, remaining loop values
    end

    -- iterator function, state variable, initial control value, closing variable
    return iterate, private.data, 0, nil
  end,
  __gc = function (self)
    arraytable_instance_private[self] = nil
  end
}

-- type implementation
local arraytable_type_is <const> = function (self, value)
  if getmetatable(value) ~= arraytable_instance_metatable then
    return false
  end

  local instance_private <const>, _ = arraytable_instance_check(value)
  return (instance_private.arraytable == self)
end

local arraytable_type_is_frozen <const> = function (self, instance)
  local instance_private <const>, _ = arraytable_instance_check(instance)
  assert(instance_private.arraytable == self, "ArrayTable type method used with incompatible type")

  return instance_private.frozen
end

local arraytable_type_class_methods <const> = {
  ['is']=arraytable_type_is,
  ['is_frozen']=arraytable_type_is_frozen,
}

local arraytable_type_internal_metatable <const> = {
  __name = 'ArrayTableType',
  __metatable = arraytable_type_metatable,
  __index = function (self, key)
    local private <const> = assert(
      arraytable_type_private[self],
      "ArrayTable type not recognized: " .. tostring(self)
    )

    -- value slot
    if key == 'value_slot' then
      return private.value_slot
    -- arraytable frozen flag
    elseif key == 'freeze_instances' then
      return private.freeze_instances
    -- class methods
    elseif arraytable_type_class_methods[key] ~= nil then
      return arraytable_type_class_methods[key]
    -- unknown key
    else
      return nil
    end
  end,
  __newindex = function (_, _, _)
    error("ArrayTable definition cannot be modified")
  end,
  __call = function (self, value_data, flag_data)
    local private <const> = assert(
      arraytable_type_private[self],
      "ArrayTable type not recognized: " .. tostring(self)
    )

    local key_count = 0
    local initial_data <const> = {}
    for key, value in pairs(value_data) do
      if math.type(key) ~= 'integer' then
        error("ArrayTable indices must be integers")
      end

      if key <= 0 then
        error("ArrayTable indices must be positive")
      end

      local value, message = private.value_slot('validate', value)
      if message then
        error("ArrayTable index " .. tostring(index) .. ": " .. message)
      end

      key_count = key_count + 1
      initial_data[key] = value
    end

    if key_count ~= #value_data then
      error("ArrayTable indices must be contiguous")
    end

    local message <const> = private.validator(initial_data)
    if message ~= nil then
      assert(type(message) == 'string', "ArrayTable validator function must return a string message")
      error("ArrayTable instance data is not valid: " .. message)
    end

    local flags <const> = flag_data or {}
    if type(flags) ~= 'table' then
      error("ArrayTable instance flags must be a table")
    end

    local frozen <const> = flags['frozen']
    if frozen ~= nil then
      if type(frozen) ~= 'boolean' then
        error("ArrayTable instance frozen flag must be a boolean")
      end

      if private.freeze_instances and not frozen then
        error("ArrayTable type freeze_instances requires instances to also be frozen")
      end
    end

    local instance_frozen <const> = (frozen or private.freeze_instances)
    local instance <const> = {}
    arraytable_instance_private[instance] = {
      arraytable=self,
      data=initial_data,
      frozen=instance_frozen
    }

    return setmetatable(instance, arraytable_instance_internal_metatable)
  end,
  __gc = function (self)
    arraytable_type_private[self] = nil
  end
}

-- public interface
local ArrayTable <const> = setmetatable({
  create = function (config_data)
    if type(config_data) ~= 'table' then
      error("ArrayTable config must be a table")
    end

    local value_slot <const> = (config_data['value_slot'] or AnySlot)
    if not Slot.is(value_slot) then
      error("ArrayTable value_slot must be a Slot instance")
    end

    local freeze_instances <const> = (config_data['freeze_instances'] or false)
    if type(freeze_instances) ~= 'boolean' then
      error("ArrayTable freeze_instances flag must be a boolean")
    end

    local validator <const> = (config_data['validator'] or (function (_) return end))
    if type(validator) ~= 'function' then
      error("ArrayTable validator flag must be a function")
    end

    local instance <const> = {}
    arraytable_type_private[instance] = {
      value_slot=value_slot,
      freeze_instances=freeze_instances,
      validator=validator
    }

    return setmetatable(instance, arraytable_type_internal_metatable)
  end,
  is = function (value)
    return (getmetatable(value) == arraytable_type_metatable)
  end
}, {
  __call = function (self, ...)
    return self.create(...)
  end
})

--[[
MapTable

A table with slot enforced keys pointing to slot enforced values.
--]]

local maptable_type_metatable <const> = {}
local maptable_type_private <const> = setmetatable({}, {__mode='k'})

local maptable_instance_metatable <const> = {}
local maptable_instance_private <const> = setmetatable({}, {__mode='k'})

-- instance implementation
local maptable_instance_check <const> = function (value)
  local instance_private <const> = assert(
    maptable_instance_private[value],
    "MapTable instance not recognized: " .. tostring(value)
  )

  local maptable_private <const> = assert(
    maptable_type_private[instance_private.maptable],
    "MapTable type not recognized: " .. tostring(value)
  )

  return instance_private, maptable_private
end

local maptable_instance_internal_metatable <const> = {
  __name = 'MapTable',
  __metatable = maptable_instance_metatable,
  __index = function (self, key)
    local private <const>, _ = maptable_instance_check(self)

    return private.data[key]
  end,
  __newindex = function (self, key, value)
    local private <const>, maptable_private <const> = maptable_instance_check(self)
    assert(not private.frozen, "MapTable instance is frozen")

    if key == nil then
      error("MapTable keys cannot be nil")
    end

    local key, message = maptable_private.key_slot('validate', key)
    if message then
      error("MapTable key is invalid: " .. message)
    end

    if value ~= nil then
      local value, message = maptable_private.value_slot('validate', value)
      if message then
        error("MapTable value is invalid: " .. message)
      end
    end

    -- TODO: use a flag to toggle whether we should always run the arraytable
    -- validator or not, we may want to delay that until later

    local previous_value <const> = private.data[key]
    private.data[key] = value

    -- validate new map data
    local message = maptable_private.validator(private.data)
    if message ~= nil then
      private.data[key] = previous_value
      assert(type(message) == 'string', "MapTable validator function must return a string message")
      error("MapTable instance data is not valid: " .. message)
    end
  end,
  __pairs = function (self)
    local private <const>, _ = maptable_instance_check(self)

    -- for loops: https://www.lua.org/manual/5.4/manual.html#3.3.5
    local function iterate(keys, key) -- state variable, initial or previous control value
      -- note: not strictly necessary as table.remove({}, 1) and inner[nil]
      -- both return nil so the loop ends on it's own but this is safer
      if #keys == 0 then
        return
      end

      local key <const> = table.remove(keys, 1)
      local value <const> = private.data[key]
      return key, value -- control value, remaining loop values
    end

    local keys <const> = {}
    for key, _ in pairs(private.data) do
      table.insert(keys, key)
    end

    -- iterator function, state variable, initial control value, closing variable
    return iterate, keys, keys[1], nil
  end,
  __gc = function (self)
    maptable_instance_private[self] = nil
  end
}

-- type implementation
local maptable_type_is <const> = function (self, value)
  if getmetatable(value) ~= maptable_instance_metatable then
    return false
  end

  local instance_private <const>, _ = maptable_instance_check(value)
  return (instance_private.maptable == self)
end

local maptable_type_is_frozen <const> = function (self, instance)
  local instance_private <const>, _ = maptable_instance_check(instance)
  assert(instance_private.maptable == self, "MapTable type method used with incompatible type")

  return instance_private.frozen
end

local maptable_type_class_methods <const> = {
  ['is']=maptable_type_is,
  ['is_frozen']=maptable_type_is_frozen,
}

local maptable_type_internal_metatable <const> = {
  __name = 'MapTableType',
  __metatable = maptable_type_metatable,
  __index = function (self, key)
    local private <const> = assert(
      maptable_type_private[self],
      "MapTable type not recognized: " .. tostring(self)
    )

    -- key slot
    if key == 'key_slot' then
      return private.key_slot
    -- value slot
    elseif key == 'value_slot' then
      return private.value_slot
    -- frozen flag
    elseif key == 'freeze_instances' then
      return private.freeze_instances
    -- class methods
    elseif maptable_type_class_methods[key] ~= nil then
      return maptable_type_class_methods[key]
    -- unknown key
    else
      return nil
    end
  end,
  __newindex = function (_, _, _)
    error("MapTable definition cannot be modified")
  end,
  __call = function (self, value_data, flag_data)
    local private <const> = assert(
      maptable_type_private[self],
      "MapTable type not recognized: " .. tostring(self)
    )

    local initial_data <const> = {}
    for key, value in pairs(value_data) do
      if key == nil then
        error("MapTable keys cannot be nil")
      end

      local valid_key <const>, message = private.key_slot('validate', key)
      if message then
        error("MapTable key '" .. tostring(key) .. "': " .. message)
      end

      local valid_value <const>, message = private.value_slot('validate', value)
      if message then
        error("MapTable value '" .. tostring(value) .. "': " .. message)
      end

      initial_data[valid_key] = valid_value
    end

    local message <const> = private.validator(initial_data)
    if message ~= nil then
      assert(type(message) == 'string', "MapTable validator function must return a string message")
      error("MapTable instance data is not valid: " .. message)
    end

    local flags <const> = flag_data or {}
    if type(flags) ~= 'table' then
      error("MapTable instance flags must be a table")
    end

    local frozen <const> = flags['frozen']
    if frozen ~= nil then
      if type(frozen) ~= 'boolean' then
        error("MapTable instance frozen flag must be a boolean")
      end

      if private.freeze_instances and not frozen then
        error("MapTable type freeze_instances requires instances to also be frozen")
      end
    end

    local instance_frozen <const> = (frozen or private.freeze_instances)
    local instance <const> = {}
    maptable_instance_private[instance] = {
      maptable=self,
      data=initial_data,
      frozen=instance_frozen
    }

    return setmetatable(instance, maptable_instance_internal_metatable)
  end,
  __gc = function (self)
    maptable_type_private[self] = nil
  end
}

-- public interface
local MapTable <const> = setmetatable({
  create = function (config_data)
    if type(config_data) ~= 'table' then
      error("MapTable config must be a table")
    end

    local key_slot <const> = (config_data['key_slot'] or AnySlot)
    if not Slot.is(key_slot) then
      error("MapTable key_slot must be a Slot instance")
    end

    local value_slot <const> = (config_data['value_slot'] or AnySlot)
    if not Slot.is(value_slot) then
      error("MapTable value_slot must be a Slot instance")
    end

    local freeze_instances <const> = (config_data['freeze_instances'] or false)
    if type(freeze_instances) ~= 'boolean' then
      error("MapTable freeze_instances flag must be a boolean")
    end

    local validator <const> = (config_data['validator'] or (function (_) return end))
    if type(validator) ~= 'function' then
      error("MapTable validator flag must be a function")
    end

    local instance <const> = {}
    maptable_type_private[instance] = {
      key_slot=key_slot,
      value_slot=value_slot,
      freeze_instances=freeze_instances,
      validator=validator,
    }

    return setmetatable(instance, maptable_type_internal_metatable)
  end,
  is = function (value)
    return (getmetatable(value) == maptable_type_metatable)
  end
}, {
  __call = function (self, ...)
    return self.create(...)
  end
})

--[[
Generic Internal Helpers
--]]

local generic_table_is_instance <const> = function (value)
  local mt <const> = getmetatable(value)
  return (
    mt == datatable_instance_metatable or
    mt == arraytable_instance_metatable or
    mt == maptable_instance_metatable
  )
end

local generic_table_is_type <const> = function (value)
  local mt <const> = getmetatable(value)
  return (
    mt == datatable_type_metatable or
    mt == arraytable_type_metatable or
    mt == maptable_type_metatable
  )
end

-- return a shallow copy of table instances contained by the provided instance
-- note: this only checks one level deep in order to avoid searching
local generic_table_nested_instances = function (instance)
  local values <const> = {}
  local mt <const> = getmetatable(instance)

  if mt == datatable_instance_metatable then
    local private <const> = assert(datatable_instance_private[instance])

    for _, value in pairs(private.data) do
      if generic_table_is_instance(value) then
        table.insert(values, value)
      end
    end
  elseif mt == arraytable_instance_metatable then
    local private <const> = assert(arraytable_instance_private[instance])

    for _, value in ipairs(private.data) do
      if generic_table_is_instance(value) then
        table.insert(values, value)
      end
    end
  elseif mt == maptable_instance_metatable then
    local private <const> = assert(maptable_instance_private[instance])

    for key, value in pairs(private.data) do
      if generic_table_is_instance(key) then
        table.insert(values, key)
      end

      if generic_table_is_instance(value) then
        table.insert(values, value)
      end
    end
  else
    error("invalid table instance type")
  end

  return values
end

--[[
Table Slot Wrapper
--]]

local function TableSlot(table_type, validate)
  assert(generic_table_is_type(table_type), "table_type must be an DataTable or ArrayTable type")
  assert(type(validate) == 'boolean' or validate == nil, "validate must be a boolean or nil")

  return Slot.create(function (value)
    if not table_type:is(value) then
      return nil, "value must be an instance of table type: " .. tostring(table_type)
    end

    if validate then
      local valid <const>, message <const> = table_type:validate(value)
      if not valid then
        return nil, message
      end
    end

    return value
  end, function (value)
    return tostring(table_type)
  end)
end

--[[
Table Validation
--]]

local generic_table_type_validate <const> = function (root_instance, recurse)
  -- freeze the provided instance
  local function _validate_instance(instance)
    local mt <const> = getmetatable(instance)
    if mt == datatable_instance_metatable then
      local instance_private <const>, datatable_private <const> = datatable_instance_check(instance)

      local message <const> = datatable_private.validator(instance_private.data)
      if message ~= nil then
        -- TODO: improve the error to specify which nested instance failed validation
        assert(type(message) == 'string', "DataTable validator function must return a string message")
        return false, message
      end
    elseif mt == arraytable_instance_metatable then
      local instance_private <const>, arraytable_private <const> = arraytable_instance_check(instance)

      local message <const> = arraytable_private.validator(instance_private.data)
      if message ~= nil then
        -- TODO: improve the error to specify which nested instance failed validation
        assert(type(message) == 'string', "ArrayTable validator function must return a string message")
        return false, message
      end
    elseif mt == maptable_instance_metatable then
      local instance_private <const>, maptable_private <const> = maptable_instance_check(instance)

      local message <const> = maptable_private.validator(instance_private.data)
      if message ~= nil then
        -- TODO: improve the error to specify which nested instance failed validation
        assert(type(message) == 'string', "MapTable validator function must return a string message")
        return false, message
      end
    else
      error("invalid table instance type")
    end

    return true, nil
  end

  -- use breadth-first search from the root instance to find all nested tables
  local instances <const> = {root_instance}
  while #instances > 0 do
    local instance <const> = table.remove(instances, 1)
    local valid <const>, message <const> = _validate_instance(instance)
    if not valid then
      return false, message
    end

    local nested_instances <const> = generic_table_nested_instances(instance)
    for _, nested_instance in ipairs(nested_instances) do
      table.insert(instances, nested_instance)
    end
  end

  return true, nil
end

local datatable_type_validate <const> = function (self, instance)
  local instance_private <const>, _ = datatable_instance_check(instance)
  assert(instance_private.datatable == self, "DataTable type method used with incompatible type")

  return generic_table_type_validate(instance)
end

local arraytable_type_validate <const> = function (self, instance)
  local instance_private <const>, _ = arraytable_instance_check(instance)
  assert(instance_private.arraytable == self, "ArrayTable type method used with incompatible type")

  return generic_table_type_validate(instance)
end

local maptable_type_validate <const> = function (self, instance)
  local instance_private <const>, _ = maptable_instance_check(instance)
  assert(instance_private.maptable == self, "MapTable type method used with incompatible type")

  return generic_table_type_validate(instance)
end

datatable_type_class_methods['validate'] = datatable_type_validate
arraytable_type_class_methods['validate'] = arraytable_type_validate
maptable_type_class_methods['validate'] = maptable_type_validate

--[[
Table Freezing
--]]

local generic_table_type_freeze <const> = function (root_instance)
  -- freeze the provided instance
  local function _freeze_instance(instance)
    local mt <const> = getmetatable(instance)
    if mt == datatable_instance_metatable then
      local instance_private <const> = assert(datatable_instance_private[instance])
      local datatable_private <const> = assert(datatable_type_private[instance_private.datatable])

      local message <const> = datatable_private.validator(instance_private.data)
      if message ~= nil then
        -- TODO: improve the error to specify which nested instance failed validation
        assert(type(message) == 'string', "DataTable validator function must return a string message")
        error("DataTable instance data is not valid: " .. message)
      end

      instance_private.frozen = true
    elseif mt == arraytable_instance_metatable then
      local instance_private <const> = assert(arraytable_instance_private[instance])
      local arraytable_private <const> = assert(arraytable_type_private[instance_private.arraytable])

      local message <const> = arraytable_private.validator(instance_private.data)
      if message ~= nil then
        -- TODO: improve the error to specify which nested instance failed validation
        assert(type(message) == 'string', "ArrayTable validator function must return a string message")
        error("ArrayTable instance data is not valid: " .. message)
      end

      instance_private.frozen = true
    elseif mt == maptable_instance_metatable then
      local instance_private <const> = assert(maptable_instance_private[instance])
      local maptable_private <const> = assert(maptable_type_private[instance_private.maptable])

      local message <const> = maptable_private.validator(instance_private.data)
      if message ~= nil then
        -- TODO: improve the error to specify which nested instance failed validation
        assert(type(message) == 'string', "MapTable validator function must return a string message")
        error("MapTable instance data is not valid: " .. message)
      end

      instance_private.frozen = true
    else
      error("invalid table instance type")
    end
  end

  -- use breadth-first search from the root instance to find all nested tables
  local instances <const> = {root_instance}
  while #instances > 0 do
    local instance <const> = table.remove(instances, 1)
    _freeze_instance(instance)

    local nested_instances <const> = generic_table_nested_instances(instance)
    for _, nested_instance in ipairs(nested_instances) do
      table.insert(instances, nested_instance)
    end
  end
end

local datatable_type_freeze <const> = function (self, instance)
  local instance_private <const>, _ = datatable_instance_check(instance)
  assert(instance_private.datatable == self, "DataTable type method used with incompatible type")

  -- use shared generic implementation
  generic_table_type_freeze(instance)

  -- return the table instance to make chaining and returning it easy
  return instance
end

local arraytable_type_freeze <const> = function (self, instance)
  local instance_private <const>, _ = arraytable_instance_check(instance)
  assert(instance_private.arraytable == self, "ArrayTable type method used with incompatible type")

  -- use shared generic implementation
  generic_table_type_freeze(instance)

  -- return the table instance to make chaining and returning it easy
  return instance
end

local maptable_type_freeze <const> = function (self, instance)
  local instance_private <const>, _ = maptable_instance_check(instance)
  assert(instance_private.maptable == self, "MapTable type method used with incompatible type")

  -- use shared generic implementation
  generic_table_type_freeze(instance)

  -- return the table instance to make chaining and returning it easy
  return instance
end

datatable_type_class_methods['freeze'] = datatable_type_freeze
arraytable_type_class_methods['freeze'] = arraytable_type_freeze
maptable_type_class_methods['freeze'] = maptable_type_freeze

--[[
Module Interface
--]]

local module = {
  -- slot
  Slot=Slot,

  -- default slots
  AnySlot=AnySlot,
  BooleanSlot=BooleanSlot,
  StringSlot=StringSlot,
  NumberSlot=NumberSlot,
  IntegerSlot=IntegerSlot,
  FloatSlot=FloatSlot,

  -- slot wrappers
  Optional=Optional,

  -- tables
  DataTable=DataTable,
  ArrayTable=ArrayTable,
  MapTable=MapTable,

  -- table slot wrappers
  TableSlot=TableSlot,
}

if os.getenv('LUA_DATATABLE_LEAK_INTERNALS') == 'TRUE' then
  -- leak internal variables and methods in order to unit test them from outside
  -- of this module but at least we can use an obvious environment variable
  -- and issue a warning to prevent someone from relying on this
  warn("lua-enum: LUA_DATATABLE_LEAK_INTERNALS is set and internals are exported in module")

  -- stating the obvious but these are not part of the public interface
  module['slot_metatable'] = slot_metatable
  module['slot_private'] = slot_private

  module['datatable_type_metatable'] = datatable_type_metatable
  module['datatable_type_private'] = datatable_type_private
  module['datatable_instance_metatable'] = datatable_instance_metatable
  module['datatable_instance_private'] = datatable_instance_private

  module['arraytable_type_metatable'] = arraytable_type_metatable
  module['arraytable_type_private'] = arraytable_type_private
  module['arraytable_instance_metatable'] = arraytable_instance_metatable
  module['arraytable_instance_private'] = arraytable_instance_private

  module['maptable_type_metatable'] = maptable_type_metatable
  module['maptable_type_private'] = maptable_type_private
  module['maptable_instance_metatable'] = maptable_instance_metatable
  module['maptable_instance_private'] = maptable_instance_private

  module['generic_table_is_instance'] = generic_table_is_instance
  module['generic_table_is_type'] = generic_table_is_type
  module['generic_table_nested_instances'] = generic_table_nested_instances
end

return module