dynamoid-cdk-schema 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e17f72b5bacad48e8d0df3aac32d6d27332a6a14c8b3f1ed39d2ef3d1e5ca5de
-  data.tar.gz: 92cdbec04b2b58ab80dba06bc809eb3ddffeec03a2107de46cad9f5a003eb37a
+  metadata.gz: 51132f9f8072871ab9915db6a75821e4c3f90582e356c2cb9f22f7a1022ae9e7
+  data.tar.gz: ba430e02974802775b082e672f4ec100a4f0a2ae4aceccfc547861665d7cb38f
 SHA512:
-  metadata.gz: d54877e0eb240cfcb1727d179c7eff84382db1fd6809a3495826f84ecc236e2bd7ce6e71e682c9c18a5803dc68283b8695294fe732f60cb25a657d7a1fae76c4
-  data.tar.gz: da0ac57c6fdedf438eec444575ae2cf2e88de1692d4fc15bc6fb69b5b3b71acd95ce222e1beec9d4d960560b307e5c7e7dab0c7d4fb39406773e7b441bb91927
+  metadata.gz: c717cbfe3c318a7b390d34653bc94cf05f6120a51c8ae5cb7ef7a7925606bcb2945d64518b83a88c8fe0bef5c68035dfa6e20353872c25957a0f5085cd6d0e07
+  data.tar.gz: b98d384b5febcebca7a81376407c0100c27bc37f6c80da2b9ce07f8625c436f6063cfe07df5a045795bb7229c228c1eea4979661a95c57c19d6ef06ba3754347

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-04
+
+- `Dynamoid::CDK::Schema.dump(model)` / `.load(data)` / `.table_from(scope, id, data, **table_props)` — carry a
+  schema between processes as JSON-native data. For CDK apps that deliberately cannot load the application:
+  a separate infra bundle, a synth step without the app's gems, or models that need config the deploy machine
+  lacks. The app dumps its schema at build time, the CDK app reads the file at synth time.
+- Dynamoid is no longer a runtime dependency, matching how `aws-cdk-lib` was already treated. Anyone introspecting
+  a model already has Dynamoid loaded; a CDK app building from dumped data should not have to install an ORM.
+  **Upgrading:** if you call `.describe` or `.table` and relied on this gem to pull Dynamoid in, declare it yourself.
+
 ## [0.1.0] - 2026-07-27
 
 - Initial release.

data/README.md

@@ -74,6 +74,31 @@ is yours to pass through as keyword arguments — this gem is about the *schema*
 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.
 
+## When the CDK app can't load your models
+
+Sometimes it shouldn't have to: an infra bundle kept deliberately separate from the application, a synth step with none
+of the app's gems, models that need configuration the deploy machine doesn't have. Dump the schema where the models
+live, and read it where the tables are built:
+
+```ruby
+# in the app, at build time — Dynamoid only
+require "json"
+File.write("build/tables.json", JSON.pretty_generate(Dynamoid::CDK::Schema.dump(Post)))
+```
+
+```ruby
+# in the CDK app, at synth time — aws-cdk-lib only, no Dynamoid, no app
+Dynamoid::CDK::Schema.table_from(
+  self, "Posts", JSON.parse(File.read("build/tables.json")), removal_policy: ...
+)
+```
+
+`dump` returns JSON-native data (strings, arrays, hashes, nil), and `load` turns it back into the same descriptor
+`describe` would have produced. `table_from` accepts either.
+
+This also makes the schema a build artifact you can diff, review or check into a deployment bundle — synthesis then
+depends only on what was built, not on whether the app happens to load.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies, then `bundle exec rspec` to run the tests and

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "dynamoid"
-
 module Dynamoid
   module CDK
     module Schema
@@ -13,6 +11,12 @@ module Dynamoid
         module_function
 
         def call(model)
+          # Required here rather than at load: {Schema.table_from} builds tables
+          # from dumped data, and a CDK app doing only that has no reason to
+          # carry Dynamoid. Anyone introspecting a model already has it loaded —
+          # the model IS a Dynamoid class.
+          require "dynamoid"
+
           Descriptor.new(
             partition_key: attribute(model, model.hash_key),
             sort_key: (attribute(model, model.range_key) if model.range_key),

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Dynamoid
+  module CDK
+    module Schema
+      # {Descriptor} to and from plain data, so the two halves of this gem can run
+      # in different processes.
+      #
+      # The usual arrangement loads the models at synth time and calls
+      # {Schema.table}. That is not always possible: a CDK app may deliberately
+      # not depend on the application it deploys — a separate infra bundle, a
+      # synth step with no database gems, an app whose models cannot load without
+      # config the deploy machine lacks. Then the app dumps its schema during
+      # build and the CDK app reads the result:
+      #
+      #   # in the app, where Dynamoid and the models are loaded
+      #   File.write("build/tables.json", JSON.dump(Schema.dump(Post)))
+      #
+      #   # in the CDK app, which needs neither
+      #   Schema.table_from(self, "Posts", JSON.parse(File.read("build/tables.json")))
+      #
+      # Keys are strings and values are strings, arrays, hashes or nil, so the
+      # result survives a JSON round trip unchanged.
+      module Serializer
+        module_function
+
+        def dump(descriptor)
+          {
+            "partition_key" => dump_attribute(descriptor.partition_key),
+            "sort_key" => dump_attribute(descriptor.sort_key),
+            "global_secondary_indexes" => descriptor.global_secondary_indexes.map { |i| dump_index(i) },
+            "local_secondary_indexes" => descriptor.local_secondary_indexes.map { |i| dump_index(i) }
+          }
+        end
+
+        def load(data)
+          data = stringify(data)
+
+          Descriptor.new(
+            partition_key: load_attribute(data["partition_key"]),
+            sort_key: load_attribute(data["sort_key"]),
+            global_secondary_indexes: Array(data["global_secondary_indexes"]).map { |i| load_index(i) },
+            local_secondary_indexes: Array(data["local_secondary_indexes"]).map { |i| load_index(i) }
+          )
+        end
+
+        def dump_attribute(attribute)
+          return nil if attribute.nil?
+
+          { "name" => attribute.name, "type" => attribute.type.to_s }
+        end
+
+        def load_attribute(data)
+          return nil if data.nil?
+
+          data = stringify(data)
+          Attribute.new(name: data.fetch("name"), type: data.fetch("type").to_sym)
+        end
+
+        def dump_index(index)
+          {
+            "name" => index.name,
+            "partition_key" => dump_attribute(index.partition_key),
+            "sort_key" => dump_attribute(index.sort_key),
+            "projection_type" => index.projection_type.to_s,
+            "non_key_attributes" => index.non_key_attributes
+          }
+        end
+
+        def load_index(data)
+          data = stringify(data)
+
+          Index.new(
+            name: data.fetch("name"),
+            partition_key: load_attribute(data["partition_key"]),
+            sort_key: load_attribute(data["sort_key"]),
+            projection_type: data.fetch("projection_type").to_sym,
+            non_key_attributes: data["non_key_attributes"]
+          )
+        end
+
+        # Accept symbol keys too: a descriptor that has not been through JSON is
+        # a reasonable thing to hand back, and failing on it would be a trap.
+        def stringify(data)
+          data.is_a?(Hash) ? data.transform_keys(&:to_s) : data
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module Dynamoid
   module CDK
     module Schema
-      VERSION = "0.1.0"
+      VERSION = "0.2.0"
     end
   end
 end

data/lib/dynamoid/cdk/schema.rb

@@ -12,6 +12,7 @@ end
 
 require_relative "schema/descriptor"
 require_relative "schema/introspector"
+require_relative "schema/serializer"
 require_relative "schema/table_builder"
 
 module Dynamoid
@@ -38,6 +39,30 @@ module Dynamoid
       def table(scope, id, model, **table_props)
         TableBuilder.build(scope, id, describe(model), **table_props)
       end
+
+      # The model's table shape as plain data that survives JSON — for when the
+      # CDK app cannot load the models, and the schema has to travel as a file
+      # from build time to synth time. Needs only Dynamoid.
+      #
+      #   File.write("build/tables.json", JSON.dump(Schema.dump(Post)))
+      def dump(model)
+        Serializer.dump(describe(model))
+      end
+
+      # The inverse: a {Descriptor} from whatever {dump} produced.
+      def load(data)
+        Serializer.load(data)
+      end
+
+      # Build a CDK +TableV2+ from dumped data (or a {Descriptor}) instead of
+      # from a model, so the CDK app needs neither Dynamoid nor the app itself.
+      # Table-level props pass through exactly as in {table}.
+      #
+      #   Schema.table_from(self, "Posts", JSON.parse(File.read("build/tables.json")))
+      def table_from(scope, id, data, **table_props)
+        descriptor = data.is_a?(Descriptor) ? data : load(data)
+        TableBuilder.build(scope, id, descriptor, **table_props)
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dynamoid-cdk-schema
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Omar Qureshi
@@ -19,7 +19,7 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '4'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -46,6 +46,7 @@ files:
 - lib/dynamoid/cdk/schema.rb
 - lib/dynamoid/cdk/schema/descriptor.rb
 - lib/dynamoid/cdk/schema/introspector.rb
+- lib/dynamoid/cdk/schema/serializer.rb
 - lib/dynamoid/cdk/schema/table_builder.rb
 - lib/dynamoid/cdk/schema/version.rb
 - sig/dynamoid/cdk/schema.rbs