Add KV storage facet

[jmoseley]

Summary

• implement new key-value storage API under gensx-storage
• support filesystem-backed KV with TTL handling
• provide KVClient and useKV helpers
• export KV facet in package index
• add basic tests for the KV filesystem implementation and usage helpers

Testing

• pnpm lint
• pnpm test (fails: create-gensx#test)
• pnpm format

---

https://chatgpt.com/codex/tasks/task_e_6841deb474f0832c81a09484e22d2581

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

2 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
gensx-docs	⬜️ Skipped (Inspect)			Jun 5, 2025 6:37pm
gensx-home	⬜️ Skipped (Inspect)			Jun 5, 2025 6:37pm

[cursor]

Bug: Incorrect `rootDir` Handling in Configuration

The condition for using a provided rootDir incorrectly checks options.kind instead of the determined kind variable. If options.kind is undefined but kind defaults to "filesystem", a provided options.rootDir is ignored, and the default directory is used instead.

packages/gensx-storage/src/kv/kvClient.ts#L16-L20

gensx/packages/gensx-storage/src/kv/kvClient.ts

Lines 16 to 20 in 74db3c5

	if (kind === "filesystem") {
	const rootDir =
	options.kind === "filesystem" && options.rootDir
	? options.rootDir
	: join(process.cwd(), ".gensx", "kv");

Fix in Cursor

---

Bug: Expired Keys Included, Inefficient File Reads

The listKeys method incorrectly includes expired keys in its results. Although the get() method correctly deletes expired files, listKeys still adds the key to the list. Additionally, listKeys reads each file twice, which is inefficient and creates a race condition where the second read can fail if the file is deleted after the first read (e.g., by the initial get() call), causing the operation to error.

packages/gensx-storage/src/kv/filesystem.ts#L110-L126

gensx/packages/gensx-storage/src/kv/filesystem.ts

Lines 110 to 126 in 74db3c5

	const keys = await Promise.all(
	page.map(async (file) => {
	const key = file.slice(0, -5);
	const kv = this.getKV(key);
	const content = await kv.get();
	const exists = content !== null;
	let expiresAt: Date | undefined;
	if (exists) {
	const raw = JSON.parse(
	await fs.readFile(path.join(this.rootDir, file), "utf8"),
	) as { expiresAt?: number };
	if (raw.expiresAt) expiresAt = new Date(raw.expiresAt);
	}
	return { key, expiresAt };
	}),
	);

Fix in Cursor

---

BugBot free trial expires on June 9, 2025
Your team has used $0.00 of the $50.00 spend limit so far. Team admins can manage spend limit in the Cursor dashboard.

Was this report helpful? Give feedback by reacting with 👍 or 👎

[github-actions]

Hey mate 👋. Thank you for opening this Pull Request 🤘. It is really awesome to see this contribution 🚀

🔎 When working with this project we are requesting to follow the Conventional Commits specification and it looks like your proposed title needs to be adjusted 🥶.

👇 Bellow you can find details about what failed:

No release type found in pull request title "Add KV storage facet". Add a prefix to indicate what kind of release this pull request corresponds to. For reference, see https://www.conventionalcommits.org/

Available types:
 - feat: A new feature
 - fix: A bug fix
 - docs: Documentation only changes
 - style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
 - refactor: A code change that neither fixes a bug nor adds a feature
 - perf: A code change that improves performance
 - test: Adding missing tests or correcting existing tests
 - build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
 - ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
 - chore: Other changes that don't modify src or test files
 - revert: Reverts a previous commit