Type-Safe Usage Examples

Server Type Safety

local PlayerState: PlayerStateServer = require(...)

-- Type-safe function with proper return types
local function awardCoins(player: Player, amount: number, source: string): boolean
    local currentCoins: number = PlayerState.Get(player, "Coins") or 0

    if amount <= 0 then
        warn(`Invalid coin amount: {amount}`)
        return false
    end

    local success = PlayerState.Set(player, "Coins", currentCoins + amount)
    if success then
        print(`Awarded {amount} coins to {player.Name} from {source}`)
    end

    return success
end

-- Type-safe batch operations
local function levelUpPlayer(player: Player): boolean
    local operations: {BatchOperation} = {
        {path = "Level", value = (PlayerState.Get(player, "Level") or 1) + 1},
        {path = "Experience", value = 0},
        {path = "Coins", value = (PlayerState.Get(player, "Coins") or 0) + 500}
    }

    return PlayerState.BatchSetValues(player, operations)
end

-- Type-safe data retrieval
local function getPlayerStats(player: Player): {Level: number, Experience: number, Coins: number}?
    local allData: PlayerData? = PlayerState.GetAll(player)

    if not allData then
        return nil
    end

    return {
        Level = allData.Level or 1,
        Experience = allData.Experience or 0,
        Coins = allData.Coins or 0
    }
end

Client Type Safety

local PlayerState: PlayerStateClient = require(...)

-- Type-safe change listeners with enhanced info
local function setupCoinDisplay(label: TextLabel): ReplicaConnection?
    return PlayerState.OnChanged("Coins", function(newValue: any, oldValue: any, info: ChangeInfo | {string}?)
        local coins: number = newValue or 0
        label.Text = tostring(coins)

        -- Handle enhanced change info
        if info and typeof(info) == "table" and info.action then
            if oldValue and coins > oldValue then
                showCoinGainEffect(coins - oldValue)
            end
        end
    end)
end

-- Type-safe global change listener
local function setupGlobalListener(): ReplicaConnection?
    return PlayerState.OnChanged(".", function(newValue: any, oldValue: any, info: ChangeInfo | {string}?)
        if info and typeof(info) == "table" and info.action then
            local changeInfo = info :: ChangeInfo
            local pathString = table.concat(changeInfo.path, ".")

            if changeInfo.action == "TableInsert" then
                print(`Item added to {pathString} at index {changeInfo.index}`)
            elseif changeInfo.action == "TableRemove" then
                print(`Item removed from {pathString} at index {changeInfo.index}`)
            end
        end
    end)
end

-- Type-safe data access with readiness check
local function getInventoryCount(): number?
    if not PlayerState.IsReady() then
        return nil
    end

    local inventory: {any} = PlayerState.GetPath("Inventory") or {}
    return #inventory
end