kevinschaffter/stork

README

Stork Tools

A collection of type-safe and validated storage wrappers using Zod schemas. Enjoy the benefits of runtime validation, automatic type inference, and better developer experience when working with storage APIs across different platforms.

✨ Features

Both packages share these core features:

🛡️ Type Safety: Full TypeScript support with automatic type inference from Zod schemas
✅ Runtime Validation: Automatic validation of stored/retrieved data using Zod schemas
🔒 Strict Mode: Strict mode enabled by default to prevent access to undefined keys
🧹 Error Handling: Configurable behavior for invalid data (clear or throw)
🚀 Zero Runtime Overhead: Only validates data when schemas are provided
🔄 Drop-in Replacement: Maintains the same API as the underlying storage with added type safety
🔄 Incremental Adoption: Start with a single schema and add more later
🪝 React Hooks: Optional React hooks for seamless integration

📦 Packages

This monorepo contains two complementary packages for type-safe storage solutions:

@stork-tools/zod-async-storage

For React Native & Expo applications

A type-safe wrapper around @react-native-async-storage/async-storage with Zod validation. Perfect for mobile development with React Native and Expo.

@stork-tools/zod-local-storage

For Web & Browser applications

A type-safe wrapper around the browser's localStorage API with Zod validation. Ideal for web applications requiring client-side persistence.

📖 Getting Started

Each package includes comprehensive documentation with installation instructions, API reference, and examples:

AsyncStorage: See the zod-async-storage README
localStorage: See the zod-local-storage README

🤝 Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or sharing feedback, your help makes this project better.

Quick Start for Contributors

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/stork.git
cd stork

Install dependencies:
```
pnpm install
```

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes following our coding standards
Add a changeset (for user-facing changes):
```
pnpm changeset
```
Commit and push your changes
Open a Pull Request - CI will handle testing and validation

Types of Contributions

🐛 Bug Reports: Use our bug report template
✨ Feature Requests: Use our feature request template
💻 Code Contributions: Follow our coding standards and include tests
📚 Documentation: Help improve our docs and examples
🧪 Testing: Add or improve test coverage
💬 Discussions: Share ideas in GitHub Discussions

Key Guidelines

Type Safety: No any types, use type guards over casting
Testing: Include tests for new features and bug fixes
Changesets: Run pnpm changeset for user-facing changes
Code Style: Follow existing patterns, JSDoc for public APIs

For detailed contributing guidelines, see CONTRIBUTING.md.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Zod for the excellent schema validation library
React Native AsyncStorage for the underlying storage implementation