turbojson 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ceaa05c135c84cc26f2b51912b98901841146dee317aa371c81ed752de1b1cf
+  data.tar.gz: 2c3d2b7af3d7b3bd7e270401c49ec5eff2f590a7a7bad17cac895e6d6e287dd4
+SHA512:
+  metadata.gz: 639625b06b99467f6714620a7a9bfe2bb4b1667b706834bfd56c9950a6fb8c56a1d0709fa8de95616e2bb716f6d705a38bf5719e1d06b97e0c0aecf7d7a805e7
+  data.tar.gz: 284b34ac41fedb2f1b37b547efda528a644bdb91c9a40b4534161f7eac66a7ebd2def8602080a1273aa6e2836cb90fceea97b827e8a7170567ff6784023350f7

data/README.md

@@ -0,0 +1,121 @@
+# turbojson
+
+Compile a Ruby serializer DSL into fast PostgreSQL JSON SQL for read-heavy APIs. Define attributes and associations in Ruby, then generate SQL that returns JSON without instantiating thousands of ActiveRecord objects.
+
+## Why
+
+ActiveRecord is excellent for writes and business logic, but JSON APIs are often read-heavy. Hydrating large object graphs just to serialize them is slow and memory-intensive. `turbojson` lets you keep a familiar serializer DSL while shifting JSON construction to PostgreSQL (`json_build_object`, `json_agg`).
+
+## Install
+
+Add to your Gemfile:
+
+```ruby
+gem "turbojson"
+```
+
+Or use a local path during development:
+
+```ruby
+gem "turbojson", path: "/path/to/turbojson"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+Define serializers:
+
+```ruby
+class CategorySerializer < Turbojson::Serializer
+  model Category
+  attributes :id, :name
+end
+
+class BarPhotoSerializer < Turbojson::Serializer
+  model BarPhoto
+  attributes :id, :url
+end
+
+class BarSerializer < Turbojson::Serializer
+  model Bar
+  attributes :id, :name
+
+  has_one :category, serializer: CategorySerializer
+  has_many :bar_photos, serializer: BarPhotoSerializer
+
+  attribute :distance do |scope|
+    "ST_Distance(#{scope.table_name}.location, 'POINT(...)')"
+  end
+end
+```
+
+Serialize an ActiveRecord scope:
+
+```ruby
+scope = Bar.where(active: true).limit(10)
+json = BarSerializer.serialize(scope)
+```
+
+Generate SQL directly:
+
+```ruby
+sql = BarSerializer.to_sql
+```
+
+## How It Works
+
+1. DSL definitions build an AST describing the model, attributes, and associations.
+2. The SQL generator compiles the AST into `json_build_object` and `json_agg` SQL.
+3. `serialize(scope)` wraps the generated SQL around your existing relation to respect `where`, `limit`, and `offset`.
+4. The database returns JSON; the gem parses it to Ruby hashes and arrays.
+
+## Strict Column Validation
+
+By default, attributes must be real columns. If a name is not a column, a `Turbojson::ConfigurationError` is raised. Column checks use `schema_cache` when available, then fall back to `columns_hash`.
+
+## Active Storage Key Post-Processing
+
+If you need signed URLs, fetch the key in SQL and post-process in Ruby:
+
+```ruby
+payload = BarSerializer.serialize(scope)
+
+signed = Turbojson::PostProcessor.process(payload) do |key|
+  blob = ActiveStorage::Blob.find_by!(key: key)
+  Rails.application.routes.url_helpers.rails_blob_url(blob, only_path: true)
+end
+```
+
+## Performance Notes
+
+- Uses `LATERAL` joins for associations to avoid correlated subquery hotspots.
+- Avoids instantiating ActiveRecord objects for read-heavy endpoints.
+
+## Testing
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+SQL snapshot tests live under `spec/fixtures/sql/`.
+
+## Roadmap
+
+- Add ActiveModel::Serializer parity specs with a real test database.
+- Expand SQL generation to handle advanced filters and custom join strategies.
+- Add Benchmark.ips and memory benchmarks under `bench/`.
+
+## Contributing
+
+See `AGENTS.md` for repository guidelines, structure, and development notes.
+
+## License
+
+MIT

data/lib/turbojson/ast.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Turbojson
+  module Ast
+    class Root
+      attr_reader :model, :table_name, :nodes
+
+      def initialize(model:, table_name:, nodes:)
+        @model = model
+        @table_name = table_name
+        @nodes = nodes
+      end
+    end
+
+    class Attribute
+      attr_reader :name, :sql
+
+      def initialize(name:, sql: nil)
+        @name = name
+        @sql = sql
+      end
+    end
+
+    class Association
+      attr_reader :name, :type, :serializer_class
+
+      def initialize(name:, type:, serializer_class:)
+        @name = name
+        @type = type
+        @serializer_class = serializer_class
+      end
+    end
+  end
+end

data/lib/turbojson/post_processor.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Turbojson
+  class PostProcessor
+    def self.process(payload, key_suffix: "_key", &block)
+      case payload
+      when Array
+        payload.map { |item| process(item, key_suffix: key_suffix, &block) }
+      when Hash
+        payload.each_with_object({}) do |(key, value), acc|
+          acc[key] = transform_value(key, value, key_suffix, &block)
+        end
+      else
+        payload
+      end
+    end
+
+    def self.transform_value(key, value, key_suffix, &block)
+      if key.to_s.end_with?(key_suffix) && block
+        block.call(value)
+      else
+        process(value, key_suffix: key_suffix, &block)
+      end
+    end
+  end
+end

data/lib/turbojson/schema_inspector.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Turbojson
+  class SchemaInspector
+    def self.column?(model_class, name)
+      table = model_class.respond_to?(:table_name) ? model_class.table_name : nil
+
+      if model_class.respond_to?(:connection)
+        cache = model_class.connection.schema_cache if model_class.connection.respond_to?(:schema_cache)
+        if cache && cache.respond_to?(:columns_hash) && table
+          return cache.columns_hash(table).key?(name.to_s)
+        end
+      end
+
+      if model_class.respond_to?(:columns_hash)
+        return model_class.columns_hash.key?(name.to_s)
+      end
+
+      false
+    end
+  end
+end

data/lib/turbojson/serializer.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "json"
+require "ostruct"
+require_relative "ast"
+require_relative "schema_inspector"
+
+module Turbojson
+  class ConfigurationError < Error; end
+
+  class Serializer
+    class << self
+      def model(klass = nil)
+        if klass
+          config[:model] = klass
+        else
+          config[:model]
+        end
+      end
+
+      def attributes(*names, &block)
+        raise ArgumentError, "attributes requires at least one name" if names.empty?
+
+        names.each do |name|
+          config[:attributes] << {
+            name: name.to_sym,
+            sql: block&.call(model_scope)
+          }
+        end
+      end
+
+      def has_one(name, serializer:)
+        config[:associations] << {
+          name: name.to_sym,
+          type: :has_one,
+          serializer: serializer
+        }
+      end
+
+      def has_many(name, serializer:)
+        config[:associations] << {
+          name: name.to_sym,
+          type: :has_many,
+          serializer: serializer
+        }
+      end
+
+      def ast
+        model_class = config[:model]
+        raise ConfigurationError, "Serializer missing model" unless model_class
+
+        table_name = infer_table_name(model_class)
+        nodes = []
+
+        config[:attributes].each do |attr|
+          validate_column!(model_class, attr[:name]) if attr[:sql].nil?
+          nodes << Ast::Attribute.new(name: attr[:name], sql: attr[:sql])
+        end
+
+        config[:associations].each do |assoc|
+          nodes << Ast::Association.new(
+            name: assoc[:name],
+            type: assoc[:type],
+            serializer_class: assoc[:serializer]
+          )
+        end
+
+        Ast::Root.new(model: model_class, table_name: table_name, nodes: nodes)
+      end
+
+      def to_sql
+        SqlGenerator.new(ast).to_sql
+      end
+
+      def serialize(scope)
+        raise ArgumentError, "scope is required" if scope.nil?
+        raise ConfigurationError, "Arel is required to build SQL" unless defined?(Arel)
+
+        generator = SqlGenerator.new(ast)
+        object_sql, joins = generator.select_parts
+
+        unless scope.respond_to?(:select) && scope.respond_to?(:joins) && scope.respond_to?(:to_sql)
+          raise ConfigurationError, "serialize expects an ActiveRecord::Relation-like scope"
+        end
+
+        relation = scope.select(Arel.sql("#{object_sql} AS data"))
+        joins.each do |join_sql|
+          relation = relation.joins(Arel.sql(join_sql))
+        end
+
+        sql = <<~SQL
+          SELECT COALESCE(json_agg(rows.data), '[]'::json) AS data
+          FROM (#{relation.to_sql}) rows
+        SQL
+
+        connection = scope.connection
+        result = connection.select_value(sql)
+
+        return result unless result.is_a?(String)
+
+        JSON.parse(result)
+      end
+
+      def model_scope
+        model_class = config[:model]
+        return nil unless model_class
+
+        if model_class.respond_to?(:table_name)
+          OpenStruct.new(table_name: model_class.table_name)
+        else
+          nil
+        end
+      end
+
+      private
+
+      def config
+        @config ||= begin
+          parent = superclass.respond_to?(:config) ? superclass.send(:config) : {}
+          {
+            model: parent[:model],
+            attributes: Array(parent[:attributes]).dup,
+            associations: Array(parent[:associations]).dup
+          }
+        end
+      end
+
+      def infer_table_name(model_class)
+        return model_class.table_name if model_class.respond_to?(:table_name)
+
+        raise ConfigurationError, "Model must respond to table_name"
+      end
+
+      def validate_column!(model_class, name)
+        unless SchemaInspector.column?(model_class, name)
+          raise ConfigurationError, "Unknown column #{name} for #{model_class}"
+        end
+      end
+    end
+  end
+end

data/lib/turbojson/sql_generator.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "ast"
+
+module Turbojson
+  class SqlGenerator
+    AssociationInfo = Struct.new(:name, :table_name, :foreign_key, :parent_key)
+
+    def initialize(ast)
+      @ast = ast
+    end
+
+    def to_sql
+      table_name = @ast.table_name
+      object_sql, joins = build_json_object(@ast, table_name)
+
+      sql = []
+      sql << "SELECT #{object_sql} AS data"
+      sql << "FROM #{table_name}"
+      sql.concat(joins) unless joins.empty?
+      sql.join("\n")
+    end
+
+    def select_parts
+      build_json_object(@ast, @ast.table_name)
+    end
+
+    private
+
+    def build_json_object(ast, table_alias)
+      select_pairs = []
+      joins = []
+
+      ast.nodes.each do |node|
+        case node
+        when Ast::Attribute
+          value = node.sql || "#{table_alias}.#{node.name}"
+          select_pairs << "'#{node.name}', #{value}"
+        when Ast::Association
+          assoc = resolve_association(ast.model, node)
+          child_ast = node.serializer_class.ast
+          lateral_alias = "#{assoc.name}_json"
+
+          subquery = if node.type == :has_many
+                       build_has_many_subquery(child_ast, assoc, table_alias)
+                     else
+                       build_has_one_subquery(child_ast, assoc, table_alias)
+                     end
+
+          joins << "LEFT JOIN LATERAL (#{subquery}) #{lateral_alias} ON TRUE"
+          select_pairs << "'#{node.name}', #{lateral_alias}.#{node.name}"
+        end
+      end
+
+      ["json_build_object(#{select_pairs.join(', ')})", joins]
+    end
+
+    def build_has_one_subquery(child_ast, assoc, parent_table)
+      object_sql, child_joins = build_json_object(child_ast, assoc.table_name)
+      sql = []
+      sql << "SELECT #{object_sql} AS #{assoc.name}"
+      sql << "FROM #{assoc.table_name}"
+      sql.concat(child_joins) unless child_joins.empty?
+      sql << "WHERE #{assoc.table_name}.#{assoc.foreign_key} = #{parent_table}.#{assoc.parent_key}"
+      sql << "LIMIT 1"
+      sql.join("\n")
+    end
+
+    def build_has_many_subquery(child_ast, assoc, parent_table)
+      object_sql, child_joins = build_json_object(child_ast, assoc.table_name)
+      inner = []
+      inner << "SELECT #{object_sql} AS data"
+      inner << "FROM #{assoc.table_name}"
+      inner.concat(child_joins) unless child_joins.empty?
+      inner << "WHERE #{assoc.table_name}.#{assoc.foreign_key} = #{parent_table}.#{assoc.parent_key}"
+
+      sql = []
+      sql << "SELECT COALESCE(json_agg(child_rows.data), '[]'::json) AS #{assoc.name}"
+      sql << "FROM (#{inner.join("\n")}) child_rows"
+      sql.join("\n")
+    end
+
+    def resolve_association(model, node)
+      reflection = model.respond_to?(:reflect_on_association) ? model.reflect_on_association(node.name) : nil
+      raise ConfigurationError, "Association #{node.name} not found for #{model}" unless reflection
+
+      table_name = reflection.klass.table_name
+      foreign_key = reflection.foreign_key
+      parent_key = model.respond_to?(:primary_key) ? model.primary_key : "id"
+
+      AssociationInfo.new(node.name, table_name, foreign_key, parent_key)
+    end
+  end
+end

data/lib/turbojson/version.rb

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

data/lib/turbojson.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "turbojson/version"
+require_relative "turbojson/serializer"
+require_relative "turbojson/sql_generator"
+require_relative "turbojson/post_processor"
+
+module Turbojson
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: turbojson
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Turbojson Contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/turbojson.rb
+- lib/turbojson/ast.rb
+- lib/turbojson/post_processor.rb
+- lib/turbojson/schema_inspector.rb
+- lib/turbojson/serializer.rb
+- lib/turbojson/sql_generator.rb
+- lib/turbojson/version.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Compile serializer DSL into Postgres JSON SQL
+test_files: []