gem-hunter

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.

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

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

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.

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.

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

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

1. Fork the repository on GitHub
2. Clone your fork locally:

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

3. Install dependencies:

   pnpm install

4. Create a feature branch:

   git checkout -b feature/your-feature-name

5. Make your changes following our coding standards
6. Add a changeset (for user-facing changes):

   pnpm changeset

7. Commit and push your changes
8. Open a Pull Request - CI will handle testing and validation

• 🐛 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

• 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.

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

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