typed_enums 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: feccb1b7155c9c0bce08aca4c171c1368f9a07082962903378e925eede8087e7
+  data.tar.gz: ce34f0912b5fa25ea49e3187798b81f776bfd2b755ca4284a466659fd4639378
+SHA512:
+  metadata.gz: 48c3acf6c06bd274037335c9989e8021dbd3128dc65d5386699135caeea03b9ef4608fe9abd3faca189af1cc355efc0e74dc754502540a95885ba544dea5f1f3
+  data.tar.gz: 7f1e5519b3742de53309e81cdc28f5b70ee25e5e34ce897bcd7d13d51bffd346962d256cb6aa2d2ab4ce22eafb6ee396d03bd5ee95bef7f1e70b6019f7333b44

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial implementation of Active Record enum scanning and TypeScript generation.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 typed_enums 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,328 @@
+# typed_enums
+
+Use Rails enums in JavaScript and TypeScript without duplicating option lists.
+
+`typed_enums` is a Rails enum generator for JavaScript and TypeScript frontends. It exports Active Record enums to JavaScript constants and TypeScript declaration types, giving any frontend a Rails-like way to consume enum values.
+
+Rails routes have `js-routes`. Rails serializers have serializer type generators. Rails enums now have `typed_enums`.
+
+## What It Does
+
+`typed_enums` scans loaded Active Record models, reads `defined_enums`, and writes one generated JavaScript module plus a TypeScript declaration file:
+
+```text
+app/javascript/lib/enums.js
+app/javascript/lib/enums.d.ts
+```
+
+It works with React, Vue, Svelte, API-only Rails apps, plain JavaScript, or any TypeScript frontend. The primary runtime output is plain JavaScript. No frontend framework, bundler, or TypeScript runtime package is required by the gem itself.
+
+## What It Does Not Do
+
+This gem is not a serializer, OpenAPI generator, route helper generator, form builder, or enum replacement. It does not generate React components, Vue components, Svelte components, migrations, or runtime enum editing tools.
+
+## Installation
+
+Add the gem:
+
+```ruby
+# Gemfile
+gem "typed_enums"
+```
+
+Install and generate the initializer:
+
+```bash
+bundle install
+bin/rails generate typed_enums:install
+bin/rails typed_enums:generate
+```
+
+## Rails Setup
+
+Given a Rails model:
+
+```ruby
+class Task < ApplicationRecord
+  enum :work_priority, {
+    priority_1: 0,
+    priority_2: 1,
+    priority_3: 2,
+    priority_4: 3
+  }
+end
+```
+
+The generated JavaScript can be imported from the generated module:
+
+```ts
+import { Task } from "@/lib/enums";
+
+Task.workPriorities;
+```
+
+## Generated JavaScript
+
+The gem writes one JavaScript module containing every model enum:
+
+```js
+// AUTO-GENERATED BY typed_enums. DO NOT EDIT.
+// enum-schema-sha256: abc123
+
+export const Task = {
+  workPriorities: ["priority_1", "priority_2", "priority_3", "priority_4"],
+};
+```
+
+It also writes `enums.d.ts` for TypeScript users:
+
+```ts
+// AUTO-GENERATED BY typed_enums. DO NOT EDIT.
+// enum-schema-sha256: abc123
+
+export declare const Task: {
+  readonly workPriorities: readonly ["priority_1", "priority_2", "priority_3", "priority_4"];
+};
+
+export type TaskWorkPriority = (typeof Task.workPriorities)[number];
+```
+
+## Naming
+
+Rails exposes enum mappings through pluralized methods, such as `Task.work_priorities`. `typed_enums` mirrors that convention in camelCase:
+
+| Rails enum attribute | Rails mapping method | TypeScript property | TypeScript type |
+| --- | --- | --- | --- |
+| `ticket_status` | `ticket_statuses` | `ticketStatuses` | `TaskTicketStatus` |
+| `work_priority` | `work_priorities` | `workPriorities` | `TaskWorkPriority` |
+| `fix_priority` | `fix_priorities` | `fixPriorities` | `TaskFixPriority` |
+| `severity` | `severities` | `severities` | `TaskSeverity` |
+| `urgency` | `urgencies` | `urgencies` | `TaskUrgency` |
+
+This naming is intentionally not configurable in v1.
+
+## Type Usage
+
+```ts
+import { Task, type TaskWorkPriority } from "@/lib/enums";
+
+function setPriority(priority: TaskWorkPriority) {
+  return priority;
+}
+```
+
+## React
+
+```tsx
+import { Task, type TaskWorkPriority } from "@/lib/enums";
+
+export function PrioritySelect(props: {
+  value: TaskWorkPriority;
+  onChange: (value: TaskWorkPriority) => void;
+}) {
+  return (
+    <select value={props.value} onChange={(event) => props.onChange(event.target.value as TaskWorkPriority)}>
+      {Task.workPriorities.map((value) => (
+        <option key={value} value={value}>
+          {value}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+## Vue
+
+```vue
+<script setup lang="ts">
+import { Task, type TaskWorkPriority } from "@/lib/enums";
+
+const model = defineModel<TaskWorkPriority>();
+</script>
+
+<template>
+  <select v-model="model">
+    <option v-for="value in Task.workPriorities" :key="value" :value="value">
+      {{ value }}
+    </option>
+  </select>
+</template>
+```
+
+## Svelte Or Plain TypeScript
+
+```ts
+import { Task, type TaskWorkPriority } from "@/lib/enums";
+
+export const priorityOptions = Task.workPriorities.map((value: TaskWorkPriority) => ({
+  value,
+  label: value,
+}));
+```
+
+## Plain JavaScript
+
+```js
+import { Task } from "@/lib/enums";
+
+export const priorityOptions = Task.workPriorities.map((value) => ({
+  value,
+  label: value,
+}));
+```
+
+## i18n Labels
+
+The generated values are intentionally raw enum values. Use your frontend i18n layer to label them:
+
+```ts
+import { Task } from "@/lib/enums";
+
+Task.workPriorities.map((value) => ({
+  value,
+  label: t(`enums.task.workPriorities.${value}`),
+}));
+```
+
+Example keys:
+
+```json
+{
+  "enums": {
+    "task": {
+      "workPriorities": {
+        "priority_1": "P1",
+        "priority_2": "P2"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+The installer creates `config/initializers/typed_enums.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+TypedEnums.configure do |config|
+  config.output_dir = "app/javascript/lib"
+  config.root_model_class = "ApplicationRecord"
+  config.auto_generate_in_development = true
+  config.watch_models_in_development = true
+end
+```
+
+Keep the output directory isolated and import generated code from that directory. The generator never appends to user-owned frontend files.
+
+## Rake Tasks
+
+Generate files:
+
+```bash
+bin/rails typed_enums:generate
+```
+
+Check files in CI:
+
+```bash
+bin/rails typed_enums:check
+```
+
+The check task exits non-zero when files are missing, changed, or stale. It does not modify files.
+
+Watch model files and regenerate after saves:
+
+```bash
+bin/rails typed_enums:watch
+```
+
+This is useful when you want generated enum files to update immediately after saving a Rails model in VS Code without relying on a running Rails server.
+
+## Development Auto-Regeneration
+
+In development, generation runs on Rails boot and through `Rails.application.reloader.to_prepare` when `auto_generate_in_development` is enabled.
+
+When `watch_models_in_development` is enabled, `typed_enums` also watches `app/models/**/*.rb` and regenerates enum files after model saves. This covers normal VS Code save workflows while the Rails development process is running. If you are not running Rails, use `bin/rails typed_enums:watch` in a separate terminal.
+
+The writer compares content before writing, so unchanged files are not rewritten and file watchers should stay quiet.
+
+Production does not auto-write files by default. Run `bin/rails typed_enums:generate` as part of your build or release process when generated enum files are not committed.
+
+## Stale File Cleanup
+
+`typed_enums` only overwrites files that it created.
+
+If `enums.js` or `enums.d.ts` already exists without this generated marker, generation fails instead of overwriting the file:
+
+```ts
+// AUTO-GENERATED BY typed_enums. DO NOT EDIT.
+```
+
+Move the existing file, delete it, or configure a different `config.output_dir`.
+
+The writer removes stale generated `.js`, `.d.ts`, and legacy `.ts` files inside the configured output directory only when they start with:
+
+```ts
+// AUTO-GENERATED BY typed_enums. DO NOT EDIT.
+```
+
+It does not delete user-owned files or files outside the generated directory.
+
+## Namespaced Models
+
+Namespaced models are flattened into safe JavaScript identifiers:
+
+```ruby
+Admin::Task
+```
+
+Generates exports inside:
+
+```text
+app/javascript/lib/enums.js
+app/javascript/lib/enums.d.ts
+```
+
+```ts
+export const AdminTask = {};
+```
+
+## Empty Output
+
+If no models define enums, `typed_enums` still writes `enums.js` and `enums.d.ts` files with the generated header and no exports.
+
+## Troubleshooting
+
+If models are missing, confirm they can be eager-loaded in the current environment. The scanner calls `Rails.application.eager_load!` before reading descendants.
+
+If the root model class is not `ApplicationRecord`, configure `root_model_class`.
+
+If generated files cannot be written, check filesystem permissions for `config.output_dir`.
+
+If check mode fails in CI, run `bin/rails typed_enums:generate` locally and commit the generated files, or add generation to your build before JavaScript or TypeScript compilation.
+
+## Security
+
+Enum values are written to frontend-visible JavaScript files. Do not put secrets, credentials, private tokens, or private application state in enum values.
+
+## Compatibility
+
+The gem targets modern Rails applications and supports Rails 7.1 or newer. It uses Active Record enum APIs and ActiveSupport inflections, and it does not depend on any frontend framework.
+
+## Contributing
+
+Run:
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+```
+
+Keep the gem small and focused: Active Record enums in, JavaScript constants and TypeScript declaration types out.
+
+## License
+
+MIT.

data/lib/generators/typed_enums/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module TypedEnums
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    def create_initializer
+      template "initializer.rb", "config/initializers/typed_enums.rb"
+    end
+
+    def create_generated_directory
+      create_file "app/javascript/lib/.keep", ""
+    end
+  end
+end

data/lib/generators/typed_enums/templates/initializer.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+TypedEnums.configure do |config|
+  # Generated JavaScript and TypeScript declaration files are written here.
+  config.output_dir = "app/javascript/lib"
+
+  # Automatically regenerate enum files in development.
+  config.auto_generate_in_development = true
+
+  # Watch app/models in development and regenerate after saves.
+  config.watch_models_in_development = true
+end

data/lib/typed_enums/configuration.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module TypedEnums
+  class Configuration
+    attr_accessor :output_dir, :root_model_class, :auto_generate_in_development, :watch_models_in_development
+
+    def initialize
+      @output_dir = "app/javascript/lib"
+      @root_model_class = "ApplicationRecord"
+      @auto_generate_in_development = true
+      @watch_models_in_development = true
+    end
+  end
+end

data/lib/typed_enums/enum_definition.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TypedEnums
+  EnumDefinition = Data.define(
+    :model_name,
+    :model_export_name,
+    :attribute_name,
+    :rails_mapping_name,
+    :typescript_property_name,
+    :typescript_type_name,
+    :values
+  )
+end

data/lib/typed_enums/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module TypedEnums
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+end

data/lib/typed_enums/model_scanner.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module TypedEnums
+  class ModelScanner
+    def initialize(config: TypedEnums.configuration, name_builder: Naming::NameBuilder.new)
+      @config = config
+      @name_builder = name_builder
+    end
+
+    def call
+      eager_load_application
+
+      enum_models.flat_map do |model|
+        model.defined_enums.sort_by { |attribute_name, _values| attribute_name }.map do |attribute_name, values|
+          build_definition(model:, attribute_name:, values:)
+        end
+      end
+    end
+
+    private
+
+    attr_reader :config, :name_builder
+
+    def eager_load_application
+      Rails.application.eager_load! if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+    end
+
+    def enum_models
+      root_model_class.descendants
+                      .reject(&:abstract_class?)
+                      .select { |model| model.defined_enums.any? }
+                      .sort_by(&:name)
+    end
+
+    def root_model_class
+      config.root_model_class.to_s.constantize
+    rescue NameError => e
+      raise ConfigurationError, "Could not find root model class #{config.root_model_class.inspect}: #{e.message}"
+    end
+
+    def build_definition(model:, attribute_name:, values:)
+      model_export_name = name_builder.model_export_name(model.name)
+      rails_mapping_name = name_builder.rails_mapping_name(attribute_name)
+
+      EnumDefinition.new(
+        model_name: model.name,
+        model_export_name:,
+        attribute_name:,
+        rails_mapping_name:,
+        typescript_property_name: name_builder.property_name(rails_mapping_name),
+        typescript_type_name: name_builder.type_name(model_export_name:, rails_mapping_name:),
+        values: values.keys.map(&:to_s)
+      )
+    end
+  end
+end

data/lib/typed_enums/naming/name_builder.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module TypedEnums
+  module Naming
+    class NameBuilder
+      def model_export_name(model_name)
+        model_name.to_s.split("::").map(&:camelize).join
+      end
+
+      def rails_mapping_name(attribute_name)
+        attribute_name.to_s.pluralize
+      end
+
+      def property_name(rails_mapping_name)
+        rails_mapping_name.to_s.camelize(:lower)
+      end
+
+      def type_name(model_export_name:, rails_mapping_name:)
+        "#{model_export_name}#{rails_mapping_name.to_s.singularize.camelize}"
+      end
+    end
+  end
+end

data/lib/typed_enums/output/javascript_file.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module TypedEnums
+  module Output
+    class JavaScriptFile
+      HEADER = "// AUTO-GENERATED BY typed_enums. DO NOT EDIT."
+
+      def initialize(model_groups:)
+        @model_groups = model_groups
+      end
+
+      def render
+        <<~JAVASCRIPT
+          #{HEADER}
+          // enum-schema-sha256: #{schema_hash}
+
+          #{model_exports}
+        JAVASCRIPT
+      end
+
+      def schema_hash
+        Digest::SHA256.hexdigest(JSON.generate(schema))
+      end
+
+      private
+
+      attr_reader :model_groups
+
+      def model_exports
+        model_groups.map do |model_export_name, definitions|
+          <<~JAVASCRIPT.chomp
+            export const #{model_export_name} = {
+            #{property_lines(definitions)}
+            };
+          JAVASCRIPT
+        end.join("\n\n")
+      end
+
+      def property_lines(definitions)
+        definitions.map do |definition|
+          "  #{definition.typescript_property_name}: #{render_array(definition.values)},"
+        end.join("\n")
+      end
+
+      def render_array(values)
+        "[#{values.map { |value| JSON.generate(value) }.join(', ')}]"
+      end
+
+      def schema
+        model_groups.transform_values do |definitions|
+          definitions.map do |definition|
+            {
+              attribute: definition.attribute_name,
+              rails_mapping: definition.rails_mapping_name,
+              property: definition.typescript_property_name,
+              type: definition.typescript_type_name,
+              values: definition.values
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/typed_enums/output/type_declaration_file.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+
+module TypedEnums
+  module Output
+    class TypeDeclarationFile
+      HEADER = JavaScriptFile::HEADER
+
+      def initialize(model_groups:, schema_hash:)
+        @model_groups = model_groups
+        @schema_hash = schema_hash
+      end
+
+      def render
+        <<~TYPESCRIPT
+          #{HEADER}
+          // enum-schema-sha256: #{schema_hash}
+
+          #{declarations}
+        TYPESCRIPT
+      end
+
+      private
+
+      attr_reader :model_groups, :schema_hash
+
+      def declarations
+        model_groups.map do |model_export_name, definitions|
+          [constant_declaration(model_export_name, definitions), type_declarations(definitions)].join("\n\n")
+        end.join("\n\n")
+      end
+
+      def constant_declaration(model_export_name, definitions)
+        <<~TYPESCRIPT.chomp
+          export declare const #{model_export_name}: {
+          #{property_lines(definitions)}
+          };
+        TYPESCRIPT
+      end
+
+      def property_lines(definitions)
+        definitions.map do |definition|
+          "  readonly #{definition.typescript_property_name}: readonly #{render_tuple(definition.values)};"
+        end.join("\n")
+      end
+
+      def type_declarations(definitions)
+        definitions.map do |definition|
+          "export type #{definition.typescript_type_name} = " \
+            "(typeof #{definition.model_export_name}.#{definition.typescript_property_name})[number];"
+        end.join("\n")
+      end
+
+      def render_tuple(values)
+        "[#{values.map { |value| JSON.generate(value) }.join(', ')}]"
+      end
+    end
+  end
+end

data/lib/typed_enums/output/writer/result.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module TypedEnums
+  module Output
+    class Writer
+      Result = Data.define(:changed, :missing, :extra, :unchanged, :conflicts) do
+        def stale?
+          changed.any? || missing.any? || extra.any? || conflicts.any?
+        end
+
+        def conflict?
+          conflicts.any?
+        end
+
+        def summary
+          {
+            "conflicts" => conflicts,
+            "missing" => missing,
+            "changed" => changed,
+            "extra" => extra
+          }.filter_map do |label, files|
+            "#{label}: #{files.join(', ')}" if files.any?
+          end.join("\n")
+        end
+
+        def applied_summary
+          {
+            "created" => missing,
+            "updated" => changed,
+            "removed" => extra
+          }.filter_map do |label, files|
+            "#{label}: #{files.join(', ')}" if files.any?
+          end.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/typed_enums/output/writer.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module TypedEnums
+  module Output
+    class Writer
+      GENERATED_MARKER = JavaScriptFile::HEADER
+
+      def initialize(output_dir:, expected_files:, logger: default_logger, check: false)
+        @output_dir = Pathname(output_dir)
+        @expected_files = expected_files
+        @logger = logger
+        @check = check
+      end
+
+      def call
+        ensure_output_dir unless check
+
+        result = Result.new(changed: [], missing: [], extra: [], unchanged: [], conflicts: [])
+        reconcile_expected_files(result)
+        reconcile_stale_files(result)
+        result
+      end
+
+      private
+
+      attr_reader :output_dir, :expected_files, :logger, :check
+
+      def reconcile_expected_files(result)
+        expected_files.sort.each do |relative_path, content|
+          path = output_dir.join(relative_path)
+          reconcile_expected_file(result:, relative_path:, path:, content:)
+        end
+      end
+
+      def reconcile_expected_file(result:, relative_path:, path:, content:)
+        if !path.exist?
+          mark_missing(result:, relative_path:, path:, content:)
+        elsif path.read == content
+          result.unchanged << relative_path
+        elsif !generated_file?(path)
+          result.conflicts << relative_path
+        else
+          mark_changed(result:, relative_path:, path:, content:)
+        end
+      end
+
+      def mark_missing(result:, relative_path:, path:, content:)
+        result.missing << relative_path
+        write_file(path, content) unless check
+      end
+
+      def mark_changed(result:, relative_path:, path:, content:)
+        result.changed << relative_path
+        write_file(path, content) unless check
+      end
+
+      def reconcile_stale_files(result)
+        generated_files.each do |path|
+          relative_path = path.relative_path_from(output_dir).to_s
+          next if expected_files.key?(relative_path)
+
+          result.extra << relative_path
+          remove_file(path) unless check
+        end
+      end
+
+      def ensure_output_dir
+        FileUtils.mkdir_p(output_dir)
+      rescue SystemCallError => e
+        raise Error, "Could not create typed_enums output directory #{output_dir}: #{e.message}"
+      end
+
+      def write_file(path, content)
+        FileUtils.mkdir_p(path.dirname)
+        path.write(content)
+        logger&.info("typed_enums: wrote #{path}")
+      rescue SystemCallError => e
+        raise Error, "Could not write generated file #{path}: #{e.message}"
+      end
+
+      def remove_file(path)
+        path.delete
+        logger&.info("typed_enums: removed stale #{path}")
+      rescue SystemCallError => e
+        raise Error, "Could not remove stale generated file #{path}: #{e.message}"
+      end
+
+      def generated_files
+        return [] unless output_dir.exist?
+
+        output_dir.glob("**/*").select do |path|
+          generated_file?(path)
+        end.sort
+      end
+
+      def generated_file?(path)
+        path.file? && generated_extension?(path) && path.read.start_with?(GENERATED_MARKER)
+      end
+
+      def generated_extension?(path)
+        [".js", ".ts"].include?(path.extname) || path.to_s.end_with?(".d.ts")
+      end
+
+      def default_logger
+        defined?(Rails) ? Rails.logger : nil
+      end
+    end
+  end
+end

data/lib/typed_enums/railtie.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module TypedEnums
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("tasks.rb", __dir__)
+    end
+
+    config.after_initialize do
+      TypedEnums::Railtie.install_development_hooks
+    end
+
+    def self.install_development_hooks
+      return unless Rails.env.development?
+
+      if TypedEnums.configuration.auto_generate_in_development
+        Rails.application.reloader.to_prepare do
+          TypedEnums.generate
+        end
+      end
+
+      return unless TypedEnums.configuration.watch_models_in_development
+
+      TypedEnums.watch
+    end
+  end
+end

data/lib/typed_enums/registry.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TypedEnums
+  class Registry
+    def initialize(scanner: ModelScanner.new)
+      @scanner = scanner
+    end
+
+    def expected_files
+      javascript_file = Output::JavaScriptFile.new(model_groups:)
+
+      {
+        "enums.js" => javascript_file.render,
+        "enums.d.ts" => Output::TypeDeclarationFile.new(
+          model_groups:,
+          schema_hash: javascript_file.schema_hash
+        ).render
+      }
+    end
+
+    private
+
+    attr_reader :scanner
+
+    def model_groups
+      @model_groups ||= scanner.call.group_by(&:model_export_name).sort.to_h
+    end
+  end
+end

data/lib/typed_enums/tasks.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "rake"
+
+namespace :typed_enums do
+  desc "Generate JavaScript enum module and TypeScript declarations from Active Record enums"
+  task generate: :environment do
+    result = TypedEnums.generate
+    if result.conflict?
+      warn "typed_enums: refusing to overwrite existing non-generated files"
+      warn result.summary
+      abort "Move the files, delete them, or change config.output_dir."
+    end
+
+    if result.stale?
+      puts "typed_enums: generated files updated"
+      puts result.applied_summary
+    else
+      puts "typed_enums: generated files are current"
+    end
+  end
+
+  desc "Check whether generated enum files are current"
+  task check: :environment do
+    result = TypedEnums.check
+
+    if result.conflict?
+      warn "typed_enums: existing non-generated files block enum generation"
+      warn result.summary
+      abort "Move the files, delete them, or change config.output_dir."
+    end
+
+    if result.stale?
+      warn "typed_enums: generated files are stale"
+      warn result.summary
+      abort "Run bin/rails typed_enums:generate"
+    end
+
+    puts "typed_enums: generated files are current"
+  end
+
+  desc "Watch Rails model files and regenerate enum files after saves"
+  task watch: :environment do
+    puts "typed_enums: watching app/models for enum changes"
+    TypedEnums::Watcher.run_foreground(logger: Rails.logger)
+  end
+end

data/lib/typed_enums/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TypedEnums
+  VERSION = "0.1.0"
+end

data/lib/typed_enums/watcher.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module TypedEnums
+  class Watcher
+    MODEL_FILE_PATTERN = /\.rb\z/
+    DEFAULT_LATENCY = 0.25
+
+    class << self
+      def start(**options)
+        mutex.synchronize do
+          return instance if instance&.started?
+
+          @instance = new(**options)
+          @instance.start
+        end
+      end
+
+      def stop
+        mutex.synchronize do
+          instance&.stop
+          @instance = nil
+        end
+      end
+
+      def started?
+        instance&.started? || false
+      end
+
+      def run_foreground(**)
+        watcher = start(**)
+        sleep
+      rescue Interrupt
+        nil
+      ensure
+        watcher&.stop
+      end
+
+      private
+
+      attr_reader :instance
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+    end
+
+    def initialize(root: Rails.root, logger: Rails.logger, listener_factory: nil, generator: TypedEnums)
+      @root = Pathname(root)
+      @logger = logger
+      @listener_factory = listener_factory
+      @generator = generator
+      @started = false
+    end
+
+    def start
+      return self if started?
+
+      unless watch_path.directory?
+        logger&.warn("typed_enums: model watch path does not exist: #{watch_path}")
+        return self
+      end
+
+      @listener = build_listener
+      listener.start
+      @started = true
+      logger&.info("typed_enums: watching #{watch_path}")
+      self
+    end
+
+    def stop
+      listener&.stop
+      @started = false
+      self
+    end
+
+    def started?
+      @started
+    end
+
+    private
+
+    attr_reader :root, :logger, :listener, :listener_factory, :generator
+
+    def watch_path
+      root.join("app/models")
+    end
+
+    def build_listener
+      factory = listener_factory || default_listener_factory
+      factory.to(watch_path.to_s, only: MODEL_FILE_PATTERN, latency: DEFAULT_LATENCY) do |modified, added, removed|
+        regenerate(modified:, added:, removed:)
+      end
+    end
+
+    def default_listener_factory
+      require "listen"
+      Listen
+    end
+
+    def regenerate(modified:, added:, removed:)
+      changed_files = modified + added + removed
+      return if changed_files.empty?
+
+      logger&.info("typed_enums: model file changed, regenerating enum files")
+      reload_application
+      generate
+    rescue StandardError => e
+      logger&.error("typed_enums: watch regeneration failed: #{e.class}: #{e.message}")
+    end
+
+    def reload_application
+      return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+      reloader = Rails.application.reloader
+      reloader.reload! if reloader.respond_to?(:reload!)
+    end
+
+    def generate
+      reloader = defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.reloader
+      return generator.generate(logger:) unless reloader
+
+      if reloader.respond_to?(:wrap)
+        reloader.wrap { generator.generate(logger:) }
+      else
+        generator.generate(logger:)
+      end
+    end
+  end
+end

data/lib/typed_enums.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "typed_enums/version"
+require "pathname"
+require "typed_enums/configuration"
+require "typed_enums/error"
+require "typed_enums/enum_definition"
+require "typed_enums/naming/name_builder"
+require "typed_enums/model_scanner"
+require "typed_enums/output/javascript_file"
+require "typed_enums/output/type_declaration_file"
+require "typed_enums/registry"
+require "typed_enums/output/writer/result"
+require "typed_enums/output/writer"
+require "typed_enums/watcher"
+
+module TypedEnums
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def generate(logger: nil)
+      write(check: false, logger:)
+    end
+
+    def check(logger: nil)
+      write(check: true, logger:)
+    end
+
+    def watch(logger: nil)
+      Watcher.start(logger: logger || default_logger)
+    end
+
+    def stop_watcher
+      Watcher.stop
+    end
+
+    private
+
+    def write(check:, logger:)
+      Output::Writer.new(
+        output_dir: output_path,
+        expected_files: Registry.new.expected_files,
+        logger: logger || default_logger,
+        check:
+      ).call
+    end
+
+    def output_path
+      configured_path = Pathname(configuration.output_dir)
+      configured_path.absolute? ? configured_path : Rails.root.join(configured_path)
+    end
+
+    def default_logger
+      defined?(Rails) ? Rails.logger : nil
+    end
+  end
+end
+
+require "typed_enums/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,161 @@
+--- !ruby/object:Gem::Specification
+name: typed_enums
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ackermann
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.25'
+description: typed_enums generates a framework-agnostic JavaScript enum module from
+  Rails model enums.
+email:
+- ghostkominfinity@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/generators/typed_enums/install_generator.rb
+- lib/generators/typed_enums/templates/initializer.rb
+- lib/typed_enums.rb
+- lib/typed_enums/configuration.rb
+- lib/typed_enums/enum_definition.rb
+- lib/typed_enums/error.rb
+- lib/typed_enums/model_scanner.rb
+- lib/typed_enums/naming/name_builder.rb
+- lib/typed_enums/output/javascript_file.rb
+- lib/typed_enums/output/type_declaration_file.rb
+- lib/typed_enums/output/writer.rb
+- lib/typed_enums/output/writer/result.rb
+- lib/typed_enums/railtie.rb
+- lib/typed_enums/registry.rb
+- lib/typed_enums/tasks.rb
+- lib/typed_enums/version.rb
+- lib/typed_enums/watcher.rb
+homepage: https://github.com/AckermannTM/typed_enums
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/AckermannTM/typed_enums
+  changelog_uri: https://github.com/AckermannTM/typed_enums/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Export Rails Active Record enums to JavaScript constants and TypeScript declaration
+  types.
+test_files: []