typelizer 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 067c0e093a70b8c8273e7504004a687c08272a536367958662e9d7c2fe293151
-  data.tar.gz: 6dc5ef91af5f50ead351f90ee6cf8026360f1f605d06df5a30e20a9633ec168b
+  metadata.gz: fd7dab7ab6fabb3be94f1ca6bd6ea98337ea5b6c52811b413ed28f0804e5bd64
+  data.tar.gz: e1dc88644daebf2c3c34ded6cee520963c009568f45cde70e60d1276b8a859c2
 SHA512:
-  metadata.gz: b518818c82709eea2ef5461272c929189d0fa59f53aa3f1cb6309e538ffe586b0bd2117cd520a165def41221f9f05528caf934842584f840f64370ce035488a9
-  data.tar.gz: c89f29ad82e7fa44f3118385ccbd8a6ffb5fde9bbe1d3e400994704fdb8a709ccb9b22f029332cd36da6bdc3c8b190b5c0cf1c9492fa5e11cda4ad7d082c8898
+  metadata.gz: a910d1e73e070287d5c01d3d10f7b8c181b81a78474f4cf53f45c774fea5362d1498345a16f495630e10637f4314548266c779893dccb4dad2d8b95c15cf09da
+  data.tar.gz: 214105e604e21a4901ff437fbf26d8d19886be704c10b8981a26025bfc17fde3046fb1c9e90bf3db0f9a4abd4a954940d6c4168672e58136ff90c9961bcefc38

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.5.0] - 2025-09-01
+
+### Added
+
+- Support for multiple output writers: emit several variants (e.g., snake_case and camelCase) in parallel. ([@supdex])
+- Support for Rails' Attributes API. ([@skryukov])
+
+## [0.4.2] - 2025-06-23
+
+### Added
+
+- Map `uuid` type to `string` by default. ([@ventsislaf])
+
+### Fixed
+
+- Alba: fix `has_many` with a custom `key` generates single value type instead of array. ([@skryukov])
+
 ## [0.4.1] - 2025-06-10
 
 ### Added
@@ -166,9 +183,14 @@ and this project adheres to [Semantic Versioning].
 [@NOX73]: https://github.com/NOX73
 [@okuramasafumi]: https://github.com/okuramasafumi
 [@patvice]: https://github.com/patvice
+[@PedroAugustoRamalhoDuarte]: https://github.com/PedroAugustoRamalhoDuarte
 [@skryukov]: https://github.com/skryukov
+[@supdex]: https://github.com/supdex
+[@ventsislaf]: https://github.com/ventsislaf
 
-[Unreleased]: https://github.com/skryukov/typelizer/compare/v0.4.1...HEAD
+[Unreleased]: https://github.com/skryukov/typelizer/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/skryukov/typelizer/compare/v0.4.2...v0.5.0
+[0.4.2]: https://github.com/skryukov/typelizer/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/skryukov/typelizer/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/skryukov/typelizer/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/skryukov/typelizer/compare/v0.2.0...v0.3.0

data/README.md

@@ -2,7 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/typelizer.svg)](https://rubygems.org/gems/typelizer)
 
-Typelizer is a Ruby gem that automatically generates TypeScript interfaces from your Ruby serializers, bridging the gap between your Ruby backend and TypeScript frontend. It supports multiple serializer libraries and provides a flexible configuration system, making it easier to maintain type consistency across your full-stack application.
+Typelizer generates TypeScript types from your Ruby serializers. It supports multiple serializer libraries and a flexible, layered configuration model so you can keep your backend and frontend in sync without hand‑maintaining types.
 
 ## Table of Contents
 
@@ -16,8 +16,8 @@ Typelizer is a Ruby gem that automatically generates TypeScript interfaces from
   - [Automatic Generation in Development](#automatic-generation-in-development)
   - [Disabling Typelizer](#disabling-typelizer)
 - [Configuration](#configuration)
-  - [Global Configuration](#global-configuration)
-  - [Config Options](#config-options)
+  - [Global Configuration](#simple-configuration)
+  - [Writers (multiple outputs)](#defining-multiple-writers)
   - [Per-Serializer Configuration](#per-serializer-configuration)
 - [Credits](#credits)
 - [License](#license)
@@ -29,8 +29,10 @@ Typelizer is a Ruby gem that automatically generates TypeScript interfaces from
 ## Features
 
 - Automatic TypeScript interface generation
-- Support for multiple serializer libraries (`Alba`, `ActiveModel::Serializer`, `Oj::Serializer`, `Panko::Serializer`)
-- File watching and automatic regeneration in development
+- Infers types from database columns and associations, with support for the Attributes API
+- Supports multiple serializer libraries (`Alba`, `ActiveModel::Serializer`, `Oj::Serializer`, `Panko::Serializer`)
+- File watching with automatic regeneration in development
+- Multiple output writers: emit several variants (e.g., snake_case and camelCase) in parallel
 
 ## Installation
 
@@ -211,8 +213,6 @@ Sometimes we want to use Typelizer only with manual generation. To disable Typel
 
 ## Configuration
 
-### Global Configuration
-
 Typelizer provides several global configuration options:
 
 ```ruby
@@ -226,13 +226,159 @@ Typelizer.logger = Logger.new($stdout, level: :info)
 Typelizer.listen = nil
 ```
 
-### Config Options
+### Configuration Layers
+
+Typelizer uses a hierarchical system to resolve settings. Settings are applied in the following order of precedence, where higher numbers override lower ones:
+
+1.  **Per-Serializer Overrides**: Settings defined using `typelizer_config` directly within a serializer class. This layer has the highest priority.
+2.  **Writer-Specific Settings**: Settings defined within a `config.writer(:name) { ... }` block.
+3.  **Global Settings**: Application-wide settings defined by direct assignment (e.g., `config.comments = true`) within the `Typelizer.configure` block.
+4.  **Library Defaults**: The gem's built-in default values.
+
+### Simple Configuration (Single Output)
+
+For most apps, a single output is enough. All settings in an initializer apply to the `:default` writer and also act as a global baseline.
+
+- Settings like `dirs` are considered **Global** and establish a baseline for all writers.
+- Settings like `output_dir` or `comments` configure the implicit **`:default` writer**.
+
+```ruby
+# config/initializers/typelizer.rb
+Typelizer.configure do |config|
+  # This is a GLOBAL SETTING. It applies to ALL writers.
+  config.dirs = [Rails.root.join("app/serializers")]
+
+  # This setting configures the :default writer and ALSO acts as a global setting.
+  config.output_dir = "app/javascript/types/generated"
+  config.comments = true
+end
+```
+
+### Defining Multiple Writers
+
+The multi-writer system allows for the generation of multiple, distinct TypeScript outputs. Each output is managed by a named writer with an isolated configuration.
+
+
+#### Writer Inheritance Rules
+
+- By default, a new writer inherits its base settings from the Global Settings.
+- To inherit from another existing writer, use the `from:` option.
+
+
+**A Note on the :default Writer and Inheritance**
+- You usually do not need to declare `writer(:default)`. The implicit default writer automatically uses your global settings. 
+- Declare `writer(:default)` when you want to apply specific overrides to it that should not be inherited by other new writers. This provides a way to separate your application's global baseline from settings that are truly unique to the default output
+
+#### Example of the distinction:
+```ruby
+Typelizer.configure do |config|
+  # === Global Setting ===
+  # `comments: true` applies to :default and will be inherited by :camel_case.
+  config.comments = true
+
+  # === Default-Writer-Only Setting ===
+  # `prefer_double_quotes: true` applies ONLY to the :default writer.
+  # It is NOT a global setting and will NOT be inherited by :camel_case.
+  config.writer(:default) do |c|
+    c.prefer_double_quotes = true
+  end
+
+  # === New Writer Definition ===
+  config.writer(:camel_case) do |c|
+    c.output_dir = "app/javascript/types/camel_case"
+    # This writer inherits `comments: true` from globals.
+    # It does NOT inherit `prefer_double_quotes: true` from the :default writer's block.
+    # Its `prefer_double_quotes` will be `false` (the library default).
+  end
+end
+```
+
+#### Configuring Writers
+You can define writers either inside the configure block or directly on the Typelizer module.
+
+1. **Inside the configure block**
+
+This is the approach for keeping all configuration centralized.
+
+```ruby
+# config/initializers/typelizer.rb
+Typelizer.configure do |config|
+  # ... global settings ...
+
+  config.writer(:camel_case) do |c|
+    c.output_dir = "app/javascript/types/camel_case"
+    c.properties_transformer = ->(properties) { # ... transform ... }
+  end
+
+  config.writer(:admin, from: :camel_case) do |c|
+    c.output_dir = "app/javascript/types/admin"
+    c.null_strategy = :optional
+  end
+end
+```
+
+2. Top-Level Helper
+
+```ruby
+Typelizer.writer(:admin, from: :default) do |c|
+  c.output_dir = Rails.root.join("app/javascript/types/admin")
+  c.prefer_double_quotes = true
+end
+```
+
+#### Comprehensive Example
+This example configures three distinct outputs, demonstrating all inheritance mechanisms.
+
+```ruby
+# config/initializers/typelizer.rb
+Typelizer.configure do |config|
+  # === 1. Global Settings (Baseline for ALL writers) ===
+  config.comments = true
+  config.dirs = [Rails.root.join("app/serializers")]
+
+  # === 2. The :default writer (snake_case output) ===
+  config.writer(:default) do |c|
+    c.output_dir = "app/javascript/types/snake_case"
+  end
+
+  # === 3. A new :camel_case writer ===
+  # Inherits `comments: true` and `dirs` from the Global Settings.
+  config.writer(:camel_case) do |c|
+    c.output_dir = "app/javascript/types/camel_case"
+    c.properties_transformer = lambda do |properties|
+      properties.map { |prop| prop.with_overrides(name: prop.name.to_s.camelize(:lower)) }
+    end
+  end
+
+  # === 4. An "admin" writer that clones :camel_case ===
+  # Use `from:` to explicitly inherit another writer's complete configuration.
+  config.writer(:admin, from: :camel_case) do |c|
+    c.output_dir = "app/javascript/types/admin"
+    # This writer inherits the properties_transformer from :camel_case.
+    c.null_strategy = :optional
+  end
+end
+```
+
+### Per-serializer configuration
+
+Use `typelizer_config` within a serializer class to apply overrides with the highest possible priority. 
+These settings will supersede any conflicting settings from the active writer, global settings, or library defaults.
+
+```ruby
+class PostResource < ApplicationResource
+  typelizer_config do |c|
+    c.null_strategy = :nullable_and_optional
+    c.plugin_configs = { alba: { ts_mapper: { "UUID" => { type: :string } } } }
+  end
+end
+```
 
-`Typelizer::Config` offers fine-grained control over the gem's behavior. Here's a list of available options:
+### Option reference
 
 ```ruby
 Typelizer.configure do |config|
-  # Determines how serializer names are mapped to TypeScript interface names
+  # Name to type mapping for serializer classes
   config.serializer_name_mapper = ->(serializer) { ... }
 
   # Maps serializers to their corresponding model classes
@@ -290,20 +436,6 @@ Typelizer.configure do |config|
 end
 ```
 
-### Per-Serializer Configuration
-
-You can also configure Typelizer on a per-serializer basis:
-
-```ruby
-class PostResource < ApplicationResource
-  typelizer_config do |config|
-    config.type_mapping = config.type_mapping.merge(jsonb: "Record<string, undefined>", ... )
-    config.null_strategy = :nullable
-    # ...
-  end
-end
-```
-
 ## Credits
 
 Typelizer is inspired by [types_from_serializers](https://github.com/ElMassimo/types_from_serializers).

data/lib/typelizer/config.rb

@@ -1,18 +1,25 @@
+# frozen_string_literal: true
+
+require "pathname"
+
 module Typelizer
-  TYPE_MAPPING = {
+  TYPE_MAPPING = Hash.new(:unknown).update(
     boolean: :boolean,
     date: :string,
     datetime: :string,
+    time: :string,
     decimal: :number,
+    float: :number,
     integer: :number,
     string: :string,
     text: :string,
-    citext: :string
-  }.tap do |types|
-    types.default = :unknown
-  end
+    citext: :string,
+    uuid: :string
+  ).freeze
 
-  class Config < Struct.new(
+  DEFAULT_TYPES_GLOBAL = %w[Array Date Record File FileList].freeze
+
+  Config = Struct.new(
     :serializer_name_mapper,
     :serializer_model_mapper,
     :properties_transformer,
@@ -30,59 +37,71 @@ module Typelizer
     :comments,
     :prefer_double_quotes,
     keyword_init: true
-  ) do
-    class << self
-      def instance
-        @instance ||= new(
-          serializer_name_mapper: ->(serializer) do
-            return "" if serializer.name.nil?
-
-            serializer.name.ends_with?("Serializer") ? serializer.name&.delete_suffix("Serializer") : serializer.name&.delete_suffix("Resource")
-          end,
-          serializer_model_mapper: ->(serializer) do
-            base_class = serializer_name_mapper.call(serializer)
-            Object.const_get(base_class) if Object.const_defined?(base_class)
-          end,
-
-          model_plugin: ModelPlugins::Auto,
-          serializer_plugin: SerializerPlugins::Auto,
-          plugin_configs: {},
-
-          type_mapping: TYPE_MAPPING,
-          null_strategy: :nullable,
-          inheritance_strategy: :none,
-          associations_strategy: :database,
-          comments: false,
-          prefer_double_quotes: false,
-
-          output_dir: js_root.join("types/serializers"),
-
-          types_import_path: "@/types",
-          types_global: %w[Array Date Record File FileList],
-
-          properties_transformer: nil,
-          verbatim_module_syntax: false
-        )
-      end
-
-      private
-
-      def js_root
-        root_path = defined?(Rails) ? Rails.root : Pathname.pwd
-        js_root = defined?(ViteRuby) ? ViteRuby.config.source_code_dir : "app/javascript"
-        root_path.join(js_root)
-      end
-
-      def respond_to_missing?(name, include_private = false)
-        Typelizer.respond_to?(name) ||
-          instance.respond_to?(name, include_private)
-      end
-
-      def method_missing(method, *args, &block)
-        return Typelizer.send(method, *args, &block) if Typelizer.respond_to?(method)
-        instance.send(method, *args, &block)
-      end
+  )
+
+  # Immutable configuration object for a single writer
+  #
+  # Use .build to construct from defaults, and #with_overrides to copy with overrides.
+  class Config
+    # Returns library defaults (built-in) for building a Config.
+    # This method creates a fresh Hash each time to avoid sharing mutable state
+    # across builds
+    def self.defaults
+      {
+        serializer_name_mapper: lambda do |serializer|
+          name = serializer.name.to_s
+
+          return name if name.empty?
+
+          # remove only the end of the line
+          name.sub(/(Serializer|Resource)\z/, "")
+        end,
+
+        serializer_model_mapper: lambda do |serializer|
+          base_class = serializer_name_mapper.call(serializer)
+          Object.const_get(base_class) if Object.const_defined?(base_class)
+        end,
+
+        model_plugin: ModelPlugins::Auto,
+        serializer_plugin: SerializerPlugins::Auto,
+        plugin_configs: {}.freeze,
+        type_mapping: TYPE_MAPPING,
+        null_strategy: :nullable,
+        inheritance_strategy: :none,
+        associations_strategy: :database,
+        comments: false,
+        prefer_double_quotes: false,
+
+        output_dir: -> { default_output_dir },
+
+        types_import_path: "@/types",
+        types_global: DEFAULT_TYPES_GLOBAL,
+        properties_transformer: nil,
+        verbatim_module_syntax: false
+      }
+    end
+
+    def self.build(**overrides)
+      new(**defaults.merge(overrides))
+    end
+
+    def self.default_output_dir
+      root_path = defined?(Rails) ? Rails.root : Pathname.pwd
+      js_root = defined?(ViteRuby) ? ViteRuby.config.source_code_dir : "app/javascript"
+
+      root_path.join(js_root, "types/serializers")
+    end
+
+    def with_overrides(**overrides)
+      props = to_h
+      props.merge!(overrides) unless overrides.empty?
+
+      self.class.new(**props)
+    end
+
+    def output_dir
+      v = self[:output_dir]
+      v.respond_to?(:call) ? v.call : v
     end
-  end
   end
 end

data/lib/typelizer/configuration.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "set"
+require "pathname"
+
+module Typelizer
+  # Central registry for Typelizer multi-writer configuration
+  #
+  # Responsibilities:
+  # - Holds immutable Config per writer name (always includes :default)
+  # - Maintain flat DSL setters for :default (e.g., config.output_dir = ...)
+  # - Allows defining/updating named writers via writer(:name) { |cfg| ... }
+  # - Check unique output_dir across writers to avoid file conflicts
+  #
+  # Config priorities:
+  # - WriterContext merges in order: library defaults < global_settings < writer < DSL inheritance
+  # - global_settings are only updated by flat setters, not by writer(:default) blocks
+  class Configuration
+    DEFAULT_WRITER_NAME = :default
+
+    attr_accessor :dirs, :reject_class, :listen
+    attr_reader :writers, :global_settings
+
+    def initialize
+      @dirs = []
+      @reject_class = ->(serializer:) { false }
+      @listen = nil
+
+      default = Config.build
+
+      @writers = {DEFAULT_WRITER_NAME => default.freeze}
+      @global_settings = {}
+
+      @writer_output_dirs = {DEFAULT_WRITER_NAME => normalize_path(default.output_dir)}
+      @used_output_dirs = Set.new(@writer_output_dirs.values.compact)
+    end
+
+    # Defines or updates a writer configuration.
+    #
+    # Inherits from the existing writer config (or global_settigns if absent), yields a mutable copy,
+    # then freezes and stores it. output_dir is unique and mandatory
+    # Also accepts "from" argument, which allows us to inherit configuration from any writer
+    def writer(name = DEFAULT_WRITER_NAME, from: nil, &block)
+      writer_name = normalize_writer_name(name)
+
+      # Inherit from existing writer config or from "from" attribute or global (flatt) config
+      base_config =
+        if @writers.key?(writer_name)
+          @writers[writer_name]
+        elsif from && @writers.key?(from.to_sym)
+          @writers[from.to_sym]
+        else
+          Config.build(**@global_settings)
+        end
+
+      mutable_config = base_config.with_overrides
+
+      block&.call(mutable_config)
+
+      # Register output directory for uniqueness checking
+      register_output_dir!(writer_name, mutable_config.output_dir)
+
+      # Store and return frozen configuration
+      @writers[writer_name] = mutable_config.freeze
+    end
+
+    def writer_config(name = DEFAULT_WRITER_NAME)
+      @writers.fetch((name || DEFAULT_WRITER_NAME).to_sym)
+    end
+
+    # Reset writers and keep only `default` writer
+    def reset_writers!
+      @writers.keep_if { |key, _| key == DEFAULT_WRITER_NAME }
+
+      @writer_output_dirs = {
+        DEFAULT_WRITER_NAME => normalize_path(@writers[DEFAULT_WRITER_NAME].output_dir)
+      }
+
+      @used_output_dirs = Set.new(@writer_output_dirs.values.compact)
+    end
+
+    private
+
+    # Setters and readers to Writer(:default) config
+    # Keep the "flat" setters for the :default writer, for example:
+    #   config.output_dir = ...
+    #   config.prefer_double_quotes = true
+    def method_missing(name, *args, &block)
+      name = name.to_s
+      config_key = normalize_method_name(name)
+
+      # Setters
+      if name.end_with?("=") && args.length.positive?
+        return super unless config_attribute?(config_key)
+
+        val = args.first
+        new_default = @writers[DEFAULT_WRITER_NAME].with_overrides(config_key => val)
+
+        register_output_dir!(DEFAULT_WRITER_NAME, new_default.output_dir) if config_key == :output_dir
+
+        @writers[DEFAULT_WRITER_NAME] = new_default.freeze
+
+        return @global_settings[config_key] = val
+      end
+
+      # Readers
+      return @writers[DEFAULT_WRITER_NAME].public_send(config_key) if args.empty? && config_attribute?(config_key)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      str = name.to_s
+      key = normalize_method_name(str)
+      (config_attribute?(key) && (str.end_with?("=") || true)) || super
+    end
+
+    # Normalizes and validates writer name
+    def normalize_writer_name(name)
+      writer_name = (name || DEFAULT_WRITER_NAME).to_sym
+
+      raise ArgumentError, "Writer name cannot be empty" if writer_name.to_s.strip.empty?
+
+      writer_name
+    end
+
+    # Validates and registers output directory for uniqueness across writers
+    def register_output_dir!(writer_name, dir)
+      raise ArgumentError, "output_dir must be configured for writer :#{writer_name}" if dir.to_s.strip.empty?
+
+      path = normalize_path(dir)
+
+      current = @writer_output_dirs[writer_name]
+      return if current == path
+
+      if @writer_output_dirs.any? { |k, v| k != writer_name && v == path }
+        holder = @writer_output_dirs.key(path)
+
+        raise ArgumentError, "output_dir '#{path}' is already in use by writer :#{holder}"
+      end
+
+      @used_output_dirs.delete(current) if current
+      @writer_output_dirs[writer_name] = path
+      @used_output_dirs << path
+    end
+
+    def normalize_path(dir)
+      Pathname(dir).expand_path.to_s
+    end
+
+    def normalize_method_name(name)
+      name.to_s.chomp("=").to_sym
+    end
+
+    def config_attribute?(name)
+      Config.members.include?(name)
+    end
+  end
+end

data/lib/typelizer/contexts/scan_context.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Typelizer
+  # Builds a minimal plugin used during scan time
+  class ScanContext
+    class InvalidOperationError < StandardError; end
+
+    # Interface creation is not available during DSL scanning phase (TracePoint)
+    def self.interface_for(serializer_class)
+      class_name = serializer_class&.name || "unknown class"
+      raise InvalidOperationError,
+        "Interface creation is not allowed during DSL scan (#{class_name})"
+    end
+
+    # just in case, if we call ScanContext like an object
+    def interface_for(serializer_class)
+      self.class.interface_for(serializer_class)
+    end
+  end
+end