dynamoid-cdk-schema 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e17f72b5bacad48e8d0df3aac32d6d27332a6a14c8b3f1ed39d2ef3d1e5ca5de
+  data.tar.gz: 92cdbec04b2b58ab80dba06bc809eb3ddffeec03a2107de46cad9f5a003eb37a
+SHA512:
+  metadata.gz: d54877e0eb240cfcb1727d179c7eff84382db1fd6809a3495826f84ecc236e2bd7ce6e71e682c9c18a5803dc68283b8695294fe732f60cb25a657d7a1fae76c4
+  data.tar.gz: da0ac57c6fdedf438eec444575ae2cf2e88de1692d4fc15bc6fb69b5b3b71acd95ce222e1beec9d4d960560b307e5c7e7dab0c7d4fb39406773e7b441bb91927

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-07-27
+
+- Initial release.
+- `Dynamoid::CDK::Schema.describe(model)` — reads a Dynamoid model's schema (partition/sort keys, global and local
+  secondary indexes, attribute types) into a plain descriptor. Dynamoid only, no AWS CDK required.
+- `Dynamoid::CDK::Schema.table(scope, id, model, **table_props)` — builds the matching CDK `TableV2`; extra keyword
+  args pass through. `aws-cdk-lib` is referenced lazily (the caller's dependency).
+- Supports `ALL` / `KEYS_ONLY` / `INCLUDE` (with `non_key_attributes`) projections and binary key attributes.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"dynamoid-cdk-schema" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["omar@omarqureshi.net"](mailto:"omar@omarqureshi.net").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Omar Qureshi
+
+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,89 @@
+# dynamoid-cdk-schema
+
+Generate [AWS CDK](https://docs.aws.amazon.com/cdk/) DynamoDB tables straight from your
+[Dynamoid](https://github.com/Dynamoid/dynamoid) models.
+
+Your Dynamoid models already declare their keys and indexes. Restating that schema by hand in your CDK stack means two
+sources of truth that drift the moment you add a GSI. This gem reads a model's schema — partition and sort keys, global
+and local secondary indexes, attribute types — and builds the matching `TableV2`, so the model is the single source of
+truth for both the application and its infrastructure.
+
+It works because the AWS CDK is a first-class Ruby library your infrastructure code can `require` and reflect over — the
+same reason it can read your Dynamoid models. There is no separate template to keep in sync.
+
+## Installation
+
+```bash
+bundle add dynamoid-cdk-schema
+```
+
+`aws-cdk-lib` is intentionally **not** a dependency — it's your CDK app's, and it's referenced lazily, only when you
+build a table. So the introspection half (`.describe`) works anywhere Dynamoid is loaded.
+
+## Usage
+
+Inside a CDK stack (where `aws-cdk-lib` and your Dynamoid models are already loaded):
+
+```ruby
+class MyStack < AWSCDK::Stack
+  def initialize(scope, id, **kwargs)
+    super
+
+    # Build a TableV2 from the model. Extra keyword args pass straight through to
+    # TableV2, so the model owns keys + indexes and you own table-level config.
+    posts = Dynamoid::CDK::Schema.table(self, "Posts", Post,
+                                        removal_policy: AWSCDK::RemovalPolicy::RETAIN)
+
+    # `posts` is an ordinary AWSCDK::DynamoDB::TableV2 — grant it, reference it, etc.
+    posts.grant_read_write_data(my_function)
+  end
+end
+```
+
+That's it. If `Post` declares a `global_secondary_index` or `range` key, the table gets it, with the right attribute
+types and projection.
+
+### Just the schema, as data
+
+`.describe` needs only Dynamoid (no CDK) and returns a plain, immutable descriptor — handy for tests, tooling, or
+feeding another target:
+
+```ruby
+Dynamoid::CDK::Schema.describe(Post)
+# => #<data Dynamoid::CDK::Schema::Descriptor
+#      partition_key=#<data Attribute name="id", type=:string>,
+#      sort_key=nil,
+#      global_secondary_indexes=[#<data Index name="by_recency", ...>],
+#      local_secondary_indexes=[]>
+```
+
+### What it reads
+
+- Partition and sort keys, with DynamoDB attribute types (`:string` / `:number` / `:binary`) resolved the way Dynamoid
+  resolves them.
+- Every **global secondary index**: keys, and the projection type — `ALL`, `KEYS_ONLY`, or `INCLUDE` (with its
+  `non_key_attributes`).
+- **Local secondary indexes**.
+
+Table-level configuration Dynamoid doesn't model (billing mode, TTL, point-in-time recovery, streams, removal policy)
+is yours to pass through as keyword arguments — this gem is about the *schema*, keys and indexes.
+
+## Loading your models at synth time
+
+`cdk synth` has to be able to load the model classes you pass in, so `require` them from your CDK app. If a model reads
+application config at load time (e.g. its table name from Rails config), make that available in the synth process — the
+CDK never uses the physical table name (it assigns one), so a placeholder is enough.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies, then `bundle exec rspec` to run the tests and
+`bundle exec rubocop` to lint. `bin/console` gives an interactive prompt.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+<https://github.com/omarqureshi/dynamoid-cdk-schema>.
+
+## License
+
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

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]

data/lib/dynamoid/cdk/schema/descriptor.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Dynamoid
+  module CDK
+    module Schema
+      # A DynamoDB attribute used as a key: its name and DynamoDB type
+      # (+:string+, +:number+ or +:binary+).
+      Attribute = Data.define(:name, :type)
+
+      # A secondary index. For a GSI +partition_key+ is set; for an LSI it is nil
+      # (an LSI shares the table's partition key). +projection_type+ is +:all+,
+      # +:keys_only+ or +:include+; +non_key_attributes+ is the projected list
+      # when +:include+, otherwise nil.
+      Index = Data.define(:name, :partition_key, :sort_key, :projection_type, :non_key_attributes)
+
+      # A model's table shape as plain data — readable and buildable with no AWS
+      # CDK present. +sort_key+ is nil for a hash-only table.
+      Descriptor = Data.define(:partition_key, :sort_key, :global_secondary_indexes, :local_secondary_indexes)
+    end
+  end
+end

data/lib/dynamoid/cdk/schema/introspector.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "dynamoid"
+
+module Dynamoid
+  module CDK
+    module Schema
+      # Reads a Dynamoid model class into a {Descriptor}: partition and sort keys,
+      # GSIs and LSIs, with DynamoDB attribute types resolved exactly the way
+      # Dynamoid resolves them for its own tables. Pure metadata — no DynamoDB
+      # connection and no AWS CDK.
+      module Introspector
+        module_function
+
+        def call(model)
+          Descriptor.new(
+            partition_key: attribute(model, model.hash_key),
+            sort_key: (attribute(model, model.range_key) if model.range_key),
+            global_secondary_indexes: model.global_secondary_indexes.values.map { |i| gsi(model, i) },
+            local_secondary_indexes: model.local_secondary_indexes.values.map { |i| lsi(model, i) }
+          )
+        end
+
+        def attribute(model, name)
+          field = model.attributes[name.to_sym]
+          raise Error, "#{model}: no field #{name.inspect} declared for a key attribute" if field.nil?
+
+          Attribute.new(name: name.to_s, type: dynamodb_type(field))
+        end
+
+        # Resolve a field's DynamoDB key type the way Dynamoid does. Its mapping
+        # doesn't emit :binary, but DynamoDB permits binary keys, so fall back to
+        # the field type on UnsupportedKeyType — mirroring Dynamoid's own index
+        # validation.
+        def dynamodb_type(field)
+          Dynamoid::PrimaryKeyTypeMapping.dynamodb_type(field[:type], field)
+        rescue Dynamoid::Errors::UnsupportedKeyType
+          field[:type]
+        end
+
+        def gsi(model, index)
+          Index.new(
+            name: index.name,
+            partition_key: attribute(model, index.hash_key),
+            sort_key: (attribute(model, index.range_key) if index.range_key),
+            projection_type: index.projection_type,
+            non_key_attributes: non_key_attributes(index)
+          )
+        end
+
+        def lsi(model, index)
+          Index.new(
+            name: index.name,
+            partition_key: nil, # an LSI shares the table's partition key
+            sort_key: attribute(model, index.range_key),
+            projection_type: index.projection_type,
+            non_key_attributes: non_key_attributes(index)
+          )
+        end
+
+        # DynamoDB wants the projected attribute list only for INCLUDE projections.
+        def non_key_attributes(index)
+          return nil unless index.projection_type == :include
+
+          Array(index.projected_attributes).map(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/dynamoid/cdk/schema/table_builder.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Dynamoid
+  module CDK
+    module Schema
+      # Turns a {Descriptor} into an AWS CDK +TableV2+. AWS CDK is the caller's
+      # dependency (the Ruby CDK, from its preview feed), so it is referenced
+      # lazily at build time — the {Introspector} half of the gem works without
+      # it, and a clear error is raised if +.table+ is called without it loaded.
+      module TableBuilder
+        module_function
+
+        def build(scope, id, descriptor, **table_props)
+          props = table_props.merge(key_props(descriptor), index_props(descriptor))
+          dynamodb::TableV2.new(scope, id, props)
+        end
+
+        def key_props(descriptor)
+          props = { partition_key: cdk_attribute(descriptor.partition_key) }
+          props[:sort_key] = cdk_attribute(descriptor.sort_key) if descriptor.sort_key
+          props
+        end
+
+        def index_props(descriptor)
+          props = {}
+          gsis = descriptor.global_secondary_indexes
+          props[:global_secondary_indexes] = gsis.map { |i| cdk_gsi(i) } if gsis.any?
+          lsis = descriptor.local_secondary_indexes
+          props[:local_secondary_indexes] = lsis.map { |i| cdk_lsi(i) } if lsis.any?
+          props
+        end
+
+        def cdk_attribute(attr)
+          { name: attr.name, type: cdk_attribute_type(attr.type) }
+        end
+
+        def cdk_gsi(index)
+          props = {
+            index_name: index.name,
+            partition_key: cdk_attribute(index.partition_key),
+            projection_type: cdk_projection_type(index.projection_type)
+          }
+          props[:sort_key] = cdk_attribute(index.sort_key) if index.sort_key
+          props[:non_key_attributes] = index.non_key_attributes if index.non_key_attributes
+          props
+        end
+
+        def cdk_lsi(index)
+          props = {
+            index_name: index.name,
+            sort_key: cdk_attribute(index.sort_key),
+            projection_type: cdk_projection_type(index.projection_type)
+          }
+          props[:non_key_attributes] = index.non_key_attributes if index.non_key_attributes
+          props
+        end
+
+        def cdk_attribute_type(type)
+          case type
+          when :string then dynamodb::AttributeType::STRING
+          when :number then dynamodb::AttributeType::NUMBER
+          when :binary then dynamodb::AttributeType::BINARY
+          else raise Error, "unsupported key attribute type #{type.inspect}"
+          end
+        end
+
+        def cdk_projection_type(type)
+          case type
+          when :all then dynamodb::ProjectionType::ALL
+          when :keys_only then dynamodb::ProjectionType::KEYS_ONLY
+          when :include then dynamodb::ProjectionType::INCLUDE
+          else raise Error, "unsupported projection type #{type.inspect}"
+          end
+        end
+
+        def dynamodb
+          return AWSCDK::DynamoDB if defined?(AWSCDK::DynamoDB)
+
+          raise Error,
+                "aws-cdk-lib must be loaded to build tables — add it to your CDK app and `require \"aws-cdk-lib\"`"
+        end
+      end
+    end
+  end
+end

data/lib/dynamoid/cdk/schema/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Dynamoid
+  module CDK
+    module Schema
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/dynamoid/cdk/schema.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "schema/version"
+
+module Dynamoid
+  module CDK
+    module Schema
+      class Error < StandardError; end
+    end
+  end
+end
+
+require_relative "schema/descriptor"
+require_relative "schema/introspector"
+require_relative "schema/table_builder"
+
+module Dynamoid
+  module CDK
+    # Generate AWS CDK DynamoDB tables straight from your Dynamoid models, so the
+    # models are the single source of truth for keys and indexes and the two
+    # can't drift.
+    module Schema
+      module_function
+
+      # The model's table shape as plain data (a {Descriptor}). Needs only
+      # Dynamoid — handy for inspection, tests, or feeding another tool.
+      def describe(model)
+        Introspector.call(model)
+      end
+
+      # Build and return a CDK +TableV2+ for +model+ in +scope+ under +id+. Any
+      # extra keyword arguments pass straight through to +TableV2+ (e.g.
+      # +removal_policy:+, +billing:+, +point_in_time_recovery:+), so the model
+      # owns keys and indexes while the caller owns table-level configuration.
+      # Requires aws-cdk-lib to be loaded.
+      #
+      #   Dynamoid::CDK::Schema.table(self, "Posts", Post, removal_policy: ...)
+      def table(scope, id, model, **table_props)
+        TableBuilder.build(scope, id, describe(model), **table_props)
+      end
+    end
+  end
+end

data/sig/dynamoid/cdk/schema.rbs

@@ -0,0 +1,8 @@
+module Dynamoid
+  module CDK
+    module Schema
+      VERSION: String
+      # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+    end
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: dynamoid-cdk-schema
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Omar Qureshi
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dynamoid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+description: Reads a Dynamoid model's schema — partition/sort keys, global and local
+  secondary indexes, attribute types — and builds the matching AWS CDK TableV2, so
+  your models are the single source of truth for both the app and its infrastructure.
+email:
+- omar@omarqureshi.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/dynamoid/cdk/schema.rb
+- lib/dynamoid/cdk/schema/descriptor.rb
+- lib/dynamoid/cdk/schema/introspector.rb
+- lib/dynamoid/cdk/schema/table_builder.rb
+- lib/dynamoid/cdk/schema/version.rb
+- sig/dynamoid/cdk/schema.rbs
+homepage: https://github.com/omarqureshi/dynamoid-cdk-schema
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/omarqureshi/dynamoid-cdk-schema
+  source_code_uri: https://github.com/omarqureshi/dynamoid-cdk-schema
+  changelog_uri: https://github.com/omarqureshi/dynamoid-cdk-schema/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Generate AWS CDK DynamoDB tables from your Dynamoid models.
+test_files: []