zod_rails 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7f965cc7e0d0a036e1880f54359e0ffc173723d34016050d818adc7dc2fd3838
+  data.tar.gz: f8c5c18a640bc5820d98360b4964b3e6486ecaefc6395de1ae26c6090daa70b3
+SHA512:
+  metadata.gz: 80e23eafed4d17da2f08bf74b469210754c76bb5cfd917b745d68e6ff14dd609a48c59bb0dd6560017dd8e926548a6052e35e09879f03ffc1fb6ae4948a3be7d
+  data.tar.gz: 1fded1d84ceb8d517838e7a0cd697846fe4c1f2636852d270af80ec4e6e7c5534bb86461b0c011d83db87c8532e5302b8065a7a6d9a31acd0896cbc86caa4b6f

data/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [trunk]
+  pull_request:
+    branches: [trunk]
+  workflow_call:
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['3.2', '3.3', '3.4']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rspec --format documentation
+
+      - name: Run linter
+        run: bundle exec rubocop --parallel

data/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    needs: test
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Build gem
+        run: gem build *.gemspec
+
+      - name: Publish to RubyGems
+        uses: rubygems/release-gem@v1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ZodRails Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,282 @@
+<p align="center">
+  <img src="zod_rails.png" alt="ZodRails" width="400">
+</p>
+
+<p align="center">
+  <a href="https://github.com/mathisto/zod_rails/actions/workflows/ci.yml"><img src="https://github.com/mathisto/zod_rails/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://rubygems.org/gems/zod_rails"><img src="https://img.shields.io/gem/v/zod_rails.svg?style=flat" alt="Gem Version"></a>
+  <a href="https://rubygems.org/gems/zod_rails"><img src="https://img.shields.io/gem/dt/zod_rails.svg?style=flat" alt="Downloads"></a>
+  <a href="https://github.com/mathisto/zod_rails/blob/trunk/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+  <img src="https://img.shields.io/badge/ruby-%3E%3D%203.2-red.svg" alt="Ruby 3.2+">
+  <img src="https://img.shields.io/badge/rails-%3E%3D%207.0-red.svg" alt="Rails 7.0+">
+  <img src="https://img.shields.io/badge/zod-4.x-3068b7.svg" alt="Zod 4">
+</p>
+
+<p align="center">
+  <strong>Generate Zod schemas from ActiveRecord models</strong><br>
+  Bridge the gap between your Rails backend and TypeScript frontend with type-safe validation.
+</p>
+
+---
+
+Generate [Zod](https://zod.dev) schemas from your ActiveRecord models. Bridge the gap between your Rails backend and TypeScript frontend with type-safe validation that stays in sync with your database schema and model validations.
+
+## Why ZodRails?
+
+When building Rails APIs consumed by TypeScript frontends, you often duplicate validation logic: once in your Rails models, again in your frontend forms. ZodRails eliminates this duplication by generating Zod schemas directly from your ActiveRecord models, including:
+
+- Database column types mapped to Zod types
+- Rails validations (presence, length, numericality, format) mapped to Zod constraints
+- Enums generated as `z.enum()` with proper string literals
+- Nullable columns and default values handled correctly
+- Separate schemas for API responses vs. form inputs
+
+## Requirements
+
+- Ruby 3.2+
+- Rails 7.0+ (uses ActiveRecord and Railtie)
+- Zod 4.x in your frontend project
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "zod_rails"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### 1. Configure the gem
+
+Create an initializer at `config/initializers/zod_rails.rb`:
+
+```ruby
+ZodRails.configure do |config|
+  config.output_dir = Rails.root.join("app/javascript/schemas").to_s
+  config.models = %w[User Post Comment]
+end
+```
+
+### 2. Generate schemas
+
+```bash
+bin/rails zod_rails:generate
+```
+
+### 3. Use in your frontend
+
+```typescript
+import { UserSchema, UserInputSchema, type User } from "./schemas/user";
+
+// Validate API response
+const user = UserSchema.parse(apiResponse);
+
+// Validate form input
+const formData = UserInputSchema.parse(formValues);
+```
+
+## Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `output_dir` | `app/javascript/schemas` | Directory for generated TypeScript files |
+| `models` | `[]` | Array of model names to generate schemas for |
+| `schema_suffix` | `Schema` | Suffix for response schemas (e.g., `UserSchema`) |
+| `input_schema_suffix` | `InputSchema` | Suffix for input schemas (e.g., `UserInputSchema`) |
+| `generate_input_schemas` | `true` | Whether to generate input schemas |
+| `excluded_columns` | `["id", "created_at", "updated_at"]` | Columns to exclude from input schemas |
+
+### Full Configuration Example
+
+```ruby
+ZodRails.configure do |config|
+  config.output_dir = Rails.root.join("frontend/src/schemas").to_s
+  config.models = %w[User Post Comment Tag]
+  config.schema_suffix = "Schema"
+  config.input_schema_suffix = "FormSchema"
+  config.generate_input_schemas = true
+  config.excluded_columns = %w[id created_at updated_at deleted_at]
+end
+```
+
+## Type Mappings
+
+| Rails/DB Type | Zod Type |
+|---------------|----------|
+| `string`, `text` | `z.string()` |
+| `integer`, `bigint` | `z.int()` |
+| `float`, `decimal` | `z.number()` |
+| `boolean` | `z.boolean()` |
+| `date` | `z.iso.date()` |
+| `datetime`, `timestamp` | `z.iso.datetime()` |
+| `json`, `jsonb` | `z.json()` |
+| `uuid` | `z.uuid()` |
+| `enum` | `z.enum([...])` |
+
+## Validation Mappings
+
+ZodRails introspects your model validations and maps them to Zod constraints:
+
+| Rails Validation | Zod Constraint |
+|------------------|----------------|
+| `presence: true` | `.min(1)` for strings |
+| `length: { minimum: n }` | `.min(n)` |
+| `length: { maximum: n }` | `.max(n)` |
+| `length: { is: n }` | `.length(n)` |
+| `numericality: { greater_than: n }` | `.gt(n)` |
+| `numericality: { greater_than_or_equal_to: n }` | `.gte(n)` |
+| `numericality: { less_than: n }` | `.lt(n)` |
+| `numericality: { less_than_or_equal_to: n }` | `.lte(n)` |
+| `format: { with: /regex/ }` | `.regex(/regex/)` |
+| `inclusion: { in: n..m }` | `.min(n).max(m)` |
+
+## Generated Output Example
+
+Given this Rails model:
+
+```ruby
+class User < ApplicationRecord
+  enum :role, { member: 0, admin: 1, moderator: 2 }
+
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :name, presence: true, length: { minimum: 2, maximum: 100 }
+  validates :age, numericality: { greater_than: 0, less_than: 150 }, allow_nil: true
+end
+```
+
+ZodRails generates:
+
+```typescript
+import { z } from "zod";
+
+export const UserSchema = z.object({
+  id: z.int(),
+  email: z.string().min(1).regex(/\A[^@\s]+@[^@\s]+\z/),
+  name: z.string().min(2).max(100),
+  age: z.int().gt(0).lt(150).nullable(),
+  role: z.enum(["member", "admin", "moderator"]),
+  created_at: z.iso.datetime(),
+  updated_at: z.iso.datetime()
+});
+
+export type User = z.infer<typeof UserSchema>;
+
+export const UserInputSchema = z.object({
+  email: z.string().min(1).regex(/\A[^@\s]+@[^@\s]+\z/),
+  name: z.string().min(2).max(100),
+  age: z.int().gt(0).lt(150).nullish(),
+  role: z.enum(["member", "admin", "moderator"]).optional()
+});
+
+export type UserInput = z.infer<typeof UserInputSchema>;
+```
+
+## Schema vs InputSchema
+
+ZodRails generates two schema variants:
+
+**Schema** (e.g., `UserSchema`)
+- Represents data as returned from your API
+- Includes all columns (`id`, timestamps, etc.)
+- Uses `.nullable()` for nullable columns
+
+**InputSchema** (e.g., `UserInputSchema`)
+- Represents data for form submission
+- Excludes configured columns (defaults: `id`, `created_at`, `updated_at`)
+- Uses `.optional()` for columns with database defaults
+- Uses `.nullish()` for nullable columns without defaults
+
+## Integrating with Forms
+
+ZodRails pairs well with form libraries that support Zod:
+
+### React Hook Form
+
+```typescript
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { UserInputSchema, type UserInput } from "./schemas/user";
+
+function UserForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm<UserInput>({
+    resolver: zodResolver(UserInputSchema)
+  });
+
+  const onSubmit = (data: UserInput) => {
+    // data is fully typed and validated
+  };
+
+  return <form onSubmit={handleSubmit(onSubmit)}>...</form>;
+}
+```
+
+### Validating API Responses
+
+```typescript
+import { UserSchema, type User } from "./schemas/user";
+
+async function fetchUser(id: number): Promise<User> {
+  const response = await fetch(`/api/users/${id}`);
+  const data = await response.json();
+  return UserSchema.parse(data); // Throws if invalid
+}
+```
+
+## CI/CD Integration
+
+Add schema generation to your build process to catch type mismatches early:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Generate Zod schemas
+  run: bin/rails zod_rails:generate
+
+- name: Check for uncommitted schema changes
+  run: git diff --exit-code app/javascript/schemas/
+```
+
+## Troubleshooting
+
+### Schemas not updating after model changes
+
+Re-run the generator after any model changes:
+
+```bash
+bin/rails zod_rails:generate
+```
+
+### Validation constraints not appearing
+
+Ensure validations are defined on the model class, not in concerns that might not be loaded. Conditional validations (`:if`, `:unless`) are detected and excluded by default.
+
+### Custom column types
+
+For custom types not in the mapping table, ZodRails falls back to `z.unknown()`. Open an issue if you need support for additional types.
+
+## Development
+
+After checking out the repo:
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes (`git commit -am 'Add my feature'`)
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Create a Pull Request
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]