feat: preserve key order in decode-modify-encode workflow

[membphis]

有序编码：在 Decode-Modify-Encode 流程中保持 Key 顺序

概述

增强 qjson 的 lazy table API，使其在修改后编码时保持原始 JSON 的 key 顺序。这支持 API 网关场景：JSON 请求被解码、轻量修改、再编码，同时保持 key 顺序一致性。

需求

支持的场景

1. 修改现有值 — 修改已有 key 的值；key 顺序不变
2. 删除 key — 设置 t.key = nil 从输出中移除该 key；剩余 key 保持顺序
3. 新增 key — 新 key 追加到对象末尾

语义

• t.key = nil 表示删除（与 lua-cjson 兼容），而非 JSON null
• 删除后重新添加的 key 出现在末尾（视为新 key）
• 只保持 key 顺序；空白和数字格式可能变化
• 数组保持索引顺序（无需修改）

设计

方案：有序 Key 列表 + Value 映射

当 LazyObject 首次被修改时，物化为有序结构：

{
    _dirty = true,
    _keys = {"a", "b", "c"},      -- 有序 key 列表
    _values = {a = 1, b = 2, c = 3},  -- key -> value 映射
    -- 保留原有字段用于未修改子树的 buffer 切片
    _doc, _cur, _cur_box, _bs, _be, _parent
}

实现变更

1. LazyObject.__newindex

首次写入时：

1. 通过 qjson_cursor_object_entry_at 按顺序遍历原始 JSON 的所有 key
2. 构建 _keys 列表和 _values table
3. 应用当前赋值操作

后续写入时：

• 已有 key：更新 _values[key]
• 新 key：追加到 _keys，设置 _values[key]
• 删除（= nil）：从 _keys 移除，从 _values 删除

LazyObject.__newindex = function(t, k, v)
    -- 向上标记 dirty（现有逻辑）
    local cur = t
    while cur do
        local mt = getmetatable(cur)
        if mt ~= LazyObject and mt ~= LazyArray then break end
        rawset(cur, "_dirty", true)
        cur = rawget(cur, "_parent")
    end

    local keys = rawget(t, "_keys")
    if not keys then
        -- 首次修改：物化 key 顺序
        keys = {}
        local values = {}
        local i = 0
        while true do
            local rc = C.qjson_cursor_object_entry_at(t._cur, i, strp_box, size_box, child_box)
            if rc == QJSON_NOT_FOUND then break end
            check(rc)
            local key = ffi.string(strp_box[0], size_box[0])
            keys[#keys + 1] = key
            values[key] = decode_cursor(t, child_box)
            i = i + 1
        end
        rawset(t, "_keys", keys)
        rawset(t, "_values", values)
    end

    local values = rawget(t, "_values")
    if v == nil then
        -- 删除：从 _keys 移除
        for i, key in ipairs(keys) do
            if key == k then
                table.remove(keys, i)
                break
            end
        end
        values[k] = nil
    elseif values[k] == nil then
        -- 新 key：追加到 _keys
        keys[#keys + 1] = k
        values[k] = v
    else
        -- 已有 key：只更新值
        values[k] = v
    end
end

2. LazyObject.__index

物化后从 _values 读取。现有的 read_object_field 函数保持不变，因为：

• 物化前：使用 cursor 路径（现有行为）
• 物化后：_values 包含物化步骤中解码的所有值

这里不需要代码变更 — read_object_field 中现有的 rawget(self, key) 缓存检查不会触发，因为我们使用 _values 作为存储，而非直接 rawset 到 table。__index 元方法在检查 _keys 存在后自然会回退到 _values 查找：

local function read_object_field(self, key)
    if type(key) ~= "string" then return nil end

    -- 检查是否已物化（新增）
    local values = rawget(self, "_values")
    if values then
        return values[key]
    end

    -- 原有 lazy 路径通过 cursor（不变）
    local rc = C.qjson_cursor_field(self._cur, key, #key, child_box)
    if not check(rc) then return nil end
    local v = decode_cursor(self, child_box)
    if type(v) == "table" then rawset(self, key, v) end
    return v
end

3. LazyObject.__pairs

物化后按 _keys 顺序迭代：

function LazyObject.__pairs(t)
    local keys = rawget(t, "_keys")
    if keys then
        local values = rawget(t, "_values")
        local i = 0
        return function()
            i = i + 1
            local k = keys[i]
            if k then return k, values[k] end
        end
    end
    -- 原有 lazy 迭代器
    return lazy_object_iter, { view = t, i = 0 }, nil
end

4. encode_lazy_object_walking

使用 _keys 顺序编码：

local function encode_lazy_object_walking(t)
    local keys = rawget(t, "_keys")
    if keys then
        -- 已物化：使用 _keys 顺序
        local values = rawget(t, "_values")
        local parts = {}
        for _, k in ipairs(keys) do
            local v = values[k]
            if v ~= nil then
                parts[#parts + 1] = encode_string(k) .. ":" .. encode(v)
            end
        end
        return "{" .. table.concat(parts, ",") .. "}"
    end

    -- 原有基于 cursor 的遍历（用于仅子节点 dirty 的情况）
    local parts = {}
    local i = 0
    while true do
        local rc = C.qjson_cursor_object_entry_at(t._cur, i, strp_box, size_box, child_box)
        if rc == QJSON_NOT_FOUND then break end
        check(rc)
        local k = ffi.string(strp_box[0], size_box[0])
        local cached = rawget(t, k)
        local v = cached ~= nil and not INTERNAL_KEYS[k] and cached or decode_cursor(t, child_box)
        parts[#parts + 1] = encode_string(k) .. ":" .. encode(v)
        i = i + 1
    end
    return "{" .. table.concat(parts, ",") .. "}"
end

内部 Key 更新

将新的内部 key 添加到排除集合：

local INTERNAL_KEYS = {
    _doc = true, _cur_box = true, _cur = true, _bs = true, _be = true,
    _parent = true, _dirty = true,
    _keys = true, _values = true,  -- 新增
}

边界情况

场景	行为
读取后修改同一 key	正常工作：物化时值已在 _values 中
修改嵌套对象	子对象独立 dirty；父对象通过 encode() 编码子对象
空对象 {} 新增 key	_keys = {} 初始化，然后追加
key 名与内部字段冲突	_values 隔离用户数据；无冲突
多次删除	每次从 _keys 移除；剩余 key 顺序保持
删除所有 key	_keys = {}，编码为 {}

性能特征

• 只读路径：无变化（无 _keys/_values 开销）
• 首次修改：O(n) 物化所有 key/value
• 后续修改：删除 O(n)（线性扫描 _keys），新增/更新 O(1)
• 编码：O(n) 遍历 _keys

对于目标用例（decode、修改少量字段、encode），这是可接受的。

测试

新增测试用例

describe("ordered encode", function()
    it("preserves key order on value modification", function()
        local t = qjson.decode('{"c":3,"a":1,"b":2}')
        t.a = 100
        assert.are.equal('{"c":3,"a":100,"b":2}', qjson.encode(t))
    end)

    it("preserves order when deleting a key", function()
        local t = qjson.decode('{"c":3,"a":1,"b":2}')
        t.a = nil
        assert.are.equal('{"c":3,"b":2}', qjson.encode(t))
    end)

    it("appends new keys to the end", function()
        local t = qjson.decode('{"c":3,"a":1}')
        t.b = 2
        assert.are.equal('{"c":3,"a":1,"b":2}', qjson.encode(t))
    end)

    it("deleted then re-added key appears at end", function()
        local t = qjson.decode('{"a":1,"b":2,"c":3}')
        t.b = nil
        t.b = 999
        assert.are.equal('{"a":1,"c":3,"b":999}', qjson.encode(t))
    end)

    it("handles nested object modification", function()
        local t = qjson.decode('{"x":1,"nested":{"a":1,"b":2},"y":2}')
        t.nested.a = 100
        local out = qjson.encode(t)
        -- x 和 y 顺序保持，nested 内部有序
        assert.truthy(out:find('"x":1'))
        assert.truthy(out:find('"y":2'))
        assert.truthy(out:find('"a":100'))
    end)

    it("handles empty object with additions", function()
        local t = qjson.decode('{}')
        t.a = 1
        t.b = 2
        assert.are.equal('{"a":1,"b":2}', qjson.encode(t))
    end)

    it("handles delete all keys", function()
        local t = qjson.decode('{"a":1,"b":2}')
        t.a = nil
        t.b = nil
        assert.are.equal('{}', qjson.encode(t))
    end)

    it("read before modify works correctly", function()
        local t = qjson.decode('{"a":1,"b":2,"c":3}')
        local _ = t.b  -- 先读取
        t.b = 999
        assert.are.equal('{"a":1,"b":999,"c":3}', qjson.encode(t))
    end)
end)

需修改的文件

1. lua/qjson/table.lua — 所有变更都在此文件：

   • INTERNAL_KEYS — 添加 _keys、_values
   • LazyObject.__newindex — 重写为使用有序 key 列表
   • read_object_field / LazyObject.__index — 检查物化状态
   • LazyObject.__pairs — 支持物化后的迭代
   • encode_lazy_object_walking — 物化后使用 _keys 顺序

2. tests/lua/ — 新增测试文件 ordered_encode_spec.lua

不在范围内

• 保留原始空白/格式
• 控制新 key 的插入位置（始终追加）
• 数组元素删除语义（遵循现有 lua-cjson 行为）
• Rust 侧变更（所有变更都在 Lua 层）

[coderabbitai]

🔗 Related PRs

#54 - perf: Lua encode + cache + scanner + validation stack optimizations [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[membphis]

有序编码实现计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 增强 qjson 的 lazy table API，使其在修改后编码时保持原始 JSON 的 key 顺序。

Architecture: 在 LazyObject 首次修改时，物化为 _keys（有序列表）+ _values（key→value 映射）结构。encode 时按 _keys 顺序输出。删除操作从 _keys 移除，新增操作追加到 _keys 末尾。

Tech Stack: Lua (LuaJIT FFI)，现有 qjson Rust FFI 接口

---

文件结构

文件	职责
lua/qjson/table.lua	所有实现变更：INTERNAL_KEYS、__newindex、__index、__pairs、encode_lazy_object_walking
tests/lua/ordered_encode_spec.lua	新增测试文件，覆盖所有有序编码场景

---

Task 1: 添加 INTERNAL_KEYS 并创建测试文件骨架

Files:

• Modify: lua/qjson/table.lua:261-265

• Create: tests/lua/ordered_encode_spec.lua

• Step 1: 写第一个失败测试

创建 tests/lua/ordered_encode_spec.lua：

local qjson = require("qjson")

describe("ordered encode", function()
    it("preserves key order on value modification", function()
        local t = qjson.decode('{"c":3,"a":1,"b":2}')
        t.a = 100
        assert.are.equal('{"c":3,"a":100,"b":2}', qjson.encode(t))
    end)
end)

• Step 2: 运行测试确认失败

Run: cd /Users/yuanshengwang/work_git/lua-qjson && LD_LIBRARY_PATH=./target/release busted --lua=$(command -v luajit) tests/lua/ordered_encode_spec.lua --lpath='./lua/?.lua'

Expected: FAIL — key 顺序不保持（当前实现会丢失顺序）

• Step 3: 更新 INTERNAL_KEYS

在 lua/qjson/table.lua 中找到 INTERNAL_KEYS 定义（约第 261 行），修改为：

local INTERNAL_KEYS = {
    _doc = true, _cur_box = true, _cur = true, _bs = true, _be = true,
    _parent = true, _dirty = true,
    _keys = true, _values = true,
}

• Step 4: 提交

git add lua/qjson/table.lua tests/lua/ordered_encode_spec.lua
git commit -m "feat(ordered-encode): add INTERNAL_KEYS and test skeleton"

---

Task 2: 实现 LazyObject.__newindex 物化逻辑

Files:

• Modify: lua/qjson/table.lua:271-303 (LazyObject.__newindex)

• Step 1: 重写 LazyObject.__newindex

找到现有的 LazyObject.__newindex 函数（约第 271 行），完全替换为：

LazyObject.__newindex = function(t, k, v)
    -- 向上标记 dirty
    local cur = t
    while cur do
        local mt = getmetatable(cur)
        if mt ~= LazyObject and mt ~= LazyArray then break end
        rawset(cur, "_dirty", true)
        cur = rawget(cur, "_parent")
    end

    local keys = rawget(t, "_keys")
    if not keys then
        -- 首次修改：物化 key 顺序
        keys = {}
        local values = {}
        local i = 0
        while true do
            local rc = C.qjson_cursor_object_entry_at(t._cur, i, strp_box, size_box, child_box)
            if rc == QJSON_NOT_FOUND then break end
            check(rc)
            local key = ffi.string(strp_box[0], size_box[0])
            keys[#keys + 1] = key
            values[key] = decode_cursor(t, child_box)
            i = i + 1
        end
        rawset(t, "_keys", keys)
        rawset(t, "_values", values)
    end

    local values = rawget(t, "_values")
    if v == nil then
        -- 删除：从 _keys 移除
        for i, key in ipairs(keys) do
            if key == k then
                table.remove(keys, i)
                break
            end
        end
        values[k] = nil
    elseif values[k] == nil then
        -- 新 key：追加到 _keys
        keys[#keys + 1] = k
        values[k] = v
    else
        -- 已有 key：只更新值
        values[k] = v
    end
end

• Step 2: 运行测试

Run: cd /Users/yuanshengwang/work_git/lua-qjson && LD_LIBRARY_PATH=./target/release busted --lua=$(command -v luajit) tests/lua/ordered_encode_spec.lua --lpath='./lua/?.lua'

Expected: 仍然 FAIL — encode 还没使用 _keys 顺序

• Step 3: 提交

git add lua/qjson/table.lua
git commit -m "feat(ordered-encode): implement __newindex materialization"

---

Task 3: 实现 read_object_field 物化状态检查

Files:

• Modify: lua/qjson/table.lua:118-128 (read_object_field)

• Step 1: 修改 read_object_field

找到 read_object_field 函数（约第 118 行），在函数开头添加物化状态检查：

local function read_object_field(self, key)
    if type(key) ~= "string" then return nil end

    -- 检查是否已物化
    local values = rawget(self, "_values")
    if values then
        return values[key]
    end

    -- 原有 lazy 路径通过 cursor
    local rc = C.qjson_cursor_field(self._cur, key, #key, child_box)
    if not check(rc) then return nil end
    local v = decode_cursor(self, child_box)
    if type(v) == "table" then rawset(self, key, v) end
    return v
end

• Step 2: 运行测试

Run: cd /Users/yuanshengwang/work_git/lua-qjson && LD_LIBRARY_PATH=./target/release busted --lua=$(command -v luajit) tests/lua/ordered_encode_spec.lua --lpath='./lua/?.lua'

Expected: 仍然 FAIL — encode 还没使用 _keys 顺序

• Step 3: 提交

git add lua/qjson/table.lua
git commit -m "feat(ordered-encode): add materialized state check in __index"

---

Task 4: 实现 encode_lazy_object_walking 有序输出

Files:

• Modify: lua/qjson/table.lua:466-485 (encode_lazy_object_walking)

• Step 1: 修改 encode_lazy_object_walking

找到 encode_lazy_object_walking 函数（约第 466 行），替换为：

local function encode_lazy_object_walking(t)
    local keys = rawget(t, "_keys")
    if keys then
        -- 已物化：使用 _keys 顺序
        local values = rawget(t, "_values")
        local parts = {}
        for _, k in ipairs(keys) do
            local v = values[k]
            if v ~= nil then
                parts[#parts + 1] = encode_string(k) .. ":" .. encode(v)
            end
        end
        return "{" .. table.concat(parts, ",") .. "}"
    end

    -- 原有基于 cursor 的遍历（用于仅子节点 dirty 的情况）
    local parts = {}
    local i = 0
    while true do
        local rc = C.qjson_cursor_object_entry_at(t._cur, i, strp_box, size_box, child_box)
        if rc == QJSON_NOT_FOUND then break end
        check(rc)
        local k = ffi.string(strp_box[0], size_box[0])
        local cached = rawget(t, k)
        local v
        if cached ~= nil and not INTERNAL_KEYS[k] then
            v = cached
        else
            v = decode_cursor(t, child_box)
        end
        parts[#parts + 1] = encode_string(k) .. ":" .. encode(v)
        i = i + 1
    end
    return "{" .. table.concat(parts, ",") .. "}"
end

• Step 2: 运行测试确认通过

Run: cd /Users/yuanshengwang/work_git/lua-qjson && LD_LIBRARY_PATH=./target/release busted --lua=$(command -v luajit) tests/lua/ordered_encode_spec.lua --lpath='./lua/?.lua'

Expected: PASS

• Step 3: 提交

git add lua/qjson/table.lua
git commit -m "feat(ordered-encode): implement ordered encoding in encode_lazy_object_walking"

---

Task 5: 实现 LazyObject.__pairs 有序迭代

Files:

• Modify: lua/qjson/table.lua:166-168 (LazyObject.__pairs)

• Step 1: 添加 __pairs 测试

在 tests/lua/ordered_encode_spec.lua 中添加：

    it("pairs iterates in original order after modification", function()
        local t = qjson.decode('{"c":3,"a":1,"b":2}')
        t.a = 100
        local order = {}
        for k, _ in qjson.pairs(t) do
            order[#order + 1] = k
        end
        assert.are.same({"c", "a", "b"}, order)
    end)

• Step 2: 运行测试确认失败

Run: cd /Users/yuanshengwang/work_git/lua-qjson && LD_LIBRARY_PATH=./target/release busted --lua=$(command -v luajit) tests/lua/ordered_encode_spec.lua --lpath='./lua/?.lua'

Expected: FAIL — __pairs 还没使用 _keys 顺序

• Step 3: 修改 LazyObject.__pairs

找到 LazyObject.__pairs 函数（约第 166 行），替换为：

function LazyObject.__pairs(t)
    local keys = rawget(t, "_keys")
    if keys then
        local values = rawget(t, "_values")
        local i = 0
        return function()
            i = i + 1
            local k = keys[i]
            if k then return k, values[k] end
        end
    end
    return lazy_object_iter, { view = t, i = 0 }, nil
end

• Step 4: 运行测试确认通过

Run: cd /Users/yuanshengwang/work_git/lua-qjson && LD_LIBRARY_PATH=./target/release busted --lua=$(command -v luajit) tests/lua/ordered_encode_spec.lua --lpath='./lua/?.lua'

Expected: PASS

• Step 5: 提交

git add lua/qjson/table.lua tests/lua/ordered_encode_spec.lua
git commit -m "feat(ordered-encode): implement ordered __pairs iteration"

---

Task 6: 添加删除 key 测试

Files:

• Modify: tests/lua/ordered_encode_spec.lua

• Step 1: 添加删除测试

在 tests/lua/ordered_encode_spec.lua 中添加：

    it("preserves order when deleting a key", function()
        local t = qjson.decode('{"c":3,"a":1,"b":2}')
        t.a = nil
        assert.are.equal('{"c":3,"b":2}', qjson.encode(t))
    end)

    it("handles delete all keys", function()
        local t = qjson.decode('{"a":1,"b":2}')
        t.a = nil
        t.b = nil
        assert.are.equal('{}', qjson.encode(t))
    end)

• Step 2: 运行测试确认通过

Run: cd /Users/yuanshengwang/work_git/lua-qjson && LD_LIBRARY_PATH=./target/release busted --lua=$(command -v luajit) tests/lua/ordered_encode_spec.lua --lpath='./lua/?.lua'

Expected: PASS（删除逻辑已在 Task 2 实现）

• Step 3: 提交

git add tests/lua/ordered_encode_spec.lua
git commit -m "test(ordered-encode): add key deletion tests"

---

Task 7: 添加新增 key 测试

Files:

• Modify: tests/lua/ordered_encode_spec.lua

• Step 1: 添加新增 key 测试

在 tests/lua/ordered_encode_spec.lua 中添加：

    it("appends new keys to the end", function()
        local t = qjson.decode('{"c":3,"a":1}')
        t.b = 2
        assert.are.equal('{"c":3,"a":1,"b":2}', qjson.encode(t))
    end)

    it("deleted then re-added key appears at end", function()
        local t = qjson.decode('{"a":1,"b":2,"c":3}')
        t.b = nil
        t.b = 999
        assert.are.equal('{"a":1,"c":3,"b":999}', qjson.encode(t))
    end)

    it("handles empty object with additions", function()
        local t = qjson.decode('{}')
        t.a = 1
        t.b = 2
        assert.are.equal('{"a":1,"b":2}', qjson.encode(t))
    end)

• Step 2: 运行测试确认通过

Run: cd /Users/yuanshengwang/work_git/lua-qjson && LD_LIBRARY_PATH=./target/release busted --lua=$(command -v luajit) tests/lua/ordered_encode_spec.lua --lpath='./lua/?.lua'

Expected: PASS

• Step 3: 提交

git add tests/lua/ordered_encode_spec.lua
git commit -m "test(ordered-encode): add new key append tests"

---

Task 8: 添加嵌套对象和边界情况测试

Files:

• Modify: tests/lua/ordered_encode_spec.lua

• Step 1: 添加嵌套和边界测试

在 tests/lua/ordered_encode_spec.lua 中添加：

    it("handles nested object modification", function()
        local t = qjson.decode('{"x":1,"nested":{"a":1,"b":2},"y":2}')
        t.nested.a = 100
        local out = qjson.encode(t)
        assert.truthy(out:find('"x":1'))
        assert.truthy(out:find('"y":2'))
        assert.truthy(out:find('"a":100'))
    end)

    it("read before modify works correctly", function()
        local t = qjson.decode('{"a":1,"b":2,"c":3}')
        local _ = t.b  -- 先读取
        t.b = 999
        assert.are.equal('{"a":1,"b":999,"c":3}', qjson.encode(t))
    end)

    it("multiple modifications preserve order", function()
        local t = qjson.decode('{"a":1,"b":2,"c":3,"d":4}')
        t.b = 20
        t.d = 40
        t.a = 10
        assert.are.equal('{"a":10,"b":20,"c":3,"d":40}', qjson.encode(t))
    end)

• Step 2: 运行测试确认通过

Run: cd /Users/yuanshengwang/work_git/lua-qjson && LD_LIBRARY_PATH=./target/release busted --lua=$(command -v luajit) tests/lua/ordered_encode_spec.lua --lpath='./lua/?.lua'

Expected: PASS

• Step 3: 提交

git add tests/lua/ordered_encode_spec.lua
git commit -m "test(ordered-encode): add nested and edge case tests"

---

Task 9: 运行完整测试套件并验证

Files:

• None (verification only)

• Step 1: 运行完整 Lua 测试套件

Run: cd /Users/yuanshengwang/work_git/lua-qjson && make test

Expected: 所有测试通过

• Step 2: 运行 lint

Run: cd /Users/yuanshengwang/work_git/lua-qjson && make lint

Expected: 无 clippy 警告

• Step 3: 最终提交（如有遗漏）

如果有未提交的变更：

git add -A
git commit -m "chore: final cleanup for ordered-encode feature"

---

完成检查清单

• INTERNAL_KEYS 包含 _keys 和 _values
• LazyObject.__newindex 在首次修改时物化 key 顺序
• read_object_field 检查物化状态
• encode_lazy_object_walking 使用 _keys 顺序
• LazyObject.__pairs 支持物化后的有序迭代
• 所有测试通过
• 现有测试未被破坏