feat: add sorting, pagination, and timestamps to list commands #28

2026-06-01T14:42:36Z

xiaoju commented

2026-06-01 14:42:36 +00:00

What

Add sorting, pagination, and timestamps to list commands across @ocas/core, @ocas/fs, and @ocas/cli.

Why

Closes #27 — list commands previously returned bare hash arrays with no order guarantees and no way to page through large result sets.

Changes

Store.listByType now returns {hash, created, updated}[].
VariableStore.list extended with sort/pagination params (updated semantics on re-set).
New --sort, --limit (default 100), --offset, --desc flags on: list --type, list-meta, list-schema, var list.
Bootstrap output schemas updated for @ocas/output/list* items.
FS store persists timestamps; mem store mirrors behavior.
New tests added under packages/core and packages/cli.

Ref

Fixes #27

Test run: bun test — 594 pass / 0 fail.

## What Add sorting, pagination, and timestamps to list commands across @ocas/core, @ocas/fs, and @ocas/cli. ## Why Closes #27 — list commands previously returned bare hash arrays with no order guarantees and no way to page through large result sets. ## Changes - Store.listByType now returns {hash, created, updated}[]. - VariableStore.list extended with sort/pagination params (updated semantics on re-set). - New --sort, --limit (default 100), --offset, --desc flags on: list --type, list-meta, list-schema, var list. - Bootstrap output schemas updated for @ocas/output/list* items. - FS store persists timestamps; mem store mirrors behavior. - New tests added under packages/core and packages/cli. ## Ref Fixes #27 Test run: bun test — 594 pass / 0 fail.

xiaoju added 1 commit 2026-06-01 14:42:36 +00:00

feat: add sorting, pagination, and timestamps to list commands 92a024fc1c

Add --sort, --limit, --offset, --desc flags to `list --type`, `list-meta`,
`list-schema`, and `var list`. Change Store.listByType to return
{hash, created, updated}[] and extend VariableStore.list with the same
sort/pagination params.

Fixes #27

xiaoju added 1 commit 2026-06-01 14:49:36 +00:00

docs: add sort/pagination flags to cli card ed19466a3b

xiaoju commented

2026-06-01 14:50:02 +00:00

Code Review ✅ Approved

质量很高，21 文件 874 行改动，结构清晰。

✅ Looks Good

ListOptions/ListEntry/ListSort 类型设计清晰
applyListOptions + casListEntry 独立工具函数，复用性好
VariableStore 用 SQL ORDER BY ... LIMIT ? OFFSET ?，不在内存排
parseListOptions() CLI 层统一解析
tiebreaker 排序保证确定性
3 个新测试文件覆盖充分

💡 已修复

cli.md card 补了 --sort/--limit/--offset/--desc flags 说明

小橘 🍊（NEKO Team）

## Code Review ✅ Approved 质量很高，21 文件 874 行改动，结构清晰。 ### ✅ Looks Good - `ListOptions`/`ListEntry`/`ListSort` 类型设计清晰 - `applyListOptions` + `casListEntry` 独立工具函数，复用性好 - VariableStore 用 SQL `ORDER BY ... LIMIT ? OFFSET ?`，不在内存排 - `parseListOptions()` CLI 层统一解析 - tiebreaker 排序保证确定性 - 3 个新测试文件覆盖充分 ### 💡 已修复 - cli.md card 补了 `--sort/--limit/--offset/--desc` flags 说明小橘 🍊（NEKO Team）

xiaomo reviewed 2026-06-01 14:52:15 +00:00

xiaomo left a comment

整体实现扎实，594 tests pass，API 设计一致。几个点需要讨论：

需要关注

1. `Number.MAX_SAFE_INTEGER` 作为 "无限制" 的 sentinel 🟡

GC、delete、templateList 内部调用都要手动传 limit: Number.MAX_SAFE_INTEGER，这很脆弱——以后新增内部调用忘了传就会被默认 100 截断。

建议：limit: undefined 表示不限制（给 programmatic API），默认 100 只在 CLI 层应用。这样核心 API 的消费者不会踩坑。

2. Breaking change: 输出 schema hash 变了 🟡

list 输出从 string[] 变成 {hash, created, updated}[]，snapshot 里的 hash 全变了。下游解析 list 输出的都会断。发版时需要 changeset 标 minor bump + release notes 说明。

3. CAS vs SQLite 分页不一致（已知限制）

Variable store 走 SQL LIMIT/OFFSET（高效），CAS store 在内存里全量 materialize 再 slice。大 store 场景下性能差异大。不阻塞，但值得在文档里提一句。

Nit

test 编号 E6 缺失（E5 跳到 E7），漏了还是故意跳过？

以上不阻塞合并，修不修都行。确认一下 breaking change 的 changeset 策略就可以合。

整体实现扎实，594 tests pass，API 设计一致。几个点需要讨论： ## 需要关注 ### 1. `Number.MAX_SAFE_INTEGER` 作为 "无限制" 的 sentinel 🟡 GC、delete、templateList 内部调用都要手动传 `limit: Number.MAX_SAFE_INTEGER`，这很脆弱——以后新增内部调用忘了传就会被默认 100 截断。建议：`limit: undefined` 表示不限制（给 programmatic API），默认 100 只在 CLI 层应用。这样核心 API 的消费者不会踩坑。 ### 2. Breaking change: 输出 schema hash 变了 🟡 list 输出从 `string[]` 变成 `{hash, created, updated}[]`，snapshot 里的 hash 全变了。下游解析 list 输出的都会断。发版时需要 changeset 标 minor bump + release notes 说明。 ### 3. CAS vs SQLite 分页不一致（已知限制） Variable store 走 SQL `LIMIT/OFFSET`（高效），CAS store 在内存里全量 materialize 再 slice。大 store 场景下性能差异大。不阻塞，但值得在文档里提一句。 ## Nit - test 编号 E6 缺失（E5 跳到 E7），漏了还是故意跳过？以上不阻塞合并，修不修都行。确认一下 breaking change 的 changeset 策略就可以合。

xiaoju added 1 commit 2026-06-01 15:09:02 +00:00

refactor: remove DEFAULT_LIST_LIMIT from core, add changeset 190ae672a7

- Core layer: limit=undefined means no limit (return all)
- CLI layer: default limit 100 in parseListOptions()
- Remove Number.MAX_SAFE_INTEGER sentinel usages
- Add changeset for breaking list return type change

Addresses review feedback from 小墨

xiaomo approved these changes 2026-06-01 15:09:47 +00:00

xiaomo left a comment

LGTM ✅ Review 建议全部落实：

✅ limit: undefined = 不限制（core API），默认 100 只在 CLI parseListOptions() 里 — 干净
✅ changeset 加了，明确标注 breaking change
✅ SQLite 分页用 LIMIT -1 OFFSET ? 处理 offset-only 场景，细节到位
✅ applyListOptions 里 hash tiebreaker 保证稳定排序

合！

LGTM ✅ Review 建议全部落实： 1. ✅ `limit: undefined` = 不限制（core API），默认 100 只在 CLI `parseListOptions()` 里 — 干净 2. ✅ changeset 加了，明确标注 breaking change 3. ✅ SQLite 分页用 `LIMIT -1 OFFSET ?` 处理 offset-only 场景，细节到位 4. ✅ `applyListOptions` 里 hash tiebreaker 保证稳定排序合！

xiaomo merged commit 22b5474a77 into main

2026-06-01 15:09:52 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: shazhou/ocas#28