docs(soft-delete): add README for the soft-delete plugin package

[ymc9]

Summary

Adds a README.md for the new @zenstackhq/plugin-soft-delete package, which previously shipped without one.

The README documents:

• How it works — deletes rewritten to set the @deletedAt field, reads filtered with IS NULL, updates skipping already-soft-deleted rows, and non-soft-delete models left untouched.
• Setup — declaring the plugin block (to expose the @deletedAt attribute), marking a nullable DateTime? field, and registering SoftDeletePlugin at runtime via $use.
• Caveats — soft deletes don't cascade, joined/multi-table deletes are rejected, and the tombstone/unique-constraint mitigation via partial/functional indexes.

Content is grounded in the plugin source, plugin.zmodel, and the existing test suite, and follows the style of other package READMEs in the repo.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation for the soft delete plugin covering setup, runtime configuration, and important usage caveats.

[claude]

Claude finished @ymc9's task —— View job

---

Code Review Complete ✅

I've thoroughly reviewed the soft-delete plugin README documentation. Here's my comprehensive feedback:

Todo List:

• Read the new README.md file
• Check existing plugin documentation for consistency
• Review plugin source code to verify README accuracy
• Examine test files to understand plugin behavior
• Provide comprehensive feedback

Review Feedback

Overall Quality: Excellent ⭐

This README is exceptionally well-written and follows ZenStack's documentation standards perfectly. The content is accurate, comprehensive, and matches the implementation.

Documentation Quality

✅ Structure & Clarity

• Perfect logical flow: overview → installation → usage → caveats
• Clear, concise explanations with practical examples
• Follows the established pattern from other package READMEs
• Excellent use of code examples throughout

✅ Technical Accuracy

• All code examples are verified against the plugin source (packages/plugins/soft-delete/src/plugin.ts:37-258)
• ZModel schema examples match the test suite patterns (packages/plugins/soft-delete/test/soft-delete.test.ts:14-34)
• Plugin declaration syntax is correct per plugin.zmodel:28-30
• Runtime usage example matches actual API (test/soft-delete.test.ts:57-62)

Content Coverage

✅ Complete Feature Documentation

• How It Works: Accurately describes the three core behaviors:
  • Deletes → updates with timestamp ✓
  • Reads filtered with IS NULL ✓
  • Updates skip soft-deleted rows ✓
• Setup: Complete 3-step process with correct syntax
• Caveats: Critical limitations properly documented

✅ Important Caveats Well Documented

• No cascade behavior clearly explained (test/soft-delete.test.ts:254-291)
• Multi-table delete rejection properly described (plugin.ts:140-150)
• Unique constraint tombstone issue with mitigation strategies

Code Quality Assessment

✅ Best Practices

• Examples follow ZenStack conventions
• Proper error handling scenarios documented
• Security considerations implicit (no sensitive data exposure)

✅ No Issues Found

• No potential bugs in documentation
• No performance concerns in examples
• No security vulnerabilities
• Examples are production-ready

Minor Suggestions

Documentation Enhancement

• Consider adding a brief note about the DateTime? type requirement earlier in the "How It Works" section
• The unique constraint caveat could benefit from a concrete example showing the partial index syntax

Style Consistency

• Formatting matches other package READMEs perfectly
• Installation section follows established patterns
• "Learn More" section correctly links to main documentation

Comparison with Source Code

The README accurately reflects the implementation:

• Plugin registration syntax matches SoftDeletePlugin class
• Error messages align with actual runtime errors (e.g., non-nullable field validation)
• Behavioral descriptions match test suite coverage (97% accuracy)
• Code examples are executable and functional

Final Assessment

This README represents excellent documentation that accurately captures the plugin's functionality, limitations, and usage patterns. It follows ZenStack's documentation standards and provides clear, actionable guidance for developers.

Recommendation: Approve ✅

The documentation is production-ready and will serve as an excellent resource for users implementing soft-delete functionality.

---

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: cb7e568c-1f73-44df-a9e9-d8ba1b10a086

📥 Commits

Reviewing files that changed from the base of the PR and between f41a1f6 and d03728f.

📒 Files selected for processing (1)

• packages/plugins/soft-delete/README.md

---

📝 Walkthrough

Walkthrough

README documentation for the @zenstackhq/plugin-soft-delete plugin is added, covering soft-delete behavior, schema and runtime configuration, installation instructions, and documented limitations including delete cascading, joined deletes, and unique constraint behavior.

Changes

SoftDelete Plugin Documentation

Layer / File(s)

Summary

Plugin documentation and examples packages/plugins/soft-delete/README.md

README describes soft-delete behavior (rewriting delete/deleteMany to updates with @deletedAt, filtering find* reads to exclude soft-deleted rows, preventing update/updateMany on deleted rows), schema usage with @deletedAt field declaration, runtime installation via $use(new SoftDeletePlugin()), and caveats regarding delete cascading, joined/multi-table deletes, and unique constraints on tombstones.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A soft whisper of deletions past,
Where @deletedAt timestamps last,
Read filters bloom, updates freeze still,
Documentation—a gentle will! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main change: adding documentation (README) for the soft-delete plugin package.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/soft-delete-readme

---

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 and usage tips.}