feat(codecs): Standard Schema wraps; remove zod codec

[SutuSebastian]

Summary

• Add ./codecs/standard-schema with sync/async PersistStorage wraps (withStandardSchema / withStandardSchemaAsync), JSON sugar factories, and standardSchemaCodec (Form-style lanes; no silent hybrid).
• Remove ./codecs/zod — migrate to any sync ~standard schema (Zod ≥3.24); Yup / Promise-returning validate → async lane (always-async hydrate — gate UI).
• Docs, homepage, architecture, and changeset updated for the new surface.

Test plan

• bun test ./src/adapters/codecs/standard-schema.test.ts (24)
• bun run typecheck / lint / format (pre-commit)
• bun run size — standard-schema under 2 kB
• Spot-check recipe + entry-points on docs site
• Confirm no remaining ./codecs/zod imports in consumers (pre-1.0 breaking)

Summary by CodeRabbit

• New Features

  • Added Standard Schema support for validating persisted data.
  • Added sync and async storage helpers for schema-gated persistence.
  • Supports schema transformations, invalid-data handling, and optional cleanup of corrupt entries.
  • Compatible with multiple Standard Schema validators, including Zod and async validators.

• Documentation

  • Replaced Zod codec guidance with Standard Schema examples and API references.
  • Added a recipe covering synchronous and asynchronous schema validation.

• Breaking Changes

  • Removed the dedicated Zod codec entry point; migrate to the Standard Schema codec.

[changeset-bot]

🦋 Changeset detected

Latest commit: 7d57e08

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@stainless-code/persist	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR replaces the Zod codec entry point with a Standard Schema implementation, adding sync and async validation wrappers, JSON storage factories, tests, package exports, build configuration, and corresponding documentation and recipe updates.

Changes

Standard Schema persistence

Layer / File(s)	Summary
Schema validation and storage integration src/adapters/codecs/standard-schema.ts	Adds Standard Schema v1 types, synchronous and asynchronous validation, standardSchemaCodec, storage wrappers, and JSON storage factories.
Codec and wrapper validation coverage src/adapters/codecs/standard-schema.test.ts	Tests round-trips, validation failures, corrupt-entry clearing, async behavior, transformations, Zod interoperability, integration, and import isolation.
Public package and build wiring package.json, tsdown.config.ts, typedoc.json, .size-limit.json, .changeset/standard-schema-codec.md	Adds the Standard Schema export and updates bundle, documentation, peer-dependency, size-limit, and release metadata.
Documentation and recipe migration apps/docs/content/..., apps/docs/pages/_home/*, docs/*	Replaces Zod references with Standard Schema guidance, entry points, examples, architecture notes, and a new sync/async recipe.

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested labels: docs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 35.71% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding Standard Schema codec wrappers and removing the Zod codec.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/standard-schema-codec

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 Checkov (3.3.8)

.size-limit.json

Traceback (most recent call last):
File "/usr/local/bin/checkov", line 2, in
from checkov.main import Checkov
ModuleNotFoundError: No module named 'checkov'

package.json

Traceback (most recent call last):
File "/usr/local/bin/checkov", line 2, in
from checkov.main import Checkov
ModuleNotFoundError: No module named 'checkov'

typedoc.json

Traceback (most recent call last):
File "/usr/local/bin/checkov", line 2, in
from checkov.main import Checkov
ModuleNotFoundError: No module named 'checkov'

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/docs/content/concepts/three-seams.mdx`:
- Line 41: Qualify the corruption-handling guarantees in both documentation
examples: in apps/docs/content/concepts/three-seams.mdx at line 41, clarify that
invalid-state discard or cleanup occurs through createStorage or the Standard
Schema wrapper, not standardSchemaCodec alone; in
apps/docs/content/recipes/standard-schema.mdx at line 8, change “deletes the
key” to indicate that removal is only attempted.

In `@src/adapters/codecs/standard-schema.test.ts`:
- Around line 493-594: Add a regression test in the “standardSchemaCodec direct
seam” block covering createStorage with clearCorruptOnFailure enabled and an
accidentally asynchronous schema. Seed a valid stored value, assert the
synchronous get throws the async-validation error, and verify the value remains
in MemoryStorage instead of being cleared.

In `@src/adapters/codecs/standard-schema.ts`:
- Around line 102-123: Update standardSchemaCodec, specifically its decode path,
to rethrow async-schema wrong-lane errors in the same way as withStandardSchema
so createStorage does not classify them as corrupt or delete data when
clearCorruptOnFailure is enabled. Add a direct seam test in
src/adapters/codecs/standard-schema.test.ts covering standardSchemaCodec with
createStorage({ clearCorruptOnFailure: true }), verifying the key remains intact
and the async validation error propagates; the existing wrapper protection needs
no separate change.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4f96ae11-9fcc-41b8-aa4f-98ab6be7d57a

📥 Commits

Reviewing files that changed from the base of the PR and between 18761b4 and 7d57e08.

📒 Files selected for processing (25)

• .changeset/standard-schema-codec.md
• .size-limit.json
• apps/docs/content/adapters/index.mdx
• apps/docs/content/concepts/choosing-codec.mdx
• apps/docs/content/concepts/entry-points.mdx
• apps/docs/content/concepts/index.mdx
• apps/docs/content/concepts/three-seams.mdx
• apps/docs/content/recipes/index.mdx
• apps/docs/content/recipes/meta.ts
• apps/docs/content/recipes/standard-schema.mdx
• apps/docs/content/recipes/zod.mdx
• apps/docs/content/reference/api/index.mdx
• apps/docs/content/reference/api/meta.ts
• apps/docs/pages/_home/Batteries.astro
• apps/docs/pages/_home/Seams.astro
• apps/docs/pages/_home/UseCases.astro
• docs/architecture.md
• docs/plans/upstream-tanstack-pitch.md
• package.json
• src/adapters/codecs/standard-schema.test.ts
• src/adapters/codecs/standard-schema.ts
• src/adapters/codecs/zod.test.ts
• src/adapters/codecs/zod.ts
• tsdown.config.ts
• typedoc.json

💤 Files with no reviewable changes (3)

• src/adapters/codecs/zod.test.ts
• src/adapters/codecs/zod.ts
• apps/docs/content/recipes/zod.mdx