structured_store 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98749f2601c0f1a634bfe3b4765766b30f406466946cbd302a04017ba31eb5ae
-  data.tar.gz: f3037e8181f55ab3268f200d28378f2523aca48cc635e13d727e399554db1a62
+  metadata.gz: e03aa6f80b366b7dbb2b3312426a4d7da960e4e96d1840523b061a6de20cf17a
+  data.tar.gz: 24455f358faff6932c5d78d8dc7963f687a35e888b2bafb798d9dae1ca3fe52b
 SHA512:
-  metadata.gz: 380929ef3aca9f2fd7fb4db9500e73c2a127ecc3d1a6f951b20b39097afa60e49164e060866a9fd77abb567f7b1847a32e0c9f00f3a49f3daa0e09d28d2f3bf4
-  data.tar.gz: aa71ce6db686a4a3ba156ec9e59b942ebe6abc77195fc527c4021abcd840d88e04228085ceaa8d8cbc7475dadf16ac561d58006f94bb189bd90a6d067d271aa5
+  metadata.gz: b76620f3c30d6161424accbd88baede2a265040ab5f3dec5d564a981fad9002eae10e4cef3cb1e86c70b1d311e3d338b12773730e535296c0e794ed0316767ae
+  data.tar.gz: 5bbb7b690c4490be4948401b36434a67893cb7fcbb7d149dc96245a7f718210676ec5242eff9902acd6d0bddc6c7453abb29571553a7045000a6d3a2df928858

data/README.md

@@ -107,7 +107,7 @@ class UserPreference < ApplicationRecord
 end
 ```
 
-Generate and run a migration for your model:
+Generate and run a migration for your model (for advanced configuration options like custom foreign keys, see section 9):
 
 ```ruby
 # db/migrate/xxx_create_user_preferences.rb
@@ -425,13 +425,93 @@ all_versions = StructuredStore::VersionedSchema.where(name: "UserPreferences")
                                                .order(:version)
 ```
 
-### 9. Configurable Store Columns
+### 9. Custom Schema Names and Association Options
+
+StructuredStore provides flexibility in configuring your schema associations. The `structured_store` method accepts any `belongs_to` options via the `**belongs_to_options` parameter:
+
+```ruby
+class Product < ApplicationRecord
+  include StructuredStore::Storable
+
+  # Default naming: creates belongs_to :config_versioned_schema
+  # with foreign_key: 'structured_store_config_versioned_schema_id'
+  # and class_name: 'StructuredStore::VersionedSchema'
+  structured_store :config
+
+  # Custom schema name: creates belongs_to :product_configuration
+  # with foreign_key: 'structured_store_product_configuration_id'
+  structured_store :settings, schema_name: 'product_configuration'
+
+  # Custom foreign key: creates belongs_to :metadata_versioned_schema
+  # with foreign_key: 'custom_metadata_fk'
+  structured_store :metadata, foreign_key: 'custom_metadata_fk'
+
+  # Custom class name for using a different schema model
+  structured_store :advanced_config, class_name: 'CustomSchema'
+
+  # Multiple custom options
+  structured_store :options,
+                   schema_name: 'product_options',
+                   foreign_key: 'options_schema_id',
+                   class_name: 'ProductSchema'
+end
+```
+
+#### Using Custom Schema Models
+
+You can associate with custom schema models that have non-conventional primary keys:
+
+```ruby
+# Custom schema model with non-standard primary key
+class CustomSchema < ApplicationRecord
+  self.primary_key = 'schema_key'
+end
+
+class Product < ApplicationRecord
+  include StructuredStore::Storable
+
+  # Associate with CustomSchema using its custom primary key
+  structured_store :settings,
+                   schema_name: 'custom_schema',
+                   class_name: 'CustomSchema',
+                   foreign_key: 'custom_schema_key',
+                   primary_key: 'schema_key'
+end
+```
+
+#### Additional belongs_to Options
+
+Since all keyword arguments are passed through to `belongs_to`, you can use any standard Rails association options:
+
+```ruby
+class Product < ApplicationRecord
+  include StructuredStore::Storable
+
+  # Make the association optional
+  structured_store :config, optional: true
+
+  # Specify inverse_of
+  structured_store :settings,
+                   class_name: 'CustomSchema',
+                   inverse_of: :products
+
+  # Enable touch
+  structured_store :metadata, touch: true
+end
+```
+
+For complete working examples, see:
+
+- `test/dummy/app/models/custom_foreign_key_record.rb` - Custom foreign key example
+- `test/dummy/app/models/custom_primary_key_record.rb` - Custom primary key and class name example
+
+### 10. Configurable Store Columns
 
 StructuredStore supports configurable store columns, allowing you to use alternative column names for a single store (e.g., `depot` instead of `store`) or configure multiple store columns within the same model. This enables you to organize different types of structured data separately while maintaining proper schema versioning.
 
 For detailed information on configuring single custom stores and multiple stores, see the [Custom Stores documentation](docs/custom_stores.md).
 
-### 10. Advanced Usage: Custom Reference Resolvers
+### 11. Advanced Usage: Custom Reference Resolvers
 
 StructuredStore includes a resolver system for handling JSON schema references. You can create custom resolvers by extending `StructuredStore::RefResolvers::Base`:
 
@@ -463,6 +543,7 @@ CustomResolver.register
 ```
 
 **Available instance variables in your resolver:**
+
 - `property_schema` - The property's JSON schema hash
 - `parent_schema` - The parent SchemaInspector for looking up definitions
 - `property_name` - The property name (for error messages)

data/app/models/concerns/structured_store/storable.rb

@@ -41,6 +41,13 @@ module StructuredStore
       # @param column_name [String, Symbol] The name of the store column in your model
       # @param schema_name [String, Symbol, nil] Optional custom name for the schema association
       #   If not provided, defaults to "#{column_name}_versioned_schema"
+      # @param belongs_to_options [Hash] Options to pass to the belongs_to association
+      # @option belongs_to_options [String, Symbol] :foreign_key Custom foreign key for the belongs_to association
+      #   If not provided, defaults to "structured_store_#{schema_name}_id"
+      # @option belongs_to_options [String, Symbol] :primary_key Custom primary key for the belongs_to association
+      #   If not provided, uses the default primary key of the associated model
+      # @option belongs_to_options [String] :class_name Custom class name for the belongs_to association
+      #   If not provided, defaults to 'StructuredStore::VersionedSchema'
       #
       # @example Simple store configuration
       #   structured_store :preferences
@@ -51,11 +58,27 @@ module StructuredStore
       #   structured_store :config, schema_name: 'product_configuration'
       #   # Creates: belongs_to :product_configuration
       #   # Helper method: product_configuration_json_schema
-      def structured_store(column_name, schema_name: nil)
+      #
+      # @example Custom foreign key
+      #   structured_store :settings, foreign_key: 'custom_schema_id'
+      #   # Creates: belongs_to with foreign_key: 'custom_schema_id'
+      #
+      # @example Custom primary key
+      #   structured_store :settings, primary_key: 'custom_pk'
+      #   # Creates: belongs_to with primary_key: 'custom_pk'
+      #
+      # @example Custom class name
+      #   structured_store :settings, class_name: 'CustomSchema'
+      #   # Creates: belongs_to with class_name: 'CustomSchema'
+      def structured_store(column_name, schema_name: nil, **belongs_to_options)
         column_name = column_name.to_s
         schema_name ||= "#{column_name}_versioned_schema"
         schema_name = schema_name.to_s
 
+        # Set defaults for belongs_to options if not provided
+        belongs_to_options[:foreign_key] ||= "structured_store_#{schema_name}_id"
+        belongs_to_options[:class_name] ||= 'StructuredStore::VersionedSchema'
+
         # Add configuration for this column
         self._structured_store_configurations = _structured_store_configurations + [{
           column_name: column_name,
@@ -63,9 +86,7 @@ module StructuredStore
         }]
 
         # Define the belongs_to association immediately
-        belongs_to schema_name.to_sym, # rubocop:disable Rails/InverseOf
-                   class_name: 'StructuredStore::VersionedSchema',
-                   foreign_key: "structured_store_#{schema_name}_id"
+        belongs_to schema_name.to_sym, **belongs_to_options
 
         # Define helper method to get schema for this specific store
         define_method "#{column_name}_json_schema" do

data/lib/structured_store/version.rb

@@ -1,3 +1,3 @@
 module StructuredStore
-  VERSION = '1.0.1'.freeze
+  VERSION = '1.1.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: structured_store
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Tim Gentry
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-12 00:00:00.000000000 Z
+date: 2025-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json_schemer